Hi! This is a gentle ping about my terminological reforms about manual page chapters. 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 01:28:12 +0100 From: Alejandro Colomar <alx.manpages@xxxxxxxxx>To: Colin Watson <cjwatson@xxxxxxxxxx>, Ingo Schwarze <schwarze@xxxxxxx>, G. Branden Robinson <g.branden.robinson@xxxxxxxxx>, linux-man <linux-man@xxxxxxxxxxxxxxx>, groff@xxxxxxx CC: Michael Haardt <michael@xxxxxxxx>, Andries Brouwer <Andries.Brouwer@xxxxxx>, Michael Kerrisk <mtk.manpages@xxxxxxxxx>, Douglas McIlroy <douglas.mcilroy@xxxxxxxxxxxxx>, Andries E. Brouwer <aeb@xxxxxx>
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@xxxxxxxxx> To: G. Branden Robinson <g.branden.robinson@xxxxxxxxx>CC: groff@xxxxxxx, Michael Haardt <michael@xxxxxxxx>, Andries Brouwer <Andries.Brouwer@xxxxxx>, Michael Kerrisk <mtk.manpages@xxxxxxxxx>, Douglas McIlroy <douglas.mcilroy@xxxxxxxxxxxxx>
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@xxxxxxxxx> To: Andries E. Brouwer <aeb@xxxxxx>CC: G. Branden Robinson <g.branden.robinson@xxxxxxxxx>, groff@xxxxxxx, Michael Haardt <michael@xxxxxxxx>, Andries Brouwer <Andries.Brouwer@xxxxxx>, Michael Kerrisk <mtk.manpages@xxxxxxxxx>, Douglas McIlroy <douglas.mcilroy@xxxxxxxxxxxxx>
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/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
