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