bug#31803: Problems in chroot.2, ln.1, test.1, [.1

[Eric S. Raymond]

Eric Blake <address@hidden>:
> 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.