Re: The downside of math::

[Jani Nikula <jani.nikula@linux.intel.com>]

On Thu, 20 Oct 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> Hi Jon,
>
> Em Wed, 19 Oct 2016 17:02:46 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
>> Hey, Mauro,
>> 
>> So I was a little surprised to find that the htmldocs build now breaks on
>> one of my machines due to a lack of LaTeX.  A bit of digging turned up
>> the culprit: commit b7ff94df5628 (pixfmt-007.rst: use Sphinx math::
>> expressions).  The math:: directive uses LaTeX to process the math markup. 
>> 
>> What this means is that said commit has made LaTeX a dependency for the
>> htmldocs build.  I'm not convinced that this is a good idea; that's a
>> massive dependency to add for web builds that, ostensibly, should not
>> need it.  Certainly we shouldn't add it without discussion...:)
>> 
>> So I'll ask: how important to you is the math extension, and is there any
>> way we could get you your fancy math in a way that doesn't force
>> everybody to install the whole LaTeX package set?
>
> As you know, image handling comes with complex expressions ;) We have lots
> of expressions at the media documentation, but right now, the complex ones
> that require ReST math:: directive are related to colorspace conversions:
>
> 	https://linuxtv.org/downloads/v4l-dvb-apis-new/uapi/v4l/pixfmt-007.html
>
> On DocBook, we used to represent the same expressions using several
> tricks, like superscript and used some UTF-8 math symbols. As
> expected, they didn't look nice there:
>
> 	https://linuxtv.org/downloads/v4l-dvb-apis/ch02s06.html
>
> The initial conversion of those math expressions from DocBook make
> them look even worse. It also broke PDF generation, because LaTeX
> fonts were not compatible with UTF-8 math symbols (such issue was
> latter solved with xelatex - for some other remaining UTF-8 symbols).
>
> That's said, we're currently discussing APIs for codecs on media.
> Eventually, their documentation could come with a way more complex
> expressions than what we have so far.
>
> So, I really prefer not removing math support.

I wonder if we could cook up a nice way to make the math:: usage
conditional on actually being able to render it.

I would rather have the math:: directive produce just the preformatted
indented block as-is in the html output, instead of failing, when latex
is not available.

Adapt to the environment, produce the prettiest thing when you can, but
fallback to something uglier if all the dependencies are not there. See
what I did with the sphinx_rtd_theme in conf.py - we use it if it's
there, but it's not a hard dependency.

BR,
Jani.


>
> From what's written at Sphinx documentation:
> 	http://www.sphinx-doc.org/en/stable/ext/math.html
>
> It sounded to me that only sphinx.ext.imgmath extension is capable of
> providing math on all outputs, by generating an image like this one,
> using LaTeX:
> 	https://linuxtv.org/downloads/v4l-dvb-apis-new/_images/math/ae0a381368b3837b88b1308aaccedcd9a438757a.png
>
> There are two alternative math extensions that handle math::, but both
> seem to be specific for HTML, as they use JavaScript. Also, Sphinx
> require using either one of the extension, so we cannot enable both,
> one for PDF and the other one for HTML.
>
> Perhaps there are some extensions that would allow using something else,
> like this one:
> 	https://bitbucket.org/coh/sphinx-contrib-mathml/overview
>
> But I haven't test. So, I'm not sure:
> 	- if it would work;
> 	- if it would be portable to both HTML and PDF outputs;
> 	- if it won't require an even weirder toolbox.
>
> Thanks,
> Mauro
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

-- 
Jani Nikula, Intel Open Source Technology Center