Re: syntax of options in man1

Re: syntax of options in man1

[Alejandro Colomar]

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

[Added linux-man@]

Hi Doug,

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.

> I think the description belongs in intro(1).

Agree.

> Incidentally, the actual content of intro(1) is absurdly bloated and much
> of it is way off topic.

Agree.

I think there should be a separation between an introduction to the
entire system (maybe this could be intro(0)), and an introduction to the
first section of the manual (intro(1)).

What do you think?


Have a lovely day!
Alex

> Doug

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

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

Re: syntax of options in man1

[G. Branden Robinson]

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

Hi Alex,

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.

Illustration:

$ cat ATTIC/tail.man
.TH tail 1 2026-07-16 "groff test suite"
.SH Name
tail \- a porcine corkscrew
.SH Description
Print the last 10 lines of each
.I file
to standard output.
.SH Options
.TP
.BR \-\-lines= [ + ]\c
.IR num
.TQ
.BR \-n\~ [ + ]\c
.IR num
Print the last
.I num
lines instead.
.
Prefixing
.I num
with
.RB \[lq] + \[rq]
prints all lines from
.I num
forward.

Rendering:

$ nroff -rLL=72n -P -c -man ATTIC/tail.man
tail(1)                  General Commands Manual                 tail(1)

Name
     tail - a porcine corkscrew

Description
     Print the last 10 lines of each file to standard output.

Options
     --lines=[+]num
     -n [+]num
            Print  the  last  num lines instead.  Prefixing num with “+”
            prints all lines from num forward.

groff test suite               2026‐07‐16                        tail(1)

Regards,
Branden

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

Re: syntax of options in man1

[Alejandro Colomar]

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

Hi Branden,

On 2026-07-16T10:55:44-0500, G. Branden Robinson wrote:
> Hi Alex,
> 
> 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.
> 
> Illustration:
> 
> $ cat ATTIC/tail.man
> .TH tail 1 2026-07-16 "groff test suite"
> .SH Name
> tail \- a porcine corkscrew
> .SH Description
> Print the last 10 lines of each
> .I file
> to standard output.
> .SH Options
> .TP
> .BR \-\-lines= [ + ]\c
> .IR num
> .TQ
> .BR \-n\~ [ + ]\c
> .IR num
> Print the last
> .I num
> lines instead.
> .
> Prefixing
> .I num
> with
> .RB \[lq] + \[rq]
> prints all lines from
> .I num
> forward.
> 
> Rendering:
> 
> $ nroff -rLL=72n -P -c -man ATTIC/tail.man
> tail(1)                  General Commands Manual                 tail(1)
> 
> Name
>      tail - a porcine corkscrew
> 
> Description
>      Print the last 10 lines of each file to standard output.
> 
> Options
>      --lines=[+]num
>      -n [+]num
>             Print  the  last  num lines instead.  Prefixing num with “+”
>             prints all lines from num forward.
> 
> groff test suite               2026‐07‐16                        tail(1)
> 
> Regards,
> Branden

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.


Have a lovely day!
Alex

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

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

Re: syntax of options in man1

[G. Branden Robinson]

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

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.

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

Re: syntax of options in man1

[Alejandro Colomar]

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

Re: syntax of options in man1

[G. Branden Robinson]

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

Re: syntax of options in man1

[Alejandro Colomar]

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

Re: syntax of options in man1

[Douglas McIlroy]

> I think there should be a separation between an introduction to the
> entire system (maybe this could be intro(0)), and an introduction to the
> first section of the manual (intro(1)).

I agree. In the early days, at least, there was such a section, called
"getting started". I like the idea of calling it intro(0). The very name
suggests that there are more intro(.) pages. Elegant!

Doug


On Thu, Jul 16, 2026 at 1:19 PM Douglas McIlroy
<douglas.mcilroy@dartmouth.edu> wrote:
>
> > I think there should be a separation between an introduction to the
> > entire system (maybe this could be intro(0)), and an introduction to the
> > first section of the manual (intro(1)).
>
> I agree. In the early days, at least, there was such a section, called
> "getting started". I like the idea of calling it intro(0). The very name
> suggests that there are more intro(.) pages. Elegant!
>
> Doug
>
>
>
> Doug
>
> On Thu, Jul 16, 2026 at 10:45 AM Alejandro Colomar <alx@kernel.org> wrote:
>>
>> [Added linux-man@]
>>
>> Hi Doug,
>>
>> 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.
>>
>> > I think the description belongs in intro(1).
>>
>> Agree.
>>
>> > Incidentally, the actual content of intro(1) is absurdly bloated and much
>> > of it is way off topic.
>>
>> Agree.
>>
>> I think there should be a separation between an introduction to the
>> entire system (maybe this could be intro(0)), and an introduction to the
>> first section of the manual (intro(1)).
>>
>> What do you think?
>>
>>
>> Have a lovely day!
>> Alex
>>
>> > Doug
>>
>> --
>> <https://www.alejandro-colomar.es>

Re: syntax of options in man1

[Alejandro Colomar]

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

Hi Doug,

On 2026-07-16T13:19:20-0400, Douglas McIlroy wrote:
> > I think there should be a separation between an introduction to the
> > entire system (maybe this could be intro(0)), and an introduction to the
> > first section of the manual (intro(1)).
> 
> I agree. In the early days, at least, there was such a section, called
> "getting started". I like the idea of calling it intro(0). The very name
> suggests that there are more intro(.) pages. Elegant!

Thanks!  I've done the split already.

	commit 214f536963b0a108abc54b336d8ac21b4c9f1c7f
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   2026-07-17 14:05:19 +0200

	    man/man?/intro.[01]: Split part of intro(1) into a new intro(0)
	    
	    Let's keep intro(1) for introducing just the man1 section, and move the
	    more general introduction of the entire manual to a new intro(0).
	    
	    Acked-by: Douglas McIlroy <douglas.mcilroy@dartmouth.edu>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

