Re: Minor RST rant

[Steven Rostedt <rostedt@goodmis.org>]

On Tue, 28 Jul 2020 14:52:52 +0200
peterz@infradead.org wrote:

> On Fri, Jul 24, 2020 at 11:33:25AM -0600, Jonathan Corbet wrote:
> 
> > I'm not sure what to do other than to continue to push for minimal use of
> > intrusive markup.  
> 
> Perhaps make it clearer in:
> 
>   Documentation/doc-guide/

Well, it's currently in:

https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#specific-guidelines-for-the-kernel-documentation

	Please don’t go overboard with reStructuredText markup. Keep it
	simple. For the most part the documentation should be plain text
	with just enough consistency in formatting that it can be
	converted to other formats.

But perhaps we should stress that in other locations and make it more
prevalent in the documentation.

> 
> because people claim they follow that, but the result is that I get
> completely unreadable garbage from them.
> 
> Like I've written many times before, I'm starting to loathe RST, it's an
> absolute failure. I'm near the point where I'm looking to write a script
> that will silently convert any RST crap to plain text in my commit
> script.

Sometimes I do look at the html output on kernel.org, and it is nicely
organized. The future of developers will probably prefer that format
over plain text whether we like it or not, so I encourage that we
continue using RST. That said, people still need to be very careful not
to make their markup in the text files focused so much on the html
output, that they make it unreadable for the rest of us.

I think Jon has been doing a great job at having the rst files still be
readable in their raw formats, but people still get carried away.
Instead of writing scripts to rip it out, we need to continue the
conversations to educate people that some of us need these files to
remain readable as plain text.

-- Steve