The following principles are meant to make the collaborative
development of a paper (written in LaTeX) more efficient.
We have successfully used these principles since years and now compiled
them here for our students and collaborators
in order to make it more efficient for us to ask them to adhere.
(This page is written by me but I learned the most important guidelines
from Tom Henzinger.)
General Comments
Treat the source code of a paper as a valuable object that is
beeing used, just like program code.
Keep the source code clean, readable, and minimal.
This really reduces the number of bugs in the document, just like with
a good program source code.
Clean: Organize and format the code nicely.
Readable: Structure and organize.
Minimal: Use macros to abbreviate recurring terms, delete
unnecessary comments.
Editing Text
Start each sentence in a new line (makes it easier to move
sentences around).
Change line breaks only if you change the text of the line.
(Switch off automatic line wrapping of your editor, switch off
auto-deletion of white space at the end of line.)
Keep the lines shorter than 80 characters, so that it works with
every standard editor.
Avoid tabs, use spaces instead.
Commit everything that is needed to compile the paper.
Check your changes before committing, especially when fixing a
text that is considered stable.
(Use svn diff, or the Trac web page.)
Commenting
Use the LaTeX comment symbol '%' for text that you want to keep
for later reuse.
Use three of them '%%%' and your name when you want to put
explanation for your co-authors.
(For example, %%%db: Rick, please prove the following.)
Start each comment on a new line.
Macros
Use \newcommand instead of \def (safer, lets you know if already
defined).
Writing Style
We write "a set S of states", not "a set of states S" (the latter
could make the reader think that S is a example single state).
We use "iff" in conditions only, to define someting we use "if".
Text Style
Be careful with spaces and periods:
French spacing: write "John F.\ Kennedy" in order to avoid the
larger space after "F.".
Measures: between numbers and the unit, use the appropriate
space "\,", e.g., 3.3\,GHz.
Short symbols: write "the state~$s$" and "for all~$i$" and
"location~$l$" such that the symbol does not go on next line.
Same holds for citations.
Citations:
A reference to literature is gramatically not part of the
sentence, always put before period or comma, never use as noun.
Bad: "[3] says ..." "as described in [4]"
Good: "... as described by Smith [4]."
Hyphen, dash, and em-dash:
Hyphen is used to connect words in order to ease human parsing:
"logic-based, model-checking algorithm".
Dash is used for intervals: "pages 3--17".
Em-dash is used as parenthetic remark in a sentence: "text
---remark--- text". Note that there is no space inside of the em-dash,
in order to mimic opening and closing.
BibTeX File
Use meaningful BibTeX keys (tool or concept, name of an author,
perhaps add conference or year).
It is a good idea to write a small excerpt after reading a paper,
and store it in the 'note' field; this makes it later easy to find out
what this paper is about, and how and why that paper is related.
Repository Organization
Every piece of the paper is exchanged via a version repository.
The main LaTeX file is named "main.tex", and "latex main" or
"make" will produce the document.
Once the structure of the paper is quite stable, it is a good
idea to break the tex file into several files, one for each section.
When you start writing about a new idea, create a name for the
topic (not necessarily the title yet) and create a directory.
Every submitted version of the paper will have one subdirectory (if no
plan yet on where to submit, start with "Draft").
For example:
ConfigurableSoftwareVerification/
CAV07-submission
CAV07-proceedings
FMSD-submission
FMSD-revision
Add BBL files to the repository. Sometimes we optimize the BBL
files for space and don't want to run bibtex anymore.
DOS/Unix headache: In your file "~/.subversion/config", add the
lines
*.tex = svn:eol-style=native
*.bbl = svn:eol-style=native
*.png = svn:mime-type=image/png
*.jpg = svn:mime-type=image/jpeg
*.pdf = svn:mime-type=application/pdf
If already too late, ask everybody to commit, take token for the whole
paper, and run
find ./ -name "*" -exec svn propset svn:eol-style native {} \; svn commit -m "Cleaned up the CF/LF mess."
That should clean it up.
If this is not done then any change done by a user on the other OS will
cause "ghost changes", i.e., lots of lines changed when looking at "svn
diff" but they are only due to new line breaks, and it is impossible to
track real changes.
An advise that cannot be given
often enough
"I think there is no substitute to a careful reading, in one sitting
from beginning to end, in order to catch inconsistencies (mark them
on paper; fix them later). Just searching for words or patterns
within emacs often introduces more problems than it solves ..."
Tom Henzinger, 2006-10-13