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

[Jani Nikula]

On Mon, 28 Nov 2016, Peter Zijlstra <peterz@xxxxxxxxxxxxx> wrote:
> On Mon, Nov 28, 2016 at 09:44:42AM +0100, Daniel Vetter wrote:
>
>> > 
>> > 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.
>
> Well, good docs begin with useful content; and many docs lack that.
> Fixing that would be a much more useful thing to do.
>
> In any case, I've never had any problems with typing things like: "go
> read: Documentation/file.txt for more information.".

Using rst we can produce decent HTML pages, and make them available at
[1], in context. You don't have to read that, but it will be a lot more
discoverable for other people, another important quality of good
documentation. And perhaps you don't have to tell people to go read it
so much.

[1] https://www.kernel.org/doc/html/latest/

> Very much agreed, once a file is no longer readable with less or the
> text editor of your choice, it as good doesn't exist at all. So I very
> much worry about RST even supporting such heavy markup that the end
> result is unreadable.

The goal is to have the best of both worlds, keeping it pretty much
plain text, but adding just enough consistency in formatting that you
can generate other formats out of it. We don't have to and we shouldn't
go overboard with the markup.

Arguably you could call rst a "coding style" for plain text. We have
pretty uniform C code, I don't think it's unreasonable to have a little
bit of consistency in the plain text. And really, it's not much we're
asking.


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center