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

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 6743 bytes --]

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@gmail.com>
To: Colin Watson <cjwatson@debian.org>, Ingo Schwarze <schwarze@usta.de>, G. 
Branden Robinson <g.branden.robinson@gmail.com>, linux-man 
<linux-man@vger.kernel.org>, groff@gnu.org
CC: Michael Haardt <michael@moria.de>, Andries Brouwer <Andries.Brouwer@cwi.nl>, 
Michael Kerrisk <mtk.manpages@gmail.com>, Douglas McIlroy 
<douglas.mcilroy@dartmouth.edu>, Andries E. Brouwer <aeb@cwi.nl>

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

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]