Re: 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 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/>

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