Lab Guidelines for LaTeX

Last update: 2026-01-22

Download a summary slide deck, auto-generated by NotebookLM.

A short video overview, auto-generated by NotebookLM is available at the bottom of this page.

Organization of LaTeX documents

• For short documents (e.g., a paper of 15 pages or less, a short report, a book chapter):
  • If a single author (the first author) is mainly responsible for writing and editing the paper, possibly with inputs from co-authors, then use a single file main.tex and write the entire content in it (i.e., do not split each section into a separate file).
  • However, if multiple authors will co-edit the paper at the same time, especially using a version control system like git, there is a risk of conflicts and the document should be split into multiple files as for long documents (see below).
• For long documents (e.g., a very long paper or report, a thesis, a book, which often has multiple “chapters”), or when there is a significant risk of conflicts when multiple authors edit the paper at the same time:
  • Split the document into multiple TeX files, one for each logical part of the document, such as a chapter or a section.
  • Use descriptive names for these files, such as intro.tex and experiment.tex; do not use generic names like section1.tex and do not include orders in the file names like 1-intro.tex. The order should be specified in the main document, not fixed by the file name. The main document main.tex then include / input these part files, using \input (or in certain cases, \include or \includeonly).
• If desired or if the preamble is too long and complex (e.g., many complex settings, custom commands, etc.), write the preamble in a separate file such as preamble.tex and \input it in the main file.
• For figures:
  • Store the figure files in a folder figs or figures (lowercase letters, no spaces) and include them from that folder.
  • If a figure is created with LaTeX (like TikZ, pgfplots), use a separate TeX file for it (don’t put the code in the main LaTeX file), store that file in the figure folder, and \input it in the main document.
  • If a figure is created using a tool like draw.io, IPE, or Dia, include the source file in the folder in addition to the exported figure file (preferably PDF).
• Tables should be written directly in the main TeX file, unless it’s a long and complex table (like a whole-page table) or it’s created automatically by another tool then it may be stored in a separate TeX file and included in the main document. A useful tool for LaTeX tables, especially complex ones, is https://www.tablesgenerator.com/.
• BibTeX files and other support files are separate.

General rules

• Line breaks: these rules are created to work well with version control, like git.

  • Write each sentence on its own line. New sentence = new line.
  • But do not include a commented line like %% everytime between two consecutive sentences/lines.
  • Change-of-state commands are on their own line, e.g. \begin{environment}, \[.
  • Long pieces of inline maths should be on their own lines.
  • Within, say, an align environment long column entries should be on their own lines and certainly \\ should terminate a line.
  • A new paragraph is created with a blank line, not with \\.

• Labeling: Name a label (of a section, figure, table, etc.) with a prefix, followed by a colon, followed by a short but descriptive name: <prefix>:<name>. Use the standard prefixes in the table below.

  • The name should be descriptive; for example fig:figure1 is bad (what is figure 1?) while fig:rmse-room-temp is good (it’s a plot of the RMSE of the room temperature predictions).
  • Use : or - to separate scopes, use - instead of _ for a space, and never include spaces in labels.
  • For example, sec:overview:dnn or sec:overview-dnn for a subsection on DNN within the larger section “Overview”, and fig:rmse-room-temp instead of fig:rmse_room_temp or fig:rmse room temp (the last one is really bad, don’t use spaces in label identifiers).
  • Similarly, use short but descriptive names for equations, for example: don’t use eq:equation1 but use eq:system-model for the system model, eq:mpc-objective (or eq:mpc:objective) and eq:mpc-state-constraint (or eq:mpc:state-constraint) for the objective function subequation and the state constraint subequation, respectively, of an MPC problem.
  • The tables below list some standard prefixes and some good and bad examples.

• Put ~ in front of each reference or citation command, unless the reference/citation is the subject of a sentence or starts a sentence. Example: The authors of~\cite{paper}, a method is proposed in~\cite{paper}, see Figure~\ref{figure}.
• Use \eqref{}, not (\ref{}), for equations.
• For references, can use the package cleveref and use the command \cref, which automatically determines the type of the reference and uses the correct name for it. For example: \cref{fig:myfig} produces equivalently Figure~\ref{fig:myfig}.

Defining LaTeX Commands / Macros

A macro should improve clarity, consistency, and maintainability, especially in collaborative writing. They are not meant to save keystrokes or encode personal shorthand.

Define a command only when it provides real value

A new command is appropriate only if at least one applies:

• Complex or error-prone constructs: Use macros for long, nontrivial, or error-prone definitions that are hard to remember or reproduce correctly (e.g., structured math layouts, optimization problems, custom formatting).
• High-frequency usage with semantic clarity: It is frequently used (many times) and adds semantic clarity/readability or improves consistency. Example: \textblue{text} instead of repeatedly typing \textcolor{blue}{text}) to mark many changes in the document.
• Semantic abstraction (future-proofing): It represents a concept, symbol, name, or notation that may change later (e.g., \CovMatrix, \LossFn). If the notation changes, redefine the macro, no need to search-and-replace the document.

