ORE Studio Manual

./compass.sh build --direct manual

This invokes emacs -Q --script projects/ores.lisp/src/ores-build-manual.el, which calls org-latex-export-to-pdf on doc/manual/user_guide/user_manual.org. LaTeX is run twice (pdflatex × 2) so that cross-references and the table of contents are fully resolved.

Two custom classes are registered in ores-build-manual.el:

• ores-manual — a plain book class (a4paper, 11pt). Heading hierarchy: * → \chapter, ** → \section, etc. Used as a fallback.
• ores-tufte — the primary class, based on tufte-book (a4paper, justified). Provides the wide-margin aesthetic: sidenotes, margin figures, and full-bleed headings. tufte-book manages its own geometry, fonts, and hyperref; user_manual.org keeps only a minimal preamble.

Small figures (width ≤ 510 px AND height ≤ 320 px) are automatically promoted to LaTeX marginfigure environments by the ores/figures-to-margin filter, registered via org-export-filter-final-output-functions. Larger screenshots stay in the text column. This transform is LaTeX-only; the HTML site is unaffected.

The filter inspects each \begin{figure}…\end{figure} block, reads the PNG header of the referenced image to get pixel dimensions, and rewrites the block to \begin{marginfigure} when both thresholds are met.

org-latex-image-default-width is set to \\maxwidth, a custom LaTeX macro defined in user_manual.org that yields the image's natural pixel width when it is smaller than 0.6\linewidth, and 0.6\linewidth otherwise. This prevents large dialog screenshots from overflowing the text column while letting small crops render at their natural size.

The manual is exported to both PDF (pdflatex) and HTML (via the site pipeline). The two exporters handle links differently, so authors must follow these rules:

• Internal links (within the manual): [[id:UUID]] org-roam links between manual chapter files are permitted. The exporter resolves them as \hyperref internal cross-references in the PDF and as anchor links in the HTML. Both work correctly.
• External links (outside the manual): [[id:UUID]] links to any document outside doc/manual/ — knowledge docs, recipes, agile artefacts — must not be used in chapter files. The deploy_manual pipeline scans only the manual's own org-id index; an unresolvable ID aborts the export with an error. Use a plain HTTP URL ([[https://example.com][label]]) or a plain text citation instead. If the target document has a canonical public URL (e.g. an ISO standard or a Wikipedia article) use that. If there is no public URL, use italic prose: /Document Title/ (=path/to/file.org)=.
• Image links: [[file:../../../assets/images/foo.png]] links are fine; they resolve to the asset path at export time.
• Site-only files (user_manual_site.org, manuals.org): these are not included in the PDF export and may freely use [[id:UUID]] links for site navigation.

The cover page version number is read at export time from CMakeLists.txt by ores/cmake-version, which greps for the project(OreStudio VERSION …) line. This keeps the PDF cover in sync with the single source of truth without any manual update step.

A custom org-latex-title-command generates the cover page: centred title, author, version, and the login-screen screenshot (assets/images/login_screen.png) scaled to 60% of the text width.