linux-kernel - Re: [PATCH 1/1] Rewrite mathematical expressions

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]

Date:   Wed, 09 Mar 2022 08:38:55 -0700
From:   Jonathan Corbet <corbet@....net>
To:     Jui-Tse Huang <juitse.huang@...il.com>, peterz@...radead.org,
        valentin.schneider@....com, daniel.m.jordan@...cle.com,
        siyanteng01@...il.com, song.bao.hua@...ilicon.com,
        henrybear327@...il.com, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org
Cc:     jserv@...s.ncku.edu.tw, Jui-Tse Huang <juitse.huang@...il.com>
Subject: Re: [PATCH 1/1] Rewrite mathematical expressions

Jui-Tse Huang <juitse.huang@...il.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