GNU bug report logs - #46808
Man page of "tail"

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 46808 in the body.
You can then email your comments to 46808 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: Reuti <reuti <at> staff.uni-marburg.de>
To: bug-coreutils <at> gnu.org
Subject: Man page of "tail"
Date: Sat, 27 Feb 2021 08:32:22 +0100

Hi,

I noticed some formatting issues in the man page of `tail`, and I wonder whether they are intentional as they occur at some places. They happen up to version 8.32:

line: "-c, --bytes=[+]NUM" the "[" is in italic: \fB\-c\fR, \fB\-\-bytes\fR=\fI\,[\/\fR+]NUM
line: "-f, --follow[={name|descriptor}]" the "[=" is in bold: \fB\-f\fR, \fB\-\-follow[=\fR{name|descriptor}]
line: "-n, --lines=[+]NUM" the "[" is "[" is in italic: \fB\-n\fR, \fB\-\-lines\fR=\fI\,[\/\fR+]NUM

I'm not a `groff` expert, but the sequence "\,some-text\/" appears a couple of times. What effect does it have for the formatting as the "," and "/" are not output?

-- Reuti

Message #10 received at 46808-done <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Reuti <reuti <at> staff.uni-marburg.de>
Cc: 46808-done <at> debbugs.gnu.org, bug-help2man <at> gnu.org
Subject: Re: bug#46808: Man page of "tail"
Date: Wed, 23 Feb 2022 14:36:34 -0800

On 2/26/21 23:32, Reuti wrote:

> I noticed some formatting issues in the man page of `tail`, and I wonder whether they are intentional as they occur at some places. They happen up to version 8.32:
> 
> line: "-c, --bytes=[+]NUM" the "[" is in italic: \fB\-c\fR, \fB\-\-bytes\fR=\fI\,[\/\fR+]NUM
> line: "-f, --follow[={name|descriptor}]" the "[=" is in bold: \fB\-f\fR, \fB\-\-follow[=\fR{name|descriptor}]
> line: "-n, --lines=[+]NUM" the "[" is "[" is in italic: \fB\-n\fR, \fB\-\-lines\fR=\fI\,[\/\fR+]NUM
> 
> I'm not a `groff` expert, but the sequence "\,some-text\/" appears a couple of times. What effect does it have for the formatting as the "," and "/" are not output?

Thanks for the bug report. Those lines are automatically generated by 
help2man, so I'm cc'ing this to bug-help2man <at> gnu.org and will close the 
coreutils bug report.

The problem is that "tail --help" outputs this:

  -c, --bytes=[+]NUM       output the last NUM bytes; or use -c +NUM to
                             output starting with byte NUM of each file
  -f, --follow[={name|descriptor}]
                           output appended data as the file grows;
                             an absent option argument means 'descriptor'
  -F                       same as --follow=name --retry
  -n, --lines=[+]NUM       output the last NUM lines, instead of the 
last 10;
                             or use -n +NUM to output starting with 
line NUM


and help2man transforms that into:

.TP
\fB\-c\fR, \fB\-\-bytes\fR=\fI\,[\/\fR+]NUM
output the last NUM bytes; or use \fB\-c\fR +NUM to
output starting with byte NUM of each file
.TP
\fB\-f\fR, \fB\-\-follow[=\fR{name|descriptor}]
output appended data as the file grows;
.IP
an absent option argument means 'descriptor'
.TP
\fB\-F\fR
same as \fB\-\-follow\fR=\fI\,name\/\fR \fB\-\-retry\fR
.TP
\fB\-n\fR, \fB\-\-lines\fR=\fI\,[\/\fR+]NUM
output the last NUM lines, instead of the last 10;
or use \fB\-n\fR +NUM to output starting with line NUM

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

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Reuti <reuti <at> staff.uni-marburg.de>
Cc: 46808 <at> debbugs.gnu.org
Subject: Re: bug#46808: Man page of "tail"
Date: Thu, 24 Feb 2022 00:02:55 +0100

On Feb 27 2021, Reuti wrote:

> I'm not a `groff` expert, but the sequence "\,some-text\/" appears a couple of times. What effect does it have for the formatting as the "," and "/" are not output?

\, and \/ add some space as italic correction, see (groff) Ligatures and
Kerning.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

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

From: Brendan O'Dea <bod <at> debian.org>
To: Reuti <reuti <at> staff.uni-marburg.de>, 46808 <at> debbugs.gnu.org
Cc: Paul Eggert <eggert <at> cs.ucla.edu>
Subject: Re: bug#46808: Man page of "tail"
Date: Thu, 24 Feb 2022 21:44:28 +1100

On Thu, Feb 24, 2022 at 12:02:55AM +0100, Andreas Schwab wrote:
>On Feb 27 2021, Reuti wrote:
>
>> I'm not a `groff` expert, but the sequence "\,some-text\/" appears a couple of times. What effect does it have for the formatting as the "," and "/" are not output?
>
>\, and \/ add some space as italic correction, see (groff) Ligatures and
>Kerning.

https://www.gnu.org/software/groff/manual/html_node/Ligatures-and-Kerning.html

Note that these escapes are a no-op when manual pages are formatted for
a terminal (e.g. running "man tail" and viewing the output in a pager).

They are added to improve output rendered for printing (ps, pdf, dvi,
etc):

  man -t tail | lpr -Pps
  man -Tpdf tail >tail.1.pdf

As Paul noted, those escapes and other formatting are added by help2man,
using a heuristic which mostly works, but seems a bit hit and miss with
some of the tail flags: "--bytes=[+]NUM" as you identified doesn't fare
well.  Compare to ls flags "--block-size=SIZE" and "--color[=WHEN]".

I'll take a look to see if I can do something to handle tail's output
better.

--bod

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

From: Reuti <reuti <at> staff.uni-marburg.de>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: 46808 <at> debbugs.gnu.org
Subject: Re: bug#46808: Man page of "tail"
Date: Fri, 25 Feb 2022 16:47:49 +0100

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

> Am 24.02.2022 um 00:02 schrieb Andreas Schwab <schwab <at> linux-m68k.org>:
> 
> On Feb 27 2021, Reuti wrote:
> 
>> I'm not a `groff` expert, but the sequence "\,some-text\/" appears a couple of times. What effect does it have for the formatting as the "," and "/" are not output?
> 
> \, and \/ add some space as italic correction, see (groff) Ligatures and
> Kerning.

Aha – thx for the pointer.

-- Reuti


> --
> Andreas Schwab, schwab <at> linux-m68k.org
> GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
> "And now for something completely different."

[signature.asc (application/pgp-signature, attachment)]

Previous Next

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