Re: syntax of options in man1

"G. Branden Robinson" <[email protected]> Thu, 16 Jul 2026 10:55:44 -0500

Newsgroups	org.kernel.vger.linux-man
Message-ID	<20260716155544.o7fx7ecnpjj5sdai@illithid>

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

signature.asc (application/pgp-signature, 833 B)