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

[Alejandro Colomar]

Hi Ralph,

On 11/17/22 12:58, Ralph Corderoy wrote:
> Hi Alejandro,
>
> > 'chapter' definitely makes more sense, at least considering the manual
> > as a book.  Since it seems to have been in general use in the past,
> > it's not so much of a breaking change to start using it now again.
>
> Yes it is a breaking.

And changing from chapter to section was also breaking.  And that was really a 
terrible idea, not only because it change backwards-incompatible, but because it 
also increased inconsistency and ambiguity.  Please also complain to those minds 
behind that change, whoever they were, and hopefully more strongly, since their 
change was actually braindamaged.

>  This is a terrible idea.

It also seemed a terrible idea to change the precedence of the & operator once 
the && operator was added to C [1].  Now we have the consequences.

[1]:  <https://www.lysator.liu.se/c/dmr-on-or.html>

>  Colin Watson's man(1)
> has -s to specify a section and talks of sections throughout.

Yes, that worries me, and all websites that would get outdated by a simple 
action too.  I'm thinking about the possible consequences, both bad and good, 
and of course there are plenty of both.  There's always a balance.

> Plan 9's man page refers to section.

Plan 9.  It's interesting that a new operating system that attempts to copy all 
good things from Unix but fix the bad ones with backwards-incompatible changes 
is referred to with the intention of asking me to keep the old broken way.

> Working with Unix from the ’80s, including many different commercial
> versions, and reading dozens of published Unix books which pre-date the
> web, I have only seen section be used, not chapter.

Me and aeb have shown you that chapter has been used in the past at least 
several times,.  Maybe you should check those old sacred sources, quoted by 
Andries, and see by yourself.  :)

> > With time, I expect to replace all occurrences of section that should
> > be chapter in the man-pages.
>
> There are projects which need custodians rather than radicals.

I hope you don't really believe me to be a radical.  Yes, I've done many changes 
to the man-pages project, but I've held back myself in many more cases.  I'd 
like to think that my work in the project has been quite positive, and suggest 
anyone else to either (a) fork and prove they can do better, (b) be content with 
the changes and hopefully say so (it's very nice to read every now and then some 
random people thanking me for doing this for free and even more when they point 
to specific changes they liked), (c) propose better alternatives.  A combination 
of some or all of them would also make sense, if you don't like some changes but 
do like others.  But that last line feels a bit offending to me.

And I bet that you can ask the previous maintainers about my changes, and you 
won't get an answer like that at all; especially from Michael.

Cheers,

Alex

--
<http://www.alejandro-colomar.es/>

OpenPGP_signature
Description: OpenPGP digital signature