use XITS for math typesetting (#70)

This change fixes up a conflict between fontspec and unicode-math, and chooses a better math font.

Author: chrisfenner

Dockerfile

@@ -44,7 +44,8 @@ RUN tlmgr update --self && \
     changepage \
     draftwatermark \
     appendix \
-    multirow
+    multirow \
+    xits
 
 RUN apk upgrade && apk add --no-cache \
     bash \

build.sh

@@ -315,9 +315,11 @@ if [ -n "${pdf_output}" ]; then
 		${extra_pandoc_options} \
 		--to=pdf \
 		--output="${pdf_output}"
-	echo "PDF Output Generated to file: ${pdf_output}"
 	if [ $? -ne 0 ]; then
 		RESULT=$?
+		echo "PDF output failed"
+	else
+		echo "PDF output generated to file: ${pdf_output}"
 	fi
 fi
 
@@ -358,9 +360,11 @@ if [ -n "${latex_output}" ]; then
 		${extra_pandoc_options} \
 		--to=latex \
 		--output="${latex_output}"
-	echo "LaTeX Output Generated to file: ${latex_output}"
 	if [ $? -ne 0 ]; then
 		RESULT=$?
+		echo "LaTeX output failed"
+	else
+		echo "LaTeX output generated to file: ${latex_output}"
 	fi
 fi
 
@@ -391,9 +395,11 @@ if [ -n "${docx_output}" ]; then
 		${extra_pandoc_options} \
 		--to=docx \
 		--output="${docx_output}"
-	echo "DOCX Output Generated to file: ${docx_output}"
 	if [ $? -ne 0 ]; then
 		RESULT=$?
+		echo "DOCX output failed"
+	else
+		echo "DOCX output generated to file: ${docx_output}"
 	fi
 fi
 
@@ -439,9 +445,11 @@ if [ -n "${html_output}" ]; then
 		${extra_pandoc_options} \
 		--to=html \
 		--output="${html_output}"
-	echo "HTML Output Generated to file: ${html_output}"
 	if [ $? -ne 0 ]; then
 		RESULT=$?
+		echo "HTML output failed"
+	else
+		echo "HTML output generated to file: ${html_output}"
 	fi
 fi
 

guide.md

@@ -716,6 +716,8 @@ To get an HTML table to word-wrap its contents, use `<colgroup>` to style the wi
 
 # Math {#sec:math}
 
+## Equations
+
 Markdown supports inline math notation. For example, @eq:fermat can be typeset as:
 
 ```md
@@ -726,8 +728,28 @@ Note the `{#eq:fermat}` at the end of the equation. This allows referencing @eq:
 
 $$ \nexists {n \ge 3; a, b, c \in \mathbb{Z}} \mid a^n + b^n = c^n $$ {#eq:fermat}
 
+## Inline math
+
 Sometimes, you just need a little inline math in the middle of a sentence, like with `$a^2 + b^2 = c^2$` to get $a^2 + b^2 = c^2$.
 
+## Words in equations
+
+To typeset complex equations with multi-character identifiers (such as the function "HMAC" or the word "OPAD") in @eq:hmac-iso,
+we recommend using the functions `\symbf` (for functions) and `\symup` (for identifiers).
+This avoids strange kerning issues where a string is treated as a product of single-character symbols, like in @eq:hmac-iso-bad-kerning:
+
+```md
+$$ \symbf{HMAC}(K, \symup{"text"}) \coloneq H((\bar{K} \oplus \symup{OPAD}) \Vert H((\bar{K} \oplus \symup{IPAD}) \Vert \symup{"text"})) $$ {#eq:hmac-iso}
+```
+
+$$ \symbf{HMAC}(K, \symup{"text"}) \coloneq H((\bar{K} \oplus \symup{OPAD}) \Vert H((\bar{K} \oplus \symup{IPAD}) \Vert \symup{"text"})) $$ {#eq:hmac-iso}
+
+```md
+$$ HMAC(K, "text") \coloneq H((\bar{K} \oplus OPAD) \Vert H((\bar{K} \oplus IPAD) \Vert "text")) $$ {#eq:hmac-iso-bad-kerning}
+```
+
+$$ HMAC(K, "text") \coloneq H((\bar{K} \oplus OPAD) \Vert H((\bar{K} \oplus IPAD) \Vert "text")) $$ {#eq:hmac-iso-bad-kerning}
+
 \beginappendices
 
 # Reporting Issues with the Tools

template/eisvogel.latex

@@ -70,18 +70,6 @@ $endif$
 \setstretch{1.0}
 \usepackage[absolute,overlay]{textpos}
 \usepackage{ifxetex,ifluatex}
-$if(mathspec)$
-  \ifxetex{}
-    \usepackage{mathspec}
-  \else
-    \usepackage{unicode-math}
-  \fi
-$else$
-  \usepackage{unicode-math}
-$endif$
-
-\defaultfontfeatures{Scale=MatchLowercase}
-\defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
 
 $if(luatexjapresetoptions)$
   \ifluatex{}
@@ -410,6 +398,17 @@ $endif$
 \newunicodechar{™}{\textfallback{™}}
 \newunicodechar{→}{\textfallback{→}}
 
+\usepackage[mathit=sym]{unicode-math}
+\setmathfont{XITS Math}
+
+% Customize the spacing for math to relax it a bit.
+\thinmuskip=6mu
+\medmuskip=8mu plus 4mu minus 2mu
+\thickmuskip=10mu plus 10mu
+
+\defaultfontfeatures{Scale=MatchLowercase}
+\defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
+
 %
 % Set the heading color and ensure that every section begins on its own page.
 %