Collaborative Writing of LaTeX Documents

Collaborative writing of documents requires a strong synchronisation among authors. This guide describes various possible ways to organise the collaborative preparation of LaTeX documents.

1. First several methods are presented which are not based on a version control system.
2. Then several latex style files are discussed which are suited for collaboration.
3. This is followed by a solution which is based on the version control system Subversion. The guide describes how Subversion can be used together with several other software tools and LaTeX packages to organise the collaborative preparation of LaTeX documents.
4. Another approach is to use mercurial and bitbucket.

Other Methods (not version control based)

• You can use one of the online solutions listed in the Installation chapter. Most of them have collaboration features.
• Another option for collaboration is Dropbox. It has 2 GB free storage and versioning system. Works like SVN, but more automated and therefore especially useful for beginning LaTeX users. However, Dropbox is not a true versioning control system, and as such it does not allow you to roll the article back to previous versions. Web-based editor LaTeX Base supports syncing to Dropbox.
• You can use an online collaborative tool built on top of a versioning control system, such as Authorea or ShareLaTeX. Authorea performs most of the actions described in this document, but in the background (it is built on Git). It allows authors to enter LaTeX or Markdown via a GUI with mathematical notation, figures, d3.js plots, IPython notebooks, data, and tables. All content is rendered to HTML5. Authorea also features a commenting system and article-based chat to ease collaboration and review.
• As the LaTeX system uses plain text, you can use synchronous collaborative editors like Gobby. In Gobby you can write your documents in collaboration with anyone in real-time. It is strongly recommended that you use utf8 encoding (especially if there are users on multiple operating systems collaborating) and a stable network (typically wired networks).
• An instance of EtherPad. To compile use the command:

  wget -O filename.tex "https://etherpad.wikimedia.org/ep/pad/export/xxxx/latest?format=txt" && (latex filename.tex)
  

  
  where 'xxxx' should be replaced by the pad number (something like 'z7rSrfrYcH').
• With a dedicated Linux box with LaTeX & Dropbox it's possible to use Google docs and some scripting to get automatically generated PDFs on Dropbox from updates on Google Docs.
• You can use a distributed version control system such as Fossil, Mercurial or Git. This is the definitive solution for users looking for control and advanced features like a branch and merge. The learning curve will be steeper than that for a web-based solution.
• Syncthing is another opensource alternative to synchronizing files across machines.

Visualizing diffs in LaTeX: latexdiff and changebar

The tools latexdiff and changebar can visualize differences of two LaTeX files inside a generated document. This makes it easier to see the impact of certain changes or discuss changes with people not custom to LaTeX. Changebar comes with a script chbar.sh which inserts a bar in the margin indicating parts that have changed. Latexdiff allows different styles of visualization. The default is that discarded text is marked as red and added text is marked as blue. It also supports a mode similar to Changebar which adds a bar in the margin. Latexdiff comes with a script latexrevise which can be used to accept or decline changes. It also has a wrapper script to support version control systems such as the discussed Subversion.

An example on how to use Latexdiff in the Terminal:

latexdiff old.tex new.tex > diff.tex    # Files old.tex and new.tex are compared and the file visualizing the changes is written to diff.tex
pdflatex diff.tex                        # Create a PDF showing the changes

If you use mercurial the syntax is as follows latexdiff-vc --hg test.tex -r revnumber

where revnumber is the (local) revnumber of the relevant changeset.

Important advice:

Sometimes latexdiff runs into problems (the resulting latex code cannot be compiled). This can happen if there are major changes concerning mathematical equations. To deal with this difficulty latexdiff offers the option --math-markup:

1. --math-markup=3 very sensitive to changes in mathematical equations.
2. --math-markup=0 changes in mathematical equations are ignored. See the documentation for details.

The program DiffPDF can be used to compare two existing PDFs visually. There is also a command line tool comparepdf based on DiffPDF.

Useful LaTeX styles

Subfiles

In general for collaboration a modular approach is recommended since it minimizes the danger of conflicting edits. See the Modular Documents section for details; subfiles are recommended but not the only solution.

Todonotes

The todonotes.sty allows you to insert todo-items, either as margins or inline and adds a (hyperref supported) list of todos at the beginning document. What makes this package special (compared say to the fixme.sty) is the fact that the margin todo items point with a line to the text in question. This feature is familiar from Libreoffice, MS Office etc., see the manual for details at ctan.org/pkg/todonotes.

Here is an example:

