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

[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