Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST markup

[Daniel Vetter]

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