Rendered linux-next documentation on kernel.org
Posted Sep 21, 2022 14:27 UTC (Wed)
by mricon (subscriber, #59252)
[Link]
Posted Sep 25, 2022 3:32 UTC (Sun)
by milesrout (subscriber, #126894)
[Link] (6 responses)
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.
Posted Sep 25, 2022 6:37 UTC (Sun)
by neilbrown (subscriber, #359)
[Link] (3 responses)
Posted Sep 25, 2022 8:06 UTC (Sun)
by Wol (subscriber, #4433)
[Link] (2 responses)
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,
Posted Sep 25, 2022 9:30 UTC (Sun)
by neilbrown (subscriber, #359)
[Link] (1 responses)
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.
Posted Sep 25, 2022 14:46 UTC (Sun)
by corbet (editor, #1)
[Link]
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.
Posted Sep 25, 2022 14:54 UTC (Sun)
by flussence (guest, #85566)
[Link] (1 responses)
Posted Sep 26, 2022 7:38 UTC (Mon)
by Wol (subscriber, #4433)
[Link]
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,
Rendered linux-next documentation on kernel.org
Rendered linux-next documentation on kernel.org
Rendered linux-next documentation on kernel.org
As a bug report, it would be quite useful - thanks. As a rant .... less so.
Rendered linux-next documentation on kernel.org
Wol
Rendered linux-next documentation on kernel.org
The plain-text format that milesrout prefers is, of course, available via the "view source" link at the top of the page.
Rendered linux-next documentation on kernel.org
Rendered linux-next documentation on kernel.org
Rendered linux-next documentation on kernel.org
Wol