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

[Michael Haardt]

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

Well, one are the volume sections and the other manpage sections. :)

Originally, Unix documentation was split into volumes, each taking many
heavy books or binders and a site typically had a big shelf or closet
holding those. In addition there was a documentation overview and a giant
permuted index.

One volume was the reference documentation, that's what we know as
manual pages, and those were also available online. There were no
chapters really. After yacc(1) came intro(2) and then all pages from (2)
in alphabetical order. No separation page or title and the intro pages
looked like all others. Hence .TH, so you could quickly browse through
the pages up to the top line of the page you were looking for. The
binders were labelled with volume and section on their back to speed up
finding something.

The Oxford dictionary defines chapter as "a separate section of a book,
usually with a number or title". Given the lack of separation I see why
they were just called sections, not chapters, and why the term chapter
was removed where it was used in the old days. No ambiguity or regression
there.

The other volumes were a collection of papers on various subsystems and
topics, often written using ms(7). Each Unix distribution extended them
to their desire. Those were not online, because they consumed more space
than the reference manual volume, so they are much less known.

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

If those agree, I won't object. That's not an area where I argue about
semantics of single words.

In addition, you could separate the sections into true chapters by making
sure the intro pages can be recognized as introduction, and provide an
chapter overview that links to all intro pages. Back then new users got
to know them from the printed versions, but that is decades ago.

Michael