DOC: Fix latexpdf build #18948

QuLogic · 2020-11-14T01:47:18Z

PR Summary

This is a rebase of #15797, plus additional fixes for new errors and a patch for macOS font paths.

PR Checklist

[n/a] Has pytest style unit tests (and pytest passes).
Is Flake 8 compliant (run flake8 on changed files to check).
[n/a] New features are documented, with examples if plot related.
Documentation is sphinx and numpydoc compliant (the docs should build without error).
Conforms to Matplotlib style conventions (install flake8-docstrings and run flake8 --docstring-convention=all).
[n/a] New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
[n/a] API changes documented in doc/api/next_api_changes/ (follow instructions in README.rst there).

This commit reactivates original latex_elements['preamble'] key which was shadowed by the bug about latex_elements being defined twice in the conf.py. It removes from this latex preamble the loading of amsmath, amssymb, amsfonts as this is already added by Sphinx, and of txfonts because this is not compatible with fontspec and the already executed command \setmainfont{DejaVu Serif}. Memo: expdlist package breaks PDF build if a description list ends up in a table cell, as happens actually with Matplotlib.tex file. But, by luck, the enumitem LaTeX package modifications of LaTeX description lists masks the expdlist potential breakage.

But removing enumitem package reveals a bug in expdlist. Import the fix from the SciPy and NumPy projects. numpy/numpy#15028 scipy/scipy@c881fde

XITS has all the Unicode mathematical symbols glyphs needed for the section of the documentation related to Mathtext. (DejaVu Serif was missing 134 of them, and GNU FreeFont 19 of them) XITS Math (and unicode-math) is needed for \mathbb supporting letters b, c, d, there is one \mathbb{blackboard} once in the documentation. It also gives better calligraphy font. The Ubuntu package texlive-fonts-extra provides these latex dependencies.

modified: doc/conf.py

This appears unnecessary in mathtext, but LaTeX requires the dimension.

Limit math symbol table columns to number of symbols. In Hebrew, there are only 4 symbols, but the table is 6 columns with two extra empty columns. Fix Delimiters table as pipe and backslash need to be escaped. Replace the `get_n` function with a simpler `range` operation.

When the Glossary existed, they would go in there, but now they are stuck at the end of the Developer Guide. Neither was really correct, so now they are in their own Part.

QuLogic · 2020-11-14T01:50:59Z

tutorials/text/mathtext.py

@@ -94,7 +94,7 @@

 .. math::

-    \frac{3}{4} \binom{3}{4} \genfrac{}{}{0}{}{3}{4}
+    \frac{3}{4} \binom{3}{4} \genfrac{}{}{0pt}{}{3}{4}


This dimension appears to be required by LaTeX, but not our parser. I couldn't find anything in the parser that could require it, (if we wanted to do that)?

cc @anntzer

Indeed, \genfrac behaves differently between mathtext and TeX: TeX wants (quite reasonably) a unit whereas we have not implemented support for it. I don't actually know what's the unit we implicitly use?
I guess adding support for units there is not "too" hard (mostly just figuring out the right multiplier); but in the meantime I guess you could just exclude that from the pdf build using .. only:: or .. ifconfig::?

Well this is in .. math::; according to the build here, it works fine with the unit in regular HTML builds, too. It's just inconsistent with the Matplotlib version in the plain text source.

I guess you should mostly just open an issue for supporting {0pt} on our side? (which seems like a reasonable request) Or did I miss something?

Yes, as it seems I didn't miss anything, #19001.

tacaswell · 2020-11-24T18:35:59Z

This is failing for me on arch with

kpathsea: Running mktextfm XITS-Regular
/usr/share/texmf-dist/web2c/mktexnam: Could not map source abbreviation X for XITS-Regular.
/usr/share/texmf-dist/web2c/mktexnam: Need to update /usr/share/texmf-dist/fonts/map/fontname/special.map?
mktextfm: Running mf-nowin -progname=mf \mode:=ljfour; mag:=1; ; nonstopmode; input XITS-Regular
This is METAFONT, Version 2.7182818 (TeX Live 2020/Arch Linux) (preloaded base=mf)


kpathsea: Running mktexmf XITS-Regular
! I can't find file `XITS-Regular'.
<*> ...; mag:=1; ; nonstopmode; input XITS-Regular
                                                  
Please type another input file name
! Emergency stop.
<*> ...; mag:=1; ; nonstopmode; input XITS-Regular
                                                  
