linux-kernel - 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: <20200728112828.459307a5@oasis.local.home>
Date:   Tue, 28 Jul 2020 11:28:28 -0400
From:   Steven Rostedt <rostedt@...dmis.org>
To:     peterz@...radead.org
Cc:     Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org,
        LKML <linux-kernel@...r.kernel.org>, Neil Brown <neilb@...e.de>
Subject: Re: Minor RST rant

On Tue, 28 Jul 2020 14:52:52 +0200
peterz@...radead.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