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

[Alejandro Colomar]

Hi Colin, Ingo, and Branden,

On 11/17/22 01:06, G. Branden Robinson wrote:
>> I used temporarily the term [sub]chapter to see how it fits.
> I think the adoption of the term (sub)chapter has a potential benefit in
> that it removes a terminological collision with (sub)sections as
> subdivisions of individual man pages (man: SH, SS; mdoc: Sh, Ss).
>
> If this terminological reform is adopted, I think it should be done
> across all of (1) Linux man-pages, (2) groff, (3) mandoc, and (4)
> man-db.  If we can't speak with one voice on this then I think it's
> better not to undertake that reform at all, to avoid frustrating the
> discoverabilty of man pages.
>
> Possibly the biggest barrier to this is the mnemonic and documentation
> of the man(1) '-s' option.  In man-db man, '-C' and '-c' are both
> already in use.

That can be documented as a historical detail in the documentation of the option 
itself, which makes sense, as to avoid programmers that have heard of sections 
to try to grep section and find nothing.

>
> Probably a good idea to loop Colin Watson in on this proposal of yours,
> which is strictly speaking severable from the below.

Yes, especially since part of the discussion is in linux-man@ (I'm not sure if 
he reads it; I think not) and not in groff@ (which he reads, AFAIK).  So, I'll 
merge the 2 discussions about this by forwarding the 2 most interesting other 
emails below.

So, does it make sense to all of us to start using the term chapter for 
divisions of the man-pages single volume, so that the manual pages in Linux are 
organized from now on in chapters 1 to 9 instead of sections 1 to 9?

Cheers,

Alex


-------- Forwarded Message --------
Subject: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: 
.TH 5th field shouldn't be empty)
Date: Wed, 16 Nov 2022 23:46:13 +0100
From: Alejandro Colomar <alx.manpages@gmail.com>
To: G. Branden Robinson <g.branden.robinson@gmail.com>
CC: groff@gnu.org, Michael Haardt <michael@moria.de>, Andries Brouwer 
<Andries.Brouwer@cwi.nl>, Michael Kerrisk <mtk.manpages@gmail.com>, Douglas 
McIlroy <douglas.mcilroy@dartmouth.edu>

Hi Branden!

On 9/7/22 00:13, Alejandro Colomar wrote:
>>> I've seen sporadically references to the numbers as chapters, probably
>>> from when the manual was a proper book, but that term seems to have
>>> fallen in use.
>>
>> I don't recall seeing this.  While not my preference, I would regard it
>> as an excusable innovation in response to an unhelpful overlap in prior
>> usage.
>
> I don't remember where I've seen this.  I seem to recall it, but maybe it's 
just
> a glitch in my memory.  It would certainly simplify nomenclature.  If we come 
up
> with a good term for subsections such as 3head, I might start using the term
> colloquially.  Does subchapter sound good to you?
>


I've got good news for you.  I started writing intro(3type), after I got the 
first contribution of a new page to chapter 3type of the manual.

And while doing it, I found a place where the term 'chapter' is used.  It's very 
likely that there's where I saw it the other time.  It's in a comment in the 
intro(3) page, which seems to be there since there's git history.

The author of the page seems to be Michael Haardt; his last commit to the 
man-pages is from 2015, so I guess his email is still active.  Maybe he can 
comment.  I also CCed aeb and mtk, as they maintained the pages before me and 
may know if that term was in use at the time.


Cheers,

Alex






-------- Forwarded Message --------
Subject: Re: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: 
rst2man: .TH 5th field shouldn't be empty)
Date: Thu, 17 Nov 2022 00:47:43 +0100
From: Alejandro Colomar <alx.manpages@gmail.com>
To: Andries E. Brouwer <aeb@cwi.nl>
CC: G. Branden Robinson <g.branden.robinson@gmail.com>, groff@gnu.org, Michael 
Haardt <michael@moria.de>, Andries Brouwer <Andries.Brouwer@cwi.nl>, Michael 
Kerrisk <mtk.manpages@gmail.com>, Douglas McIlroy <douglas.mcilroy@dartmouth.edu>

Hi Andries!

On 11/17/22 00:40, Andries E. Brouwer wrote:
>
>> On 9/7/22 00:13, Alejandro Colomar wrote:
>>>>> I've seen sporadically references to the numbers as chapters, probably
>>>>> from when the manual was a proper book, but that term seems to have
>>>>> fallen in use.
>
> Unix Programmer's Manual (4.2 BSD) August, 1983
> Volume 1
> Chapter I: Commands: intro, adb, ...
> Chapter II: System calls: intro, accept, access, ...
> Chapter III: Subroutines: intro, abort, abs, ...
> Chapter IV: Special files: intro, acc, ...
> Chapter V: File formats and conventions: a.out, ...
> Chapter VI: Games: aardvark, adventure, ...
> Chapter VII: Macro packages and language conventions: intro, ascii, ...
> Chapter VIII: Maintenance commands and procedures: intro, ac, ...
>
> Seventh Edition, January, 1979
> Volume 2A
> 1 and 2: General Works
> 3 through 7: Getting Started
> 8 through 13: Document Preparation
> 14 through 18: Programming
>
> Volume 2B:
> 19 through 28: Supporting Tools and Languages
> 29 through 38: Implementation, Maintenance and Miscellaneous
> ...
>
> Volume 1 had chapters. The later volumes had numbered documents.

Thanks for the prompt reply!
'chapter' definitely makes more sense, at least considering the manual as a 
book.  Since it seems to have been in general use in the past, it's not so much 
of a breaking change to start using it now again.  So, to avoid ambiguity 
between section referring to a chapter or section referring to part of a page, 
I'll start using the term [sub]chapter consistently.

With time, I expect to replace all occurrences of section that should be chapter 
in the man-pages.

>
> Andries

Cheers,

Alex

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

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

OpenPGP_signature
Description: OpenPGP digital signature