On Mon, Nov 28, 2016 at 08:26:26AM +0100, Peter Zijlstra wrote: > On Sun, Nov 27, 2016 at 04:59:14PM -0700, Jonathan Corbet wrote: > > On Fri, 25 Nov 2016 22:58:14 +0100 > > Peter Zijlstra <peterz@xxxxxxxxxxxxx> wrote: > > > > > Not a fan of this. The atomic_ops.txt file needs a lot of love, and I > > > wouldn't want to edit a .rst file. > > > > > > Then again, I probably won't actually get around to fixing this document > > > any time soon either. > > > > > > But if and when I would get around to it, I'll have to change it back to > > > a regular .txt file. I definitely don't want to make rst/sphinx a pain for anyone, so very much welcome your feedback. > > Peter, could you please describe what the trouble with RST is? > > Mostly that its not txt. I don't know what RST is, and I frankly don't > care. For me changing this is 'make work', and I really don't need that. > > Changing this away from txt will simply make want to write documentation > less, because it means having to figure out wtf RST is first, which > means I'll simply won't do it. I don't think you have to care at all. We've converted thousands of pages of entirely free-form .txt to .rst, and sphinx/rst happily parsed it all. There's the occasional warning, and 0day will report them. But if you don't want to care, then you can choose not to care at all here. The checkpatch/warning police is already picking up on these, so they will get fixed. And if that's too much, then you can also ignore those. > > Most of > > the files in Documentation/ are already almost in RST format; should we > > change them to something else? :) > > Why change them? What was wrong with txt to begin with? In my opinion good docs matter, and one of the key things is to be able to cross reference stuff. And I'd really like to be able to cross-reference to all the core kernel stuff (locks, atomics, workers, timers, all of these) from my driver/subsystem docs. This isn't something you or I ever really will use, but in my experience it is rather useful for people newly reading into a subsystem. And getting new folks on board (at least in subsystems like DRM where we're chronically understaffed for everything) matters. Given that I hope the change in file-ending from .txt to .rst is ok with you, and it won't stop you from updating the docs. If not that'd be bad, since imo anything that makes it harder to type good docs is bad. Another concern some core kernel folks raised is that the .rst markup was too heavy-handed, and makes the text much harder to read. Christoph called it "cat spew". That can be fixed with a much lighter-handed conversion (and 2nd patch iteration was acceptable for Christoph). In this patch the biggest part seems to be the indent shift on the code snippets, and it'd be good to keep those to tell sphinx to fixed-width layout them. But a lot of the other stuff really doesn't need to be if it bothers you. Thanks, Daniel -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
