¶ Zubax LaTeX coding conventions
This page summarizes the coding conventions and best practices adopted by Zubax for LaTeX documents.
The reader is assumed to be well familiar with LaTeX; if not, make sure to read the Not So Short Introduction to LaTeX2e, attached here: lshort.pdf
¶ Style
¶ 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.
¶ References
Always insert a non-breakable space before reference: refer to section~\ref{sec:chapter_section}.
When defining a new label, you must use the prefix following the pattern kind:chapter, where:
- "kind" is the kind of the labeled item, such as
fig,tableorsec; - "chapter" is the name of the file where the chapter is contained.
The label that contains only the prefix points to the chapter itself using the kind sec. For example, if the chapter is named "Transport layer", its label would be sec:transport.
Items contained inside the chapter (sections, figures, tables) are named using free form appended to the prefix. For example, one could refer to a figure contained inside the chapter "Chapter" as fig:chapter_my_figure.
The above rules are crucial to follow to keep cross-references usable in large documents. Without strict conventions in place, they quickly become unmanageable.
¶ Headings and captions
Do not force capitalization. For example, "Power supply characteristics" is a well-formed heading, whereas "Power Supply Characteristics" is not.
Do not put a full stop after a caption unless it contains any other punctuation or is more than one sentence long.
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:
-
LaTeX didn't know how to hyphenate the long words at the ends of the respective headings.
-
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\-zation, inter\-face.
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
Avoid unnecessary column separating lines! Almost all 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!
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.
¶ Footnotes
When starting a footnote on a new line after an opening brace, don't forget to squelch the unnecessary whitespace by inserting a comment character after the brace:
Footnote
Some regular text\footnote{%
The text of the footnote. Notice the comment character above.
} ends here.
¶ Working with graphics
JPEG images are not permitted except for photos.
Drawings, diagrams, plots, and other similar kinds of imagery must be in vector formats such as PDF, EPS, SVG, etc; PNG is explicitly prohibited because of image quality issues.
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:
- 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.
- Open the exported file with Inkscape.
- 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.
- Edit the graphics as necessary (e.g. add annotations), and save it as Inkscape SVG with extension
.inkscape.svg. - 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.
- 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}
The decimal separator is a dot, e.g., 12.34.
¶ 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!
¶ LaTeX source 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 are not allowed.
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.
All environments should be intended, excepting the outermost \begin{document} environment.
There shall be no more than one consecutive blank line.
There shall be at most one chapter per source file.
There shall be one blank line above and below a section header, unless the section header is at the top of the source file.
Multi-line content enclosed in curly braces should be indented.
If a list item spills on the next line, the spilled text should be indented on the same level with the first line.
\begin{itemize}
\item This list item is sufficiently long to exceed the limit of 120 characters per line,
so it has to spill onto the next line.
The spilled part is indented correctly.
\item Another item.
\end{itemize}
% The next line contains a comment to remove the whitespace in the beginning of the footnote.
Regulated non-standard definitions\footnote{%
I.e., public definitions contributed by vendors and other users
of the specification, as explained in section~\ref{sec:basic_data_type_regulation}.
} are not included in this list.
¶ Toolchain
¶ LaTeX distribution
To use LaTeX and the required dependencies on a Debian-based system (e.g., Ubuntu or Mint), install the following packages:
Setting up LaTeX
sudo apt-get install texlive-full lyx python-pygments
An Arch-based distro requires the following packages:
texlive-most(group)
¶ IDE
VSCode is the recommended choice for editing LaTeX documents. Use the following extensions:
ban.spellrightorznck.grammarlyJames-Yu.latex-workshopms-vscode-remote.vscode-remote-extensionpack(you will need it for containerized toolchains)
Beware that you may run into issues if you use an OSS build of VSCode. It is recommended to use the official binary from Micro$oft.
Don't forget to configure Hunspell for SpellRight, otherwise spell checking will not work.
You will need to manually configure the LaTeX toolchain. You can use the existing projects as a reference, or you could base your configuration on the following snippet:
settings.json (fragment)
"latex-workshop.latex.recipes": [
{
"name": "pdflatex x3",
"tools": [
"pdflatex",
"pdflatex",
"pdflatex"
]
}
],
"latex-workshop.latex.tools": [
{
"name": "pdflatex",
"command": "pdflatex",
"args": [
"-synctex=1",
"-interaction=nonstopmode",
"-file-line-error",
"--halt-on-error",
"--shell-escape",
"%DOC%"
]
},
{
"name": "bibtex",
"command": "bibtex",
"args": [
"%DOCFILE%"
]
}
]
¶ 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*