Hi Jon, Em Wed, 19 Oct 2016 17:02:46 -0600 Jonathan Corbet <corbet@xxxxxxx> 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
