Re: New PARAMETERS section in manual pages (was: [PATCH v2] src/bin/mansectf, man/man1/mansectf.1: Add program and manual page)

[Alejandro Colomar <alx@kernel.org>]

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

Hi Branden,

On 2026-01-29T14:24:57-0600, G. Branden Robinson wrote:

[...]
> > I've been wanting to add this section for some time.  It would make
> > the pages more schematic, which I think improves readability.
> 
> I'd like to propose making it a _subsection_ instead.  Subsections are
> under-used in man pages, and for no good reason I can see (apart from
> not being documented in the man(7) page of the Seventh Edition Unix
> manual that introduced the package to the world).

I think I prefer a section.  PARAMETERS would be closer to OPTIONS than
DESCRIPTION.

> > What I wonder is wether it should go before or after the description.
> 
> By making it a subsection, it can go _within_ the description, as early
> or late as makes sense.  In many cases, if you need a "Parameters"
> subsection at all, it should appear as soon as you need it--but no
> sooner.

I think I'll leave it for below the DESCRIPTION.  A problem with a
subsection is that it would force using subsections below it, if we want
to continue with the description.

We might change later.

> I personally feel that at least one paragraph of description orienting
> the user to the overall purpose of the page is a superior approach to
> presenting parameteric details before the context within which those
> details apply has been presented to the reader.

Agree.

> That is also why, in section 1 and 8 (and, strictly, 6) man pages, I
> prefer to put an "Options" section well down the page, after a full
> "Description", because often, an option's description can only make
> sense once the capabilities of the command have been explored.[1]

Agree.

> I think it would also be fine to either


> (a) not ape FreeBSD in this respect or

Sorry; non-native speaker here.  What does ape mean as a verb?

> (b) restrict this "Parameters" subsection to section 2 man
> pages, as the Linux system call interface is indeed huge and complex.
> The Standard C library, by contrast, has remained fairly manageable,
> with bsearch() the fattest cardinal chirping in section 3.

I agree to start with chapter 2.  I can't promise not continuing later
with chapter 3, but I agree it has significantly less priority.

> ...as far as I know.  You are well placed to know better.

:-)

> Regards,
> Branden
> 
> [1] I acknowledge two schools of thought that disagree with me (usually
>     stridently) and with each other on this point.
> 
>     A.  Ingo Schwarze thinks man pages shouldn't have "Options" sections
>         at all.  I suppose this viewpoint descends from the Rob Pike
>         "anti-cat-v" school of thought, which holds roughly that because
>         a Unix command should do one thing and do it well (a principle
>         articulated by McIlroy), then if you need a command to do a
>         different thing, you introduce a new command.  (While this
>         principle risks exhausting the 676-element set of ideal Thompson
>         Unix command names juxtaposing 2 lowercase letters, McIlroy
>         reports that Thompson's own usage patterns--not to say needs--
>         were satisfied by only about 100 commands.[2])

I tend to be on this side, but not too radically.  Some options are
necessary.

>     B.  A generally anonymous horde of man page users feel that the
>         "Options" section should start on the first screenful of text
>         they see in their pager, no matter what the dimensions of their
>         terminal window.  (Presumably, pressing the space bar demands
>         too much of the impatient hacker.)

... or the slash.

>	  This requirement can be
>         difficult to satisfy, and tends to promote the creation of a
>         subsequent "Usage" section, which is simply a continuation of
>         "Description" split asunder to accommodate the horde.
> 
> [2] "As the [Unix] system grew to encompass facilities beyond any
>     individual's ken*, the task of organizing an ever-growing manual for
>     printing became increasingly daunting.  ... * Ken's ken was probably
>     the last to saturate.  At the time of v5 [1974], shell accounting
>     once revealed that Thompson had used 102 distinctly named programs
>     in the course of a week.  Nobody else came close."
> 
>     https://www.cs.dartmouth.edu/~doug/reader.pdf

:D


Have a lovely night!
Alex

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

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