8. Good practice and version control¶
8.1 A tidy project¶
paper/
main.tex the document's skeleton
sections/ one file for each section
figures/ generated by scripts
tables/ generated by scripts
refs.bib
code/ scripts that make the figures, tables and numbers
build/ outputs, not tracked
8.2 Version control¶
LaTeX is text, so Git handles it well. Put each sentence on its own line, so that a change shows as one changed sentence. Keep helper files out of Git with a .gitignore:
*.aux
*.log
*.out
*.toc
*.bbl
*.blg
*.synctex.gz
Tag each version you send out, as covered in the Git and automation guide.
8.3 Reproducible builds¶
A document is reproducible if someone else can rebuild it from your files.
-
Record the commands in a README or a script.
-
Generate figures, tables and numbers with code.
-
Build in a clean folder now and then, because old helper files can hide faults.
-
Keep paths relative, never tied to your own machine.
-
Fix
\date{...}to a real date for a version, because\todaychanges at every compile.
8.4 Accessible documents¶
-
Use real headings, lists and captions.
-
Choose colours with good contrast that still work in greyscale.
-
Prefer colourblind-safe palettes.
-
Set the document's title and language, for screen readers:
\hypersetup{pdftitle={...}}.
8.5 Working with others¶
Overleaf offers live co-editing, and it can sync with Git. Otherwise, agree who changes what, keep to one sentence per line, and use latexdiff old.tex new.tex > changes.tex to produce a marked-up comparison for readers who don't use Git.