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;
Message-ID: <c41cab17-afd6-bc99-56a1-e4e73b8c1ef6@gmail.com>
Date:   Mon, 8 Aug 2022 17:49:36 +0900
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.11.0
Content-Language: en-US
From:   Akira Yokosawa <akiyks@gmail.com>
Subject: [PATCH v2 0/3] docs: conf.py: Reduce texlive dependency
To:     Jonathan Corbet <corbet@lwn.net>,
        Mauro Carvalho Chehab <mchehab@kernel.org>
Cc:     linux-doc@vger.kernel.org,
        Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
        linux-kernel@vger.kernel.org, Akira Yokosawa <akiyks@gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

Hi,

This is v2 with the env variable of SPHINX_IMGMATH as suggested by
Mauro.

Changes since v1 [1]:
 - Patch 2/3: Rename LOAD_IMGMATH -> SPHINX_IMGMATH (Mauro).
 - For the series: Acked-bys from Mauro.

This was inspired from the discussion on the expected behavior of
sphinx-pre-install [2].

There was a mismatch between Mauro's intent and my expectation for
the --no-pdf option of sphinx-pre-install.

My thought was if I installed all the packages suggested from
"./scripts/sphinx-pre-install --no-pdf", "make htmldocs" should run
free of complaints of missing commands or packages.

However, I got this warning when I tried the procedure on a debian-
based container image:

    WARNING: LaTeX command 'latex' cannot be run (needed for math display),
    check the imgmath_latex setting

, or:

    WARNING: dvipng command 'dvipng' cannot be run (needed for math display),
    check the imgmath_dvipng setting

Mauro's response to my complaint was this:

> The idea of using --no-pdf is to setup an environment without LaTeX,
> meaning that math tags would only be partially parsed: basically, the
> output would be html with LaTeX-like math expressions (at least last
> time I tried).

The mismatch can be resolved by using "mathjax" for math rendering
and making "make htmldocs" be free of texlive packages.

mathjax is the default math renderer since Sphinx 1.8.  It delegates
math rendering to web browsers.  

As Mauro has pointed out, "make epubdocs" requires imgmath.

So this patch set treats mathjax as a fallback math renderer for html
docs when imgmath requirements are not met.
Existing systems which meet imgmath requirements are not affected by
this change.

Summary of math rendering in html:

         dvipng, browser             before           after
    ==========================  ===============  ================
    dvipng                      imgmath (png)    <--
    no divpng, with javascript  raw math:: code  mathjax
    no dvipng, w/o javascript   raw math:: code  raw mathjax code

Patch 1/3 adds code in conf.py so that for html docs, the imgmath
extension will be loaded only when both latex and dvipng are available.
For epub docs, imgmath will always be loaded (no change).

Patch 2/3 adds code respecting a new env variable "SPHINX_IMGMATH" which
will override the math renderer choice. This variable can be helpful
on distros such as Arch linux, Mageia, etc. whose packaging policy is
coarse-grained.

E.g., to test math rendering by mathjax, run:
    make SPHINX_IMGMATH=no htmldocs

I mentioned in the thread of [2] that imgmath can generate scalable
math images in SVG.

My plan was to implement that option as well.  But during tests under
Fedora/CentOS/openSUSE, I encountered a couple of warnings from dvisvgm.
That would be regressions on existing systems which happen to have
not-working dvisvgm along with working dvipng.  I'm thinking of adding
the SVG option later if I can figure out the minimal requirement for
dvisvgm under imgmath.

Patch 3/3 is an independent change in the LaTeX preamble for pdf docs.
Currently, xeCJK.sty provided for RHEL 9 (and its clones) is broken
due to the lack of new dependency.  As a workaround, treat the absence
of xeCJK.sty as the additional knob for skipping CJK contents.

Note: Generated LaTeX sources will be the same regardless of existence
of the "Noto Sans CJK SC" font and xeCJK.sty.

[1] v1: https://lore.kernel.org/r/12d078f5-6995-b039-7076-bdb1f372a799@gmail.com/
[2]: https://lore.kernel.org/r/3ba5a52e-cab6-05cf-a66e-adc58c467e1f@gmail.com/

        Thanks, Akira

--
Akira Yokosawa (3):
  docs/conf.py: Treat mathjax as fallback math renderer
  docs/conf.py: Respect env variable SPHINX_IMGMATH
  docs: kerneldoc-preamble: Test xeCJK.sty before loading

 Documentation/conf.py                       | 46 ++++++++++++++++++++-
 Documentation/sphinx/kerneldoc-preamble.sty | 22 +++++++---
 2 files changed, 61 insertions(+), 7 deletions(-)


base-commit: 339170d8d3da5685762619080263abb78700ab4c
-- 
2.25.1