Page History

Key

• This line was added.
• This line was removed.
• Formatting was changed.

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

Contents

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:

View file
name lshort.pdf 150

 maxLevel 3

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.

IDE options

Visual Studio Code

VSCode is the recommended choice for editing LaTeX documents. Use the following extensions:

• ban.spellright

• James-Yu.latex-workshop

Don't forget to configure Hunspell for SpellRight, otherwise spell checking will not work.

Image Removed

Texmaker IDE

Installation

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

Code Block
language bash 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:

Code Block
language bash
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:

Image Removed

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

...

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 figtable, or sec;
• "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.

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.

...

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 Almost all tables can do just fine without them at all.

...

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.

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:

Code Block
title 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.

...

Code Block
title Wrong

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


...

Code Block
title Correct

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


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.

Code Block
\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:

Code Block
language bash 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.spellright or znck.grammarly

• James-Yu.latex-workshop

• ms-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:

Code Block
language py settings.json (fragment) true
    "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%"
]
}
]