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

[Eric Blake]

On 06/12/2018 02:16 PM, address@hidden 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