Expectation to --no-pdf option (was Re: [PATCH v2 0/5] Address some issues with sphinx detection)

From: Akira Yokosawa <akiyks@gmail.com>
To: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: corbet@lwn.net, ksummit-discuss@lists.linuxfoundation.org,
	linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
	mchehab+huawei@kernel.org, Akira Yokosawa <akiyks@gmail.com>
Subject: Expectation to --no-pdf option (was Re: [PATCH v2 0/5] Address some issues with sphinx detection)
Date: Fri, 8 Jul 2022 20:34:00 +0900	[thread overview]
Message-ID: <3ba5a52e-cab6-05cf-a66e-adc58c467e1f@gmail.com> (raw)
In-Reply-To: <20220707211558.438a27d4@sal.lan>

On Thu, 7 Jul 2022 21:15:58 +0100, Mauro Carvalho Chehab wrote:
> Em Tue, 5 Jul 2022 13:15:57 +0900
> Akira Yokosawa <akiyks@gmail.com> escreveu:
> 
>> Hi Mauro,
>>
[...]

>> So this is a meta-level feedback considering the most likely uses
>> of sphinx-pre-install.
>>
>> I think first-time users of sphinx-pre-install are more likely
>> interested in getting ready for running "make html".  They won't
>> bother with "make pdfdocs". 
> 
> True, but, as you're pointing below, math expressions require LaTeX.
> 
> 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).

Oh, that is your intention.  :-/

When I saw this help text in "./scripts/sphinx-pre-install --help":

    --no-pdf	- don't check for dependencies required to build PDF docs

for the first time, my expectation was like this:

    If I make "./scripts/sphinx-pre-install --no-pdf" happy, "make htmldocs"
    will complete without any warning on package requirements.

But I got this warning from "make htmldocs" among others:

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

And my reaction to it was something like:

    "What!!!  Why sphinx-pre-install didn't complain?"
    "OK. I'll ignore sphinx-pre-install.  Let's see what I need to install."

The reason why this mismatch has never surfaced as a problem is, I suppose,
because most people don't use --no-pdf at all.

However, in thinking of making --no-pdf the default, I thought --no-pdf
should be more trustworthy.

If your goal is to provide LaTeX-free packages for "make htmldocs",
the option should have been named --no-latex or similar (probably in
addition to --no-pdf), no?

Well, arguing does not help. I stop here.

More constructive approach would be to make "make htmldocs" be
truly latex-free.  Then --no-pdf and --no-latex will be equivalent.

Fortunately, it is possible by using the mathjax extension instead of
imgmath.  With mathjax, rendering of math expressions is delegated to
web browsers.

The resulting HTML will depend on mathjax code and math fonts from
somewhere in the cloud (by default, https://cdnjs.cloudflare.com/ajax/libs/mathjax/...
or https://cdn.jsdelivr.net/npm/mathjax@3/... depending on the Sphinx
version).

All you need is this one-liner:

--------

diff --git a/Documentation/conf.py b/Documentation/conf.py

index 934727e23e0e..fe1084510329 100644

--- a/Documentation/conf.py

+++ b/Documentation/conf.py

@@ -106,7 +106,7 @@ else:

 autosectionlabel_prefix_document = True

 autosectionlabel_maxdepth = 2

 

-extensions.append("sphinx.ext.imgmath")

+extensions.append("sphinx.ext.mathjax")

 

 # Add any paths that contain templates here, relative to this directory.

 templates_path = ['_templates']
--------

In my tests, the mathjax extension works with all the versions of Sphinx
I tested (1.7.9, 2.4.4, 3.4.3 (debian bullseye), 4.2.0 (openSUSE LEAP 15.4),
and 5.0.2).
Note that math expressions should look much sharper (vector fonts)
than those from imgmath (pixel images).
The time for a browser to complete the rendering might be longer than
with imgmath, especially for pages with a lot of math expressions,
though.  (Yes, I see some of media documents have a lot of them.)

When you are detached from network connections, browsers will give
up and show those expressions in mathjax source code.

Mauro, wouldn't this approach work for you?

        Thanks, Akira

PS: Replies to the other topics will be sent separately.
