Nbconvert: Add TeX requirements to install docs

[gnestor]

The current docs don't mention anything about installing TeX or having TeX installed but it is required to convert to PDF, etc. I understand that installing TeX differs depending on the user's OS (e.g. mactex for OS X), so I'm creating an issue vs. creating a PR because I'm not sure what the suggested TeX packages are for other OSs. It seems to me that this should be included right alongside the pandoc install instructions.

[gnestor]

@michaelpacer @takluyver Do you know what the recommended packages are for Linux (or specific Linux distributions)? Windows?

[takluyver]

On Ubuntu (and probably Debian and other Debian-based distros), I think installing texlive is a good way to start. I don't know if we require packages that aren't in that default set.

There's also a texlive package on Fedora, so hopefully that installs the same things.

I vaguely recall hearing Miktex recommended for Windows installation, but I know ~nothing about it.

[Tagar]

thank you @takluyver

As I mentioned in https://github.com/jupyter/nbconvert/issues/357#issuecomment-239194998 texlive wasn't enough to make things work. At least not on RHEL.

[takluyver]

OK, here are the packages I needed to make it work on a recent Fedora installation:

sudo dnf install texlive texlive-xetex texlive-adjustbox texlive-upquote texlive-ulem

Or we can install more stuff but probably make it more future proof by using the 'extra' metapackage instead of specific pieces:

sudo dnf install texlive-collection-latexextra texlive-xetex

[Tagar]

From all of the above metnioned Fedora packages, on RHEL, I can only see

texlive and texlive-xetex in list of yum packages.

[takluyver]

