Re: syntax of options in man1

"G. Branden Robinson" <[email protected]> Thu, 16 Jul 2026 12:05:48 -0500
Newsgroups	org.kernel.vger.linux-man
Message-ID	<20260716170548.am3fg45uaudlqpl2@illithid>
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.
signature.asc (application/pgp-signature, 833 B)