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:     Jui-Tse Huang <juitse.huang@gmail.com>, peterz@infradead.org,
        valentin.schneider@arm.com, daniel.m.jordan@oracle.com,
        siyanteng01@gmail.com, song.bao.hua@hisilicon.com,
        henrybear327@gmail.com, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org
Cc:     jserv@ccns.ncku.edu.tw, Jui-Tse Huang <juitse.huang@gmail.com>
Subject: Re: [PATCH 1/1] Rewrite mathematical expressions
In-Reply-To: <20220309122206.37497-1-juitse.huang@gmail.com>
References: <20220309122206.37497-1-juitse.huang@gmail.com>
Date:   Wed, 09 Mar 2022 08:38:55 -0700
Message-ID: <87r17b9lv4.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

Jui-Tse Huang <juitse.huang@gmail.com> writes:

>   There are lots of mathematical expressions in the documentation
> which are written in plain text format, which costs reader more time to
> recognize the expressions. If those expressions are written in LaTeX
> format which is supported as an extension of Sphinx, the expressions
> might become prettier as well as more straight forward to reader.

I'm sorry, but I'm not going to be able to apply this.  We have to think
about the readability of the plain-text documentation *first*, and LeTeX
source scores poorly on that metric.

So, just for example:

> -  capacity(cpu) = work_per_hz(cpu) * max_freq(cpu)
> +.. math::
> +  \text{capacity(cpu)} = \text{work\_per\_hz(cpu)} \times \text{max\_freq(cpu)}

The document is not improved by this kind of change, even if the
rendered version is prettier.

I do appreciate your effort to make the documentation better, but please
focus on the readability of the original docs and not just the rendered
version.

Thanks,

jon