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

From: Mauro Carvalho Chehab <mchehab@kernel.org>
To: Jonathan Corbet <corbet@lwn.net>
Cc: Akira Yokosawa <akiyks@gmail.com>,
	ksummit-discuss@lists.linuxfoundation.org,
	linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
	mchehab+huawei@kernel.org
Subject: Re: Expectation to --no-pdf option (was Re: [PATCH v2 0/5] Address some issues with sphinx detection)
Date: Fri, 8 Jul 2022 15:59:10 +0100	[thread overview]
Message-ID: <20220708155910.7c4ea35c@sal.lan> (raw)
In-Reply-To: <87bktzhfcj.fsf@meer.lwn.net>

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;
2. Some Kernel developers disable javascript.

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. 
> 
> 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. 

If we could change conf.py to either load either one depending if it is
building PDF or not would be the best. The technical problem is that the 
javascript solution is not compatible with PDF output.

> I kind of wish we could
> just do without the fancy math processing entirely, but I lost that
> battle some time ago...:)

The media uAPI book uses math, and also vm/memory-model.rst. The last
one could easily use just a C code.

yet, it sounds funny to not have it used inside DRM. GPU processing
does lots of math. i would expect to have math used there for things
similar to the usages on media.

Trying to describe the colorspace conversion expressions there without
math would be really painful:

	https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/colorspaces-details.html?highlight=detailed+colorspace

Anyway, if you have some other solution, I'd gladly use something else.

> 
> Mauro, have you looked at that option?

Yes, but it got discarded due to pdf output. Not sure if this would work
on epub either.

> 
> Thanks,
> 
> jon