Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Jonathan Corbet <corbet@lwn.net>
To:     Federico Vaga <federico.vaga@vaga.pv.it>
Cc:     linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH V2] doc: monospace style for inline code in botching ioctl
In-Reply-To: <20230112195552.qapndatj66nqmu4n@numero-86.vaga.pv.it>
References: <20230102183649.9626-1-federico.vaga@vaga.pv.it>
 <874jswwuc2.fsf@meer.lwn.net>
 <20230112195552.qapndatj66nqmu4n@numero-86.vaga.pv.it>
Date:   Thu, 12 Jan 2023 13:33:30 -0700
Message-ID: <87cz7jtrvp.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

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

> On Wed, Jan 11, 2023 at 03:59:57PM -0700, Jonathan Corbet wrote:
>>Federico Vaga <federico.vaga@vaga.pv.it> writes:
>>
>>> Highlighting inline code improves text readability.
>>>
>>> Signed-off-by: Federico Vaga <federico.vaga@vaga.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