Using latexdiff#

In some situation, e.g., in shepherding, we might be required to submit a PDF that highlights changes between two versions of a TeX project. For this, we can use latexdiff. It is a command line Perl script that runs locally (not on Overleaf) that compares two versions and automatically creates a markup that visually highlights deletions and additions between the two versions.

latexdiff. latexdiffis a fairly old project, although still being maintained, but might come with unecepected pitfalls. Expect a painful journey and manual bug fixing, as not everything might work out-of-the-box. That said, plan additional time ahead, and (ideally) don’t try this a few hours before a deadline.

Step by Step Guide:#

The following guide outlines how to create a diff LaTeX document with latexdiff.

Step 1: Install latexdiff#

latexdiff is available for Windows, Mac, and Linux. Our easiest way so far was to use it with TeX Live under Linux.

Step 2: Download the LaTeX source of the old and new version from Overleaf.#

Once you know that you will want to create a LatexDiff, it is very helpful to mark the current (old) version in Overleaf before you begin to make any changes (History -> Click on appropriate version -> “Label this version” in the top left)

To get the input files for your latex diff, go to history (“Single version mode”), select the version you want, and click “Download project at this version”. Once you have done this, you should have two .zip files, one containing the original (old) version, and one containing the revised (new) version.

Step 3: Unzip old and new version#

Unzip both archive files and place them in two seperate folders (old/ and new/).

Step 4: Compile both versions one time#

As latexdiff needs the .bbl files that are created upon compilation of the project, we need to compile each project once. Alternatively, you can grab them from Overleaf (‘Other logs and files’ at the bottom of the warning/log screen). Note that you might need to import older versions of the project into a new one to be able to compile the respective .bbl, and that you need to move the .bbl in the same folder as your main.tex, and rename it accordingly (typically main.bbl). This can be a bit fiddly, but if you do not have Tex installed locally, it might be easier.

For example, you can compile those locally (in each of the two folders):

latexmk -pdflatex -pvc -view=none main.tex

Step 5: Create the diff file#

Create the diff file by running:

latexdiff old/main.tex new/main.tex --flatten > diff.tex

--flatten is an option that is needed to follow \input{} and \include{} commands, as we usually have not a single flat file project, but split them across multiple .tex files. The resulting diff.tex is therefore completely flattened, i.e., it contains all text in a single file and does not load any additional files via \input{} and \include{}.

latexdiff then creates a new diff.tex file that contains the marked-up changes. The script might produce some warnings that can be ignored most times.

If recompilation later fails, experiment with different markup options like -t CFONT. (This fixed many problems for us, but is not the most beautiful markup.)

Step 6: Compile the diff-ed version#

Overleaf#

To compile the diff using Overleaf, upload the resulting diff.tex file to the root folder of your Overleaf project. Go to the Menu and select the diff.tex file as the main document, then compile.

Note: If it still compiles your normal main.tex, Overleaf tries to be “smart” and compiles the file you’re currently looking at. Open diff.tex in the editor to fix it (or explicitly change the Overleaf project setting).

Locally#

1. Move diff.tex to new/.
2. Compile Tex to PDF:

   latexmk -pdflatex -pvc -view=none diff.tex

Step 7: Check for warnings, errors, PDF and resolve any issues#

Check the compiled PDF for formatting and styling errors. You may also have to troubleshoot additional compilation errors and warnings depending on what LaTeX packages your project uses. This is a highly manual process that takes time, and is hard to debug. Currently there seems to be no real plan for this. First thing to try is to check different markup options, as outlined above.

Experiences, Problems, and (Possible?) Solutions#

As a general rule of thumb, check the logs for any errors and warnings when compiling diff.tex to PDF. Chances are, that there will be some problem, especially with tables (in our experience). Any error should be investigated in detail, also check the PDF visually for any problems.

If you have any errors, you can try some of the following things.

• Make sure both versions that you want to latexdiff compile on their own without errors. That way you know that a problem was introduced in the diffing process itself.
• Try to change the markup first. latexdiff offers several different markups for deletions and additions in text. In one case, setting the option -t CFONT, helped to compile the diffed version without problems.
• In our experience, latexdiff works especially bad in more complex tables (e.g., multicolumns, booktab’s rules, etc.). You might try to exlucde whole environments from diffing. Some more hints in this SO post.
• You might want to change how specific commands are treated by latexdiff, e.g., as necessary for scalebox, or special caption commands.

Manually Troubleshooting Tables#

The following describes one approach that can manually (i.e., after running latexdiff) fix problems we once had with tables. (There might be other or better solutions. However, the following one worked and we had no time to invesitgate more.)

The problem is, that specific commands like \multicolumn, \toprule, etc. require to not have any non-expandable commands before themselfes. However, latexdiff does not handle this when diffing, violating this “rule”. In that case, you get errors similar to the following:

! Misplaced \noalign.
\toprule ->\noalign 
                    {\ifnum 0=`}\fi \@aboverulesep =\abovetopsep \global \@b...
l.2483 \end{tabularx}

(The error might also come slightly different, such as ! Misplaced \omit. \multispan ->\omit.)

To give an example, the following is an excerpt from a table as in the output of latexdiff:

\DIFaddbeginFL \begin{tabularx}{\columnwidth}{X>{\hspace{12pt}}rrr>{\hspace{12pt}}rrr>{\hspace{8pt}}r}  
    \DIFaddendFL \toprule
   \DIFdelbeginFL \textbf{\DIFdelFL{Target}}%DIFAUXCMD
\DIFdelendFL & \DIFaddbeginFL \multicolumn{7}{c}{\textbf{Target}} \\

The problem here is the \DIFaddendFL, which is before \toprule where it should not be. We can just remove it, together with the openein \DIFaddbeginFL, as it is only marking an addition, but highlighting it in the PDF later (the enclosed line handels width and number and type of columns – visuallising this diff in the PDF does not make sense anyway). This results in the following “fixed” version, that should compile without problems.

\begin{tabularx}{\columnwidth}{X>{\hspace{12pt}}rrr>{\hspace{12pt}}rrr>{\hspace{8pt}}r}  
     \toprule
     \DIFdelbeginFL \textbf{\DIFdelFL{Target}}%DIFAUXCMD
\DIFdelendFL & \multicolumn{7}{c}{\textbf{Target}} \\

Also watch out for removed lines, which might cause similar problems (the link also contains a sed command that might be worth trying).