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>
Subject: Ping^1: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)
Date: Sun, 11 Dec 2022 17:40:10 +0100 [thread overview]
Message-ID: <b13137bb-8eb9-dc69-da3b-191eda8e5642@gmail.com> (raw)
In-Reply-To: <c23b1a4f-1269-55a6-53ac-abbd2cff5786@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 --]
next prev parent reply other threads:[~2022-12-11 16:40 UTC|newest]
Thread overview: 31+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <20220906191320.447t5awx3rcb5d5b@illithid>
[not found] ` <a7b8c6b3-a8e8-6ab7-6cf4-118446849a9c@gmail.com>
[not found] ` <dca0e251-7481-7f1e-4077-0ddee070a357@gmail.com>
[not found] ` <20220906204245.hzhq2s7yha6zzgrh@illithid>
[not found] ` <30e80fe0-f0ce-d6cd-ee40-28692e5a5f82@gmail.com>
[not found] ` <5c1e8620-e4ff-c79a-1d4e-11f797276726@gmail.com>
[not found] ` <20221116234049.GA1229865@if>
[not found] ` <f306a83a-306d-e3d0-5d25-bf07da3da59f@gmail.com>
2022-11-17 0:28 ` Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty) Alejandro Colomar
2022-12-11 16:40 ` Alejandro Colomar [this message]
2022-12-11 19:05 ` Ping^1: " Michael Haardt
2022-12-11 19:21 ` Alejandro Colomar
2022-12-11 21:10 ` Michael Haardt
2022-12-12 0:34 ` Douglas McIlroy
2022-12-12 11:39 ` Alejandro Colomar
2022-12-12 8:58 ` Ralph Corderoy
2022-12-12 13:19 ` G. Branden Robinson
2022-12-12 13:57 ` Andries E. Brouwer
2022-12-12 13:39 ` Colin Watson
2022-12-12 13:48 ` Alejandro Colomar
[not found] ` <1719285.QkHrqEjB74@pip>
[not found] ` <01989003-349f-fb6b-f460-89106b82bc34@gmail.com>
[not found] ` <2176657.1BCLMh4Saa@pip>
2022-12-17 11:51 ` Ping^1: " Alejandro Colomar
2022-12-17 13:19 ` [BUG] gropdf, tbl: Completely broken table (was: Ping^1: Chapters of the manual (was: Bug#1018737: ...)) Alejandro Colomar
2022-12-17 16:08 ` G. Branden Robinson
2022-12-17 21:26 ` Deri
2022-12-18 11:25 ` Alejandro Colomar
2022-12-18 5:49 ` [BUG] gropdf, tbl: Completely broken table Ralph Corderoy
2022-12-18 11:01 ` Alejandro Colomar
2022-12-18 11:46 ` [BUG] gropdf, tbl: Completely broken table (was: Ping^1: Chapters of the manual (was: Bug#1018737: ...)) Alejandro Colomar
2022-12-19 5:32 ` groff 1.23.0.rc2 status report (was: [BUG] gropdf, tbl: Completely broken table) G. Branden Robinson
2022-12-19 12:58 ` Deri
2022-12-19 16:39 ` Alejandro Colomar
2022-12-19 16:59 ` patching suffixes(7) (was: groff 1.23.0.rc2 status report) G. Branden Robinson
2022-12-19 19:10 ` Alejandro Colomar
2022-12-19 19:54 ` prehistory branch (was: patching suffixes(7) (was: groff 1.23.0.rc2 status report)) Alejandro Colomar
2022-12-19 20:05 ` Alejandro Colomar
2022-12-20 3:40 ` patching suffixes(7) (was: groff 1.23.0.rc2 status report) G. Branden Robinson
2022-12-20 10:12 ` Alejandro Colomar
2022-12-19 16:51 ` groff 1.23.0.rc2 status report (was: [BUG] gropdf, tbl: Completely broken table) G. Branden Robinson
2022-12-17 21:37 ` Ping^1: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty) Deri
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=b13137bb-8eb9-dc69-da3b-191eda8e5642@gmail.com \
--to=alx.manpages@gmail.com \
--cc=Andries.Brouwer@cwi.nl \
--cc=aeb@cwi.nl \
--cc=cjwatson@debian.org \
--cc=douglas.mcilroy@dartmouth.edu \
--cc=g.branden.robinson@gmail.com \
--cc=groff@gnu.org \
--cc=linux-man@vger.kernel.org \
--cc=michael@moria.de \
--cc=mtk.manpages@gmail.com \
--cc=schwarze@usta.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.