Re: The downside of math::

[Markus Heiser <markus.heiser@darmarit.de>]

Am 21.10.2016 um 23:38 schrieb Jonathan Corbet <corbet@lwn.net>:

> On Thu, 20 Oct 2016 17:55:21 +0300
> Jani Nikula <jani.nikula@linux.intel.com> wrote:
> 
>> I wonder if we could cook up a nice way to make the math:: usage
>> conditional on actually being able to render it.
> 
> I think that's the ideal solution.
> 
> I got the docs build working again on my Fedora machine, but it threw me
> back into this loop for several iterations:
> 
> 	while (htmldocs build fails)
> 		see which goddam LaTex file is missing now
> 		dig around to find which Fedora package provides it
> 		dnf install YA-texlive-package

Hmm, when I deinstall latex on my Debian box, I only get a warning:

 WARNING: LaTeX command 'latex' cannot be run (needed for math display), check the pngmath_latex setting

IMO the warning is OK, if not read below.

> This is just the kind of thing that I don't want to impose on anybody
> wanting to build the docs; if we get back to a place where almost nobody
> can do it again, we'll not have improved much.

I guess, that Jon walks through the latex installation hell on fedora,
which mauro has already done in August. Please take a look at the
discussion we had about math and PDF generation:

 https://www.mail-archive.com/linux-doc@vger.kernel.org/msg05583.html

With this, I think we have a leak of knowledge and we should document
latex installation dependencies right now.

If you don't want to see a warning log, we have to consider 
a solution like Johannes Berg posted here:

 https://www.mail-archive.com/linux-doc@vger.kernel.org/msg07071.html

@johannes: since this thread and our "sequence diagrams" thread addressing
the same questions (how should we handle dependencies from extensions)
I propose to continue the discussion here in this thread with Jon.

> LaTeX is a necessary evil for PDF output, it seems, but I really think
> that, one way or another, we need to be able to build the other formats
> without it.

I wish, but I can't see any serious alternative. Thats why I think, we
should accept latex and have to document it well.

Further I think we should not generate more (and more) external requirements
like e.g. plantuml, Java or reportlab discussed here:

 https://www.mail-archive.com/linux-doc@vger.kernel.org/msg07035.html

I understand the need of sequences diagrams and I like to see such a feature
in the kernel documentation. On the other side, since we have to maintain all
dependencies well over a long time period on distributions with different 
package managers, I really hesitate to include dependencies which might flood
out the banks. Right here, in the discussion of the math:: extension (which
is part of the standard sphinx installation) we see, what problems can occur on
different systems installations.

-- Markus --