Transcript written on mfput.log.
grep: XITS-Regular.log: No such file or directory
mktextfm: `mf-nowin -progname=mf \mode:=ljfour; mag:=1; ; nonstopmode; input XITS-Regular' failed to make XITS-Regular.tfm.
kpathsea: Appending font creation commands to missfont.log.


! Package fontspec Error: The font "XITS-Regular" cannot be found.

For immediate help type H <return>.
 ...                                              
                                                  
l.31 ]

I do have the XITS-Regular file on my system:

jupiter@12:53  ➤  locate XITS-Regular
/usr/share/texmf-dist/fonts/opentype/public/xits/XITS-Regular.otf

If I go through the darwin code path then it builds cleanly so I think we need to be a bit more precise about sorting out how to specify the fonts than just if we are on darwin :(.

QuLogic · 2020-11-24T21:00:39Z

That's unfortunate; I was hoping to avoid figuring out how to query kpathsea.

anntzer · 2020-11-24T21:25:28Z

Not really sure what you exactly need here but is it something along the lines of \setmathfont{XITS-Regular.otf}[Path=/usr/share/texmf-dist/fonts/opentype/public/xits/] where the full path is basically given to you by kpsewhich XITS-Regular.otf? (Feel free to ignore if irrelevant...)

QuLogic · 2020-12-03T06:38:20Z

Maybe. @tacaswell what is the output of kpsewhich XITS-Regular.otf on Arch?

tacaswell · 2020-12-03T20:15:50Z

on arch:

~                                                                                                                                                                    
 11:36:16 $  kpsewhich XITS-Regular.otf                                                                                                                              
/usr/share/texmf-dist/fonts/opentype/public/xits/XITS-Regular.otf

on ubuntu

tcaswell@sharon:~$ kpsewhich XITS-Regular.otf 
/usr/share/texlive/texmf-dist/fonts/opentype/public/xits/XITS-Regular.otf

On macOS, xelatex uses the system font directories, but MacTeX fonts are not added there. However, these files can be found by specifying the file name instead of the font name, so do so on macOS. On Linux, it is mostly better to continue to specify the font name, as different distros ship different extensions. This should still work on systems that don't do this, using the same fallback as macOS.

QuLogic · 2020-12-08T10:28:22Z

I spent a while trying to get this to work with kpsewhich, but then I looked back at the fontspec docs and found that it had some builtin support to do this. This currently works on Fedora and macOS, and hopefully works on Arch since it should trigger the fallback like it does on macOS.

tacaswell · 2020-12-16T20:38:40Z

I tested that this now builds cleanly for me on an Arch box.

tacaswell · 2020-12-16T20:40:14Z

Merged on a single review because this configuration to build the latex docs and some of these commits came from the OP.

@jfbu Thank you for getting this work started!

jfbu · 2021-01-26T21:58:05Z

@tacaswell @QuLogic great to hear that you seem to have solved tricky multi-platform issues there!

jfbu and others added 9 commits November 12, 2020 22:04

LaTeX: resolve "Too deeply nested" error without enumitem package

2b212a0

But removing enumitem package reveals a bug in expdlist. Import the fix from the SciPy and NumPy projects. numpy/numpy#15028 scipy/scipy@c881fde

Better looking general index in PDF documentation

8d9ebb5

modified: doc/conf.py

LaTeX: backport sphinx-doc/sphinx/pull/6888 to fix double quote issue

e6b341d

Drop Extension = .otf lines from LaTeX font loading

3947e83

modified: doc/conf.py

Add missing dimension in genfrac LaTeX example.

89b6314

This appears unnecessary in mathtext, but LaTeX requires the dimension.

DOC: Put bibliography/indices in their own Part.

2bec173

When the Glossary existed, they would go in there, but now they are stuck at the end of the Developer Guide. Neither was really correct, so now they are in their own Part.

QuLogic added the Documentation label Nov 14, 2020

QuLogic added this to the v3.4.0 milestone Nov 14, 2020

QuLogic commented Nov 14, 2020

View reviewed changes

QuLogic mentioned this pull request Dec 8, 2020

Docs 3.3.3 PDF missing 404 #19065

Closed

QuLogic force-pushed the doc-pdf branch from a300336 to 2fd6983 Compare December 8, 2020 10:21

tacaswell approved these changes Dec 16, 2020

View reviewed changes

tacaswell merged commit 4c5ae23 into matplotlib:master Dec 16, 2020

QuLogic deleted the doc-pdf branch December 16, 2020 20:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Fix latexpdf build #18948

DOC: Fix latexpdf build #18948

QuLogic commented Nov 14, 2020

QuLogic Nov 14, 2020

anntzer Nov 14, 2020

QuLogic Nov 17, 2020

anntzer Nov 21, 2020

QuLogic Nov 24, 2020

tacaswell commented Nov 24, 2020

QuLogic commented Nov 24, 2020

anntzer commented Nov 24, 2020

QuLogic commented Dec 3, 2020

tacaswell commented Dec 3, 2020

QuLogic commented Dec 8, 2020

tacaswell commented Dec 16, 2020

tacaswell commented Dec 16, 2020

jfbu commented Jan 26, 2021

DOC: Fix latexpdf build #18948

DOC: Fix latexpdf build #18948

Conversation

QuLogic commented Nov 14, 2020

PR Summary

PR Checklist

QuLogic Nov 14, 2020

Choose a reason for hiding this comment

anntzer Nov 14, 2020

Choose a reason for hiding this comment

QuLogic Nov 17, 2020

Choose a reason for hiding this comment

anntzer Nov 21, 2020

Choose a reason for hiding this comment

QuLogic Nov 24, 2020

Choose a reason for hiding this comment

tacaswell commented Nov 24, 2020

QuLogic commented Nov 24, 2020

anntzer commented Nov 24, 2020

QuLogic commented Dec 3, 2020

tacaswell commented Dec 3, 2020

QuLogic commented Dec 8, 2020

tacaswell commented Dec 16, 2020

tacaswell commented Dec 16, 2020

jfbu commented Jan 26, 2021