\documentclass{article}
\usepackage[colorinlistoftodos, textwidth=3cm, shadow]{todonotes}
\newcounter{ubcomment}
\newcommand{\ubcomment}[2][]{%
\refstepcounter{ubcomment}%
{%
\todo[linecolor=black,backgroundcolor={green!40!},size=\footnotesize]{%
\textbf{Fixme: UB [\uppercase{#1}\theubcomment]:}~#2}%
} }
\newcommand{\ubcommentinline}[2][]{%
\refstepcounter{ubcomment}%
{%
\todo[linecolor=black,inline,backgroundcolor={green!40!},size=\footnotesize]{%
\textbf{Fixme: UB [\uppercase{#1}\theubcomment]:}~#2}%
} }

\newcommand{\ubcommentmultiline}[2]{%
\refstepcounter{ubcomment}%
{%
\todo[linecolor=black,inline,caption={\textbf{ {Fixme: UB}
    [\theubcomment] #1} } ,backgroundcolor={green!40!},size=\footnotesize]{%
\textbf{Fixme: UB [\theubcomment]:}~#2}%
} }

% add support for todo in equations
\usepackage{marginnote}
\makeatletter
\renewcommand{\@todonotes@drawMarginNoteWithLine}{%
\begin{tikzpicture}[remember picture, overlay, baseline=-0.75ex]%
    \node [coordinate] (inText) {};%
\end{tikzpicture}%
\marginnote[{% Draw note in left margin
    \@todonotes@drawMarginNote%
    \@todonotes@drawLineToLeftMargin%
}]{% Draw note in right margin
    \@todonotes@drawMarginNote%
    \@todonotes@drawLineToRightMargin%
}%
}
\makeatother

\begin{document}

\listoftodos

This is one example \ubcomment{Comment 1}

Now more text and an inline comment: \ubcommentinline{This is an
  inline comment}.

Now even more text and a comment with an enumerate list.
\ubcommentmultiline{Third comment}{
this is not true because
\begin{enumerate}
  \item Reason 1
  \item Reason 2
\end{enumerate}
}

Finally a comment inside a math environment.
\begin{equation}
\label{eq:todo-example:1}
\int f dx =0 \ubcomment{are you sure this integral is zero???}
\end{equation}
\end{document}

Please note: you need to use pdflatex (xelatex also works) and run it various, that is three or four times.

rcsinfo (and rcs-multi)

This package at ctan.org/pkg/rcsinfo (and rcs-multi at ctan.org/pkg/rcs-multi) in a similar way will insert automatically the current version, data, and owner of a file which is under version control of a system which is compatible with the syntax of RCS, like CVS, subversion and mercurial. Here is an example:

\documentclass[12pt]{article}
\usepackage[scrpage2]{rcsinfo}
\makeatletter \def\@rcsInfoFancyInfo{ {\footnotesize%
      \emph{ \fcolorbox{black}{green}{Rev: \rcsInfoRevision,}
        \fcolorbox{black}{yellow}{\rcsInfoOwner,} \rcsInfoLongDate,
        \rcsInfoTime} }} \makeatother
\rcsInfo $Id: main.tex,v [Hg:291] 2018/08/08 16:36:51 oub Exp oub $
\begin{document}
This is a test.
\end{document}

Version control systems

Independent of collaboration, version control systems are useful even for single author documents, since they allow to keep track of changes and restore older versions if necessary. The oldest still in use version control system is RCS, but it is single file orientated and is not based on a server model. CVS is based on RCS, but serves for various files and also includes a server model. This was superseded, to a certain extent by subversion (see below). A different approach was used by the so called decentralized version control systems, the most popular are git and mercurial (see below).

Requirements for collaboration using a version control system

Multi user

The system should allow various users to have read/write access to the system, on a sort of "server".

Versions should be saved

The point is not to overwrite a file, or the files by a newer version, instead the system should save in some form, different versions. The reasons are:

1. One can compare changes by running an appropriate diff program, for example latexdiff, on different versions of the file.
2. It allows to restore older version if that is necessary.

Non-sequential contributions should be managed

Sequential collaboration is one in which one user works, while the other don't do anything, obtains the changes and then the next user starts.

Let us consider a collaboration that is not sequential. (To make the point the example is done of one file, in principle the same problem occurs for different files in a directory, but it is less intuitive.)

1. User1 wants to make changes in section 1 in file1, and needs 2 weeks for this modification. The result is file1-modified-by-user1
2. Meanwhile User2 modifies section 2 in file1, which results in file1-modified-by-user2
3. And User3 modifies section 3 in file1, which results in file1-modified-by-user3

A version system must be able to "merge" these three changes without problems.

Conflicting editing should be detected

Conflicting editing is by definition editing that occurs in the same line of a file. The system should detect that, advise and provide means to solve it.

Interchanging Documents using a version control system

The collaborative preparation of documents requires a considerable amount of coordination among the authors. This coordination can be organised in many different ways, where the best way depends on the specific circumstances.

There are many ways to interchange documents among authors. One possibility is to compose documents by interchanging e-mail messages. This method has the advantage that common users generally do not have to install and learn the usage of any extra software, because virtually all authors have an e-mail account. Furthermore, the author who has modified the document can easily attach the document and explain the changes by e-mail as well. Unfortunately, there is a problem when two or more authors are working at the same time on the same document. Besides this difficulty, the email based method can become easily cumbersome if several files are involved.

A second possibility is to provide the document on a common file server, which is available in most departments. The risk of overwriting each other's modifications can be eliminated by locking files that are currently edited. However, generally the file server can be only accessed from within a department.

A third possibility is to use a version control system. A comprehensive list of version control systems can be found at Wikipedia. Version control systems keep track of all changes in files in a project. If many authors modify a document at the same time, the version control system tries to merge all modifications automatically. However, if multiple authors have modified the same line, the modifications cannot be merged automatically, and the user has to resolve the conflict by deciding manually which of the changes should be kept.

Moreover, a version control system is useful even if a single user is working on a project. First, the user can track (and possibly revoke) all previous modifications. Second, this is a convenient way to have a backup of the files on other computers. Third, this allows the user to easily switch between different computers (e.g. office, laptop, home).

The Version Control System Subversion

Subversion (SVN) comes as a successor to the popular version control system CVS. SVN operates on a client-server model in which a central server hosts a project repository that users copy and modify locally.

Each user has a local working copy of a remote repository. For instance, users can update changes from the repository to their working copy, commit changes from their own working copy to the repository, or (re)view the differences between working copy and repository.

To set up a SVN version control system, the SVN server software has to be installed on a (single) computer with permanent Internet access. It can run on many Unix, modern MS Windows, and Mac OS X platforms.

Users do not have to install the SVN server software, but a SVN "client" software. Besides the basic SVN command-line client, there are several Graphical User Interface Tools (GUIs) and plug-ins for accessing the SVN server. Additionally, there are very good manuals about SVN freely available on the Internet (e.g. svnbook.red-bean.com).

Hosting LaTeX files in Subversion

On a Subversion server, you can have one repository for a common texmf tree. Its structure complies with the TeX Directory Structure guidelines (TDS). This repository provides LaTeX classes, LaTeX styles, and BibTeX styles that are not available in the LaTeX distributions of the users.

The Subversion server hosts a separate repository for each project. Although branching, merging, and tagging is less important for writing text documents than for writing source code for software, repository layouts follow the recommendations of the 'Subversion book'. In this sense, each repository has the three directories /trunk, /branches, and /tags.

Often the question arises, which files should be put under version control. Generally, all files that are directly modified by the user and that are necessary for compiling the document should be included. Typically, these are the LaTeX source code (*.tex) files and all pictures that are inserted in the document (*.eps, *.jpg, *.png, and *.pdf files). On the other hand, all files that are automatically created or modified during the compilation process generally should not be under version control.

The features of Subversion and its workflow

A great feature of a version control system is that all authors can easily trace the workflow of a project by viewing the differences between arbitrary versions of the files.

In this sense, it is very important not to change the positions of line breaks without cause. Hence, automatic line wrapping of the users' LaTeX editors should be turned off and line breaks should be added manually.

A reasonable convention is to add a line break after each sentence and start each new sentence in a new line. Furthermore, split long sentences into several lines so that each line has at most about 80 characters.

If the authors work on different operating systems, their LaTeX editors will probably save the files with different newline (end-of-line) characters. To avoid this type of 'ineffective' modifications, all users can agree on a specific newline character or add the subversion property 'svn:eol-style' and set it to 'native'.

Furthermore, version control systems allow a very effective quality assurance measure: all authors should critically review their own modifications before they commit them to the repository.

Distributed revision-control mercurial (and git)

The distributed revision-control system Mercurial has the advantage over SVN in that it is easier to set up, does not require a dedicated server, and allows easy branching. Git is very similar in functionality to Mercurial. Here we describe the Mercurial workflow, but everything described below can be applied to Git as well, though some of the commands differ.

Setting up mercurial (git)

On Debian/Ubuntu: sudo apt-get install mercurial

For other platforms, see Mercurial's download page.

For Git, see Git's download page.

Setting up a template LaTeX directory

First, create a directory for the project:

mkdir myproject
cd myproject

Creating a local mercurial repository

hg init

For Git:

git init

Bitbucket and Helix

Bitbucket provides free hosting for Mercurial and Git repositories. It supports both public and private repositories.

Get your local Mercurial repository on Bitbucket

First create a repository on Bitbucket, then:

hg remote add origin https://yourusername@bitbucket.org/yourusername/myproject
hg push -u origin

For Git:

git remote add origin https://yourusername@bitbucket.org/yourusername/myproject
git push -u origin

Workflow

The basic workflow is:

1. Make changes to your local files
2. Commit changes locally: hg commit -m "description of changes"
3. Pull remote changes: hg pull
4. Merge if necessary: hg merge
5. Push your changes: hg push

For Git, replace hg with git and use git add before committing.

Real-Time Collaborative Writing

Real-time collaborative writing tools allow multiple authors to work on the same document simultaneously. Some options include:

• Overleaf: A popular online LaTeX editor with real-time collaboration features.
• ShareLaTeX (now part of Overleaf): Another real-time collaborative LaTeX editor.
• Git with continuous compilation: Using Git with a CI/CD pipeline that automatically compiles the document on each push.

Managing collaborative bibliographies

When working collaboratively, managing bibliographies can be challenging. Some recommendations:

1. Use a shared BibTeX file stored in the version control system.
2. Use the biblatex package with biber backend for more flexible bibliography management.
3. Consider using a collaborative bibliography management tool like Zotero or Mendeley and exporting to BibTeX format.

Conclusion

Collaborative writing of LaTeX documents requires careful planning and the right tools. The choice of method depends on the specific needs of the project, the technical expertise of the authors, and the level of collaboration required.