Tracking changes

Another limitation of using LaTeX is that you can't easily see what's changed between versions of PDFs. This makes collaboration using LaTeX difficult.

Word, for example, has a very useful "Track changes" feature that lets you record your changes and then lets the next person easily review them and decide which ones are to be applied.

There are various tools strewn over the Internet that do help with this, but they aren't quite as convenient as I'd have hoped. Some examples:

• latexdiff (Zaphod is based on this and uses it to generate changes - why reinvent the wheel?)
• the changes package
• track changes (didn't try this out)

The workflow - an example

• Create a Git repository for your LaTeX paper.
• Write your draft.

I'm using a test repository which looks like this:

[asinha@ankur  latex-changes(master=)]$ tree
.
├── LICENSE
├── README.rst
└── src
    ├── abstract.tex
    ├── conclusion.tex
    ├── discussion.tex
    ├── introduction.tex
    ├── Makefile
    ├── methods.tex
    ├── paper.pdf
    ├── paper.tex
    └── results.tex

1 directory, 19 files
[asinha@ankur  latex-changes(master=)]$

• Commit your changes.

Your repository will look something like this:

[asinha@ankur  latex-changes(master=)]$ git lg
* 280fef6 - (4 days ago) Subsection test — Ankur Sinha (Ankur Sinha Gmail) (HEAD -> master, origin/master, origin/HEAD)
* 0c0238b - (4 days ago) Moved script to its own repository — Ankur Sinha (Ankur Sinha Gmail)
....
* 164e0d3 - (8 days ago) Add vim temp files to gitignore — Ankur Sinha (Ankur Sinha Gmail)
* bd02966 - (8 days ago) Commit fake paper — Ankur Sinha (Ankur Sinha Gmail)
* 11ad32b - (8 days ago) Initial commit — Ankur Sinha

This is all pretty standard Git usage. Now, the interesting part:

• Send your PDF and LaTeX sources to your collaborator (or give them access to your repository).
• They make changes and commit them. Now, your Git revision tree will look something like this:

[asinha@ankur  latex-changes(master=)]$ git lg
* 46d0c11 - (4 hours ago) Add a new file. — Ankur Sinha (Ankur Sinha Gmail) (HEAD -> master, origin/master, origin/HEAD)
* ba4b06d - (3 days ago) Update readme — Ankur Sinha (Ankur Sinha Gmail)
* 53033b8 - (3 days ago) Remove example output directory — Ankur Sinha (Ankur Sinha Gmail)
* d82266b - (4 days ago) More subsection changes — Ankur Sinha (Ankur Sinha Gmail)
* 280fef6 - (4 days ago) Subsection test — Ankur Sinha (Ankur Sinha Gmail)
  ...

Zaphod lets you specify two Git revisions and generates a list of changes between these two. So, for example, running the diff command would do this:

[asinha@ankur  latex-changes(master=)]$ python3 ../zaphod/zaphod.py diff -r bd02966 -m paper.tex -s src
 ....
 ....
 COMPLETE: The following branches have been created:
 201602131935-latexdiff-rev1: Revision 1.
 201602131935-latexdiff-rev2: Revision 2.
 201602131935-latexdiff-annotated: Branch with annotated versions of sources and diff pdf.
 The generated diff pdf is: src/diff-bd02966-master.pdf.

and your repository now looks like this:

* 9e58178 - (2 minutes ago) Save annotated changes between bd02966 and master — Ankur Sinha (Ankur Sinha Gmail) (HEAD -> 201602131935-latexdiff-annotated)
* 46d0c11 - (5 hours ago) Add a new file. — Ankur Sinha (Ankur Sinha Gmail) (origin/master, origin/HEAD, master, 201602131935-latexdiff-rev2)
* ba4b06d - (3 days ago) Update readme — Ankur Sinha (Ankur Sinha Gmail)
....
* bd02966 - (8 days ago) Commit fake paper — Ankur Sinha (Ankur Sinha Gmail) (201602131935-latexdiff-rev1)
* 11ad32b - (8 days ago) Initial commit — Ankur Sinha

Zaphod uses latexdiff to check for differences between the two revisions, marks them as branches for easy reference, and then creates a new branch with annotated source files and a nice pdf which looks like this:

That looks rather nice, isn't it? And it resembles what a Word document with annotations looks like too. latexdiff has various markup styles which can be passed to Zaphod as arguments to modify how the annotations look. The most important part here is that because Zaphod is using mighty Git, there's no chance of you losing any work at all. In fact, if you have untracked and uncommitted changes in your repository, Zaphod refuses to run at all.

Now, a look at how the revise function works:

[asinha@ankur  latex-changes(201602131935-latexdiff-annotated)]$ python3 ../zaphod/zaphod.py revise -s src/ -m paper.tex
Working on file: src/paper.tex.
File under revision: src/paper.tex

Deletion found:
---
Tracking
---

Delete? Y/N/y/n: y
Deleted

File under revision: src/paper.tex

Addition found:
+++
Visualising
+++

Add? Y/N/y/n: n
Skipped

File under revision: src/paper.tex

Addition found:
+++
\input{discussion}

+++

Add? Y/N/y/n:
....
....
....
[201602131935-latexdiff-annotated 3ba757f] Save after going through changes
 5 files changed, 34 insertions(+), 56 deletions(-)
 create mode 100644 src/accepted.pdf
 rewrite src/paper.tex (72%)

COMPLETE: Changes accepted and committed.
The generated pdf is: src//accepted.pdf.
You can merge this branch to master if you wish.

and your repository looks like this:

[asinha@ankur  latex-changes(201602131935-latexdiff-annotated)]$ git lg
* 3ba757f - (53 seconds ago) Save after going through changes — Ankur Sinha (Ankur Sinha Gmail) (HEAD -> 201602131935-latexdiff-annotated)
* 9e58178 - (17 minutes ago) Save annotated changes between bd02966 and master — Ankur Sinha (Ankur Sinha Gmail)
* 46d0c11 - (5 hours ago) Add a new file. — Ankur Sinha (Ankur Sinha Gmail) (origin/master, origin/HEAD, master, 201602131935-latexdiff-rev2)
....

The new pdf, accepted.pdf, is the latest version of your document and includes the changes you think should make the cut. If you're happy with these, you can simply merge this branch into master, and continue working. If you're not, you can go back to master, or another commit, and tinker some more - we're using Git, do what you want. In line with what I did above, the PDF looks like this:

Pretty neat, huh? At least I think so ;)