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