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

[Akira Yokosawa <akiyks@gmail.com>]

[-CC: ksummit-discuss]
On Sat, 9 Jul 2022 00:27:25 +0900, Akira Yokosawa wrote:
> On Fri, 8 Jul 2022 15:59:10 +0100,
> Mauro Carvalho Chehab wrote:
>> Em Fri, 08 Jul 2022 08:02:52 -0600
>> Jonathan Corbet <corbet@lwn.net> escreveu:
>>
>>> Akira Yokosawa <akiyks@gmail.com> writes:
>>>
>>>> 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. 
>>
>>> -extensions.append("sphinx.ext.imgmath")
>>> +extensions.append("sphinx.ext.mathjax")
>>
>> There are two problems with this:
>>
>> 1. mathjax doesn't work for PDF output - nor would work if we add support
>>    for man pages some day;
> 
> Hmm, if I understand what is written in the following page:
>     https://www.sphinx-doc.org/en/master/usage/extensions/math.html
> 
> , both imgmath and mathjax extensions are relevant only for HTML output.
> 
> It says:
> 
>     Changed in version 1.8: Math support for non-HTML builders is integrated
>     to sphinx-core. So mathbase extension is no longer needed.
> 
> When did you see the issue of "mathjax doesn't work for PDF output" ?

For the record,

I tested mathjax and PDF output with Sphinx 1.7.9, whose latex mode
can't handle nested tables.
I had no problem in building userspace-api.pdf and math expressions
in it look perfect.

So I believe mathjax does not affect PDF output.

Mauro wrote:
> As imgmath works everywere, we opted to use it instead. We were
> actually hoping that the lack of proper math support on Sphinx were
> something that later Sphinx versions after 1.3.1 would have fixed. 

I'm not going to test earlier versions of Sphinx and I have no idea
of what issue Mauro saw at the time, but it sounds to me the issue
has been fixed since.

> 
>> 2. Some Kernel developers disable javascript.
> OK, mathjax has no chance, then...

On the second thought, I think mathjax (latex-free "make htmldocs")
is good enough for test build purposes.  When javascript is disabled,
math expressions are rendered in mathjax source.

As conf.py is programmable, it is possible to choose sphinx.ext.imgmath
when dvipng is found on the build system.

As for sphinx-pre-install, what about adding an option

    --no-js   For those who disable javascript in their browser.

which provide the list of required packages for dvipng?
 
Thoughts?

Some comforting news for Jon:

Jon wrote:
> Pulling in a bunch of JavaScript from the net while browsing the kernel
> docs is not an entirely pleasing solution either.  But perhaps it's
> preferable to loading the system with Latex.

With Sphinx >=4.0, mathjax is loaded only when a page with math expressions
is opened.  Sphinx is improving in this regard.
    
        Thanks, Akira

> 
>         Thanks, Akira
>