Re: [PATCH 1/1] Rewrite mathematical expressions

[Jonathan Corbet <corbet@lwn.net>]

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