Skip to content

Commit

Permalink
Move font hints from README into cookbook
Browse files Browse the repository at this point in the history 
Most of this content was duplication anyway
  • Loading branch information
@alexpovel
alexpovel committed Oct 18, 2021
1 parent a99df09 commit bcb4d69
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 122 deletions.
115 changes: 2 additions & 113 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# A LaTeX Cookbook
# LaTeX Cookbook

[![forthebadge](https://forthebadge.com/images/badges/gluten-free.svg)](https://forthebadge.com)
[![forthebadge](https://forthebadge.com/images/badges/compatibility-club-penguin.svg)](https://forthebadge.com)
Expand All @@ -10,116 +10,5 @@
---

This repo contains a [LaTeX](https://en.wikipedia.org/wiki/LaTeX) [document](cookbook.tex), usable as a cookbook (different "recipes" to achieve various things in LaTeX) and also as a template.
The resulting PDF covers LaTeX-specific topics and instructions on compiling the LaTeX source using Docker.
The resulting PDF covers LaTeX-specific topics and instructions on compiling the LaTeX source.
It is available for [**download**](https://collaborating.tuhh.de/alex/latex-git-cookbook/-/jobs/artifacts/master/raw/cookbook.pdf?job=tex).

This very README is also made available for [download as a PDF](https://collaborating.tuhh.de/alex/latex-git-cookbook/-/jobs/artifacts/master/raw/README.pdf?job=README.pdf), converted from Markdown using [pandoc](https://pandoc.org/) with the [*Eisvogel*](https://github.com/Wandmalfarbe/pandoc-latex-template) template.

## Appendix

### Hints on Fonts

We use beautiful, capable fonts based on
[TeX Gyre](https://www.gust.org.pl/projects/e-foundry/tex-gyre/index_html)
for high-quality typesetting.
Particularly, [*TeX Gyre Pagella*](https://www.gust.org.pl/projects/e-foundry/tex-gyre/pagella)
as an open and free *Palatino* (by [Hermann Zapf](https://en.wikipedia.org/wiki/Hermann_Zapf))
clone.
It comes with [an accompanying math font](https://www.gust.org.pl/projects/e-foundry/tg-math),
*TeX Gyre Pagella Math*.
This is *extremely* important, since only with two matching (or even basically identical
fonts like in our case) fonts will a document like this one here look good.
If math and text fonts don't mix well, it will look terrible.
If the math font is not highly capable and provides all the glyphs we need,
it will also look terrible.

There aren't very many high-quality free fonts with a math companion available,
see [this compilation](https://tex.stackexchange.com/a/425099/120853).
A similar compilation of 'nice' fonts is [found here](https://tex.stackexchange.com/a/59706/120853),
however that is specifically for `pdflatex`, not `lualatex`.
Of all of the available ones, *Pagella* was chosen.
This can be changed with relative ease in the package options for the responsible package,
[`unicode-math`](https://ctan.org/pkg/unicode-math?lang=en).
If the new font does not come with at least the same amount of features,
parts of the document might break!
There is also a list of
[symbols defined by unicode-math](https://mirrors.ctan.org/macros/latex/contrib/unicode-math/unimath-symbols.pdf)
for reference.

`unicode-math` builds on top of and loads, then extends, `fontspec`.
`fontspec` is a package for `lualatex` and `xelatex` designed to allow usage of outside, system
fonts (as opposed to fonts that ship with latex distributions/packages).
These can be system-installed fonts, but **we bring our own fonts**, and they reside in this directory.
This is to ensure everyone can compile this repository/document,
as long as they have this subdirectory intact.
It is also OS-agnostic
(with system-installed fonts, calling them by their name can get really out of hand;
with plain filenames, we know exactly what to call them).
Some fonts ship with regular LaTeX distributions and are available *without* being explicitly installed by the user.
TeX Gyre fonts are an example.
These need to neither be included here nor installed, they are ship with the LaTeX installation (TeXLive).

The distinct advantage of `unicode-math` over its parent `fontspec` is the additional
feature of a **math font** (`\setmathfont`).

Note that `unicode-math` **requires** `lua(la)tex` or `xe(la)tex`.
You cannot compile this document with `pdf(la)tex`.
This also means that the packages `inputenc` and `fontenc` are *not needed*.
In fact, they are, as far as I know, incompatible and may break the document.
They used to be employed to allow advanced encoding for both the plain-text source as
well as the output PDF.
This allowed usage of Umlauts *etc.*, but that's a relic of a distant past.
In fact, if we wanted to, we could input Unicode characters *directly into the source code*,
*e.g.* `\(α = 2\)` over `\(\alpha = 2\)`
(we don't do this because we use an entirely different system in the form of [`glossaries-extra`](glossaries)).

Now, it remains to choose between `lualatex` and `xelatex`
(`luatex` and `xetex` exist too, but output to `DVI`, which we don't care for nowadays;
`lualatex` and `xelatex` output to `PDF`).
The choice falls to `lualatex` and is quite easy:

- we make use of the `contour` packages to print characters (of any color) with a thick
contour aka background around them (in any color as well).
Of course, the most obvious use is black text with a white contour.
Text set like that will be legible on various colored or otherwise obstructed
(for example by plot grids) page backgrounds.
To this purpose, there is the command `\ctrw{<text>}`, which is used *a lot*.
The `contour` capabilities don't care for math mode, font weight, size, shape...
it all just works.

Finally, the kicker here is that **it does not work in `xelatex`**.
I tried [this](https://tex.stackexchange.com/questions/421970/contour-text-in-xelatex)
and [this](https://tex.stackexchange.com/questions/354410/how-should-the-effects-of-manipulating-specials-be-switched-off)
and [this](https://tex.stackexchange.com/questions/225637/how-to-add-outline-to-a-character-under-xelatex)
and lastly [this](https://tex.stackexchange.com/questions/25221/outlined-characters)
and eventually failed horribly.
- further, `pdflatex`, with its roots in probably the 80s,
still to this day has strict and low memory limits.
For more advanced computations, it will
[complain and claim to be out of memory](https://tex.stackexchange.com/questions/7953/how-to-expand-texs-main-memory-size-pgfplots-memory-overload)
(the good old `TeX capacity exceeded, sorry`),
when in reality the host computer has Gigabytes and Gigabytes of RAM to spare.
This lead to the package/library `tikz-externalize`,
which puts Ti*k*z-pictures into their own compile jobs.
That way, each job is much smaller and can succeed within memory limits.
Another way to solve the limitation is to increase all the various memory limits manually,
to arbitrarily high values.
That this seems laborious, hacky and, well, arbitrary, is quickly apparent.

Now, even if we used `tikz-externalize`, it truncates the features we can make use of.
Since it exports the Ti*k*z environments to outside PDFs and then inputs those,
**labels/references/links cannot really be supported**.
I noticed this when I wanted equation references as a legend
(if that is a good idea is another question ...).
So `tikz-externalize` and its many caveats
(despite it being a brilliant solution to a problem we shouldn't even be having anymore nowadays)
is off the table.

`lualatex` simply solves all these concerns: it allocates memory as required.
I don't know to what degree it does this (if it can fill up modern machine memory),
but I can compile our entire document with countless Ti*k*z environments and demanding
plots (with high `sample=` values) with no memory issues.
As far as I know, `xelatex` doesn't do this, so forget about it.

These two reasons are easily enough to choose `lualatex` over `xelatex`.
I don't have more reasons anyway, since otherwise, the programs are quite identical.
39 changes: 30 additions & 9 deletions chapters/mainmatter/base-features.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,10 @@ \chapter{Base Features}
This is the go\-/to default for generating \abb{portable_document_format} output.
Its most popular modern alternatives are \hologo{XeLaTeX} and \hologo{LuaLaTeX}.
These two offer various new, shiny features, chief among which is Unicode
support through the package \ctanpackage{unicode-math}, which builds onto
\ctanpackage{fontspec} and extends it by capabilities for math fonts.
support through the \ctanpackage{unicode-math} package, which builds onto
\ctanpackage{fontspec} and extends it with math fonts capabilities.
Note that these packages \emph{require} \hologo{XeLaTeX} or \hologo{LuaLaTeX} use:
\hologo{pdfLaTeX} is \emph{old} and will no longer work.
More on that in \cref{ch:fonts_text}.

\hologo{LuaLaTeX} is preferred over \hologo{XeLaTeX} for the following reasons:
Expand All @@ -20,12 +22,18 @@ \chapter{Base Features}
\contour{black}{\textcolor{white}{this}}, works.
For an application of that, see \cref{fig:bitmap_tikz} on
\cpageref{fig:bitmap_tikz}.
Getting \ctanpackage{contour} to work on \hologo{XeLaTeX} is somewhat impossible.
Getting \ctanpackage{contour} to work on \hologo{XeLaTeX} is somewhat impossible,
see also
\href{https://tex.stackexchange.com/questions/421970/contour-text-in-xelatex}{here},
\href{https://tex.stackexchange.com/questions/354410/how-should-the-effects-of-manipulating-specials-be-switched-off}{here},
\href{https://tex.stackexchange.com/questions/225637/how-to-add-outline-to-a-character-under-xelatex}{here} and
\href{https://tex.stackexchange.com/questions/25221/outlined-characters}{here}.
\item \hologo{LuaLaTeX} allocates as much memory as it happens to need.
The ancient limitations of \TeX{} are easily reached by packages like
\ctanpackage{tikz} and \ctanpackage{pgfplots}.
Circumventing that either feels hacky, or actually is hacky.
\texttt{tikzexternalize} is a great module, but has a long list of caveats.
\texttt{tikzexternalize} is a great module, but has some caveats, like
breakage of clickable references.
It solves a problem that should no longer exist in the first place.
\item The fantastic \ctanpackage{microtype} package has a number of unavailable
functionalities when using \hologo{XeLaTeX}.
Expand All @@ -44,8 +52,8 @@ \section{Fonts and Text}
Using high-quality fonts is one goal.
This includes the fantastic
\href{https://ctan.org/texarchive/fonts/tex-gyre/opentype}{\TeX Gyre fonts},
of which the \textit{\href{https://en.wikipedia.org/wiki/Palatino}{Palatino}}
(by Hermann Zapf) clone \textit{\href{https://ctan.org/pkg/tex-gyre-pagella}{Pagella}}
of which the \emph{\href{https://en.wikipedia.org/wiki/Palatino}{Palatino}}
(by Hermann Zapf) clone \emph{\href{https://ctan.org/pkg/tex-gyre-pagella}{Pagella}}
was chosen for this document.
It comes with an accompanying
\href{https://ctan.org/texarchive/fonts/tex-gyre-math/opentype}{math font}
Expand All @@ -56,7 +64,20 @@ \section{Fonts and Text}
that is bogus and can be ignored.
}%
.
Using both fonts together is made possible by the \ctanpackage{unicode-math} package.
There are not very many high\-/quality free fonts with a math companion available,
see also \href{https://tex.stackexchange.com/a/425099/120853}{this compilation}.
A similar compilation of \enquote{nice} fonts is
\href{https://tex.stackexchange.com/a/59706/120853}{found here},
however that is specifically for \hologo{pdfLaTeX}, not \hologo{LuaLaTeX}.
The font choice can be changed with relative ease in the options for the
\ctanpackage{unicode-math} package.
If a new font does not provide at least the same array of features,
parts of the document might break!
For reference, there is a list of
\href{https://mirrors.ctan.org/macros/unicodetex/latex/unicode-math/unimath-symbols.pdf}{symbols defined by \ctanpackage{unicode-math}}.

Using both normal and maths fonts in conjunction is made possible through the
\ctanpackage{unicode-math} package.
As such, an exact match of the text and math fonts is achieved.
This is important but often overlooked.
However, such a match is often plain unavailable in the typesetting tool at hand.
Expand Down Expand Up @@ -119,7 +140,7 @@ \section{Fonts and Text}
easy on the eyes and very readable.

\paragraph{Old approach}
The overwhelming majority of \LaTeX{} documents rely on the two lines
The overwhelming majority of \LaTeX{} documents relies on the two lines
\begin{minted}[linenos=false]{latex}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
Expand All @@ -129,7 +150,7 @@ \section{Fonts and Text}
However, these two packages should at least not be used for \emph{new} work anymore!
Using \hologo{LuaLaTeX}, they are not required anymore:
\begin{itemize}
\item input encoding is automatically UTF-8 (as it should be in 2020),
\item input encoding is automatically UTF-8 (as it should be in \verb|$CURRENTYEAR|),
\item font encoding is also not required, since fully capable fonts are used,
which come with all the glyphs required.
\end{itemize}
Expand Down

0 comments on commit bcb4d69

Please sign in to comment.