From: Michael Haardt <michael@moria.de>
To: Alejandro Colomar <alx.manpages@gmail.com>
Cc: 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, 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: Re: 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 22:10:03 +0100 [thread overview]
Message-ID: <E1p4TaF-0002j0-7s@moria.de> (raw)
In-Reply-To: <59fb70b0-f4b7-d257-117e-767135fa39c3@gmail.com>
> Admittedly, it's hard to defend my proposal as _necessary_. Especially after
> the world has lived for decades with the ambiguity of having chapters as
> sections and sections also as... sections.
Well, one are the volume sections and the other manpage sections. :)
Originally, Unix documentation was split into volumes, each taking many
heavy books or binders and a site typically had a big shelf or closet
holding those. In addition there was a documentation overview and a giant
permuted index.
One volume was the reference documentation, that's what we know as
manual pages, and those were also available online. There were no
chapters really. After yacc(1) came intro(2) and then all pages from (2)
in alphabetical order. No separation page or title and the intro pages
looked like all others. Hence .TH, so you could quickly browse through
the pages up to the top line of the page you were looking for. The
binders were labelled with volume and section on their back to speed up
finding something.
The Oxford dictionary defines chapter as "a separate section of a book,
usually with a number or title". Given the lack of separation I see why
they were just called sections, not chapters, and why the term chapter
was removed where it was used in the old days. No ambiguity or regression
there.
The other volumes were a collection of papers on various subsystems and
topics, often written using ms(7). Each Unix distribution extended them
to their desire. Those were not online, because they consumed more space
than the reference manual volume, so they are much less known.
> IMO, there's undoubtedly a reason to fix the regression, and reform the old
> term. However, the reason is not very strong, so it all depends on reaching an
> agreement with all of man-db, mandoc(1), and groff(1). That would probably have
> the side-effect that we also have agreement with OpenBSD. That would be a large
> subset of the relevant parties.
If those agree, I won't object. That's not an area where I argue about
semantics of single words.
In addition, you could separate the sections into true chapters by making
sure the intro pages can be recognized as introduction, and provide an
chapter overview that links to all intro pages. Back then new users got
to know them from the printed versions, but that is decades ago.
Michael
next prev parent reply other threads:[~2022-12-11 21:10 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 ` Ping^1: " Alejandro Colomar
2022-12-11 19:05 ` Michael Haardt
2022-12-11 19:21 ` Alejandro Colomar
2022-12-11 21:10 ` Michael Haardt [this message]
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=E1p4TaF-0002j0-7s@moria.de \
--to=michael@moria.de \
--cc=Andries.Brouwer@cwi.nl \
--cc=aeb@cwi.nl \
--cc=alx.manpages@gmail.com \
--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=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.