Page tree
Skip to end of metadata
Go to start of metadata

This page summarizes the coding conventions and best practices adopted by Zubax for LaTeX documents.

Contents

Document templates

The following repository contains a set of templates that should be used for all documentation published by Zubax: https://github.com/Zubax/document_templates. Usage of any other templates is discouraged.

Texmaker IDE

Installation

The recommended LaTeX IDE is Texmaker. The following commands can be used to install a development environment on a Debian-based GNU/Linux distribution.

Setting up LaTeX
sudo apt-get install texlive-full lyx python-pygments texmaker

Configuration

Modify the compilation command so that the command pdflatex (or another LaTeX compiler) is invoked with the option -shell-escape, otherwise the syntax coloring feature (and probably something else) will not work. The compiler should be invoked twice during the compilation cycle in order to resolve internal references in the document. The resulting command should look similar to this:

pdflatex -shell-escape -synctex=1 -interaction=nonstopmode %.tex|pdflatex -shell-escape -synctex=1 -interaction=nonstopmode %.tex|okular %.pdf

An example of the resulting configuration is shown on the following screenshot:

Spell checking

It is required to have a working spell checker while working with LaTeX. The following instructions show how to configure it in Texmaker.

  1. Get the dictionary file en_US.oxt from Open Office. Try this link: https://extensions.openoffice.org/en/project/en_US-dict, or Google "en_US.oxt".
  2. Unarchive the file.
  3. Copy both en_US.aff and en_US.dic to your default or preferred dictionary location. Normally, the directory would be located at /usr/share/myspell/dicts/.
  4. Navigate to Texmaker --> Options --> Configure Texmaker --> Editor --> Spelling dictionary to select the extracted earlier en_US.dic as your preferred spelling dictionary.

The user-added words are kept in the Texmaker configuration file, which is located at ~/.config/xm1/texmaker.ini. The parameter key is Spell\Words=. You can use this knowledge to transfer the user-added words between different computers.

Editing notes

Headings

Do not force capitalization in headings. For example, "Power supply characteristics" is a well-formed heading, whereas "Power Supply Characteristics" is not.

On the importance of hyphenation

Ensure that LaTeX can hyphenate long words used in the headings, otherwise bad things may happen.

If LaTeX doesn't know how to hyphenate a word, you can help it by typing \- within the word at the desired hyphenation points; for example, syn\-chroni\-zation. The \- sequence will not be rendered in the final document.

Consider the following listing:

Minimal working example
\documentclass[a4paper,onecolumn]{book}

\RequirePackage{titletoc}
\RequirePackage[a4paper]{geometry}
\setlength\columnsep{6mm}
\geometry{margin=20mm}

\dottedcontents{chapter}[10mm]{\bfseries}{10mm}{1pc}
\dottedcontents{section}[20mm]{}{10mm}{1pc}
\dottedcontents{subsection}[30mm]{\small}{10mm}{1pc}

\makeatletter
\renewcommand\tableofcontents{\@starttoc{toc}}
\makeatother

\begin{document}
    \twocolumn%\sloppy
    \frontmatter

    \tableofcontents

    \onecolumn
    \mainmatter

    \chapter{Chapter}
    \section{A short title}
    \section{An obscenely long yet decent-looking title}
    \section{Network-wide time synchronization}
    \subsection{This subtitle is rendered correctly, too}
    \subsection{Dronecode debug port interface}
    \subsection{aaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaa}
\end{document}

If we were to compile it (e.g. pdflatex -interaction=nonstopmode test.tex), we'd see the following disaster:

Observe that the page numbers for the entries 1.3, 1.3.2, and 1.3.3 have been pushed off their places. This happened because of two things:

  1. LaTeX didn't know how to hyphenate the long words at the ends of the respective headings.
  2. The default tolerance settings didn't permit LaTeX to move the offending words to the next line, because that would have required it to put large white spaces between words on the previous line, which it considers ugly.

We can fix it by providing LaTeX with explicit hyphenation specification for the problem words, e.g. syn\-chroni\-zationinter\-faceaaa\-aaa\-aaa, disregard the last one).

It also makes sense to tell LaTeX that it's okay to have long white spaces in the table of contents, because the alternative that we can observe above looks far uglier. In order to permit that, use the macro \sloppy (it is commented out in the example listing above). This is what we get as the result:

Tables

Column separators

Avoid unnecessary column separating lines! 90% of tables can do just fine without them at all.

Vertical column-separating lines can be useful only if:

  • The table contains a lot of columns that should be sensibly grouped. In this case, the vertical lines are used to separate columns that belong to different groups.
  • The cells in the table contain a lot of text, so that the separating lines improve the readability of the text.

If nothing of the above describes your situation, you don't need column-separating lines!

Table footnotes

When using table footnotes, label them using lowercase letters rather than numbers. This eliminates confusion between regular footnotes (which are normally numbered) and per-table footnotes. The first table footnote should be labeled a, the second b, and so on.

Code formatting

The coding conventions for documentation are far less strict than those used for program source code, for obvious reasons of the different levels of complexity and maintenance requirements.

Blocks of code should be indented with 4 spaces. Tab characters should be avoided whenever possible.

No line of code should be longer than 120 characters.

Trailing whitespaces are not allowed; make sure to configure your text editor to automatically trim trailing whitespaces on save in the entire file.

Every text file should contain exactly one empty line at the end.

Allowed end-of-line character sequence is Unix-style (\n, LF). Windows or Mac line endings are not allowed.

Working with graphics

Avoid inclusion of complex graphics in the EPS format, because it tends to be rendered poorly by pdflatex. Prefer the PDF format instead.

Wolfram Mathematica

When exporting graphics from Wolfram Mathematica, try PDF first, and if it doesn't work (the PDF export feature often breaks on complex graphics), resort to EPS. Overall the exporting workflow should look like this:

  1. Export the graphics from Mathematica to PDF (if it doesn't work, use EPS). If annotations or other changes aren't necessary, the process ends here.
  2. Open the exported file with Inkscape.
  3. Ungroup the graphics (right click --> ungroup). If the graphics file is a plot that contains grid lines, move them all the way to the back (select the grid lines and press "End" on the keyboard). This is mandatory, otherwise the quality of the exported image may suffer.
  4. Edit the graphics as necessary (e.g. add annotations), and save it as Inkscape SVG with extension .inkscape.svg.
  5. Delete the temporary file obtained in the step 1. There is no need to keep temporary files. The Inkscape file, however, should be kept under version control in order to make editing easier later.
  6. Export the file from Inkscape into PDF and include it into the LaTeX file.

It is best to avoid grid lines when exporting via EPS; or, if they are still required, try to avoid making them dotted or dashed, because these features tend to look ugly when exported through EPS.

Linking to Confluence pages

Whenever you need to refer to a particular Confluence article, avoid copy-pasting its URL from the progress bar, because that link would be non-persistent, meaning that it may break if the article gets renamed or moved. Instead, click Share in the page menu, and then copy the short URL offered by the website. The short URL is persistent, meaning that it won't break, no matter what happens to the page as long as it is not removed.

Math expressions

Remember that by convention, variables in math expressions are written in italics, which is the default, whereas text is written in normal font.

Wrong
\begin{equation}
last{\_}response{\_}latency + 1 / (1 + can{\_}bus{\_}bit{\_}rate / 65536)
\end{equation}


Correct
\begin{equation}
\text{last{\_}response{\_}latency} + 1 / (1 + \text{can{\_}bus{\_}bit{\_}rate} / 65536)
\end{equation}

Warning management

In order to suppress useless warnings about improperly filled hbox, add the following in the preamble of the document: \hbadness=10000.

Always check the warning outputs of the compiler, especially when compiling the final version of the document!

Manual compilation

The following script is an example showing how LaTeX documents can be compiled manually without an IDE. Note that the invoked commands largely depend on what particular distribution of LaTeX is used.

#!/bin/bash

SRC=main

#rm -rf out &> /dev/null
mkdir out &> /dev/null
cp -fP *.bib out/ &> /dev/null

rm out/$SRC.pdf

pdflatex --halt-on-error --shell-escape -output-directory=out ../$SRC.tex
cd out
bibtex $SRC
#biber $SRC
cd ..
pdflatex --halt-on-error --shell-escape -output-directory=out ../$SRC.tex
pdflatex --halt-on-error --shell-escape -output-directory=out ../$SRC.tex

rm *.pdf*