How can you use LaTeX to write a document with other people?

Question

I imagine that many users are or were [PhD] students, so I would like to know: how do you use LaTeX to write a document (like the final dissertation) that requires many revisions from other people.

When I work with my professor, I usually send him a PDF generated by LaTeX and the source files. He then uses a process like such:

• Define some color for his commentaries or additions to the text

  \usepackage{xcolor}
  ...
  \define{\profSmith}[1]{{\color{red} #1}}
  ...
  Lorem ipsum \profSmith{not very clever}
  

• He sends me his changes and I check his observations, marking my changes with another \define

• Repeat until everyone is satisfied
• For final versions comment defines and replace for \define{\profSmith}[1]{#1}

So yes, it is a bit cumbersome. I have tried margin notes, but space is limited and sometimes the professor's correction are inside some phrases or paragraphs.

I also thought about Version control differences (like svn, mercurial, etc), but my chances are low: everyone but me uses a one-liner for each paragraph. In consequence, I have a hard time checking these differences.

What do you guys [would] use in this case? Any other ideas or comments?

Answer 1

I am using todonotes with enlarged margins. You just enlarge the size of your document and one margin, but you keep the textwidth the same. You need to use the geometry package for that.

I actually wrote a blogpost about it.

A nice point about todonotes is that they are configurable (you can change the colour & background colour of your notes), that way you can define a \todojim{} command, a \todojeff{} command with different colour sets and you will know without any ambiguity who wrote the note.

Of course this would not be complete without a proper version control system. Pick your favourite!

Answer 2

I use the changes package, which allows authors to mark their changes and makes them colourful and so easier to spot. There's also the latexdiff program which is a bit like running diff except that you can process the output via LaTeX and get a more useful way of displaying the differences, (see also ldiff).

One tip if you're using non-LaTeX-specific tools (such as a DVCS or commands like diff): use linebreaks only at the end of sentences. It makes the output from diff (and similar) much more informative (for more detailed reasoning, see this part of my experiences of switching to using a DVCS with LaTeX).

Answer 3

My 2 cents (from experience with my thesis + several papers):

• even if your coauthors don't use version control, use it alone for your own work.

• typical workflow: give the .tex to your advisor, tell him to modify the source file directly, and forget about macros to mark differences manually. Whenever you get a revised version back from him, check it in (you can use git commit --author to mark these changes as made by him).

• Even better, once you are familiar with branches you can keep a separate branch advisor with the last version shared with him and merge the changes back in when you receive a revision.

• if you have good LaTeX habits (i.e., you don't skip curly brackets like in \frac a b or \tilde a), then latexdiff works painlessly and does a great job of highlighting the differences. Don't send you advisor the pdf, send him the tex and the pdf output from latexdiff; this will save him a lot of time, too.

• everyone around you writes paragraphs in a single source line? Consider yourself lucky: my advisor used an Emacs macro that did "hard" text rewrap adding newlines in random places in the document.

• as mentioned above, git diff --color-words highlights word differences.

Answer 4

Git has nifty options to do diffs like you want =)

http://idnotfound.wordpress.com/2009/05/09/word-by-word-diffs-in-git/

Also consider this tip to store preamble as a git submodule:

http://markelikalderon.com/2008/07/31/keeping-your-latex-preamble-in-a-git-submodule/

Answer 5

I think the free web-based Overleaf is worth mention. With this tool, all authors can share documents, review, comment and edit. Since it is web-based all documents will be accessible across platforms.

Answer 6

I am one of the co-founders at Authorea and we recently have witnessed and supported the writing of very large collaborative papers in High Energy Physics. One example is this paper by the CERN TLEP collaboration (300+ authors).

Authorea brings authorship of articles to the web and uses the web's native collaborative infrastructure to enable collaboration (and Git for version control). Authorea solves the problem that many scholars have when they tell their co-authors: "please do not touch the article, I am working on it". In Authorea, articles are modular (e.g. one module = one section). Only one article collaborator can check out and work on a module at any time, so that the entire article stays open for editing but individual elements are checked out and then checked back in with edits.

Rather than using ad-hoc methods for providing comments (e.g. color highlighting), authors can use a commenting system (public and private), integrated with an article-based chat.

Answer 7

You can use a diff/merge tool to jump through each change made in a file and decide whether you want to accept that change or not. I personally use diffmerge (which is free).

If the other users were to each access your source control system (or if you checked in Professor Smith's changes under an appropriate username), several source controls have a "blame" feature that allows you to identify who made a change to a file (based on who checked that version in).

Answer 8

I usually use Dropbox to manage files, using comments in the code to specify changes and notes, though the collaboration is usually done somewhat synchronously, with communication in some other form (IM, talking IRL, etc.) to help co-ordinate who is doing what...

Answer 9

There is a new git-based web tool named SciGit that aims to do exactly that with LaTeX and other formats. It is still beta, but I've tested it and it looks promising though it's still rough around the edges. I would recommend it if you are working with text-based documents (LaTeX!) but not yet with stuff like MS Word docs (unlikely in TeX.sx!).

Answer 10

I use svn to do version control (but I am the only one with access to the repository, so all I manually commit all edits sent to me via e-mail, with comments about who did what either included in the commit log or in the file itself as comments).

To see and merge differences, I just use vimdiff, which is the same as using the diff mode in the vim editor. This, however, requires prior knowledge on how to use vim.