Re: syntax of options in man1

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 2039 bytes --]

Hi Branden,

On 2026-07-16T10:55:44-0500, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2026-07-16T16:45:16+0200, Alejandro Colomar wrote:
> > On 2026-07-16T09:46:25-0400, Douglas McIlroy wrote:
> > > Here's a typical option heading (from tail(1))
> > >   *    -n, --lines=[+]NUM*
> > > 
> > > It is tempting to assume (incorrectly) that the short alternative is
> > > -n=4.  As far as I can tell, the convention that "=" is part of only
> > > the long alternative is described nowhere.
> > 
> > Agree.  I've had that concern for a long time.
> 
> That's why I recommend a somewhat different presentation format.
> 
> Illustration:
> 
> $ cat ATTIC/tail.man
> .TH tail 1 2026-07-16 "groff test suite"
> .SH Name
> tail \- a porcine corkscrew
> .SH Description
> Print the last 10 lines of each
> .I file
> to standard output.
> .SH Options
> .TP
> .BR \-\-lines= [ + ]\c
> .IR num
> .TQ
> .BR \-n\~ [ + ]\c
> .IR num
> Print the last
> .I num
> lines instead.
> .
> Prefixing
> .I num
> with
> .RB \[lq] + \[rq]
> prints all lines from
> .I num
> forward.
> 
> Rendering:
> 
> $ nroff -rLL=72n -P -c -man ATTIC/tail.man
> tail(1)                  General Commands Manual                 tail(1)
> 
> Name
>      tail - a porcine corkscrew
> 
> Description
>      Print the last 10 lines of each file to standard output.
> 
> Options
>      --lines=[+]num
>      -n [+]num
>             Print  the  last  num lines instead.  Prefixing num with “+”
>             prints all lines from num forward.
> 
> groff test suite               2026‐07‐16                        tail(1)
> 
> Regards,
> Branden

Agree; indeed, after checking, the manual pages of the Linux man-pages
project follow this convention.

The pages that use the dubious convention come from GNU coreutils.

I've had plans to write new pages for coreutils, and haven't done it
yet.  Maybe it's the time that I do that.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]