Re: Ping^1: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[Alejandro Colomar]

Hi Michael,

On 12/11/22 20:05, Michael Haardt wrote:
> I just checked what is easily available to me: >
> v7 calls them sections in intro pages, but chapters in man(1) and man(7).
>
> Celerity Computing UNIX (looks like a BSD port) calls them sections in
> intro pages and man(7), but chapter in manv(7) (dtroff version of man(7)).
>
> SunOS 4.1.1 calls them sections everywhere.
>
> HP-UX 11.11 calls them sections everywhere.

Thanks for checking!

> Given the changes it looks like you are not the first person to note an
> inconsistency here, but I see a majority calling them sections and
> getting rid of the term chapter over time.

It seems like a regression to me.  The old term was, at least in terms of 
ambiguity, better.

Do we need to fix a decades-old regression in the manual pages?  Well, _need_ is 
a strong word for that.

> Now all of the above is commercially obsolete by now and Linux
> dominates, but I don't see a good reason to break an established term
> and instead suggest to follow the above and s/chapter/section/g.

Admittedly, it's hard to defend my proposal as _necessary_.  Especially after 
the world has lived for decades with the ambiguity of having chapters as 
sections and sections also as... sections.

I have several times had to come up with imaginative ways to disambiguate the 
term section.  Am I a corner case that has to live with that ambiguity way more 
than the average programmer?  Quite likely.

Since I'll some day (likely for 6.02, that's 2 years from now) be publishing the 
Linux man-pages as a single-volume PDF, the term chapter will regain significance.

IMO, there's undoubtedly a reason to fix the regression, and reform the old 
term.  However, the reason is not very strong, so it all depends on reaching an 
agreement with all of man-db, mandoc(1), and groff(1).  That would probably have 
the side-effect that we also have agreement with OpenBSD.  That would be a large 
subset of the relevant parties.

Cheers,

Alex

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

OpenPGP_signature
Description: OpenPGP digital signature