Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

Jonathan Corbet
2019-04-23T22:06:40Z

On Tue, 23 Apr 2019 23:38:16 +0200
Borislav Petkov <bp-Gina5bIWoIWzQB+pC5nmwQ@public.gmane.org> wrote:

> But exactly this - *having* to do rst formatting would mean a lot of
> getting used to and people writing something which is not necessarily
> correct rst and someone else fixing up after them.

Remember that most of our docs are 99% RST even though they were written
by people who had never even heard of RST. I really don't think it's a
big deal - a far smaller cognitive load than trying to keep up with any
given subsystem's variable-declaration-ordering rules, for example :)

> Another pain point is changing the file paths. Without cscope I would've
> been cursing each time I'm looking for kernel-parameters.txt, for
> example. First of all, it is in Documentation/admin-guide/ now and then
> there's Documentation/admin-guide/kernel-parameters.rst too.

Moving of files has nothing to do with RST, of course. That you can
blame entirely on me trying to bring some order to Documentation/. As a
predecessor of mine once put it (https://lkml.org/lkml/2007/7/3/422):

Documentation/* is a gigantic mess, currently organized based on
where random passers-by put things down last.

When other parts of the kernel tree turn out to be organized in
less-than-useful ways, we move things around. I'm trying to do the same
in Documentation/, with an attempt to be sympathetic toward our readers,
sort things by intended audience, and create (someday) a coherent whole.
I agree that moving docs is a short-term annoyance, but I'm hoping that
it brings a long-term benefit.

> So* I'd suggest having as less markup in those files as possible and if
> it is needed, automate adding the needed markup, as Jon suggested.

Minimal markup is the policy (it's even documented :). Automating stuff
that can be automated is an area that has definitely not received
enough attention; hopefully some things can be done there in the very
near future.

Thanks,

jon