Re: syntax of options in man1

Re: syntax of options in man1

[Alejandro Colomar]

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

[Added linux-man@]

Hi Doug,

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.

> I think the description belongs in intro(1).

Agree.

> Incidentally, the actual content of intro(1) is absurdly bloated and much
> of it is way off topic.

Agree.

I think there should be a separation between an introduction to the
entire system (maybe this could be intro(0)), and an introduction to the
first section of the manual (intro(1)).

What do you think?


Have a lovely day!
Alex

> Doug

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

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

Re: syntax of options in man1

[G. Branden Robinson]

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

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

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

Re: syntax of options in man1

[Alejandro Colomar]

[-- 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 --]

Re: syntax of options in man1

[G. Branden Robinson]

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

Hi Alex,

At 2026-07-16T18:20:30+0200, Alejandro Colomar wrote:
> On 2026-07-16T10:55:44-0500, G. Branden Robinson wrote:
> > 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.
[...]
> >      --lines=[+]num
> >      -n [+]num
> >             Print  the  last  num lines instead.  Prefixing num with
> >             “+” prints all lines from num forward.
> 
> 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.

The reason coreutils's man pages look this way is because they prefer to
maintain much or all traditional man page information in each command's
help message ("tail --help")[1] and then generate a man page from that
using help2man(1), which fills in a man page template named "chmod.x" or
similar.

Here's the thread where I learned that fact.

https://lists.gnu.org/r/coreutils/2026-05/msg00080.html

Maybe we can make help2man(1) better.  And/or drive constructive reforms
to GNU-style help messages...

Regards,
Branden

[1] I distinguish "usage" messages from "help" messages because a
    "usage" message is what you get when you invoke a command in a
    manner it recognizes as syntactically invalid.  This is an ancient
    Unix tradition.  The usage message should be short, summarizing only
    the available invocation forms without attempting to explain them.

    A "help message" is more of a GNU thing, part of that system's
    campaign to standardize `--version` and `--help` "long options", a
    practice I regard as mostly salutary and benign.  For example, I am
    annoyed by *BSD utilities that afford no means of inquiring of their
    provenance.  There's often no way to say "identify yourself".

    What I _don't_ want, as a user, is to be blitzed with 100 lines of
    "help" when all I did was mistype a command invocation.

    In an attempt to practice what I preach, groff's usage messages--
    uniformly, I think--look like this.

    $ tbl -X
    tbl: error: unrecognized command-line option 'X'
    usage: tbl [-C] [file ...]
    usage: tbl {-v | --version}
    usage: tbl --help

    A true Unix grognard would desire _only_ the second line, but I
    think that (1) error messages should be _explicit_, and (2) _all_
    valid invocation forms should be summarized when reporting "usage",
    even if "everybody knows that all GNU commands support `--version`
    and `--help`" because (a) that's not true--historically, GNU find(1)
    didn't support it, and the GNU dynamic linker ld.so appears still
    not to--and (b) not all commands are GNU commands.

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

Re: syntax of options in man1

[Douglas McIlroy]

> I think there should be a separation between an introduction to the
> entire system (maybe this could be intro(0)), and an introduction to the
> first section of the manual (intro(1)).

I agree. In the early days, at least, there was such a section, called
"getting started". I like the idea of calling it intro(0). The very name
suggests that there are more intro(.) pages. Elegant!

Doug


On Thu, Jul 16, 2026 at 1:19 PM Douglas McIlroy
<douglas.mcilroy@dartmouth.edu> wrote:
>
> > I think there should be a separation between an introduction to the
> > entire system (maybe this could be intro(0)), and an introduction to the
> > first section of the manual (intro(1)).
>
> I agree. In the early days, at least, there was such a section, called
> "getting started". I like the idea of calling it intro(0). The very name
> suggests that there are more intro(.) pages. Elegant!
>
> Doug
>
>
>
> Doug
>
> On Thu, Jul 16, 2026 at 10:45 AM Alejandro Colomar <alx@kernel.org> wrote:
>>
>> [Added linux-man@]
>>
>> Hi Doug,
>>
>> 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.
>>
>> > I think the description belongs in intro(1).
>>
>> Agree.
>>
>> > Incidentally, the actual content of intro(1) is absurdly bloated and much
>> > of it is way off topic.
>>
>> Agree.
>>
>> I think there should be a separation between an introduction to the
>> entire system (maybe this could be intro(0)), and an introduction to the
>> first section of the manual (intro(1)).
>>
>> What do you think?
>>
>>
>> Have a lovely day!
>> Alex
>>
>> > Doug
>>
>> --
>> <https://www.alejandro-colomar.es>