[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. -- Colin Watson (he/him) [cjwatson@xxxxxxxxxx]
