| name | building-the-paper |
| description | Build the manuscript to PDF/DOCX/HTML, create figures and diagrams, manage cross-references, and run writing-quality checks (lint, grammar, readability). |
Building the Paper
Building
make bib first, so the bibliography is currentmake pdf (or make docx, make html, make all)- Report the output location (
output/manuscript.pdf etc.)
The PDF engine prefers tectonic (self-contained, downloads LaTeX packages on demand), falling back to xelatex. Override: make pdf PDF_ENGINE=xelatex. An unresolved [@key] citation breaks the PDF build — check the build log for "citation ... not found".
make wordcount — words in the manuscriptmake clean — remove generated outputmake diff OLD="manuscript/draft-v1.md" NEW="manuscript/main.md" — track-changes PDF between versions
Figures and diagrams
- Ask what kind: flowchart/sequence → Mermaid; data plot → gnuplot
- Diagrams: write
figures/name.mmd, then make figure SRC="figures/name.mmd" (make figures builds all)
- Plots: write
figures/name.gp, then make plot SRC="figures/name.gp"
- Add to manuscript:
{#fig:label}, reference with @fig:label
- Check figures in the built PDF at print size — titles overlap and legends shrink in ways the source preview hides
Cross-references (pandoc-crossref auto-numbers on build)
- Figures:
{#fig:label} → @fig:label
- Tables:
Table: Caption {#tbl:label} → @tbl:label
- Equations:
$$ ... $$ {#eq:label} → @eq:label
- Sections:
# Section {#sec:label} → @sec:label
Writing quality
make lint — prose style via Vale (passive voice, jargon, weasel words, hedging)make grammar — grammar/spelling via LanguageTool (optional tool, not installed by default — skip gracefully if missing)make readability — Flesch-Kincaid grade, fog index, sentence complexity- Summarize plainly: "3 style issues, 2 grammar issues; reading level grade 14 — appropriate for journals"
- Offer to fix issues directly in the manuscript
All three accept FILE="path" to check one file.
