GNU bug report logs - #31803
Problems in chroot.2, ln.1, test.1, [.1

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 31803 in the body.
You can then email your comments to 31803 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: esr <at> thyrsus.com
To: bug-coreutils <at> gnu.org
Subject: Problems in chroot.2, ln.1, test.1, [.1
Date: Tue, 12 Jun 2018 15:16:14 -0400 (EDT)

[Message part 1 (text/plain, inline)]

This is automatically generated email about markup problems in a man
page for which you appear to be responsible.  If you are not the right
person or list, please tell me so I can correct my database.

See http://catb.org/~esr/doclifter/bugs.html for details on how and
why these patches were generated.  Feel free to email me with any
questions.  Note: These patches do not change the modification date of
any manual page.  You may wish to do that by hand.

I apologize if this message seems spammy or impersonal. The volume of
markup bugs I am tracking is over five hundred - there is no real
alternative to generating bugmail from a database and template.

--
                             Eric S. Raymond

[Message part 2 (text/plain, inline)]

Problems with test.1:

(Identical patches should apply to: [.1)

Broken command synopsis syntax.  This may mean you're using a
construction in the command synopsis other than the standard
[ ] | { }, or it may mean you have running text in the command synopsis
section (the latter is not technically an error, but most cases of it
are impossible to translate into DocBook markup), or it may mean the
command syntax fails to match the description.

Command-line options described are not actually implemented.

--- test.1-unpatched	2018-04-17 21:54:23.971441556 -0400
+++ test.1	2018-04-17 21:58:02.075011621 -0400
@@ -7,20 +7,15 @@
 \fI\,EXPRESSION\/\fR
 .br
 .B test
-
-.br
-.B [
-\fI\,EXPRESSION \/\fR]
-.br
-.B [
-]
-.br
-.B [
-\fI\,OPTION\/\fR
 .SH DESCRIPTION
 .\" Add any additional description here
 .PP
 Exit with the status determined by EXPRESSION.
+.PP
+The command "[" is linked to test, and a trailing "]" im the arguments
+is ignored.  Thus, acomposition of the operations described below may
+be surrounded by [ ] and will be interpreted as a test command.  This
+syntax is frequently used in shell conditionals.
 .TP
 \fB\-\-help\fR
 display this help and exit

[Message part 3 (text/plain, inline)]

Problems with chroot.2:

My translator trips over a useless command in list markup.

List syntax error. This means .IP, .TP or .RS/.RE markup is garbled.
Common causes include .TP just before a section header, .TP entries
with tags but no bodies, and mandoc lists with no trailing .El.
These confuse doclifter, and may also mess up stricter man-page
browsers like Xman and Rosetta.

--- chroot.2-unpatched	2018-05-17 13:06:30.287251247 -0400
+++ chroot.2	2018-05-17 13:08:13.406550442 -0400
@@ -46,17 +46,13 @@
 .BR chroot ():
 .ad l
 .RS 4
-.PD 0
-.TP 4
 Since glibc 2.2.2:
 .nf
 _XOPEN_SOURCE && ! (_POSIX_C_SOURCE\ >=\ 200112L)
     || /* Since glibc 2.20: */ _DEFAULT_SOURCE
     || /* Glibc versions <= 2.19: */ _BSD_SOURCE
-.TP 4
 .fi
 Before glibc 2.2.2: none
-.PD
 .RE
 .ad b
 .SH DESCRIPTION

[Message part 4 (text/plain, inline)]

Problems with ln.1:

Parenthesized comments in command synopsis.  This is impossible
to translate to DocBook.

--- ln.1-unpatched	2018-04-17 21:19:33.699561983 -0400
+++ ln.1	2018-04-17 21:20:35.227440696 -0400
@@ -4,16 +4,16 @@
 ln \- make links between files
 .SH SYNOPSIS
 .B ln
-[\fI\,OPTION\/\fR]... [\fI\,-T\/\fR] \fI\,TARGET LINK_NAME   (1st form)\/\fR
+[\fI\,OPTION\/\fR]... [\fI\,-T\/\fR] \fI\,TARGET LINK_NAME\/\fR
 .br
 .B ln
-[\fI\,OPTION\/\fR]... \fI\,TARGET                  (2nd form)\/\fR
+[\fI\,OPTION\/\fR]... \fI\,TARGET\/\fR
 .br
 .B ln
-[\fI\,OPTION\/\fR]... \fI\,TARGET\/\fR... \fI\,DIRECTORY     (3rd form)\/\fR
+[\fI\,OPTION\/\fR]... \fI\,TARGET\/\fR... \fI\,DIRECTORY\/\fR
 .br
 .B ln
-[\fI\,OPTION\/\fR]... \fI\,-t DIRECTORY TARGET\/\fR...  \fI\,(4th form)\/\fR
+[\fI\,OPTION\/\fR]... \fI\,-t DIRECTORY TARGET\/\fR...
 .SH DESCRIPTION
 .\" Add any additional description here
 .PP

Message #8 received at 31803 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: esr <at> thyrsus.com, 31803 <at> debbugs.gnu.org
Subject: Re: bug#31803: Problems in chroot.2, ln.1, test.1, [.1
Date: Tue, 12 Jun 2018 15:18:27 -0500

On 06/12/2018 02:16 PM, esr <at> thyrsus.com wrote:
> 
> Problems with test.1:
> 
> (Identical patches should apply to: [.1)

Well, it's the same page, so there's only one file to patch, if at all.

> 
> Broken command synopsis syntax.  This may mean you're using a
> construction in the command synopsis other than the standard
> [ ] | { }, or it may mean you have running text in the command synopsis
> section (the latter is not technically an error, but most cases of it
> are impossible to translate into DocBook markup), or it may mean the
> command syntax fails to match the description.
> 
> Command-line options described are not actually implemented.
> 
> --- test.1-unpatched	2018-04-17 21:54:23.971441556 -0400
> +++ test.1	2018-04-17 21:58:02.075011621 -0400
> @@ -7,20 +7,15 @@
>   \fI\,EXPRESSION\/\fR
>   .br
>   .B test
> -
> -.br
> -.B [
> -\fI\,EXPRESSION \/\fR]
> -.br
> -.B [
> -]
> -.br
> -.B [
> -\fI\,OPTION\/\fR

Is your complaint that these are not rendering correctly?  They match 
the output of '[ --help' (since that is the canonical source that 
generates the coreutils man pages); it may be that the bug is in 
help2man in not knowing how to render the [ utility properly.

>   .SH DESCRIPTION
>   .\" Add any additional description here
>   .PP
>   Exit with the status determined by EXPRESSION.
> +.PP
> +The command "[" is linked to test, and a trailing "]" im the arguments

s/im/in/

> +is ignored.  Thus, acomposition of the operations described below may

s/acomposition/a composition/

> +be surrounded by [ ] and will be interpreted as a test command.  This
> +syntax is frequently used in shell conditionals.

I'm not a fan of this rewording (even if it were done without typos). 
While the man pages test.1 and [.1 are identical (can and should be hard 
linked), the utilities test(1) and [(1) are intentionally NOT hard 
links.  Per GNU Coding Standards, we compile two separate binaries, with 
two different behaviors chosen at compile time, rather than one utility 
that pays attention to argv[0].  In fact, if I do 'ln -s /bin/[ 
$HOME/test', I'd get the [ behavior rather than the test behavior when 
invoking $HOME/test (rather confusing, but fits with the fact that POSIX 
says that invoking test and/or [ via a symlink with an inappropriate 
basename is non-portable - caveat emptor).

At any rate, the behavior of --help and whether a trailing ] is 
significant differs between the two utilities, and a wall of prose does 
not do justice to the fact that the two invocations are intentionally 
different (in particular, you've gotten rid of the '[ OPTION' synopsis, 
which does not exist for the test utility, but is essential for the '[ 
--help' trick that generates the man page in the first place).

>   .TP
>   \fB\-\-help\fR
>   display this help and exit
> 
> 
> 
> Problems with chroot.2:
> 
> My translator trips over a useless command in list markup.
> 
> List syntax error. This means .IP, .TP or .RS/.RE markup is garbled.
> Common causes include .TP just before a section header, .TP entries
> with tags but no bodies, and mandoc lists with no trailing .El.
> These confuse doclifter, and may also mess up stricter man-page
> browsers like Xman and Rosetta.
> 
> --- chroot.2-unpatched	2018-05-17 13:06:30.287251247 -0400
> +++ chroot.2	2018-05-17 13:08:13.406550442 -0400
> @@ -46,17 +46,13 @@
>   .BR chroot ():
>   .ad l
>   .RS 4
> -.PD 0
> -.TP 4
>   Since glibc 2.2.2:
>   .nf
>   _XOPEN_SOURCE && ! (_POSIX_C_SOURCE\ >=\ 200112L)
>       || /* Since glibc 2.20: */ _DEFAULT_SOURCE
>       || /* Glibc versions <= 2.19: */ _BSD_SOURCE
> -.TP 4
>   .fi
>   Before glibc 2.2.2: none
> -.PD
>   .RE
>   .ad b
>   .SH DESCRIPTION
> 

Thanks. Again, that's probably a bug in help2man rendering 'chroot 
--help' output incorrectly, so we should fix that tool (coreutils has 
man/chroot.x as a template to guide things that help2man can't do by 
itself, but the templates are very minimal, and there is no usage of the 
empty list construct in the template file, so it is being generated by 
help2man).

> 
> 
> Problems with ln.1:
> 
> Parenthesized comments in command synopsis.  This is impossible
> to translate to DocBook.
> 
> --- ln.1-unpatched	2018-04-17 21:19:33.699561983 -0400
> +++ ln.1	2018-04-17 21:20:35.227440696 -0400
> @@ -4,16 +4,16 @@
>   ln \- make links between files
>   .SH SYNOPSIS
>   .B ln
> -[\fI\,OPTION\/\fR]... [\fI\,-T\/\fR] \fI\,TARGET LINK_NAME   (1st form)\/\fR
> +[\fI\,OPTION\/\fR]... [\fI\,-T\/\fR] \fI\,TARGET LINK_NAME\/\fR
>   .br
>   .B ln
> -[\fI\,OPTION\/\fR]... \fI\,TARGET                  (2nd form)\/\fR
> +[\fI\,OPTION\/\fR]... \fI\,TARGET\/\fR
>   .br
>   .B ln
> -[\fI\,OPTION\/\fR]... \fI\,TARGET\/\fR... \fI\,DIRECTORY     (3rd form)\/\fR
> +[\fI\,OPTION\/\fR]... \fI\,TARGET\/\fR... \fI\,DIRECTORY\/\fR
>   .br
>   .B ln
> -[\fI\,OPTION\/\fR]... \fI\,-t DIRECTORY TARGET\/\fR...  \fI\,(4th form)\/\fR
> +[\fI\,OPTION\/\fR]... \fI\,-t DIRECTORY TARGET\/\fR...

Here, the problem lies in 'ln --help' output, which is easy to patch via 
src/ln.c, rather than trying to patch man/ln.x or help2man.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

Message #11 received at 31803 <at> debbugs.gnu.org (full text, mbox):

From: "Eric S. Raymond" <esr <at> thyrsus.com>
To: Eric Blake <eblake <at> redhat.com>
Cc: 31803 <at> debbugs.gnu.org
Subject: Re: bug#31803: Problems in chroot.2, ln.1, test.1, [.1
Date: Tue, 12 Jun 2018 17:34:01 -0400

Eric Blake <eblake <at> redhat.com>:
> Is your complaint that these are not rendering correctly?  They match the
> output of '[ --help' (since that is the canonical source that generates the
> coreutils man pages); it may be that the bug is in help2man in not knowing
> how to render the [ utility properly.

No, it renders properly in man.  The problem is that some of what the
page does cannot be lifted to Docbook-XML.

What this matters: You find me near the end of the hard part of a
project I've been working for 17 years - beating the horrible tag soup
that is the Unix manual-page corpus into something uniform enough that
high-quality HTML can be generated from it reliably and mechanically.

Why DocBook-XML?  Because it turns out that trying to move directly from
presentation-level man markup to HTML produces crappy HTML.  Better
to use cliche analysis to get to semantic markup and than to HTML from that;
it means (for example) that things like emphasized content and examples
render in the output HTML in a uniform way rather than carrying through
idiosyncratic presentation choices from the input.  Also you get things
like working hyperlinks from man page references.

I'm down to 13 errors and 397 patches for markup errors out of 13699
pages in an Ubuntu 18.04 with a lot of development stuff loaded.  Your
pages are in only 3% that don't yet lift clean.  That number will drop
further because mosr of the patches I ship are plain and simple bug
fixes, nit 

The end goal is that `man foo' should by default no longer produce
plain text through a pager, but rather get you high-quality HTML
through a text browser with all hypertext features working.  Without
package authors having to do anything special - with automatic
conversion good enough all the magic can be done at the distro-package
level.

In your specific case, one problem is that the '[' that is test's
alias desperately confuses my parser for command synopses, which is
trying to lift these into the XML submarkup for these synoposes.  This
is a harder problem than simply making sure the synopsis looks
reasonable.

Another issue is that the XML-Docbook command syntax has no way to
embed explanatory text win a command synopsis. Thus, in order to
achieve the end goal I have to jawbone manpage authors into not doing
this.

> I'm not a fan of this rewording (even if it were done without typos). While
> the man pages test.1 and [.1 are identical (can and should be hard linked),
> the utilities test(1) and [(1) are intentionally NOT hard links.  Per GNU
> Coding Standards, we compile two separate binaries, with two different
> behaviors chosen at compile time, rather than one utility that pays
> attention to argv[0].  In fact, if I do 'ln -s /bin/[ $HOME/test', I'd get
> the [ behavior rather than the test behavior when invoking $HOME/test
> (rather confusing, but fits with the fact that POSIX says that invoking test
> and/or [ via a symlink with an inappropriate basename is non-portable -
> caveat emptor).
> 
> At any rate, the behavior of --help and whether a trailing ] is significant
> differs between the two utilities, and a wall of prose does not do justice
> to the fact that the two invocations are intentionally different (in
> particular, you've gotten rid of the '[ OPTION' synopsis, which does not
> exist for the test utility, but is essential for the '[ --help' trick that
> generates the man page in the first place).

I think these objections are perfectly reasonable.  Your page is one
of the awkward cases where I had to bend the markup and text somewhat
out of its natural shape (more so than I wanted to) to fit the
XML-Docbook constraints.

We can cooperate to work around this.  One obvious way: If the
square-bracket aliases on your page were marked up as the groff
escapes \*[lB] and \*[rB] instead of '[' and ']' they would render the
same, but I think I could teach my parser to no longer be confused and
I wouldn't have to try to patch them out in favor of a wall of text.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

My work is funded by the Internet Civil Engineering Institute: https://icei.org
Please visit their site and donate: the civilization you save might be your own.

Message #14 received at 31803 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: esr <at> thyrsus.com, Eric Blake <eblake <at> redhat.com>
Cc: 31803 <at> debbugs.gnu.org
Subject: Re: bug#31803: Problems in chroot.2, ln.1, test.1, [.1
Date: Wed, 13 Jun 2018 09:03:04 -0700

Eric S. Raymond wrote:
> We can cooperate to work around this.  One obvious way: If the
> square-bracket aliases on your page were marked up as the groff
> escapes \*[lB] and \*[rB] instead of '[' and ']' they would render the
> same, but I think I could teach my parser to no longer be confused and
> I wouldn't have to try to patch them out in favor of a wall of text.

Something like that should be fine. However, wouldn't it cause the man page to 
fail with traditional troff, as still shipped and supported on Solaris 10? In 
that case, perhaps we could use [\"[ and ]\"] as special markers instead of 
using \*[lB] and \*[rB]; this should work with bold old troff and groff, if I 
understand the proposal correctly.

Message #17 received at 31803 <at> debbugs.gnu.org (full text, mbox):

From: "Eric S. Raymond" <esr <at> thyrsus.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 31803 <at> debbugs.gnu.org, Eric Blake <eblake <at> redhat.com>
Subject: Re: bug#31803: Problems in chroot.2, ln.1, test.1, [.1
Date: Wed, 13 Jun 2018 16:24:23 -0400

Paul Eggert <eggert <at> cs.ucla.edu>:
> Eric S. Raymond wrote:
> > We can cooperate to work around this.  One obvious way: If the
> > square-bracket aliases on your page were marked up as the groff
> > escapes \*[lB] and \*[rB] instead of '[' and ']' they would render the
> > same, but I think I could teach my parser to no longer be confused and
> > I wouldn't have to try to patch them out in favor of a wall of text.
> 
> Something like that should be fine. However, wouldn't it cause the man page
> to fail with traditional troff, as still shipped and supported on Solaris
> 10? In that case, perhaps we could use [\"[ and ]\"] as special markers
> instead of using \*[lB] and \*[rB]; this should work with bold old troff and
> groff, if I understand the proposal correctly.

I see the problem, but I'm afraid my groff-fu is no strong enough to grok your
proposed solution.  Why will those sequences work? What are they doing?
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

My work is funded by the Internet Civil Engineering Institute: https://icei.org
Please visit their site and donate: the civilization you save might be your own.

Message #20 received at 31803 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: esr <at> thyrsus.com
Cc: 31803 <at> debbugs.gnu.org, Eric Blake <eblake <at> redhat.com>
Subject: Re: bug#31803: Problems in chroot.2, ln.1, test.1, [.1
Date: Wed, 13 Jun 2018 15:00:19 -0700

On 06/13/2018 01:24 PM, Eric S. Raymond wrote:
> I see the problem, but I'm afraid my groff-fu is no strong enough to grok your
> proposed solution.  Why will those sequences work? What are they doing?

They should work for groff and traditional troff, because \" begins a 
comment. I was hoping that they would also work for whatever 
preprocessor you're writing, because it can treat [\"[ etc. specially 
and your preprocessor can key off that.

Message #23 received at 31803 <at> debbugs.gnu.org (full text, mbox):

From: "Eric S. Raymond" <esr <at> thyrsus.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 31803 <at> debbugs.gnu.org, Eric Blake <eblake <at> redhat.com>
Subject: Re: bug#31803: Problems in chroot.2, ln.1, test.1, [.1
Date: Wed, 13 Jun 2018 18:07:56 -0400

Paul Eggert <eggert <at> cs.ucla.edu>:
> On 06/13/2018 01:24 PM, Eric S. Raymond wrote:
> > I see the problem, but I'm afraid my groff-fu is no strong enough to grok your
> > proposed solution.  Why will those sequences work? What are they doing?
> 
> They should work for groff and traditional troff, because \" begins a
> comment. I was hoping that they would also work for whatever preprocessor
> you're writing, because it can treat [\"[ etc. specially and your
> preprocessor can key off that.

Ahh, I see.  I was confused because I thought you were proposing using those
inline and I didn't see how that could work.

OK, this should fly.  Please mark up the manual sources with those (and put
a comment somewhere explaining why we're doing this, to deconfuse future
maintainers) and mail me a copy.  Then I'll teach doclifter to DTRT.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

My work is funded by the Internet Civil Engineering Institute: https://icei.org
Please visit their site and donate: the civilization you save might be your own.

Message #26 received at 31803 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: esr <at> thyrsus.com
Cc: 31803 <at> debbugs.gnu.org, Eric Blake <eblake <at> redhat.com>
Subject: Re: bug#31803: Problems in chroot.2, ln.1, test.1, [.1
Date: Wed, 13 Jun 2018 16:12:15 -0700

On 06/13/2018 03:07 PM, Eric S. Raymond wrote:
> OK, this should fly.  Please mark up the manual sources with those (and put
> a comment somewhere explaining why we're doing this, to deconfuse future
> maintainers) and mail me a copy.  Then I'll teach doclifter to DTRT.

It turns out to be more complicated, since test.1 and ln.1 are 
automatically generated by help2man. Also, in looking at the troff 
source I thought it'd be cleaner to quote the square brackets, like this 
for example:

.B "["

If this doesn't work for doclifter please let me know; we could use '.B 
[\&' instead, as now that I think about it that's a more common way to 
address similar issues than the comment hack I mentioned in my previous 
email.

Your bug report mentioned chroot.2, but that man page belongs to the 
kernel; coreutils is in charge of chroot.1 so I guess you should send 
the chroot.2 section to the kernel man page maintainers.

Finally, there is no file '[.1' in coreutils. Perhaps this is some alias 
maintained downstream? Anyway, it's likely just a copy of test.1 so we 
should be OK here.

I installed the following patches into coreutils and I hope this fixes 
things for you.

https://git.savannah.gnu.org/cgit/coreutils.git/commit/?id=de73c801f34438c1457118f33e26e688554019d3

Message #29 received at 31803 <at> debbugs.gnu.org (full text, mbox):

From: "Eric S. Raymond" <esr <at> thyrsus.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 31803 <at> debbugs.gnu.org, Eric Blake <eblake <at> redhat.com>
Subject: Re: bug#31803: Problems in chroot.2, ln.1, test.1, [.1
Date: Thu, 14 Jun 2018 00:09:45 -0400

Paul Eggert <eggert <at> cs.ucla.edu>:
> It turns out to be more complicated, since test.1 and ln.1 are automatically
> generated by help2man. Also, in looking at the troff source I thought it'd
> be cleaner to quote the square brackets, like this for example:
> 
> .B "["
> 
> If this doesn't work for doclifter please let me know; we could use '.B [\&'
> instead, as now that I think about it that's a more common way to address
> similar issues than the comment hack I mentioned in my previous email.

I think [\& would be better.  I have to quote-strip while parsing
synopsis sections, so there's an order-of-operations issue there
that's best avoided.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

My work is funded by the Internet Civil Engineering Institute: https://icei.org
Please visit their site and donate: the civilization you save might be your own.

Message #32 received at 31803 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: esr <at> thyrsus.com
Cc: 31803 <at> debbugs.gnu.org, Eric Blake <eblake <at> redhat.com>
Subject: Re: bug#31803: Problems in chroot.2, ln.1, test.1, [.1
Date: Thu, 14 Jun 2018 12:09:08 -0700

[Message part 1 (text/plain, inline)]

On 06/13/2018 09:09 PM, Eric S. Raymond wrote:
> I think [\& would be better.  I have to quote-strip while parsing
> synopsis sections, so there's an order-of-operations issue there
> that's best avoided.

OK, I installed the attached. Though in hindsight I wonder, can't 
doclifter see that the brackets are bolded, and so are literals instead 
of being metanotation? (Can't hurt to ask...)

[0001-doc-port-test.1-to-doclifter.patch (text/x-patch, attachment)]

Message #35 received at 31803 <at> debbugs.gnu.org (full text, mbox):

From: "Eric S. Raymond" <esr <at> thyrsus.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 31803 <at> debbugs.gnu.org, Eric Blake <eblake <at> redhat.com>
Subject: Re: bug#31803: Problems in chroot.2, ln.1, test.1, [.1
Date: Thu, 14 Jun 2018 16:24:48 -0400

Paul Eggert <eggert <at> cs.ucla.edu>:
> OK, I installed the attached. Though in hindsight I wonder, can't doclifter
> see that the brackets are bolded, and so are literals instead of being
> metanotation? (Can't hurt to ask...)

It's a perfectly reasonable question and I would probably be asking it myself
in your shoes.

Unfortunately, use of highlighting in these synopses is so inconsistent (and
in some cases downright perverse) that I had to give up trying to back out
syntactic/semantic info from it.  Too many false positives from very
reasonable-sounding rules like yours.

This is one aspect of The Problem With Synopses - which is definitely
the biggest single pain in my ass by far about parsing man-page tag
soup. What can be in a Synopsis section is not standardized anywhere,
and governed only by tradition.  DocBook-XML does a pretty good job of
capturing a large subset of that tradition in a subset of its DTD, but
is necessarily unable to express lots of edge cases other than by
treating them as unstrucured text.

Doing that, of course, defeats the point of the semantic markup.  So I
fight a constant uphill battle to improve the parser.  Been working on
this for 17 years and have my residuals down to a hair less than 2% of
the man-page corpus, but it's what I've elsewhere called a Zeno tarpit:

http://esr.ibiblio.org/?p=6772
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

My work is funded by the Internet Civil Engineering Institute: https://icei.org
Please visit their site and donate: the civilization you save might be your own.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.