Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Subject: Re: Re: Minor RST rant
To:     peterz@infradead.org, NeilBrown <neilb@suse.de>
Cc:     Steven Rostedt <rostedt@goodmis.org>,
        Jonathan Corbet <corbet@lwn.net>, linux-doc@vger.kernel.org,
        LKML <linux-kernel@vger.kernel.org>
References: <20200724132200.51fd2065@oasis.local.home>
 <20200724113325.44923f75@lwn.net> <20200724144234.3227b501@oasis.local.home>
 <877dusv5lc.fsf@notabene.neil.brown.name>
 <20200729124445.GB2638@hirez.programming.kicks-ass.net>
From:   Vegard Nossum <vegard.nossum@oracle.com>
Message-ID: <1e60ff85-4965-92cb-e50b-8ea9ccf6788e@oracle.com>
Date:   Wed, 5 Aug 2020 16:49:50 +0200
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.10.0
MIME-Version: 1.0
In-Reply-To: <20200729124445.GB2638@hirez.programming.kicks-ass.net>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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