On Tue, 23 Apr 2019 23:38:16 +0200 Borislav Petkov bp@alien8.de 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