GNU bug report logs - #74107
Spurious ".IP" macros in a few coreutils 9.5 man pages

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 74107 in the body.
You can then email your comments to 74107 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: Glenn Golden <gdg <at> zplane.com>
To: bug-coreutils <at> gnu.org
Subject: Spurious ".IP" macros in a few coreutils 9.5 man pages
Date: Wed, 30 Oct 2024 08:14:55 -0600

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

A few man pages from coreutils 9.5 seem to have spurious ".IP" troff macros
in several places.  Noticed in tail.1, timeout.1.  Not present in cat.1, df.1,
du.1, ls.1, rm.1, tr.1. Did not check others.

See attached screenshots of rendered pages for tail and timeout. The extra
vertical spacings seem to be due to what appear to be spurious .IP macros.

Platform/version info:
   Arch linux, coreutils package 9.5-2 (latest), commodity x86_64 laptop.

[format_ex_1.png (image/png, attachment)]

[format_ex_2.png (image/png, attachment)]

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

From: Pádraig Brady <P <at> draigBrady.com>
To: gdg <at> zplane.com, 74107 <at> debbugs.gnu.org
Subject: Re: bug#74107: Spurious ".IP" macros in a few coreutils 9.5 man pages
Date: Wed, 30 Oct 2024 15:31:28 +0000

On 30/10/2024 14:14, Glenn Golden wrote:
> A few man pages from coreutils 9.5 seem to have spurious ".IP" troff macros
> in several places.  Noticed in tail.1, timeout.1.  Not present in cat.1, df.1,
> du.1, ls.1, rm.1, tr.1. Did not check others.
> 
> See attached screenshots of rendered pages for tail and timeout. The extra
> vertical spacings seem to be due to what appear to be spurious .IP macros.
> 
> Platform/version info:
>     Arch linux, coreutils package 9.5-2 (latest), commodity x86_64 laptop.

This comes from the manual indentation present in --help output
to help delineate option descriptions.  help2man will insert a .IP
when it sees such indentation.  I'm not sure how to easily address this.
We previously discussed more programmatic alignment in --help output,
which may implicitly solve the issue.

cheers,
Pádraig

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

From: "Glenn Golden" <gdg <at> zplane.com>
To: "Brendan O'Dea" <bod <at> debian.org>, 74107 <at> debbugs.gnu.org
Subject: Re: bug#74808: date.1: Some remarks and and a patch for editorial
 changes for this man page
Date: Fri, 13 Dec 2024 14:13:44 -0700

On Fri, Dec 13, 2024, at 00:38, Brendan O'Dea wrote:
>
> bug-help2man is is an alias to my email address, and I have fallen behind.
> I finally got to working through the backlog yesterday (mostly prompted by
> an email about this issue), but ran out of time.  I'll push a release when
> I return.
>

While the patient is on the table, might it be possible to also look into this: 

    https://debbugs.gnu.org/cgi/bugreport.cgi?bug=74107

From what Padraig said in his response to the above report, it sounded like 
fixing it on the source side (modifying -help output) is one way that had been 
discussed to avoid it, but just wondering (since you're going to be working
on it anyway) if it might be possible for help2man to recognize the type of 
indentation construct that results in the extra vertical space and just avoid
inserting an addtional ".IP"?

- Glenn Golden

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

From: Brendan O'Dea <bod <at> debian.org>
To: Glenn Golden <gdg <at> zplane.com>
Cc: 74107 <at> debbugs.gnu.org
Subject: Re: bug#74808: date.1: Some remarks and and a patch for editorial
 changes for this man page
Date: Mon, 3 Feb 2025 17:24:28 +1100

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

On Fri, Dec 13, 2024 at 02:13:44PM -0700, Glenn Golden wrote:
>While the patient is on the table, might it be possible to also look into this: 
>
>    https://debbugs.gnu.org/cgi/bugreport.cgi?bug=74107
>
>From what Padraig said in his response to the above report, it sounded like 
>fixing it on the source side (modifying -help output) is one way that had been 
>discussed to avoid it, but just wondering (since you're going to be working
>on it anyway) if it might be possible for help2man to recognize the type of 
>indentation construct that results in the extra vertical space and just avoid
>inserting an addtional ".IP"?

The problem is that the indentation of wrapped lines doesn't
match. e.g.:

    -f, --follow[={name|descriptor}]
                             output appended data as the file grows;
                               an absent option argument means 'descriptor'

