From: Alejandro Colomar <alx.manpages@gmail.com>
To: Ingo Schwarze <schwarze@usta.de>,
"G. Branden Robinson" <g.branden.robinson@gmail.com>,
linux-man <linux-man@vger.kernel.org>,
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>,
"Andries E. Brouwer" <aeb@cwi.nl>
Subject: Re: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)
Date: Mon, 12 Dec 2022 14:48:33 +0100 [thread overview]
Message-ID: <2c618bc2-2caf-efff-c2d8-f680eb172bb8@gmail.com> (raw)
In-Reply-To: <Y5cvIUuBIx2RptPP@riva.ucam.org>
[-- Attachment #1.1: Type: text/plain, Size: 3077 bytes --]
Hi Colin!
On 12/12/22 14:39, Colin Watson wrote:
> [Sorry for the delay; a succession of business travel, holidays, and
> Covid have together eaten up much of my time recently.]
>
> On Thu, Nov 17, 2022 at 01:28:12AM +0100, Alejandro Colomar wrote:
>> On 11/17/22 01:06, G. Branden Robinson wrote:
>>> 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.
>
> I'm not subscribed to linux-man@, and while I am technically subscribed
> to groff@ I read it very infrequently these days, so thanks for
> explicitly copying me in.
>
>> 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?
>
> I find myself relatively agnostic on this whole discussion. There are
> good reasons for reform, and also some good reasons to wonder whether
> the grass will in fact be greener on the other side (given the necessity
> to keep many bits of "section" terminology around in things like
> man(1)'s option handling and the man-db configuration file more or less
> indefinitely).
>
> I'm not going to veto it, but I also have no great enthusiasm for the
> upheaval. If the community consensus is for it to happen, then I'd ask
> that somebody who is enthusiastic about it put the work into the various
> necessary updates to man-db's code and documentation and send an
> appropriate merge request.
I can do that. Don't expect it to be perfect, but I can iterate on it upon your
requests.
Branden's seems to have predisposition for the change, like me. But like you we
have some doubts. Let's see what Ingo has to say.
Thanks!
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-12 13:49 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
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 [this message]
[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=2c618bc2-2caf-efff-c2d8-f680eb172bb8@gmail.com \
--to=alx.manpages@gmail.com \
--cc=Andries.Brouwer@cwi.nl \
--cc=aeb@cwi.nl \
--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.