Large document edited by a dozen people

We, a team of 12 people, plan to write a 50 pages paper. The paper will be divided into chapters. Usually, no more than 2 or 3 people will work on a given chapter.

Having one large file will create problems when everyone will be editing and committing it in our VCS. I thought to split it into several files and input them. It works fine however one is still forced to compile the whole document. I could educate people to use \includeonly but we really want to use input and not include.

To alleviate this problem, I came up with the idea of extra "steering" files, one for each chapter, that does the same as the "main" file but only for a given chapter. It works but seems a bit cumbersome...

What is your feeling about it? How would you handle such a use case?

-
lipsum or kantlipsum the rest of the document,maybe? –  percusse Jun 5 '12 at 9:23
etherpad perhaps? –  topskip Jun 5 '12 at 9:26
Making specific main files for chapters sounds reasonable to me. If you put all the preamble stuff into a separate file, such a "chapter main file" will look like \input{preamble} \begin{document} \input{chapter_n} \end{document}  which doesn't look cumbersome to me. –  Stephan Lehmke Jun 5 '12 at 9:32
@StephanLehmke Indeed putting the preamble in a separate file would make things cleaner. Thank you for your input. –  Barth Jun 5 '12 at 9:42
If you use a distributed VCS and each group works on only their chapter, then even using one file should not be a problem. However, splitting the input is a good thing. As an aside: one useful technique is to use a mercurial repository in a shared Dropbox folder. This also allows contributions from collaborators uncomfortable with a DVCS (I occasionally commit their changes for them). You can also keep and share a master generated pdf of the complete final version for reference too. –  mforbes Jun 5 '12 at 10:17

2 Answers

As several people have pointed out, it is useful to put all of your prefactory material into a separate preamble. I usually make a custom class to contain all of the required packages, formatting information, etc.

Write each chapter as a completely separate document, and then – as Martin Scharrer pointed out – you can use one of the following packages to allow you to directly \input these chapters in the master document:

• docmute: A minimal package providing just enough to allow you to include standalone chapters in the main document.
• combine: A more comprehensive set of classes and packages designed for combining conference proceedings. Provides more functionality for dealing with titles and bibliographies.
• standalone: When used as a package, this works very similarly to docmute but provides much more functionality, such as the standalone class which crops the output.
• subfiles: Similar functionality to docmute but requires a slightly modified usage format (\subfile{} instead of \input{} etc.)

The class myclass.cls should look something like this:

\ProvidesClass{myclass}[2012/06/01 v1 Custom class for ... project]
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{scrbook}}% or whatever
\ProcessOptions\relax

\LoadClass{scrbook}

% Include whatever packages you need here...

% Use either one of these:
\RequirePackage{standalone}
%\RequirePackage{docmute}


Now your chapters can look and behave like like self-contained documents:

\documentclass{myclass}

\begin{document}
\chapter{First Chapter}
Here is the first chapter
\end{document}


and your master file can input these like

\documentclass{myclass}

\begin{document}
\input{chapter1.tex}
\input{chapter2.tex}
\end{document}


The packages modify the outer document so that the inner \documentclass and document environments in each of the \input chapters have no effect.

-
There are already several package which do this: docmute, standalone and at least one more I can't recall. –  Martin Scharrer Jun 5 '12 at 9:50
@MartinScharrer: I did not realize that standalone et al. worked this way too! I will include this. –  mforbes Jun 5 '12 at 9:59
Very nice. I don't understand however where I have to put the first code you show (ProvideClass...). In a file myclass.sty ? –  Barth Jun 5 '12 at 10:23
@Barth: Put the first code in a file myclass.cls, then each chapter into files chapter1.tex, chapter2.tex etc. and finally the last code in master.tex. Then run latex master to generate the whole shebang, or latex chapter1 to generate just the first chapter. –  mforbes Jun 5 '12 at 10:31
It works perfectly with docmute. Simple but powerful. Thank you very much. I will accept this answer as it is what I am going to use. –  Barth Jun 5 '12 at 11:50

In ConTeXt you can create an environment file (the layout) and several components (the individual chapters). The components are linked to the environment. That way you can complile one chapter, parts of it or the entire document.

The details are explained in the ConTeXt wiki - Project Structure or in the Project Structure manual.

Here is an example of how the structure looks:

% file: introduction.tex
\startcomponent introduction
\project paper
\startchapter [title=Introduction]
\stopchapter
\stopcomponent

% file: theory.tex
\startcomponent theory
\project paper
\startchapter [title=Theory]
\stopchapter
\stopcomponent

% file: main.tex
\startproduct main
\project paper
\component introduction
\component theory
\stopproduct

% file: environ.tex
\startenvironment environ
\setupbodyfont [palatino]
\stopenvironment

% file: project.tex
\startproject project
\environment environ
\stopproject


The project file is a way to gather common inclusions: it links to environment files using \environment, so that \startproduct and \startcomponent blocks can use \project to include all the project's environment files at once. You can also always include environment files directly in the file if needed.

Using this setup, you can compile the individual chapters with context introduction… and the entire document with context main.

-
Context seems very powerful and useful. I'll have a look at it asap. For now I 'll go with the simple solution proposed by mforbes. Thank you. –  Barth Jun 5 '12 at 11:54