dspinellis/latex-advice: how to treat a LaTeX source file like the software it is

Advice with an explicit scope, and a long pedigree

This is a guide for writing LaTeX documents, aimed at people writing a scientific book, a paper or a thesis in computer science, engineering, mathematics, physics or a related field. The case for LaTeX in those fields is stated in terms of content rather than taste, particularly when the work contains formulas, symbols and heavy cross referencing.

The advice was collected over decades of writing hundreds of papers and books, and the author links to his own publication list as the evidence.

What the guide is not is as important as what it is. The introduction states that the list is not intended to provide advice on English writing style, scientific writing or TeX programming, and that there are many other excellent guides for all of these topics. That boundary is useful, because it is exactly the boundary that keeps a document about document engineering from turning into a writing course.

The table of contents gives the shape of the whole thing: version control, readable and maintainable source, an automated build, continuous integration, automated management of bibliographic references, style files, third-party packages, avoiding explicit formatting, symbolic references, then sections on mathematics, number and unit formatting, tables, figures, floats, typography, LaTeX formatting and writing, and finally pointers to further material. Contributions through GitHub pull requests are welcomed, and the last push to the repository was on 2026-09-21.

The source goes in Git, the PDF does not

The first advice is the most immediately useful, and it is the advice most people get wrong by accident.

Create a repository for the document and add all of its source code. It can live on GitHub if you plan to work with others or want a copy on another server, or it can be a local repository created with `git init`. What must not go in is the generated output: the formatted PDF, the compiled bibliographies, and PDF charts generated from R or Python scripts. Instead, add Makefile rules to create these files at build time. The stated reasons are that generated files needlessly increase the size of the repository, making cloning and fetching updates time-consuming, and that they pollute difference listings with immaterial changes.

The commit discipline advice is just as specific. Commit in logical chunks with meaningful commit messages, and do not combine heavy formatting changes such as adopting a different publisher's style with semantic changes such as edits following a second reviewer's suggestions, because a separate commit for each set of changes keeps the history readable. When you remove text, delete it completely rather than commenting it out, and let version control keep track of it.

Tag the revisions you submit, using annotated tag objects, so that you can return to a specific version while working through review comments or when starting a version for a new publication venue:

git tag -a
git push --tags

Pushing the tags to the online repository matters as much as creating them, since the point of tagging a submitted revision is that everyone can see it.

Semantic line breaks make the diff readable

The section on readable and maintainable LaTeX source opens with an instruction to treat the source with the same care as software code, and then makes a specific and unusual demand: avoid long lines, splitting text somewhere between column 60 and 70, and employ semantic line breaks, starting each phrase on a separate line and further splitting a phrase according to its logical structure.

The example makes the convention concrete.

Obtaining metrics from large code bodies is difficult
for technical and operational reasons~\cite{Moc09,GS13}.
On the technical side,
code dependencies make it difficult to establish
the full context needed in order to parse and semantically analyse the code.

The claim is that splitting lines at the level of phrases and a sentence's logical structure gives you three things. A line change corresponds at most to a single phrase, so difference listings read as prose edits rather than as rewrapped walls of text. Sentences or list elements can be reordered by moving lines around. And you get a second, structural view of the document that complements the flowed typeset output, which gives extra chances to spot syntax, grammar and style mistakes, including inconsistent or repetitive structure between the sentences of a paragraph.

That last benefit is the one that is easy to underestimate. The source file becomes a readable outline of the argument, and you can review the logic of a section without compiling anything. The cost is that you have to configure your editor to wrap at the right places, since the convention does not survive a reformat by a tool that does not know about it.

One file for a paper, one file per chapter for a thesis

The advice on splitting documents is conditional, and the condition is length. Short documents such as a journal or conference paper should not be split into files like `introduction.tex`, `methods.tex`, `results.tex` and `conclusions.tex`. The stated reason is that splitting makes three editor tasks harder: overviewing the material's composition, such as the balance of the sections' length, globally searching or replacing a particular term, and moving matter from one section to another. When the document is split, those tasks require switching from one file to another or reaching for external tools.

Long documents, such as a book or a thesis, are the opposite case. They should be split into multiple files, one for each chapter, in order to shorten the project's long build and loading times.

The tension between the two rules is real and the guide resolves it by document type rather than by principle, which is the right way to resolve it. A paper is a single unit of thought that people will read end to end and edit in one sitting, and splitting it buys nothing but friction. A thesis is built over months, compiled repeatedly, and worked on by several people at once, and the build time alone justifies the split.

The general lesson for a LaTeX project is that the source layout should follow how the document is edited rather than how a textbook suggests a large document is organised.

Comments, fold marks and a structural outline

The remaining source level advice is about making the file navigable.

Use comments, sequences starting with `%`, to indicate the key idea of each paragraph or section, and use comment keywords such as `XXX` or `TODO` to mark places where more work is needed. The keyword convention is the same one programmers use, for the same reason: a marker that can be searched for beats a marker you have to remember.

Then write the LaTeX code and configure the editor so that sections and paragraphs can be folded, which lets you inspect the document's structure as an outline. Where the editor needs help, add fold marks in comments, for example level 1 and level 2 folds for sections and subsections and a level 3 fold for paragraphs:

% Advantages of model-based development {{{3

The point is that folding gives a second, outline-shaped view of a document that is otherwise one long stream of text, and a writer working on structure benefits from seeing the skeleton separately from the prose.

These two habits, comments that name the idea and folds that mark the structure, are cheap to set up once and they change how you work with a long document, because the answer to what is in this chapter becomes a glance rather than a scroll.

Beyond the source file: build, CI, references and styles

The table of contents lists what comes after the source level advice, and it is where the guide turns from file organisation to a working practice.

Automate the document's build, and use continuous integration. The build automation theme is the same one that appeared in the version control section, where Makefile rules replace committed PDFs. Continuous integration extends it, so that a document that must compile is checked on every change rather than discovered broken when a co-author pulls it.

Automate the management of bibliographic references, which is the part of a LaTeX project that otherwise decays into a hand maintained `.bib` file with duplicated entries and dangling keys. Use style files, so that the visual conventions of a venue live in one file rather than in the body of the document. Use third-party LaTeX packages, and use symbolic references so that a change of numbering does not require hunting through the text.

Then there is the advice to avoid explicit formatting, which is the theme that runs through the later sections on mathematics, number and unit formatting, tables, figures and floats, and typography. The arguments there are about letting the style file do the work, so that the document remains portable between venues and the source stays readable.

The final sections point at additional material on LaTeX and on writing and presenting information, which is the guide acknowledging that it stops at a boundary. The repository itself is minimal: a `README.md` and a `schema.bib`. The licence is not one GitHub could classify, and there is no licence file in the tree, so the terms are the ones stated in the README's own licence section rather than a recognised open source grant.

Editorial conclusion

Adopt this guide if you write LaTeX for a living, as a researcher, a graduate student or a technical writer, because the specific advice on semantic line breaks, on what to keep out of version control and on how to split a document is the kind of thing that is expensive to learn by hand and free to read. Do not treat it as a style manual, since the author explicitly excludes English writing style, scientific writing and TeX programming from its scope, and do not expect it to answer questions about a specific publisher's requirements. Verify first which LaTeX distribution and packages you actually have available, since the guide points at style files and third-party packages without pinning versions, and check the licence situation yourself, since the repository does not carry a licence file that GitHub could classify.

Frequently asked questions

Official sources

1. dspinellis/latex-advice on GitHub
2. Issues
3. README