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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux