Tips for Technical Writing in Latex

Sun, Apr 18, 2021 3-minute read

I recently finished my Ph.D thesis (yay!) and accumulated a few tips related to formatting technical writing in Latex.

Hyphenation and Line Breaks

Many people are familiar with the \hyphenation command, which tells Latex where it may hyphenate words it does not already know about to prevent lines from being too long. Latex will not know about many technical words, or function names that are not “plain english.” In English writing, line breaks should occur at syllable boundaries only.

\hyphenation{cuda-Memcpy-Peer-Async bi-di-rec-tion-al}

You can also allow breaks at underscores, which is convenient for certain programming languages or libraries.

\renewcommand\_{\textunderscore\allowbreak}

You may then want to prevent line breaks in some places. Use \mbox for that.

\mbox{\_\_device\_\_}

Latex will only break already-hypenated words at the hyphen position. You can add more optional breaks with {\-}

A super-hypenated-latex-confusing compound adjective.
A su{\-}per-hy{\-}phen{\-}at{\-}ed...

lstlisting

The lstlisting environment is used to add and format code in Latex documents. You can use minipage to prevent short lstlistings from being broken across pages. You can also use the \noindent command to prevent the minipage from being indented if it starts a new paragraph The

\noindent
\begin{minipage}{\linewidth}
\begin{lstlisting}
\end{lstlisting}

SI units

Use the siunit package to automatically format numbers with SI units.

\usepackage[binary-units, group-separator={,}]{siunitx}
\SI{512}{\byte}

Digit grouping and separators.

Latex can make it hard to manually format digit grouping and separators in numbers. The number package makes this easy.

\num{242000}

CLI spell-checking

You can use aspell with the Latex filter (to reduce false positives). The -t flag puts it in Latex mode.

aspell -t -c main.tex

Latex and Version Control

Write one latex sentence on each line, so version control diffs are easier to follow. It feels a little unnatural at first.

This is one sentence.
This is another sentence.

Latex and arxiv

Arxiv does not want a raw PDF, annoyingly. You can defined a makefile target that will create a zip for you to upload. You’ll need to tweak this to get all the files uploaded you need. Arxiv usually wants the pre-processed bib file that ends in bbl, so you need to run bibtex.

arxiv: main.tex main.bib ${FIGS}
  pdflatex ${PAPER}.tex
  bibtex ${PAPER}.aux
  rm -f upload.zip
  zip -r upload.zip main.tex main.bbl figures acmart.cls ACM-Reference*

Tables that are too wide or too tall

Use resizebox for tables that are too wide or too tall (which is almost always the case, right???)

To match the text width:

\label{tab:related}
\resizebox{\textwidth}{!}{%
\begin{tabular}{...}
\end{tabular}
}%resizebox
\end{table*}

To match the text height:

\label{tab:related}
\resizebox{!}{\textheight}{%
\begin{tabular}{...}
\end{tabular}
}%resizebox
\end{table*}

Reducing space between captions and figures

I think there is too much wasted space between figures and captions in some templates. You may be able to tweak this yourself with the caption package.

\usepackage{caption}
\captionsetup{skip=1pt}

Shortcuts for repeated formatting

You may wish to repeatedly apply formatting to a particular word. You can define your own command for that. The xpsace command will try to be smart about whether to put a space after the word.

\newcommand{\StreamData}{\textit{StreamData}\xspace}

Now \StreamData is in italics.

% notice the absence of \xspace
\newcommand{\DenseData}{\textit{DenseData}}

When I use \DenseData{} I may need to put the braces afterwords to get a space.

Figures and text

Use the pifont package, and then the \ding command

\usepackage{pifont}

This: \ding{202} will make a black circle with a white "1" in it.
You can then draw a matching object in your figure.
\ding{203} will make a 2, \ding{204} will make a 3, etc.