On Tue, 23 Apr 2019 23:38:16 +0200 Borislav Petkov <bp@xxxxxxxxx> 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 -- dm-devel mailing list dm-devel@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/dm-devel
