Re: syntax of options in man1

[Alejandro Colomar <alx@kernel.org>]

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

Hi Branden,

> Date: 2026-09-11 23:39:10-0500
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
>
> 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.

Yup!  For now nothing weird, though.  :)

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

Yes, they are.

<https://lore.kernel.org/linux-man/aluIbrKBtAxweITC@devuan/T/>
and earlier:
<https://lore.kernel.org/linux-man/wqfzoyixsh4l3wg7tkz3c4bjejy4wlski2s5g2pwoqiy2wg3ty@lkqy5semt757/T/#u>

> Have they opined?

Yes.  You can follow those two links.  Here are some key comments:

<https://lore.kernel.org/linux-man/wqfzoyixsh4l3wg7tkz3c4bjejy4wlski2s5g2pwoqiy2wg3ty@lkqy5semt757/T/#m131081b230029607ad21c29265533b947a026b9f>
Arsen seemed okay with the idea, as long as the pages are maintained in
within coreutils, and not moved to the Linux man-pages project.

<https://lore.kernel.org/linux-man/wqfzoyixsh4l3wg7tkz3c4bjejy4wlski2s5g2pwoqiy2wg3ty@lkqy5semt757/T/#m5fd441c47cb079fcacf574e0e1adcc760e44ba44>
Pádraig also seemed happy with it.

<https://lore.kernel.org/linux-man/wqfzoyixsh4l3wg7tkz3c4bjejy4wlski2s5g2pwoqiy2wg3ty@lkqy5semt757/T/#m34d7b3ecf7fc787fbd17b76919f0d595aec409a1>
Bernhard Voelker seemed worried about keeping the up to date.

Pádraig seems to be the one that has to decide, so it looks good.

BTW, by looking at the links above, I see you were (tangentially)
involved in that discussion.

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

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

The problem with Thompson's '?' is that it doesn't say where the problem
is.  That's something essential.  Even in the simplest programs, there
are enough error conditions, that it's not easy to find which one
happened.  That would indeed justify the format of the first error line:

	tbl: error: unrecognized command-line option 'X'
	                                              ^~~ user input
	            ^~~ exact reason
	     ^~~ error, warning, information?
	^~~ program name

All of that is necessary for identifying a problem.
But lines 2..4 are not part of that diagnostic.

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

Indeed, I think many manual pages need fixing.

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

But you develop for embedded systems in non-embedded systems, right?
I expect when you're working on an embedded system, you have nearby a
non-embedded system with the documentation available.

Moreover, I expect embedded systems don't want the heavy help strings
around.  (This might be part of the reason they go for non-GNU tools.)

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

That's one I find very useful.  I even requested (successfully) that one
program adds support for it:
<https://github.com/PCRE2Project/pcre2/issues/865>

BTW, git(1) has some slightly different interpretation of '--'.  Commit
references go to the left of it, while pathnames go to the right of it.

But yes, '--' is undoubtedly useful.

> 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 guess you mean the interpretation of escape sequences such as '\n',
which varies across implementations.  Is that it?  Otherwise, would you
mind pointing me to some sources of information?

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


Cheers,
Alex


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

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