Both LaTeX Versions Compile, but the Latexdiff File Does Not

The old manuscript compiles. The revised manuscript compiles. Then latexdiff produces a file that fails somewhere inside a table, equation, custom command, or long preamble.

That does not usually mean the revision is lost. It means the redline is a third LaTeX program, with its own generated commands and failure modes. Build it as deliberately as the two manuscripts it compares.

Freeze two versions that build on their own

Start with two complete snapshots, not two loose main.tex files copied from different moments:

revision-package/
├── old/
│   ├── main.tex
│   ├── sections/
│   ├── figures/
│   └── references.bib
└── new/
    ├── main.tex
    ├── sections/
    ├── figures/
    └── references.bib

Record the engine and build command, then compile both snapshots independently:

cd old
latexmk -pdf -interaction=nonstopmode -halt-on-error main.tex

cd ../new
latexmk -pdf -interaction=nonstopmode -halt-on-error main.tex

If one baseline does not compile, stop there. A redline cannot tell you whether an error came from the manuscript, the environment, or the inserted diff markup when one of its inputs was already broken.

This is also the moment to record the actual toolchain:

pdflatex --version
latexmk -v
latexdiff --version

“It works in Overleaf” is useful evidence, but it is not a version number. Package order and indirectly loaded packages can change behavior even when the visible source looks the same.

Flatten multi-file projects before comparing them

For a small single-file paper, the ordinary command is enough:

latexdiff old/main.tex new/main.tex > new/redline.tex

Most papers are not single files. They use \input, \include, \subfile, figures, and a bibliography. The current latexdiff manual documents --flatten, which expands included body files recursively:

latexdiff --flatten old/main.tex new/main.tex > new/redline.tex
cd new
latexmk -pdf -interaction=nonstopmode -halt-on-error redline.tex

Keep the old/ and new/ trees intact until the redline is accepted. Flattening makes comparison easier, but the generated file no longer mirrors the source hierarchy. It should be reproducible output, not the new canonical manuscript.

If the manuscript is already in Git, latexdiff-vc can compare named revisions. The same rule still applies: pin the two revisions and save the exact command used to produce the PDF.

Generate first, compile second

Overleaf documents both a latexmkrc route and a \ShellEscape route in its latexdiff guide. They are convenient for a small example. For a complicated submission, I prefer generating redline.tex as an explicit step and compiling it separately.

That separation gives you two logs:

  1. Did latexdiff finish and create sensible TeX?
  2. Did the generated TeX compile in the same environment as the revised manuscript?

It also prevents a normal manuscript build from silently regenerating a different redline because one of the inputs changed.

If you must generate inside Overleaf, keep the official latexmkrc or shellesc pattern small, confirm which file is selected as the main document, and download the exact old and new project snapshots used for the editor request. Overleaf’s History feature can download named versions; relying on memory or “the file from last week” is much harder to audit.

Read the first real error, not the last fifty

Diff markup often causes a cascade. The useful error is normally the first one after redline.tex begins compiling.

Open the log and ask four questions:

  1. Is the failing command present in old/main.tex, new/main.tex, or only in redline.tex?
  2. Is it inside math, a moving argument, a table cell, a caption, or a citation?
  3. Did the redline insert \DIFadd or \DIFdel across a command boundary?
  4. Does the same generated file fail in the exact environment where new/main.tex succeeds?

Do not start by deleting packages from the revised manuscript. That may make the redline compile while changing the paper the editor is supposed to review.

For a custom command that merely wraps text, teach latexdiff how to treat it. The manual provides command lists such as --append-safecmd and --exclude-textcmd. Keep that configuration in a file or build script so the fix is repeatable. Do not add every unfamiliar macro to a safe list: commands that change counters, write files, or expect fragile arguments deserve closer inspection.

For equations and tables, reduce one failing region at a time. Generate the redline again after each configuration change, compile it, and compare the rendered page with both clean PDFs. A redline that builds but hides a changed minus sign, row, caption, or citation is not finished.

Keep the editor-facing PDF separate from revision history

Overleaf’s native Track Changes is useful while collaborators are editing. A journal redline answers a different question: what changed between two accepted manuscript states?

For that, keep three artifacts:

  • the baseline PDF;
  • the clean revised PDF;
  • the redline PDF generated from their matching sources.

Add a short manifest with source hashes, engine, command, date, and unresolved warnings. If the response letter says “revised in Section 3,” verify the location in the current clean PDF. Use the redline to see the change, not as the only source of page and section locations.

A quick audit can save a long repair

I ran this check on the public PaperAgentDemo scaffold. Its current main.tex builds reproducibly with latexmk into a two-page A4 PDF; the final pass resolves the equation, algorithm, and table references. But the repository has no distinct manuscript baseline, and the checked toolchain does not include latexdiff. So it is a useful clean-build sample, not yet proof of a redline workflow.

That boundary matters. Before promising a journal-ready revision package, prove all three builds, preserve the baseline, and keep every manual exception in a script or audit note.

The public synthetic redline sample now keeps the old source, revised source, three PDFs, generated redline.tex, clean final logs, and a hash manifest together. It is deliberately one page: enough to reproduce the three-build path, not a claim about a complex customer manuscript.

I maintain a public plan-gated paper revision workflow for that process: stable manuscript files, named baselines, generated redlines, PDF-backed response locations, and explicit unresolved issues. Even if you never use the workflow itself, those five boundaries make a difficult latexdiff repair much easier to reason about.

If you want a second pair of eyes on one bounded paper, I also offer a USD 250 manuscript build and redline sprint. The free fit check asks only for the source shape, target template, and deadline; keep the manuscript private until we agree on the scope and handling.

Leave a Reply