diff --git a/README.md b/README.md index 4ec9445..61b0965 100644 --- a/README.md +++ b/README.md @@ -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) @@ -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](http://www.gust.org.pl/projects/e-foundry/tex-gyre/index_html) -for high-quality typesetting. -Particularly, [*TeX Gyre Pagella*](http://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](http://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](http://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{}`, 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. diff --git a/chapters/mainmatter/base-features.tex b/chapters/mainmatter/base-features.tex index 8a4ce4d..c5cbcf9 100644 --- a/chapters/mainmatter/base-features.tex +++ b/chapters/mainmatter/base-features.tex @@ -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: @@ -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}. @@ -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} @@ -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{http://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. @@ -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} @@ -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}