Skip to content

writing style guide

Jump to bottom
Mark Gates edited this page Jul 13, 2023 · 1 revision

[TOC]

General

  • See example.tex and example.bib for examples that generate example.pdf.

  • See the example Makefile, which uses latexmk to compile tex files. It handles repeating pdflatex and bibtex as needed. Only the docs = example.pdf line needs to be changed for each project.

  • When in doubt, look at older documents or ask on slate-dev or slack.

  • Turn on the automatic spell checker in your text editor!

    • Use flyspell in Emacs, :set spell in Vim
    • Check with aspell.

  • Need be, seek help with grammar, punctuation, etc., from ICL's technical writer, Sam.

  • Break lines at 80 character limit. Yes, break lines in your LaTeX source!

    • This makes diffs much smaller and conflicts more rare.
    • Not strictly enforced, especially for figures, tables, and algorithms.

  • Do not rewrap paragraphs when editing. Doing so makes large diffs and increases chances of conflicts. Only lines where you actually changed the text should change.

  • Use

    • \emph{...} for emphasized (italic) text,
    • \textbf{...} for bold text,
    • \texttt{...} for typewriter (fixed width) text.

  • Do not use {\em ...}, {\bf ...}, etc., which are obsolete. Avoid underlining text---underlining was invented because typewriters and handwriting don't have italics; we do.

  • For dashes in text, use text---text (em dash, no spaces). (The alternative style is an en dash with spaces before and after: text -- text. Don't use em dash with spaces: text --- text.)

  • For numeric ranges (pages, dates, etc.), use 1--100 (en dash, no spaces).

  • For speedups, use $2.3 \times$.

  • For keywords, use \emph{text} when used for the first time:

      \emph{thread block}

  • Explain acronyms on first use:

      \emph{Single Program Multiple Data} (SPMD)

    or

      \emph{SPMD} (Single Program Multiple Data)

Equations

  • Equations should be punctuated as part of the sentence, often with a comma before the equation and a comma or period at the end of the equation. Hence, do not separate an equation from its paragraph by blank lines.

  • Follow common math conventions. For example, use uppercase for matrices (A, B, X), lowercase for vectors (x, y, z), lowercase Greek for scalars (\alpha, \beta, \gamma). Uppercase Greek is used for some things like the diagonal matrices of eigenvalues and singular values (\Lambda, \Sigma).

  • For abs, use \abs{...} macro from example.tex, which does \left \lvert ... \right \rvert, instead of |...|. The vert tags format better, especially for things like fractions.

  • For norm, use \norm{...} macro from example.tex, which does \left \lVert ... \right \rVert, instead of ||...||.

Lists

  • Use \begin{itemize} \item text \end{itemize} for bullet lists.

  • Use \begin{enumerate} \item text \end{enumerate} for numbered lists.

  • Use \begin{description} \item[bold text:] text \end{description} for definition lists.

Figures, Tables, Algorithms

  • Lists, Figures, Tables, and Algorithms should be surrounded by a blank line. Ideally, their contents are indented as well.

  • For sub-figures, use subfigure package. Refer to Figure 1a, 1b rather than Figure 1 (top), Figure 1 (left). See example.tex.

  • For tables, don't put rule lines between every row and every column; prefer minimal number of rule lines, such as one under column headings, one right of row headings.

  • In academic journal and conference articles, do not wrap text around figures, i.e., don't use package wrapfig.

  • Put algorithm code listings and pseudocode inside \begin{algorithm} ... \end{algorithm}, from \usepackage{algorithm}, which is similar to a figure or table.

  • For code listing (C++, etc.), use \begin{lstlisting} ... \end{lstlisting} from \usepackage{listing}. See example.tex for customization.

  • For inline code in a paragraph, e.g., routine names, clauses, filenames, use \lstinline|...| from \usepackage{listing}.

  • For pseudocode, use \begin{algorithmic} ... \end{algorithmic} from \usepackage{algpseudocode}, part of the algorithmicx package. See example.tex for customization.

Labels and references

  • Define labels like this:

    • \label{chap:chapter_label} for report chapters
    • \label{sec:section_label} for sections
    • \label{sec:section_label:subsec_label} for sub-sections
    • \label{fig:figure_label} for figures
    • \label{fig:figure_label:subfig_label} for sub-figures
    • \label{alg:algorithm_label} for algorithms
    • \label{alg:algorithm_label:line_label} for lines in algorithms
    • \label{tbl:table_label} for tables
    • \label{eqn:equation_label} for equations

  • To work correctly, labels go on a separate line right after the chapter title, section title, or figure/table/algorithm caption:

      \section{...}
  \label{sec:intro}

  \caption{...}
  \label{fig:matrix}

  • Equation labels go on the same line as begin:

      \begin{equation} \label{eqn:residual}
      R = B - AX
  \end{equation}

  • Refer to labels using \cref, from \usepackage{cleveref}. It automatically includes the appropriate text (Chapter, Section, Figure, Equation, etc.) before the reference. At the beginning of a sentence, use capital \Cref{}. For example:

      \usepackage[capitalize,noabbrev]{cleveref}  % with common options

  The matrix is shown in \cref{fig:matrix}.
  \Cref{fig:matirx} illustrates the matrix.

  • If cref can't be used, spell out Section, etc., and use tilde:

      Section~\ref{sec:intro}

Citations

  • The text should make sense when citations are removed:

    • Do not say "as shown in [3]" because "[3]" is not a noun.
    • Say "as shown by Dongarra et al. [3]".

  • You can use the natbib command \citet{} to obtain author names automatically:

      as shown by \citet{dongarra1988extended}.

    yields:

      as shown by Dongarra et al. [3].

  • Otherwise, use a tilde so line breaking does not move the citation to the next line:

      as shown by Dongarra et al.~\cite{dongarra1988extended}.

  • For consistency, find citations on Google Scholar, then copy and paste the BibTeX.

    • Please add the DOI. It's super useful to link to the article.

      doi={10.1145/77626.79170}

      NOT: doi={http://doi.org/10.1145/77626.79170}

    • In the title field, put braces around acronyms and proper nouns to preserve capitalization. Include the entire word, not just the capital letters, to preserve correct letter spacing. Don't include every word; allow BibTeX to apply its capitalization rules.

      title={Analysis and Optimization of {SGEMM} on {Fermi} and {Kepler} {GPUs}}

      NOT: title={Analysis and Optimization of {SGEMM} on {F}ermi and {K}epler {GPU}s}

      NOT: title={{A}nalysis and {O}ptimization of {SGEMM} on {F}ermi and {K}epler {GPU}s}

      NOT: title={{Analysis and Optimization of SGEMM on Fermi and Kepler GPUs}}

  • Use Google's keys for consistency.

    • Doing so catches repeated citations right away.

    • If the document is not on Google, follow Google's convention to create the key: first author's last name, year, first real word of title.

    • Use bibextract.py from bibtex-utilities (by yours truly)

Clone this wiki locally