GNU bug report logs - #14649
Problems in chroot.2, ln.1, ptx.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 14649 in the body.
You can then email your comments to 14649 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, ptx.1, test.1, [.1
Date: Tue, 18 Jun 2013 01:14:03 -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 ln.1:

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

--- ln.1-unpatched	2012-06-28 19:08:11.104797083 -0400
+++ ln.1	2012-06-28 19:08:38.520796573 -0400
@@ -4,16 +4,16 @@
 ln \- make links between files
 .SH SYNOPSIS
 .B ln
-[\fIOPTION\fR]... [\fI-T\fR] \fITARGET LINK_NAME   (1st form)\fR
+[\fIOPTION\fR]... [\fI-T\fR] \fITARGET LINK_NAME
 .br
 .B ln
-[\fIOPTION\fR]... \fITARGET                  (2nd form)\fR
+[\fIOPTION\fR]... \fITARGET
 .br
 .B ln
-[\fIOPTION\fR]... \fITARGET\fR... \fIDIRECTORY     (3rd form)\fR
+[\fIOPTION\fR]... \fITARGET\fR... \fIDIRECTORY
 .br
 .B ln
-[\fIOPTION\fR]... \fI-t DIRECTORY TARGET\fR...  \fI(4th form)\fR
+[\fIOPTION\fR]... \fI-t DIRECTORY TARGET\fR...
 .SH DESCRIPTION
 .\" Add any additional description here
 .PP

[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	2012-06-30 16:40:34.828017118 -0400
+++ chroot.2	2012-06-30 16:41:39.536015957 -0400
@@ -46,15 +46,12 @@
 .BR chroot ():
 .ad l
 .RS 4
-.PD 0
-.TP 4
 Since glibc 2.2.2:
 .nf
 _BSD_SOURCE ||
     (_XOPEN_SOURCE\ >=\ 500 ||
         _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) &&
     !(_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600)
-.TP 4
 .fi
 Before glibc 2.2.2: none
 .PD

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

Problems with ptx.1:

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

--- ptx.1-unpatched	2010-07-22 16:30:37.000000000 -0400
+++ ptx.1	2010-07-22 16:31:32.000000000 -0400
@@ -4,7 +4,7 @@
 ptx \- produce a permuted index of file contents
 .SH SYNOPSIS
 .B ptx
-[\fIOPTION\fR]... [\fIINPUT\fR]...   \fI(without -G)\fR
+[\fIOPTION\fR]... [\fIINPUT\fR]...
 .br
 .B ptx
 \fI-G \fR[\fIOPTION\fR]... [\fIINPUT \fR[\fIOUTPUT\fR]]

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

Problems with test.1:

(Identical patches should apply to: [.1)

--- test.1-unpatched	2012-06-30 11:52:03.264340869 -0400
+++ test.1	2012-06-30 11:53:49.460338879 -0400
@@ -7,16 +7,13 @@
 \fIEXPRESSION\fR
 .br
 .B test
-
-.br
-.B [
-\fIEXPRESSION \fR]
-.br
-.B [
+[
+--help
+] [
+--version
+] [
+\fIEXPRESSION
 ]
-.br
-.B [
-\fIOPTION\fR
 .SH DESCRIPTION
 .\" Add any additional description here
 .PP

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

From: Pádraig Brady <P <at> draigBrady.com>
To: esr <at> thyrsus.com
Cc: 14649 <at> debbugs.gnu.org
Subject: Re: bug#14649: Problems in chroot.2, ln.1, ptx.1, test.1, [.1
Date: Tue, 18 Jun 2013 15:47:13 +0100

On 06/18/2013 06:14 AM, esr <at> thyrsus.com wrote:
> 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
> 
> 
> 
> Problems with ln.1:
> 
> Parenthesized comments in command synopsis.  This is impossible
> to translate to DocBook.

So is this a limitation of docbook, troff or doclifter?
I'm unsure what to do here, but we can't just remove the comments.

> Problems with test.1:
> 
> (Identical patches should apply to: [.1)

The reason for the non symmetry is documented in the source.

thanks,
Pádraig.

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

From: "Eric S. Raymond" <esr <at> thyrsus.com>
To: Pádraig Brady <P <at> draigBrady.com>
Cc: 14649 <at> debbugs.gnu.org
Subject: Re: bug#14649: Problems in chroot.2, ln.1, ptx.1, test.1, [.1
Date: Tue, 18 Jun 2013 12:22:35 -0400

Pádraig Brady <P <at> draigBrady.com>:
> > Parenthesized comments in command synopsis.  This is impossible
> > to translate to DocBook.
> 
> So is this a limitation of docbook, troff or doclifter?

It's a limitation of XML-DocBook.  The markup includes a special syntax
for synopses with a fixed grammar and terminals. Over 99.7% of manual
pages with command synopses fit that grammar; yours is one of the very few 
exceptions.

> I'm unsure what to do here, but we can't just remove the comments.

I don't see why not; they're just ordinal numbering and thus convey
little or no information.  But if you want a rewrite less dependent
obn the numbering, here's how I'd do it:


With the -T option (1st form above), create a link to TARGET with the
name LINK_NAME.

With a single file or directory argument (2nd form), create a link to
TARGET in the current directory.

With the -t option (3rd form) or a final directory argument (4th form),
create links to each TARGET in DIRECTORY.

Create hard links by default, symbolic links with \fB\-\-symbolic\fR.
By default, each destination (name of new link) should not already exist.
When creating hard links, each TARGET must exist.  Symbolic links
can hold arbitrary text; if later resolved, a relative link is
interpreted in relation to its parent directory.

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

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

From: Assaf Gordon <assafgordon <at> gmail.com>
To: 14649 <at> debbugs.gnu.org
Subject: Re: bug#14649: Problems in chroot.2, ln.1, ptx.1, test.1, [.1
Date: Fri, 19 Oct 2018 11:03:50 -0600

merge 14649 31803
tags 14649 fixed
close 14649
stop

(triaging old bugs)

ln.1 and test.1 fixed here:
https://git.savannah.gnu.org/cgit/coreutils.git/commit/?id=de73c801f34438c1457118f33e26e688554019d3


closing.

-assaf

Previous Next

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