Technical Hints for Writing a Paper

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 received most of the guidelines myself as postdoc 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. Also, we want to notice in case we accidentally remove a reference.
• 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

Useful Links

• Oliver Strunk. The Elements of Style.
• Donald E. Knuth, Tracy L. Larrabee, and Paul M. Roberts. Mathematical Writing.
  
• The Comprehensive LaTeX Symbol List
• Online help with LaTeX commands
  
• LaTeX web page
  
• A one-page intro to LaTeX
• The (Not So) Short Introduction to LaTeX2e
• Subversion book
• Subversion tutorial
  
• Nice software to draw pictures: InkScape (based on SVG, provides export to EPS and PDF)
  
  

---

Author: Dirk Beyer
Last check-in: $Date: 2009-01-05 07:58:21 $