I haven't yet documented the syntax we were talking about, though.  I'll
think about the best way to document that.

Here's how intro(1) looks like now:

	$ MANWIDTH=64 man man1/intro.1 | cat
	intro(1)            General Commands Manual            intro(1)

	NAME
	     intro - introduction to user commands

	DESCRIPTION
	     Section 1 of the manual describes user commands and tools,
	     for  example,  file manipulation tools, shells, compilers,
	     web browsers, file and image viewers and editors,  and  so
	     on.

	SEE ALSO
	     intro(0)

	Linux man‐pages (unreleased) (date)                    intro(1)


Have a lovely day!
Alex

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

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

Re: syntax of options in man1

[G. Branden Robinson]

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

Hi Alex,

At 2026-07-17T14:10:23+0200, Alejandro Colomar wrote:
> On 2026-07-16T13:19:20-0400, Douglas McIlroy wrote:
> > > I think there should be a separation between an introduction to
> > > the entire system (maybe this could be intro(0)), and an
> > > introduction to the first section of the manual (intro(1)).
> > 
> > I agree. In the early days, at least, there was such a section,
> > called "getting started". I like the idea of calling it intro(0).
> > The very name suggests that there are more intro(.) pages. Elegant!
> 
> Thanks!  I've done the split already.
> 
> 	commit 214f536963b0a108abc54b336d8ac21b4c9f1c7f
> 	Author: Alejandro Colomar <alx@kernel.org>
> 	Date:   2026-07-17 14:05:19 +0200
> 
> 	    man/man?/intro.[01]: Split part of intro(1) into a new intro(0)
> 	    
> 	    Let's keep intro(1) for introducing just the man1 section,
> 	    and move the more general introduction of the entire manual
> 	    to a new intro(0).
> 	    
> 	    Acked-by: Douglas McIlroy <douglas.mcilroy@dartmouth.edu>
> 	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

I wonder if James K. Lowden's proposed "man-intro" document might be
worth a second look at this time.

https://lists.gnu.org/archive/html/groff/2021-05/msg00032.html

Regards,
Branden

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

Re: syntax of options in man1

[Alejandro Colomar]

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

Hi Branden,

On 2026-07-17T12:15:09-0500, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2026-07-17T14:10:23+0200, Alejandro Colomar wrote:
> > On 2026-07-16T13:19:20-0400, Douglas McIlroy wrote:
> > > > I think there should be a separation between an introduction to
> > > > the entire system (maybe this could be intro(0)), and an
> > > > introduction to the first section of the manual (intro(1)).
> > > 
> > > I agree. In the early days, at least, there was such a section,
> > > called "getting started". I like the idea of calling it intro(0).
> > > The very name suggests that there are more intro(.) pages. Elegant!
> > 
> > Thanks!  I've done the split already.
> > 
> > 	commit 214f536963b0a108abc54b336d8ac21b4c9f1c7f
> > 	Author: Alejandro Colomar <alx@kernel.org>
> > 	Date:   2026-07-17 14:05:19 +0200
> > 
> > 	    man/man?/intro.[01]: Split part of intro(1) into a new intro(0)
> > 	    
> > 	    Let's keep intro(1) for introducing just the man1 section,
> > 	    and move the more general introduction of the entire manual
> > 	    to a new intro(0).
> > 	    
> > 	    Acked-by: Douglas McIlroy <douglas.mcilroy@dartmouth.edu>
> > 	    Signed-off-by: Alejandro Colomar <alx@kernel.org>
> 
> I wonder if James K. Lowden's proposed "man-intro" document might be
> worth a second look at this time.

Would you mind bouncing the email to me?  (If you have it.)

> https://lists.gnu.org/archive/html/groff/2021-05/msg00032.html

The thing is, I hate big-bang replacements.  I'd like to see small
patches that can be reviewed on their own.  If you would like to send
the most valuable pieces of it patch by patch, I'd like to have a look
at them.

Considering a full replacement of a manual page in a single commit is
something I don't enjoy.

Also, deciding on my own is boring and prone to mistakes.  I'd prefer
a long discussion where we iterate over versions of patches.


Have a lovely day!
Alex

> 
> Regards,
> Branden



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

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

Re: syntax of options in man1

[James K. Lowden]

On Fri, 17 Jul 2026 12:15:09 -0500
"G. Branden Robinson" <g.branden.robinson@gmail.com> wrote:

> I wonder if James K. Lowden's proposed "man-intro" document might be
> worth a second look at this time.

Thanks for the vote of confidence, Branden.  :-)  

It so happens I was musing not long ago what might ever happen to that
page. In my memory, I reorganized it against my better judgement, and
then gave up when I was asked to make mechanical changes (such as but
not only starting every sentence on a new line).  

If it were up to me, we'd return to my original submission and use it.
From my pov it's better than nothing and the user suffers from our
inability to reach consensus on what is an acceptable starting point.
It would not be, as you well know, the only part of the documentation
that could stand improvement.  

I would only observe that lo this five years later the name of the
file, man-intro.1, places it in the wrong section.  I suppose
man-intro.7 is more appropriate.  

I am unable to participate in groff these days, my spirit having been
hijacked by gcc.  But you will perhaps be amused that your camel now
has its nose in their tent.  I showed GCC how to render mdoc pages as
PDF and HTML, and that became part of the distribution.  One of these
days I will follow through on my threat to use Ingo's mandoc library to
generate so-called railroad diagrams for COBOL syntax.  

Kind regards, 

--jkl