Rendered linux-next documentation on kernel.org

Posted Sep 25, 2022 3:32 UTC (Sun) by milesrout (subscriber, #126894)
Parent article: Rendered linux-next documentation on kernel.org

It's quite amazing how much worse this documentation is to read than the old plain text documentation. Compare the new CODING-STYLE document to the old one:

https://docs.kernel.org/next/process/coding-style.html

This presentation has no limitation on the width of the document. As a result, it's nigh-unreadable. It's been known for _hundreds of years_ that documents are much easier to read when they have relatively narrow text width. Note for example that the text on this website has a maximum width, because it's written to be read. The old plain text document was wrapped properly. Ironically, the coding style document itself says:

>Coding style is all about readability and maintainability using commonly available tools.

>The preferred limit on the length of a single line is 80 columns.

>Statements longer than 80 columns should be broken into sensible chunks, unless exceeding 80 columns significantly increases readability and does not hide information.

And yet while this is still applied to code, and it was applied to the old documentation, whoever is responsible for converting the documentation from plain text (that was readable and maintainable everywhere using any tool) into "restructured text" did not pay attention to this.

Rendered linux-next documentation on kernel.org

Posted Sep 25, 2022 6:37 UTC (Sun) by neilbrown (subscriber, #359) [Link] (3 responses)

What this meant to be a bug report, or a rant?
As a bug report, it would be quite useful - thanks. As a rant .... less so.

Rendered linux-next documentation on kernel.org

Posted Sep 25, 2022 8:06 UTC (Sun) by Wol (subscriber, #4433) [Link] (2 responses)

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.

Rendered linux-next documentation on kernel.org

Posted Sep 25, 2022 14:54 UTC (Sun) by flussence (guest, #85566) [Link] (1 responses)

Is the complaint here that when you make your browser window unreasonably wide, it tries to use that space instead of filling half of it with blank white padding?

Rendered linux-next documentation on kernel.org

Posted Sep 26, 2022 7:38 UTC (Mon) by Wol (subscriber, #4433) [Link]

There are a LOT of people out there who don't understand the concept of windowing - like Barclays Bank :-(

They just assume everything runs full-screen, which, in the case of a 4K monitor, I assume meets your criteria of "unreasonably wide".

(Barclays Bank - if I run my browser full-screen, it is *still not* wide enough to accommodate the login screen properly, making logging in tricky, shall we say ... I think my screen is an HD ...)

Cheers,
Wol