linux-kernel - Re: [PATCH v3 2/4] Documentation/atomic

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Mon, 28 Nov 2016 13:16:45 +0200
From:   Jani Nikula <jani.nikula@...ux.intel.com>
To:     Peter Zijlstra <peterz@...radead.org>,
        Jonathan Corbet <corbet@....net>,
        Silvio Fricke <silvio.fricke@...il.com>,
        linux-doc@...r.kernel.org, Ming Lei <ming.lei@...onical.com>,
        "Luis R . Rodriguez" <mcgrof@...nel.org>,
        Mauro Carvalho Chehab <mchehab@...nel.org>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST markup

On Mon, 28 Nov 2016, Peter Zijlstra <peterz@...radead.org> 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