Re: syntax of options in man1

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

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

Hi Alex,

At 2026-09-11T20:43:12+0200, Alejandro Colomar wrote:
> > Date: 2026-07-16 12:05:48-0500
> > From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> > At 2026-07-16T18:20:30+0200, Alejandro Colomar wrote:
> > > 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.

Cool!  Please apprise the groff list of any questions or difficulties
with man(7) markup.

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

Are the coreutils maintainers aware of your plan?  Have they opined?

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

As you anticipate below, that works great until you encounter a system,
possibly an embedded one, where a package manager isn't present in the
environment.  Think of tools like Buildroot.[1]

Historically, as in decades ago, system builders used to mandate SCCS or
RCS revision control of source files, and the population of static
strings in those source files to store RCS "ident"s or SCCS "what"s.
I'm using the names of the tools that scanned for these strings.  You
could then run such a tool on the compiled executable--on _any_
host--and get a dump of the configuration of source files that it was
translated from.

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

That's one alternative solution.  Another, arguably even better though
it requires more overhead in terms of build system management, is to
generate a UUID for a specific compilation process.  That enables
traceability to a specific build host and other configuration details,
like compiler flags.

The more sophisticated we get with reproducible builds and producing
"software bills of materials", the easier it becomes to earnestly and
fully comply with requirements of copyleft licenses like the GNU GPL.

It follows that we must pump money into rewriting everything GPLed in
Rust and slap the Apache License on the result.  If nobody can prove
that your SWBOM is a lie, you have no liability for it.

Good engineering practices are a cost center.  Cut them, and increase
returns to shareholders.  It's your moral duty.[2]

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

Yes.  That's why I always want one in the tools I use.

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

I've found it useful to get the terse reminder of invocation methods,
though I concede that's not as terse as not offering the reminder at
all.

Consider the Thompson limit of the grognard principle.

$ tbl -X
?
$ echo $?
0

The conventions of issuing error messages _to the standard error
stream_, using a non-zero exit status on failure, and _identifying
oneself in diagnostic messages_, were all practices recognized by
McIlroy in the late 1980s as salutary--but were implemented half-
heartedly even at the Bell Labs CSRC where Unix was born.[3]

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

Indeed not.  But the information is easy to find because I made sure
that it would be, by trying to maintain a strong discipline of keeping a
program's usage messages in sync with the man page, and of course with
its actual argument processing behavior.

If you audit the tools on your system in these respects, I predict
you'll swiftly find such discipline lacking.

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

Compiler warnings offer unsolicited help now, too, and LLVM's embrace of
such chatty diagnostic output helped it make inroads against GCC
starting 20 years ago.  ("Not copyleft" and "not from GNU" did most of
the rest.  The number of people nattering about LLVM's purportedly
superior--or at least more modular--architecture exceeded the number
actually employing that architecture to any advantage by several orders
of magnitude.)

Why should people who _aren't_ compiling code get less assistance?

All that said, if the community develops a convention, say an
environment variable indicating desires suppression of expansive usage
messages--call it `TERSE_USAGE` maybe--I'll offer no resistance beyond
saying that I am _not_ offering groff as the first place to pilot it. :)

> I think you really wanted to say that usage should not print a partial
> list of valid invocation forms, and I agree with that.

Yes.

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

Think embedded again.  Some target environments rip out the man pages.

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

What about `--` to mark the end of arguments intended for interpretation
as options?

Back when I was learning Unix, the problem of eliminating a file called
`-rf` in one's home directory was considered a daunting challenge.  One
couldn't be sure how reliable shell quoting was, if one even understood
the concept.  This is also back when people did scary stuff in their
.profile like:

PATH=.:$PATH

...and the equivalent for (t)csh.

Before long I discovered the "magic" of simply prefixing troublesome
file names in the current working directory with "./", and it's remained
a typing habit even in many situations where I don't strictly need it.

> 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 urge you to research this issue more deeply.  We need printf(1) for
more reasons than that.

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

BSD "philosophy" seems to me to be largely an exercise in nostalgia.
That's not necessarily a bad thing, but it is a _vague_ thing.  I agree
with some of the principles of the "suckless" site and disagree with
others, but I credit them for actually _articulating_ the principles
they claim to have sifted from the Unix tradition.  Theirs is not the
only valid perspective, but it's much more satisfying to engage with
someone who has critically evaluated their own perspective and built a
defense of it than with someone who has identified a group of cool kids
they want to emulate, and consequently struggle to articulate defensible
reasons for their practices.

And I don't even knock nostalgia: I'm much too old to dare that.
Sometimes, good things come from it.  But you have to decide upon and
articulate a mission,[4] and see who joins you.

1.  Stallman's devise of copyleft was an explicit effort to recreate the
    ethics of the 1970s MIT AI Lab.  See Levy's _Hackers_.[5]

2.  The ongoing 2.11BSD project is an exercise in seeing how much of a
    32-bit BSD Unix (4.3/4.4-era) can be slimmed down and crammed into
    a 16-bit, at most 4MB PDP-11/70 configuration.  I admire that.[6]
    These days we consider such a device a microcontroller.

Regards,
Branden

[1] https://buildroot.org/
[2] https://www.sbs.ox.ac.uk/oxford-answers/friedman-doctrine-50-years-why-its-time-change
[3] https://www.cs.dartmouth.edu/~doug/reader.pdf

[4] Two of the major surviving BSDs have a perceptible and
    comprehensible mission: NetBSD's is "run on everything" and
    OpenBSD's is "be security-invulnerable".  These are defensible
    goals, even if they're not 100% achievable.

    By contrast, it's not clear to me what FreeBSD's mission is, beyond
    "pretend BSDI didn't fall apart due solely to a three-headed
    USL/GNU/Finnish conspiracy".  Or maybe it's simply "groom engineers
    for consumption by Apple".  If that's the case, FreeBSD may have
    succeeded best of all.

[5] https://www.stevenlevy.com/hackers-heroes-of-the-computer-revolution
[6] https://www.tuhs.org/Archive/Distributions/UCB/2BSD/2.11BSD/Patches/

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