version 2016-06-02

Christian Stump’s personal latex rules

This is my personal list of rules I follow when writing and collaborating on papers in latex to be published on www.arxiv.org. The order is simply the order I encountered those in the past year when I started typing them. Some were told me to use by coauthors and some others by referees.

I simply find it desirable to have a consistent set of rules to apply as that makes it much quicker working and collaborating on a paper.

Obviously, others might have other rules so I possibly do not use my rules but those of others sometimes, and I replace mine if I prefer given alternatives.

I appreciate any comments on items you disagree and on additional items.

  • Use names with initials.
  • This is not as ambiguous than only using the last name, and I find this also more personal. Using the complete name is too long to be used throughout a paper.
  •  Examples: A.~Einstein or H.~S.~M.~Coxeter.
  • Use complete sentences.
  • Example: Do not write “We have the following \begin{lemma} … \end{lemma}”.
  • Use “if and only if” and not “iff”.
  • Do not insert line break automatically after X characters.
  • Different people might have different preferences where to break lines on the screen, so do not force them to use yours.
  • Write one line per sentence.
  • Having one sentence per line makes it simple to check which sentences are modified by others using versioning control.
  • Bind single characters and very short expressions in inline math to the word before.
  • Example: “Let~$a$ be an element of …”.
  • Use proper indentation everywhere.
  • This makes it so much simpler to read for others.
  • Use whitespace instead of tabs.
  • Tabs can behave weirdly on different machines.
  • Strip trailing whitespaces.
  • They only pollute diff sets in versioning control.
  • Use macros such as \newcommand or \def.
  • This makes the tex file better readable and also better maintainable when changing notations.
  • Avoid low-level tricks if possible.
  • For most desired behaviours, there are good packages to achieve them. If there is no such package, the desired behaviour might even be not what one should do.
  • Use the cleveref package.
  • This way, one does not need to write “We have seen in Proposition~\ref{...}”, but rather “We have seen in \Cref{...}”. If one changes a proposition to a theorem later, the output stays consistent.
  • Labellings should be used consistently. I write them small, labelled and one word.
  • Examples: Use \label{thm:main_theorem} instead of \label{Main Theorem}.
  • Use tikz graphics if possible.
  • It takes some time to draw them nicely, but in total it saved me a lot of time doing them.
  • Keep the compilation of the tex file without errors or warnings as often as possible.
  • It might sometimes be better to have temporary warnings, such as an empty citation.
  • It might also be better not to constantly take care of bad boxes.
  • Use \hfuzz5.002pt to avoid too small overfull hbox warnings.
  • Use (properly indented) \[ … \] rather than $$ … $$.
  • Use ”~\cite[Theorem~2.2]{...}” rather than “Theorem 2.2 in \cite{...}”.
  • Avoid definitions inside theorems/propositions etc.
  • Some people consider this bad writing style, and it certainly makes it harder to read.
  • Avoid starting sentences with math expressions.
  • Again bad writing style, some journals will ask you to remove it.
  • Use vertical skips rather than space.
  • Example: \bigskip rather than \vspace{1em}.
  • Use “\ell” instead of the letter “l” in math mode.
  • The letter l is hard to parse, I remember being confused on some printouts which letters where l’s and which where i’s
  • Use \eqref to reference equations/items/enumerates.
  • Do not use \textit but rather \emph.
  • \textit makes text italic, while \emph emphasizes text. The later is cleaner to be changed if desired.
  • Put labels of non-floating environments at the beginning.
  • I find labellings at the beginning to be found quicker on scanning through the text.
  • Put labels of floating environments inside the caption at the beginning of environment.
  • Provide specific references within books.
  • Having only a book referenced makes it hard to find the exact location of a statement inside.
  • Make clear whether a reference is original or a secondary source.
  • Do not use \eqnarray, use \align instead.
  • \eqnarray adds weird spaces.
  • I was told this is deprecated, though I have not checked.
  • Use “defined by” if a defining equation follows, and use “defined as” if only the defining formula follows.
  • Example: The binomial coefficient is defined by $\binom{n}{k} := \frac{n!}{k!(n-k)!}$ and the binomial coefficient $\binom{n}{k}$ is defined as $\frac{n!}{k!(n-k)!}$.
  • Use \begin{proof} … \end{proof} for proofs, and start with \begin{proof}[Proof of ...] whenever the proof of a statement does not immediately follow the statement.
  • Label exactly those equations that are referenced in the document by using

\usepackage{mathtools}
        \mathtoolsset{showonlyrefs}.