Re: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty)

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



[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]



[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux