Tips for collaboratively editing a LaTeX document

Question

My default setup is to put the tex source in a subversion repository and insert notes to each other as comments in the source when making changes to other people's content. It all feels pretty sub-optimal, especially when there are subversion conflicts where all it tells you is "these two versions of this huge paragraph are in conflict."

I've come up with a few tricks but I'm sure there are much better ideas (or better versions of my ideas) out there.

For collaborating on code, see this question:

How do you collaborate with other coders in real time?

(Some of those answers will apply to collaboration on LaTeX documents as well.)

Answer 1

Always end each sentence with a newline. Never reformat paragraphs. These rules not only minimize spurious conflicts but also make your collaboratively edited paper easier to revise.

For author commentary I use marginal comments:

\long\def\authornote#1{%
        \leavevmode\unskip\raisebox{-3.5pt}{\rlap{$\scriptstyle\diamond$}}%
        \marginpar{\raggedright\hbadness=10000
        \def\baselinestretch{0.8}\tiny
        \it #1\par}}
\newcommand{\simon}[1]{\authornote{SLPJ: #1}}
\newcommand{\norman}[1]{\authornote{NR: #1}}
\newcommand{\john}[1]{\authornote{JD: #1}}

We put these in the margin because frequently we're preparing a paper to strict length limits, and we want the marginal notes not to change the length of the paper. Marginal notes are then turned off by

\long\def\authornote#1{\relax}

I also invented the nbibtex tool (now in Debian!) so that you can use different .bib files from your coauthors without having to agree on arbitrary BibTeX keys. nbibtex works like BibTeX except that it uses key words from author, title and other fields. Each author's BibTeX file can be different, but if the paper is there, nbibtex will find it.

Answer 2

To mitigate the problem of unhelpful subversion conflicts, you can adopt the convention of newlines at the end of sentences. (This also makes it easier to rearrange or comment out, or comment on, sentences.)

As for comments to each other in the text source, I find it's better to make those appear in the pdf document but have the ability to turn them off for the final version. I use a macro "kibitz" for that. To use it, put the following at the top of the document:

\newcount\Comments  % 0 suppresses notes to selves in text
\Comments=1   % TODO: set to 0 for final version

\documentclass{article}   % or whatever your documentclass

% for comments
\usepackage{color}
\definecolor{darkgreen}{rgb}{0,0.5,0}
\definecolor{purple}{rgb}{1,0,1}
% \kibitz{color}{comment} inserts a colored comment in the text
\newcommand{\kibitz}[2]{\ifnum\Comments=1\textcolor{#1}{#2}\fi}
% add yourself here:
\newcommand{\alice}[1]{\kibitz{red}      {[ALC: #1]}}
\newcommand{\bob}[1]  {\kibitz{purple}   {[BOB: #1]}}
\newcommand{\carol}[1]{\kibitz{cyan}     {[CAR: #1]}}
\newcommand{\deb}[1]  {\kibitz{darkgreen}{[DEB: #1]}}
\newcommand{\evan}[1] {\kibitz{blue}     {[EVN: #1]}}

Then Alice, for example, can just stick something like \alice{Bob must've added the previous sentence which is obviously false.} and it will show up in red in the pdf as long Comments is set to 1.