Date: Wed, 19 Oct 2016 22:26:18 -0200
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
To: Jonathan Corbet <corbet@lwn.net>
Cc: LKML <linux-kernel@vger.kernel.org>, linux-doc@vger.kernel.org
Subject: Re: The downside of math::
Message-ID: <20161019222618.154434f3@vento.lan>
In-Reply-To: <20161019170246.339eff9d@lwn.net>
References: <20161019170246.339eff9d@lwn.net>
Organization: Samsung
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 8BIT
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 2836
Lines: 68

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.

>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