[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.
OpenPGP_signature