linux-kernel - Re: [PATCH v2 1/3] docs/conf.py: Treat mathjax as fallback math renderer

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

Message-ID: <87wnb5bh67.fsf@meer.lwn.net>
Date:   Thu, 18 Aug 2022 11:22:24 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Akira Yokosawa <akiyks@...il.com>,
        Mauro Carvalho Chehab <mchehab@...nel.org>
Cc:     linux-doc@...r.kernel.org,
        Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        linux-kernel@...r.kernel.org, Akira Yokosawa <akiyks@...il.com>
Subject: Re: [PATCH v2 1/3] docs/conf.py: Treat mathjax as fallback math
 renderer

Akira Yokosawa <akiyks@...il.com> writes:

> Currently, math expressions using the "math::" directive or
> the ":math:" role of Sphinx need the imgmath extension for proper
> rendering in html and epub builds.
> imgmath requires dvipng (and latex).
> Otherwise, "make htmldocs" will complain of missing commands.
>
> As a matter of fact, the mathjax extension is loaded by default since
> Sphinx v1.8 and it is good enough for html docs without any dependency
> on texlive packages.
>
> Stop loading the imgmath extension for html docs unless requirements
> for imgmath are met.
>
> For epub docs, keep the same behavior of always loading imgmath.
>
> Signed-off-by: Akira Yokosawa <akiyks@...il.com>
> Acked-by: Mauro Carvalho Chehab <mchehab@...nel.org>
> ---
> Changes sinve v1:
>  - Acked-by from Mauro
>
> --
>  Documentation/conf.py | 34 +++++++++++++++++++++++++++++++++-
>  1 file changed, 33 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 934727e23e0e..3ec1f845c839 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -15,6 +15,23 @@
>  import sys
>  import os
>  import sphinx
> +from subprocess import check_output
> +
> +# helper
> +# ------
> +
> +def have_command(cmd, ver_opt, str_in_ver):
> +    """Run ```cmd`` with ``ver_opt`` and see if ``str_in_ver`` is found
> +    or not.
> +    """
> +
> +    try:
> +        ver_str = check_output([cmd, ver_opt]).decode('utf-8', 'ignore')
> +        have_cmd = str_in_ver in ver_str
> +    except:
> +        have_cmd = False
> +
> +    return have_cmd

So this is adding infrastructure that isn't really mentioned in the
changelog.

A more fundamental comment, though, is that I have learned (the hard
way, repeatedly) that good things do not come from bare "except"
statements.  They always hide bugs.  If there is an exception you're
worried about here, please list it explicitly.

Otherwise seems good.

Thanks,

jon