Re: syntax of options in man1

[Alejandro Colomar <alx@kernel.org>]

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

Hi Branden,

> Date: 2026-07-16 12:05:48-0500
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
>
> 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.

Indeed.  I'm working on getting rid of that coupling, and have
hand-written coreutils' manual pages.  I've advanced a lot already.

> 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...

No.  I'll refine the existing generated manual pages, and after that,
maintain them manually.  That'll be much better.

> 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".

I prefer asking the system to identify programs.

	alx@devuan:~$ which cat
	/usr/bin/cat
	alx@devuan:~$ which cat | xargs dpkg -S
	coreutils: /usr/bin/cat
	alx@devuan:~$ which cat | xargs dpkg -S | cut -f1 -d: | xargs dpkg -l | tail -n1
	ii  coreutils   9.10-1devuan1   amd64          GNU core utilities

When a program wasn't installed as a debian package (and thus dpkg(1)
doesn't know about it), I try to put it under /opt, in a directory that
identifies the build date and the reason to build it (the git branch).
A couple of examples:

	/opt/local/gnu/groff/20260823_master/
	/opt/local/mutt/mutt/20260906_references/

But yes, for programs not controlled by dpkg(1), it can become messy,
and thus interesting to have an "identify yourself" option.

>     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,

I might have become more grognard than the grognards, but I'd only want
the first line.  That is, the 'tbl: error: ...'.  Then it should be my
job to read the manual page, which should have this kind of information.

Indeed:

	$ MANWIDTH=64 man 1 tbl | head -n12
	tbl(1)              General Commands Manual              tbl(1)

	Name
	     tbl - prepare tables for groff documents

	Synopsis
	     tbl [-C] [file ...]

	     tbl --help

	     tbl -v
	     tbl --version

It's not like one needs to search through the manual page to find this.

>     but I
>     think that (1) error messages should be _explicit_,

Yes, but that only means line 1.  The other three lines don't help
diagnose the error.  They're about correcting it, which is a different
thing, and I'm not convinced that it's the job of the usage output.

>     and (2) _all_
>     valid invocation forms should be summarized when reporting "usage",

I think you really wanted to say that usage should not print a partial
list of valid invocation forms, and I agree with that.  But I think it
should print none, not all.  One should fire up the manual page to have
a quick look at the SYNOPSIS.  After all, that's just a few key presses
away.

>     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.

I dislike the fact that all GNU commands accept --version and --help.
That --and other flags (some from XSI)-- made echo(1) unrealiable, and
now we need to use the weirder 'printf "%s\n" $foo' in scripts.

I'm not averse to all options, but as I get older, I tend to agree more
with the BSDs, and think this growth of options wasn't good.  I can live
with it, though, and find *some* of them useful.




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

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