LithosAnanake/docs/book/README.md

docs/book/

make docs builds one PDF, build/docs/LithosAnanke.pdf, from main.tex with xelatex. make docs TARGET=<board> builds build/docs/LithosAnanke-<board>.pdf: the same book with boards/<board>/README.md added as an appendix.

Tools: sudo apt-get install -y pandoc latexmk texlive-xetex texlive-latex-extra texlive-pictures texlive-fonts-recommended fonts-dejavu fonts-dejavu-extra

Without root, a user-local TeX Live works too (this is how the book was first built): TinyTeX (curl -sL https://yihui.org/tinytex/install-bin-unix.sh | sh) plus tlmgr install latexmk xetex fontspec pgf pgfplots booktabs multirow fancyvrb fvextra lineno upquote ulem enumitem newunicodechar bookmark hyperref geometry xcolor graphics tools etoolbox fancyhdr truncate amsfonts, and the pandoc release tarball unpacked into ~/.local.

The installed DejaVu decides italics: fonts-dejavu-core alone has no serif italic, so main.tex falls back to a slanted upright face; fonts-dejavu-extra gives real italics.

How it fits together

• main.tex is the master file. It sets the parts and the chapter order.
• Chapters that are still Markdown are listed in Makefile (CHAPTERS, as name:source.md). At build time pandoc converts each one into build/docs/gen/<name>.tex, and main.tex includes it with \input{<name>}. The Markdown stays the source until the chapter is rewritten in LaTeX. At that point the .tex moves into this directory and the CHAPTERS entry is removed.
• pandoc/highlighting.latex extracts the code-highlighting macros from the installed pandoc, so the macros and the fragments always come from the same pandoc version.
• Two Lua filters run on every chapter. pandoc/table-widths.lua gives wide tables proportional wrapping columns, because pandoc's gfm reader leaves column widths unset. pandoc/code-breaks.lua lets long inline identifiers and paths break after _ / . - :. Code blocks wrap through fvextra (breaklines).
• build/docs/<book|board>/meta.tex is written on every build. It records the commit (and whether there were uncommitted changes), the date, and the board.

Rule for data

Any figure or table that shows measured numbers is generated from the CSV when the book is built. Numbers are never typed in by hand:

\begin{tikzpicture}
  \begin{axis}[xlabel=run, ylabel=K]
    \addplot table[col sep=comma, x=run, y=K]{experiments/<campaign>/results.csv};
  \end{axis}
\end{tikzpicture}
\datasource{experiments/<campaign>/results.csv}

Use \pgfplotstabletypeset[col sep=comma]{...} for tables. \datasource prints the CSV path and the commit, so a reader can find the exact file the figure was drawn from. CSV paths are repo-relative, because xelatex runs from the repo root.

Older pipelines to fold in or retire

These still exist and still have their own targets. Each one needs a decision during the curation pass: move it into this book, or retire it.

Source	Current target	Produces
docs/formal/vol1-vm-physics, vol2-kernel, vol3-research	make -C docs/formal vols	three volume PDFs
docs/formal/dev-guide, user-guide, cookbook	make -C docs/formal books	three practitioner PDFs
docs/formal/experiments, proofs, ssrn, patent	make -C docs/formal standalone	four standalone PDFs
Doxygen (Doxyfile)	make -C docs/formal doxygen	API reference PDF
scripts/generate-doxygen-appendix.sh	make -f v3/Makefile api-docs	AsciiDoc API appendix
docs/src/internal/formal/*.thy	make -f v3/Makefile docs-isabelle	Isabelle report
scripts/asciidoc-to-latex.sh	make -f v3/Makefile docs-latex	docs/latex/
docs/SSRN_companion/Math_Companion_SSRN.tex	make -f v3/Makefile math-companion	SSRN math companion