Re: [RFC] doc headings sweep

[Jonathan Corbet <corbet@lwn.net>]

Vegard Nossum <vegard.nossum@oracle.com> writes:

> I have a (very long and ugly) script that can fix these up to a
> consistent style, the attached patch is the result of running it on
> Documentation/process/ only.
>
> I've done builds before and after the patch and diffed the resulting
> HTML files, they show no difference. (HOWEVER, you do need a 'make
> cleandocs' in between, as it seems doing 'make htmldocs; find
> Documentation | xargs touch; make htmldocs' is going to change the
> generated HTML for the sidebar -- another issue to look into at some
> point, I guess; maybe it's specific to the Sphinx version I used here,
> 4.3.2.)
>
> The script will leave alone any file that it doesn't quite understand
> (e.g. for a lot of the translations there are way more underlines than
> characters in the heading and it doesn't match up with the byte count
> either).
>
> Anyway, the question is: Is this worth doing in the first place, or is
> it just churn? I assume just after -rc1 would be the ideal time to
> submit these to avoid conflicts.

So I must confess that I'm not convinced; it seems not that far removed
from the sorts of white-space fixes that drive developers nuts
elsewhere.

"Avoid conflicts" isn't going to happen.  By its nature, docs-next tends
to generate a lot of conflicts against other trees as it is -
*everybody* puts their fingers into Documentation/.  This would surely
create more of them, all of which I'd then get to explain to Linus.  I
think it might be better to encourage people to fix things up gradually
when they're in the files anyway.

But maybe others disagree?

Thanks,

jon