Rendered linux-next documentation on kernel.org

Posted Sep 25, 2022 8:06 UTC (Sun) by Wol (subscriber, #4433)
In reply to: Rendered linux-next documentation on kernel.org by neilbrown
Parent article: Rendered linux-next documentation on kernel.org

I half thought he had a point ... until I realised he was ranting about ReStructured Text.

Which is a markup language and not meant to be read by humans. It actually produces very nice, easy-to-read documentation. I know - I use it ... :-)

Cheers,
Wol

Rendered linux-next documentation on kernel.org

Posted Sep 25, 2022 9:30 UTC (Sun) by neilbrown (subscriber, #359) [Link] (1 responses)

No, milesrout does have a point. The topic isn't ReStructured Text, it is the HTML produced from that text and *specifically* the HTML that appears at https://docs.kernel.org/next/process/coding-style.html . This HTML, or the associated style sheet, does not specify a maximum width, so with a wide enough window, each sentence is on a single line no matter how long the sentence this.

That is bad.

The markup text itself (linux/Documentation/process/coding-style.rst), which wasn't the subject of the rant/bug-report. is appropriately formatted with no lines unnecessarily longer than 80 columns.

Rendered linux-next documentation on kernel.org

Posted Sep 25, 2022 14:46 UTC (Sun) by corbet (editor, #1) [Link]

The plain-text format that milesrout prefers is, of course, available via the "view source" link at the top of the page.

More to the point though; what we're seeing is an artifact of the "Read the docs" theme that was picked, kind of by default, for the kernel docs. I'm currently actively working to improve the organization of the docs (a work-in-progress rendering is out there for those who are curious), and the next step is reevaluating the theme choice. I've never been thrilled with how the docs come out when rendered in HTML; it's time to fix that up.