Based on the list you posted before, I think your RHEL packages are for an ancient version of texlive (2007 looks like a year, and it's not a recent year ;-). You may need to get a newer version of Texlive from somewhere else.

[Tagar]

Yep, that's what RHEL6 comes with. We don't have any RHEL7 servers handy (and I know many bigger companies are still in early stage of migrating to RHEL7 if even started). And I even not sure if RHEL7 has those newer tex packages. Will report here if I find out.

[mpacer]

@Tagar Had you tried installing a more recent version of TexLive on RHEL6? I don't know if this solution is workable given your setup, but there is an SO answer on one approach to this.

http://tex.stackexchange.com/questions/140649/tex-live-2013-on-red-hat-6-4

P.S. I now understand the first comment in that answer "… and Red Hat attacks again."

[mpacer]

Also, I don't know if these are the instructions that we want people to be following but it looks like IBM has some instructions that cover enterprise Windows and RedHat Enterprise Linux.

What's nice about that is that it includes instructions for installing the hanazono fonts, which would cover Japanese… technically I believe that it would cover Chinese as well but elsewhere I remember reading that Chinese readers think that the hànzì look "japanified" (which is probably a reasonable statement given that they were primarily designed for use in typesetting Japanese text).

[gnestor]

One thought: I don't know what percentage of Jupyter users are using Anaconda, but would it make sense to ask Continuum to bundle these TeX packages in Anaconda?

[takluyver]

Worth a shot. Also worth asking the conda-forge people like @pelson

[Tagar]

@michaelpacer thank you for the links - I will try to follow those documents and see if I can make it work in rhel6.

@gnestor great idea. We're not Anaconda customers, so I doubt they will listen to our suggestions. But we do use Anaconda - they distribute Anaconda as Cloudera parcels and that's what we use.

[mingwandroid]

I use MikTex when building R packages for Windows for Anaconda. Specifically I've been using the following from a bash script:

wget -c http://mirrors.ctan.org/systems/win32/miktex/setup/miktex-portable-2.9.5857.exe
7za x -y miktex-portable-2.9.5857.exe
# We also need the url, incolsolata and mptopdf packages and
# do not want a GUI to prompt us about installing these.
sed -i 's|AutoInstall=2|AutoInstall=1|g' miktex/config/miktex.ini
# see also: http://tex.stackexchange.com/q/302679
PATH=${PWD}/miktex/bin:${PATH}

[kerrywatson1]

Both MikTex and TeX 1.8 packages come up among 584 results in a search of "tex" packages available on Anaconda.org. https://anaconda.org/search?q=tex

[gnestor]

@mingwandroid and @kerrywatson1 Thanks for the info!

[gnestor]

According to CTAN:

• TeX Live is recommended for Unix
• MacTeX is recommended for OS X
• MikTex is recommended for Windows

This looks like an interesting conda package for Unix users: https://anaconda.org/pkgw/texlive-selected

[gnestor]

@mingwandroid Do you think it makes sense for Anaconda to ship with TeX support vs. requiring users install additional conda packages?

[mpacer]

I think the question is in part whether we consider TeX a hard dependency or not. If we do, then we should figure out how to include it if anaconda is going to ship Jupyter as a toolset out-of-the-box.

That said, it's possible to run nbconvert to (for example) execute notebooks without needing TeX. So my intuition is that it shouldn't be a hard dependency in the same way that IPython is not a hard dependency.

That doesn't mean we shouldn't push for Anaconda to include TeX but merely determines the frame in which we seek that feature (if we are to at all).

I can imagine them not wanting to add a couple of GBs to the install (even for the main branch of anaconda), however TeX is a crucial part of many scientific workflows (including ours if you want to output to pdf).

So I feel mixed.

[Tagar]

add a couple of GBs to the install

Good point on size .. TeX doesn't have a 'mini' version?
A few Gb just to generate a pdf seems a lot.
If not, can nbconvert use TeX-independent library to generate pdf?

[gnestor]

Agreed, given the these TeX binaries are only required for rendering TeX in PDFs, I would say it's not a hard dependency. I agree with @Tagar, there should be a much lighter-weight solution that nbconvert can use 🤔

This one is only 100MB but I haven't tested it and it only supports Linux and OS X.

[gnestor]

For the time being, should we just update the installations docs to reflect the following:

Installing TeX

For converting LaTeX to formats other than HTML, nbconvert uses
TeX. To install TeX:

• Linux: TeX Live
• macOS (OS X): MacTeX
• Windows: MikTex

[mpacer]

I _strongly_ disagree that we should find a lighter weight solution as our method of rendering PDFs. At least, not by default; and if we keep it as the default method, that will require keeping it as a dependency.

.tex files are a core part of many scientific publishing pipelines, and – though that stems heavily from TeX's ability to render genuinely beautiful mathematics (i.e., why Knuth bothered to invent it) – the TeX ecosystem has many other advantages. The .tex format accomplishes specifying in plaintext some remarkable feats of professional quality typesetting. The TeX engine's box-and-glue model (aside from being a piece of brilliant mathematical work itself) has proven to be both remarkably flexible and robust. The TeX ecosystem is supported by a strong core community of developers. I've not seen anything with anywhere near TeX's power for handling programmatic, plaintext typesetting for large scale documents. This is especially true once you consider the variety of continuously developed & supported extension packages (things like tikz, hyperref, graphicx, booktabs &c.). The strongest argument against TeX/LaTeX would have been its less than great font format and Unicode support, but now that we've shifted from pdfLaTeX to XeLaTeX, its Unicode support and OpenType support is strong (though it still needs extensions, see issues with xeCJK and CJK languages in general).

If people want to render PDFs from .tex files (at all), they will have to install at least one of XeLaTeX, LaTeX, pdfLaTeX, LuaTeX &c.. There really isn't another option (and if there is please let me know because though I will be skeptical, I am also extremely curious).

That said, having TeX as a conditional dependency rather than a hard dependency is totally reasonable. I just would argue that PDF rendering is then only a conditionally supported feature (as is converting markdown to something other than HTML).

In the (current) docs regarding markdown → formats other than HTML:

For converting markdown to formats other than HTML, nbconvert uses Pandoc <http://pandoc.org>_ (1.12.1 or later).

(Note: I'm not sure how true that statement is anymore… with the generic pandoc filter in https://github.com/jupyter/nbconvert/pull/436 I need to look into that.)

But, assuming that's true, if we wanted to treat converting markdown to formats other than HTML as an unconditionally supported feature, pandoc would need to be a hard dependency. Similarly, if we want to treat PDF rendering as an unconditionally supported feature, then TeXlive/MacTeX/MikTeX will need to be a hard dependency.

Regardless, I agree that we should add something to the docs, working on that now.

[mpacer]

Ok… Added instructions and some exposition in #441

[takluyver]

FWIW, I am experimenting with a more lightweight PDF export based on reportlab. I don't expect this to _replace_ the Latex pathway, but it may one day provide a viable alternative for people who don't require the full power of Latex.

https://github.com/takluyver/nbconvert-reportlab

[mpacer]

Fair enough — I just wouldn't want it to be our default exporter when invoking --to pdf. Maybe it'd work as a fall-back if LaTeX is not present on the system?

Also…I'm not entirely sure (and I don't want to wipe my TeX distro to find this out…) but what do our error messages say right now when someone tries to use --to pdf without TeX installed?

[gnestor]

@michaelpacer It looks like: nbconvert failed: pdflatex not found on PATH

Source: https://github.com/jupyter/notebook/issues/1674#issuecomment-247032676

[Tagar]

@takluyver https://github.com/takluyver/nbconvert-reportlab/blob/master/Trapezoid%20Rule.pdf rendered very well. thank you!

[mpacer]

Ok, @gnestor in #443 I added a more informative error when it fails to find an interpreter.

[gnestor]

@mpacer Awesome!

[jordana309]

I realize this is getting pretty old, but what about installing TexLive as per this link (https://tex.stackexchange.com/questions/140649/tex-live-2013-on-red-hat-6-4) and changing the install directories to be where needed for jupyter?

I am trying to do that, and found the following new locations when I installed TeXLive using yum:
a. /var/lib/texmf/tex
b. /var/lib/texmf/web2c/tex
c. /usr/share/texmf-errata/tex
d. /usr/share/texmf/tex

But I'm not sure how those map to the directories requested in the install script

1. TEXDIR with support tree
2. TEXMFLOCAL
3. TEXMFSYSVAR
4. TEXMFSYSCONFIG
5. TEXMFVAR
6. TEXMFCONFIG
7. TEXMFHOME

Any thoughts?

1. I installed TexLive from the link above, changing the TEXDIR to /usr/share/texlive... instead of /usr/local/texlive. That was to make sure that jupyter could write to those directories.
2. I had a file called ~/.bashrc, which is run every time a terminal is opened from my jupyter interface. I edited this to contain the following:

# LaTeX
if grep -q texlive <<<$PATH; then
echo 'TeXLive installed'
else
PATH="$PATH:/usr/share/texlive/2017/bin/i386-linux"
fi

This had the added benefit of showing me in any terminal I opened from jupyter what things I had installed. I wound up adding a line each time I installed new things and got them working so that I'd quickly see what was there just by opening a terminal.

I hope this helps!