LaTeX: use XITS and XITS Math for wide enough Unicode coverage

jfbu · QuLogic · commit 53d417051538 · 2020-11-12T22:10:54.000-05:00
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.
diff --git a/doc/conf.py b/doc/conf.py
@@ -352,8 +352,43 @@ def _check_dependencies():
 latex_elements['babel'] = r'\usepackage{babel}'
 
 # Font configuration
-# Sphinx default since 2.x is GNU FreeFont
-latex_elements['fontpkg'] = r'\setmainfont{DejaVu Serif}'
+# Sphinx 2.0 adopts GNU FreeFont by default, but it does not have all
+# the Unicode codepoints needed for the section about Mathtext
+# "Writing mathematical expressions"
+latex_elements['fontpkg'] = r"""
+\setmainfont{XITS}[
+  Extension      = .otf,
+  UprightFont    = *-Regular,
+  ItalicFont     = *-Italic,
+  BoldFont       = *-Bold,
+  BoldItalicFont = *-BoldItalic,
+]
+\setsansfont{FreeSans}[
+  Extension      = .otf,
+  UprightFont    = *,
+  ItalicFont     = *Oblique,
+  BoldFont       = *Bold,
+  BoldItalicFont = *BoldOblique,
+]
+\setmonofont{FreeMono}[
+  Extension      = .otf,
+  UprightFont    = *,
+  ItalicFont     = *Oblique,
+  BoldFont       = *Bold,
+  BoldItalicFont = *BoldOblique,
+]
+% needed for \mathbb (blackboard alphabet) to actually work
+\usepackage{unicode-math}
+\setmathfont{XITS Math}
+"""
+# Sphinx <1.8.0 or >=2.0.0 does this by default, but the 1.8.x series
+# did not for latex_engine = 'xelatex' (as it used Latin Modern font).
+# We need this for code-blocks as FreeMono has wide glyphs.
+latex_elements['fvset'] = r'\fvset{fontsize=\small}'
+# Fix fancyhdr complaining about \headheight being too small
+latex_elements['passoptionstopackages'] = r"""
+    \PassOptionsToPackage{headheight=14pt}{geometry}
+"""
 
 # Additional stuff for the LaTeX preamble.
 latex_elements['preamble'] = r"""
