• Style guidelines for student co-authors

I summarize here some of the style guidelines I like to follow when coauthoring papers. These guidelines are addressed primarily to my students. I almost invariably use Latex, so the guidelines refer to that.

How to Collaborate

I use an svn repository for collaboration (I moved from cvs to svn). A paper started in 2006 will be in https://dvlab.cse.ucsc.edu/svn/06-papernickname, and to get it, you should do:

  svn co https://dvlab.cse.ucsc.edu/svn/06-papernickname 

Typically, only people involved with the papers have access to the repositories. In the repository, there are generally the following subdirectories:

• Workspace - this is were the initial draft is kept

• FOO06 - this is the version submitted to FOO06

and so forth. In each directory, the main file is called main.tex, and you can process it via

  latex main.tex 

Sometimes, there is also a web-ready version in the directory, where the first page says where the paper appeared. This is the version of the paper that I put on the web. The version, if present, is called main-web.tex. Please check in all files required to construct the paper, but unless there is a special reason, do not check in the postscript and pdf files generated from the paper.

Useful Stylefiles

• dvlab.bib, available from https://dvlab.cse.ucsc.edu/svn/bib, contains most of the citations I use. Check it out, then make a symbolic link from it to the directory when you use it.

• luca.sty is a stylefile I almost invariably like to use. You can find it in https://dvlab.cse.ucsc.edu/svn/sty.

Paper Format

Text Formatting

• Keep the text width to less than 80 columns. I like to keep two editor windows open side-to-side on the paper, and it's difficult if the lines are wider.

• Please start every new sentence on a new line. That is, don't ever reflow paragraphs. I know it sounds like a pain at the beginning, but it makes it much easier to move text around, locate sentences in paragraphs, and judge by eyeball how long sentences are. I have an Emacs fill-sentence macro that can help you to reflow a sentence, without reflowing the whole paragraph.

• Try not to break math formulas across lines if possible.

• Leave some space around math operators, and write for example $\bigcup \set{r | r \in R} = S$ rather than $\bigcup\set{r|r\in R}=S$. For small formulas, it is acceptable to remove some space, for instance, $(v+u)(s) = v(s) + u(s)$ is quite readable. Use your judgement, keeping ease of reading as the goal.

• Please leave blank lines above and below section titles.

• Please use indentation for math and itemizations.

• Use % to separate portions of text in the editor, without causing a change of paragraph. For instance:

  Given a subset $T \subs S$ of states, the reachability goal $\Diamond T$
  consists in the paths reaching $T$, and the safety goal $\Box T$
  consists in the paths that stay always in $T$:
  %
  \begin{align*}
    \Diamond T & = \set{\overline{s} \in \Omega \mid \exists k. \overline{s}_k \in T} &
    \Box T     & = \set{\overline{s} \in \Omega \mid \forall k. \overline{s}_k \in T}
  \end{align*}
  %
  These sets of paths are measurable, so that given a ...

  The single % above are used to leave visual space in the editor around the displayed equation, without causing a change of paragraph in the Latex. This example also shows some typical macros I use (\set, \subs), and the use of the align environment, which I prefer to eqnarray.

Macro Usage

Please consider using macros for many of the non-obvious symbols and notation, so we can change notation midway through the paper. Call the macro file macro.sty, and include it from main.tex. Keep your macros informative but short.

Labels

Use labels of the form \label{def-game} . Two things are to notice:

• The label name has a first part, "def", which specifies that it is a definition. Typical first parts are: def, theo, lem, algo, fig, tab.
• The first part of the label name is separated from the rest with "-". Many people use ":" instead, but "-" is better: emacs does not consider "-" to be a word separator (unlike ":"), so that automatic word completion (M-/) enables me to quickly complete (and, more importantly, guess) the labels.

Macros

Here are some of the macros that I would really like students to follow. They are defined in luca.sty (see above).

I always confuse \cup, \cap, \vee, \wedge, so I use these macros.

Also, note the following suggestions:

• The following macros work in Latex, and they should be used to get parentheses of the appropriate sizes: \bigl, \biggl, \Bigl, \Biggl.

• Please don't write $Cpre(X)$: the spacing around the letters "Cpre" would be all wrong. Please take the time to write $\text{\textrm{Cpre}}(X)$, or better, define a macro.

• If you do define macros, please keep their names short, and preferably in all lowercase, otherwise, it is very cumbersome to write the paper.

• Do not define macros for things that have standard names, such as s for a state.