so the line starting with "an absent ..." is rendered as a separate
indented paragraph rather than the intended continuation of the previous
tagged paragraph:

  .TP
  \fB\-f\fR, \fB\-\-follow[=\fR{name|descriptor}]
  output appended data as the file grows;
  .IP
  an absent option argument means 'descriptor'

If the additional two spaces are removed:

    -f, --follow[={name|descriptor}]
                             output appended data as the file grows;
                             an absent option argument means 'descriptor'

it is interpreted as a continuation, and included in the same paragraph:

  .TP
  \fB\-f\fR, \fB\-\-follow[=\fR{name|descriptor}]
  output appended data as the file grows;
  an absent option argument means 'descriptor'

This is a bit tricky to get right for all inut: help2man is trying to
apply semantic meaning to arbitrary text, and changing the heuristic for
one use case has broken others in the past.  Which makes me cautious
about changing the default behaviour to accomodate the indented
continuation lines used by tail.

I have however added a new --loose-indent option for the next release
which will be a bit more relaxed about matching continuations such as
used by tail:

  https://salsa.debian.org/bod/help2man/-/commit/8fe02612ad71e237b1cf76054131d5b62e0c0da8

The tail manual page generated with that new option is attached.

--bod

[tail.1.gz (application/gzip, attachment)]

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

From: Pádraig Brady <P <at> draigBrady.com>
To: Brendan O'Dea <bod <at> debian.org>, Glenn Golden <gdg <at> zplane.com>
Cc: 74107-done <at> debbugs.gnu.org
Subject: Re: bug#74107: bug#74808: date.1: Some remarks and and a patch for
 editorial changes for this man page
Date: Wed, 5 Feb 2025 12:55:06 +0000

On 03/02/2025 06:24, Brendan O'Dea wrote:
> On Fri, Dec 13, 2024 at 02:13:44PM -0700, Glenn Golden wrote:
>> While the patient is on the table, might it be possible to also look into this:
>>
>>     https://debbugs.gnu.org/cgi/bugreport.cgi?bug=74107
>>
>>From what Padraig said in his response to the above report, it sounded like 
>> fixing it on the source side (modifying -help output) is one way that had been
>> discussed to avoid it, but just wondering (since you're going to be working
>> on it anyway) if it might be possible for help2man to recognize the type of
>> indentation construct that results in the extra vertical space and just avoid
>> inserting an addtional ".IP"?
> 
> The problem is that the indentation of wrapped lines doesn't
> match. e.g.:
> 
>      -f, --follow[={name|descriptor}]
>                               output appended data as the file grows;
>                                 an absent option argument means 'descriptor'
> 
> so the line starting with "an absent ..." is rendered as a separate
> indented paragraph rather than the intended continuation of the previous
> tagged paragraph:
> 
>    .TP
>    \fB\-f\fR, \fB\-\-follow[=\fR{name|descriptor}]
>    output appended data as the file grows;
>    .IP
>    an absent option argument means 'descriptor'
> 
> If the additional two spaces are removed:
> 
>      -f, --follow[={name|descriptor}]
>                               output appended data as the file grows;
>                               an absent option argument means 'descriptor'
> 
> it is interpreted as a continuation, and included in the same paragraph:
> 
>    .TP
>    \fB\-f\fR, \fB\-\-follow[=\fR{name|descriptor}]
>    output appended data as the file grows;
>    an absent option argument means 'descriptor'
> 
> This is a bit tricky to get right for all inut: help2man is trying to
> apply semantic meaning to arbitrary text, and changing the heuristic for
> one use case has broken others in the past.  Which makes me cautious
> about changing the default behaviour to accomodate the indented
> continuation lines used by tail.
> 
> I have however added a new --loose-indent option for the next release
> which will be a bit more relaxed about matching continuations such as
> used by tail:
> 
>    https://salsa.debian.org/bod/help2man/-/commit/8fe02612ad71e237b1cf76054131d5b62e0c0da8
> 
> The tail manual page generated with that new option is attached.

That works well, removing extraneous new lines in
expr.1, id.1, numfmt.1, shred.1, tail.1, and timeout.1.

I've pushed to coreutils the sync to the latest help2man,
and added the --loose-indent option.

Marking this as done.

thanks!
Pádraig

Previous Next

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