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

[Douglas McIlroy]

A nice property of "section" is that it's recursive--applies to any
level of a hierarchy--so you don't have to struggle to keep
level-specific terminology straight.

Doug

On Sun, Dec 11, 2022 at 2:21 PM Alejandro Colomar
<alx.manpages@gmail.com> wrote:
>
> 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/>