Rules for writing manuscripts

Follow these rules when working with me on manuscripts.
I, the reviewers, and your future colleagues will thank you.

Read and follow The Elements of Style, Fourth Edition by Strunk and White.

Use LaTeX. Any other word-processor I have seen is woefully inferior at formatting mathematics.

Familiarize yourself with the macros in MASTER.tex (and SEMINAR.tex, if you are working on a presentation).

Before deciding you need a new entry in my bibtex database, ALL.bib, make sure it is not there already. If a new entry is indeed needed in ALL.bib, created a temporary tmp.bib file in the directory where your work is, and add it to the search path (i.e., put \bibliography{ALL,tmp} in the main tex file). Eventually, I will add the entries to ALL.bib and remove tmp.bib. After that, you will need do svn update TeX, of course.

Be consistent in your wording. For example, in the same paper, you should not use "local spaces", "subspaces", "sub-spaces", and "local state spaces" to mean the same concept (I prefer "local state spaces", by the way). Variety might be the spice of life, but, in a scientific paper, this type of variety only leads to confusion.

Be absolutely consistent with fonts, even between text and figures. In tgif, for example, be sure to use italic, roman, and bold for a symbol the same way it is used in the text; also, be sure to use the NewCenturySchlbk font in tgif if the document is using the standard LaTeX fonts, and Times if the document is using the psfonts (which often save a little space, but alway look worse, in my opinion). Even better, use embedded latex in tgif, which takes a little longer but can be made to look exactly the same as the rest of the text.

Learn to use tgif to its fullest power. This includes knowing how to align objects, when to use a white fill or no fill, etc. Almost always you should have "Snap to grid" on. I never use "Stretch text", the results look horrible. Arcs in a graph should not be drawn as a sector of an arc. Eschew sloppy pictures!

As you iterate on the file and get closer to submitting, avoid as much as possible changing the text needlessly; your coauthors will want to run a diff on the files you edited, and needless changes make it much harder to understand the essential changes.

As you iterate on the file and get closer to submitting, realize that, often, several very small wording changes can cause huge differences in the final page count. I rarely have had to cut ideas from a paper to make it fit into the allowed page count. Usually, careful rewording is sufficient, and, as a bonus, the resulting English is often better. Keep an eye on that page count, but only as you get close to submitting!

In a LaTeX file: keep lines to no more than 80 characters whenever possible; don't leave blank characters at the end of a line; go to the next line after each "." or ";", even if this means having short lines (this makes it much easier to visually search for a pattern in a block of text when editing); always leave whitespace around parentheses: decision diagram (DD), not decision diagram(DD); type quotes like ``this'', not like "this".

Do not use $transitive closure$ to emphasize words, use \emph{transitive closure}.

Use \emph to emphasize a term you define, but only the first time you use the term (at times, you need to deviate a little from this rule since it is rarely appropriate to define a term in the abstract, and it might not be appropriate to define a term in the introduction. A similar rule applies to the definition of acronyms, but be sure to define an acronym only if it is needed later. Too many acronyms can seriously hinder readability.

Always use the appropriate punctuation at the end of display equations, just as you would for inline equations.

Any figure or table you define within a figure or table environment must have a caption and must be referenced at least once in the text (of course this does not hold for presentations).

Never use hardcoded numbers for references! Use these standards: \label{FIG:xxx} for figures; \label{TAB:xxx} for tables; \label{SEC:xxx} for chapters, sections, subsections, etc.; \label{STA:xxx} for statements in pseudocode, and so on. In the text, use a tilde after Section', Figure, etc., to force the number to be on the same line as the word:
...in Figure~\ref{FIG:xxx}, we see that...

Any work to be shared with me or other students in the group should be kept in the VerificationLab repository under svn. Only do svn add on source files such as tex, bib, obj (for tgif, in which case you should also add the corresponding eps file even if it is not a source, strictly speaking). Do not add the pdf file obtained by running LaTeX on your source tex file, except for versions to be saved (such as the official submitted or published version of a paper). Do not add to the repository various makefiles you might use to run LaTeX. Indeed, you should not use such makefiles at all, you should instead have appropriate scripts in your bin directory.

Don't be sloppy! Regularly run spell-checks, and certainly before asking me to read what you wrote! Be proud of your manuscript!


Last updated: January 8, 2014. Report suggestions and problems to: ciardo@iastate.edu