README.md

LaTeX Cookbook

This repo contains a LaTeX document, usable as a cookbook (different "recipes" to achieve various things in LaTeX) as well as as a template. The resulting PDF covers LaTeX-specific topics and instructions on compiling the LaTeX source.

See the releases page for more downloads.

Important

This project is not archived, and issues are still addressed. However, the document is regarded as "done" and no new feature development actively happens. As LaTeX is a glacially slow-moving target, the document should be useful, valid and buildable for many years to come still.

There is a fork maintained by former coworkers of the author, at the research institute this template originated from as well. Active development is still happening there.

Getting started

After installing Docker (and git), building works out of the box:

• Bash:

  $ git clone [email protected]:alexpovel/latex-cookbook.git
  $ cd latex-cookbook
  $ docker run --rm --volume $(pwd):/tex alexpovel/latex
  $ xdg-open cookbook.pdf

• PowerShell:

  PS> git clone git@github.com:alexpovel/latex-cookbook.git
  PS> cd latex-cookbook
  PS> docker run --rm --volume ${PWD}:/tex alexpovel/latex
  PS> Invoke-Item cookbook.pdf

The entrypoint is latexmk, which when given no arguments (as done here) runs on all found *.tex files, which in this case is only the root's main file.

Note

Should this fail to compile (this is a bug, please report!), feel free to try other images. When alexpovel/latex was built, texlive/texlive did not exist yet. That image is strongly recommended, as it is actively maintained by the actual authors of TeXLive. If tools are missing, like inkscape, build your own image FROM texlive/texlive, then install required software.

Alternatively, there is a fork for the image as well, accompanying the template fork.

Features

The PDF itself has much more to say on this and is meant to speak for itself, visually. The following is simply a brief overview of the features contained in this repo.

Tooling

• accompanying Docker image, usable locally and in CI/CD, guaranteeing compilation success without interfering with your local installation. In fact, using Docker (containerization in general), no LaTeX installation is required at all.

  • accompanying Visual Studio Code environment configuration.

    If you open this repository in Visual Studio Code, it should automatically put you into the correct Docker container environment for development, and just work™. See here for more info.

  • in the image, pandoc is available with the Eisvogel template, allowing beautiful PDFs to be generated from Markdown (like this README: download it from the latest Actions artifacts; it currently looks lackluster because this README is mainly PNGs)

• tests for your PDF, using Python to ensure some (basic) properties of your output adhere to expectations
• a Makefile to facilitate ease of use and platform independence (commands like make file.pdf work locally as well as in CI pipelines)

LaTeX-specific

• full Unicode support through lualatex, the successor to the obsolete pdflatex. This also affords beautiful font typesetting through unicode-math. High-quality fonts like TeX Gyre Pagella have all desirable font shapes available:

• automatic compilation using latexmk, ensuring the PDF is built fully, running all steps necessary (generation of the bibliography, glossaries, ...) automatically as needed

• comprehensive support for:

  • generating indices,
  • typesetting and displaying symbols in an automatically generated nomenclature,
  • acronyms and abbreviations, as well as
  • mathematical constants,

  made possible through glossaries-extra.

• structured and commented source code, explaining rationales and providing context

• showcasing plotting and data display (floats):

  • computing more complicated plots (in this example, a contour plot) directly in LaTeX, with no explicit outside tools used (gnuplot is used by LaTeX in the background):

    

  • ingesting a CSV directly, and plotting it (so we can skip matlab2tikz etc.). The below style is inspired by Tufte:

    

  • typesetting more complex tables, with footnotes, decimal alignment and more:

    

  • using tikz:

    • for annotating bitmap graphics:

      

    • for drawing diagrams (this template contains a (basic) pgf/tikz library for energy systems/thermodynamics/hydraulics/... symbols like pipes, compressors, valves, ...) and 3D sketches. For a much better and comprehensive collection of TikZ examples, see here.

      

• back-referencing of citations, using the excellent biblatex:

  

• support for elaborate chemical reaction equations, using chemmacros:

  

• comprehensive code syntax highlighting, thanks to minted and pygments:

  

• quick and structural switching of language contexts, provided by polyglossia:

  

• of course, support for enhanced mathematical typesetting, like highlighted equations or premade macros. The blue color are hyperlinks, turning those symbols into links to the glossary (this can be toggled off).