linux-kernel - Re: Re: Minor RST rant

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]

Message-ID: <1e60ff85-4965-92cb-e50b-8ea9ccf6788e@oracle.com>
Date:   Wed, 5 Aug 2020 16:49:50 +0200
From:   Vegard Nossum <vegard.nossum@...cle.com>
To:     peterz@...radead.org, NeilBrown <neilb@...e.de>
Cc:     Steven Rostedt <rostedt@...dmis.org>,
        Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org,
        LKML <linux-kernel@...r.kernel.org>
Subject: Re: Re: Minor RST rant

On 2020-07-29 14:44, peterz@...radead.org wrote:
> On Sat, Jul 25, 2020 at 09:46:55AM +1000, NeilBrown wrote:
> 
>>   Constant names stand out least effectively by themselves.  In
>>   kernel-doc comments they are preceded by a '%'.  Would that make the
>>   text more readable for you?  Does our doc infrastructure honour that in
>>   .rst documents?
> 
> It does not. It also still reads really weird.
> 
> And for some reason firefox chokes on the HTML file I tried it with, and
> make htmldocs takes for bloody ever.
> 
> Give me a plain text file, please. All this modern crap just doesn't
> work.
> 

FWIW, I *really* like how the extra markup renders in a browser, and I
don't think I'm the only one.

If you want to read .rst files in a terminal, I would suggest using
something like this:

$ pandoc -t plain Documentation/core-api/atomic_ops.rst | less

It looks pretty readable to me, things like lists and code are properly
indented, the only thing it's missing as far as I'm concerned is marking
headings more prominently.

The new online documentation is a great way to attract more people to
kernel development (and just spread typical kernel knowledge to
non-Linux/non-kernel programmers). The old Documentation/ was kind of
hidden away and you only really came across it by accident if you did a
treewide 'git grep'; the new online docs, on the other hand, are a
pleasure to browse and explore and frequently show up in google searches
for random kernel-related topics.

Vegard