Hi Branden, > Date: 2026-07-16 12:05:48-0500 > From: "G. Branden Robinson" > > 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. --