If none apply, do not define a macro.

When You Should Not Define a Command

Do not define macros for:

• Simply saving a few characters (\tb for \textbf)
• Aliasing standard LaTeX commands (\mb for \mathbf, \tb for \textbf, \td for \tilde, \bb for \cite)
• Structural elements (\newcommand{\bitem}{\begin{itemize}}). An environment is not a macro/command.
• Purely personal abbreviations
• Infrequent usage

Command Naming Rules

• Encode meaning, not appearance alone: Macros should represent what something is, not merely how it looks, unless the formatting itself carries meaning and is consistently used. Good name: \newcommand{\CovMatrix}{\Sigma}. Less good name: \newcommand{\bSigma}{\boldsymbol{\Sigma}}.

• Intuitive, descriptive, and guessable: Prefer clarity over brevity. Avoid cryptic abbreviations and personal shorthand. Readability and maintainability matter more than brevity. A collaborator should be able to infer the meaning from the name.

  • Good names: \textblue{...}, \CovMatrix, \LossFunction.
  • Bad names (ambiguous, unreadable, can you guess?): \tb{...}, \mb, \lam, \ba, \ea.

• Follow LaTeX conventions: it’s easier to read and understand. Examples:

  • Text commands: \textSomething like \textblue.
  • Math objects: PascalCase like \CovMatrix, \LossFcn
  • Operators: use \DeclareMathOperator and standard names, like \argmin instead of \amn, \diag instead of \dg.

Safety and Technical Rules

• Never override standard commands: Do not redefine or shadow/alias existing commands (like \bb for \cite, \lam for \lambda, \td for \tilde, etc.). This causes confusion and subtle bugs, especially across packages.

• Use \newcommand: Use \newcommand to avoid accidental redefinitions. Use \renewcommand only when intentional and clearly documented. Avoid \def.

• Be consistent and reuse when possible: Learn and use the lab’s standard package icpslab.sty instead of defining your own duplicates. Do not create multiple macros for the same concept.

• Centralize and document macros: For each document, put all custom macros in one file like defs.tex and include it in the main document. Add a brief comment if a macro may be less intuitive to understand. Delete unused macros.

Good Examples

% Covariance matrix (notation may change)
\newcommand{\CovMatrix}{\Sigma}

% Standard math notation
\DeclareMathOperator{\argmin}{arg\,min}

% Consistent typography, Easy to change globally
\newcommand{\PINN}{\textsc{PINN}}

% Semantic (not arbitrary styling), Clear purpose
\newcommand{\revchange}[1]{\textcolor{blue}{#1}}

% Clear meaning, easy to read, easy to change globally
\newcommand{\StateVector}{\bm{x}}
\newcommand{\StateSet}{\mathcal{X}}
\newcommand{\NoiseVar}{\sigma^2}

Bad Examples

% Saves minimal typing; Cryptic; Less readable
\newcommand{\lra}{\leftrightarrow}

% Overrides a standard command; ambiguous; saves minimal typing
\newcommand{\mb}{\mathbf}
\newcommand{\tb}{\textbf}
\newcommand{\td}{\tilde}
\newcommand{\non}{\nonumber}

% Cryptic; no semantic meaning (instead, name it \warning{}) 
\newcommand{\tcr}{\textcolor{red}}

% Overrides a standard environment; unclear
\newcommand{\bitem}{\begin{itemize}}

Marking changes / revisions

Use either latexdiff (for automatic marking, useful if used with a version control system) or the changes package (for manual marking, useful for multiple authors). Using the changes package requires more effort and must use it right from the beginning, while using the latexdiff tool is easier and needs little planning (just revise as usual then create the diff).

Another way is to manually color the text pieces to mark for changes, using the xcolor package and commands like \textcolor and \color.

Short video overview