linux-kernel - Re: [PATCH V2] doc: monospace style for inline code in botching ioctl

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] [day] [month] [year] [list]

Message-ID: <87cz7jtrvp.fsf@meer.lwn.net>
Date:   Thu, 12 Jan 2023 13:33:30 -0700
From:   Jonathan Corbet <corbet@....net>
To:     Federico Vaga <federico.vaga@...a.pv.it>
Cc:     linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH V2] doc: monospace style for inline code in botching ioctl

Federico Vaga <federico.vaga@...a.pv.it> writes:

> On Wed, Jan 11, 2023 at 03:59:57PM -0700, Jonathan Corbet wrote:
>>Federico Vaga <federico.vaga@...a.pv.it> writes:
>>
>>> Highlighting inline code improves text readability.
>>>
>>> Signed-off-by: Federico Vaga <federico.vaga@...a.pv.it>
>>
>>It improves *HTML* text readability; the results for plain text are
>>... less clear.  I think it's better to avoid this kind of extra markup
>>when we can.
>
> Shouldn't we consider higher priority the HTML text? Perhaps I've a biased
> opinion. Do you think that plain-text is the favorite way of reading the kernel
> documentation?

The policy all along has been that we need to prioritize the plain-text
docs.  A lot of people do use them, and it is easy to wreck their
readability with markup if sufficient attention isn't paid.  HTML output
is great, and we want it to be as good as it can be, but it can't be at
the cost of plain-text readability.

> Let me profit from this point and ask. Are there statistics about the usage of
> https://www.kernel.org/doc/html/latest/?

None that I know of.

Thanks,

jon