Re: Re: Minor RST rant

[Vegard Nossum <vegard.nossum@oracle.com>]

On 2020-07-29 14:44, peterz@infradead.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