LaTeX Writing Best Practices

This skill guides the creation of well-structured, semantically correct LaTeX documents following established best practices.

Core Principle: Semantic Markup

Use LaTeX environments that match the semantic meaning of the content, not just the visual appearance.

List Environments: When to Use What

Use

description

for Term-Definition Pairs

When you have labels followed by explanations, definitions, or descriptions, use the

description

environment:

latex

\begin{description}
\item[Term] Definition or explanation of the term
\item[Label] Content associated with the label
\item[Property] Description of the property
\end{description}

NEVER do this:

latex

\begin{itemize}
\item \textbf{Term:} Definition or explanation
\item \textbf{Label:} Content associated with label
\end{itemize}

Common Use Cases for

description

API parameters:
```
\item[username] The user's login name
```

Configuration options:

\item[timeout] Maximum wait time in seconds

Glossary entries:

\item[LaTeX] A document preparation system

Passes/Fails examples:
```
\item[Passes] Correct implementation...
```

Feature descriptions:

\item[Auto-save] Automatically saves every 5 minutes

Use

itemize

for Simple Lists

Use

itemize

when items are uniform list elements without labels:

latex

\begin{itemize}
\item First uniform item
\item Second uniform item
\item Third uniform item
\end{itemize}

Use

enumerate

for Numbered Steps or Rankings

Use

enumerate

when order matters:

latex

\begin{enumerate}
\item First step in the process
\item Second step in the process
\item Third step in the process
\end{enumerate}

Recognition Patterns

When reviewing or writing LaTeX, look for these patterns that indicate

description

should be used:

\item \textbf{SomeLabel:}

→ Should use

\item[SomeLabel]

```
\item \emph{SomeLabel:}
```
→ Should use
```
\item[SomeLabel]
```
```
\item SomeLabel ---
```
→ Should use
```
\item[SomeLabel]
```
Lists where every item starts with bold/emphasized text

Fixing Common Anti-Patterns

Anti-Pattern: Bold Labels in Itemize

latex

% INCORRECT
\begin{itemize}
\item \textbf{Passes:} \verb|\documentclass{article}|
\item \textbf{Fails:} No documentclass declaration
\end{itemize}

Correct: Description Environment

latex

% CORRECT
\begin{description}
\item[Passes] \verb|\documentclass{article}|
\item[Fails] No documentclass declaration
\end{description}

Anti-Pattern: Manual Formatting Instead of Semantic Structure

latex

% INCORRECT
\noindent\textbf{Configuration:} Set timeout to 30 seconds.\\
\textbf{Performance:} Optimized for large datasets.

Correct: Semantic Description

latex

% CORRECT
\begin{description}
\item[Configuration] Set timeout to 30 seconds
\item[Performance] Optimized for large datasets
\end{description}

Literate Programming (.nw files)

CRITICAL: When writing LaTeX in literate programming files (.nw), use noweb's

[[code]]

notation for quoting code, not

\texttt

with manual escaping.

Use

[[code]]

Notation, Not

\texttt{...\_...}

The noweb literate programming system provides special notation for code references that automatically handles special characters like underscores.

Anti-pattern: Manual underscore escaping with

\texttt

latex

% INCORRECT - in .nw files
The \texttt{get\_submission()} method calls \texttt{\_\_getattribute\_\_}.
We store \texttt{\_original\_get\_submission} in the closure.
The \texttt{NOREFRESH\_GRADES} constant defines final grades.

Correct: Use

[[code]]

notation

latex

% CORRECT - in .nw files
The [[get_submission()]] method calls [[__getattribute__]].
We store [[_original_get_submission]] in the closure.
The [[NOREFRESH_GRADES]] constant defines final grades.

Why this matters:

Automatically escapes special characters (underscores, backslashes, etc.)
Makes source code more readable (no manual escaping)
Follows literate programming conventions
Prevents LaTeX errors from forgotten escapes
Clearly distinguishes code from prose

When to Use

[[code]]

\texttt

Use
[[code]]
in .nw files for:

Function and method names:
```
[[get_submissions()]]
```
,
```
[[__init__]]
```
Variable names:
```
[[_includes]]
```
,
```
[[user_id]]
```
Class names:
```
[[LazySubmission]]
```
,
```
[[Assignment]]
```
Constants:
```
[[NOREFRESH_GRADES]]
```
,
```
[[MAX_RETRIES]]
```
Module names:
```
[[pickle]]
```
,
```
[[Canvas]]
```
Any identifier with underscores or special characters

Use
\texttt
in .nw files for:

Short non-code technical terms without special characters
File extensions:
```
\texttt{.py}
```
,
```
\texttt{.nw}
```
Simple commands without underscores

In regular .tex files (not literate programs):

Use
```
\texttt
```
with proper escaping as
```
[[...]]
```
is not available
Or use packages like
```
minted
```
or
```
listings
```
for code

Recognition Pattern for Review

When reviewing .nw files, look for these anti-patterns:

```
\texttt{..._...}
```
→ Should use
```
[[...]]
```
```
\texttt{...__...}
```
→ Should use
```
[[...]]
```

\item[SOME\_CONSTANT behavior]

→ Should use better label +

[[SOME_CONSTANT]]

in text

Examples from Real Code

Documenting methods:

latex

% INCORRECT
The \texttt{\_\_getstate\_\_} method excludes \texttt{\_original\_get\_submission}.

% CORRECT
The [[__getstate__]] method excludes [[_original_get_submission]].

Documenting constants:

latex

% INCORRECT
\item[NOREFRESH\_GRADES behavior] Submissions with final grades...

% CORRECT
\item[Final grade policy] Submissions with final grades (A, P, P+, complete)
  are never refreshed, maintaining the [[NOREFRESH_GRADES]] policy.

Documenting attributes:

latex

% INCORRECT
The decorator adds a \texttt{\_\_cache} dictionary and \texttt{\_\_all\_fetched} flag.

% CORRECT
The decorator adds a [[__cache]] dictionary and [[__all_fetched]] flag.

Additional Best Practices

Cross-References

Always use
```
\cref{...}
```
(cleveref package) for all cross-references
Never use
```
\S\ref{...}
```
or manually type section/figure prefixes
Use descriptive labels:
```
\label{sec:introduction}
```
not
```
\label{s1}
```
Examples:
- Sections:
```
\cref{sec:background}
```
  → "Section 2.1"
- Figures:
```
\cref{fig:diagram}
```
  → "Figure 3"
- Tables:
```
\cref{tab:results}
```
  → "Table 1"
- Multiple:
```
\cref{sec:intro,sec:conclusion}
```
  → "Sections 1 and 4"

Anti-pattern: Manual prefixes

latex

% INCORRECT
Section~\ref{sec:intro} shows...
\S\ref{sec:background} discusses...
Figure~\ref{fig:plot} demonstrates...

% CORRECT
\cref{sec:intro} shows...
\cref{sec:background} discusses...
\cref{fig:plot} demonstrates...

Why: The cleveref package automatically adds the correct prefix (Section, Figure, etc.) and handles pluralization, ranges, and language-specific formatting.

Citations

Use proper citation commands (
```
\cite
```
,
```
\citep
```
,
```
\citet
```
) not manual references
Never write
```
[1]
```
or
```
(Smith 2020)
```
manually

Quotations (csquotes package)

Always use
```
\enquote{...}
```
for quotes, never manual quote marks
Handles nested quotes automatically:
```
\enquote{outer \enquote{inner} quote}
```
Language-aware: Swedish uses »...« or "...", English uses "..." or '...'

For block quotes, use

\begin{displayquote}...\end{displayquote}

Anti-pattern: Manual quotes

latex

% INCORRECT
"This is a quote"
``This is a quote''
'single quotes'

Correct: Use csquotes

latex

% CORRECT
\enquote{This is a quote}
\enquote{outer \enquote{inner} quote}

Why: Manual quote marks don't adapt to language settings and can cause typographical inconsistencies. The csquotes package handles all quote styling correctly based on document language.

Emphasis

Never use ALL CAPITALS for emphasis in running text
Use
```
\emph{...}
```
to emphasize words or phrases
For strong emphasis, use
```
\textbf{...}
```
or nested
```
\emph{\emph{...}}
```
Let LaTeX handle the typographic styling

Anti-pattern: ALL CAPITALS for emphasis

latex

% INCORRECT
This is VERY important to understand.
We must do this NOW before moving forward.
The BENEFITS of classes are clear.

Correct: Semantic emphasis

latex

% CORRECT
This is \emph{very} important to understand.
We must do this \emph{now} before moving forward.
The \emph{benefits} of classes are clear.

Why: ALL CAPITALS in running text is considered shouting and poor typography. It's harder to read and looks unprofessional. Use

\emph{...}

to provide semantic emphasis, and LaTeX will render it appropriately (typically as italics, but this can be configured based on context and document style).

Exception: Acronyms and proper names that are conventionally written in capitals (e.g., NASA, USA, PDF) are fine and should not be emphasized.

Floats: Figures and Tables

Core principle: An image is not a figure, but a figure can contain an image. Use proper figure and table environments with captions and labels.

Using sidecaption (memoir class)

When using the memoir document class, prefer

sidecaption

over traditional

\caption

for better layout and accessibility:

For figures:

latex

\begin{figure}
  \begin{sidecaption}{Clear description of image content}[fig:label]
    \includegraphics[width=0.7\textwidth]{path/to/image}
  \end{sidecaption}
\end{figure}

For tables:

latex

\begin{table}
  \begin{sidecaption}{Description of table content}[tab:label]
    \begin{tabular}{lcc}
      \toprule
      Header1 & Header2 & Header3 \\
      \midrule
      Data1 & Data2 & Data3 \\
      \bottomrule
    \end{tabular}
  \end{sidecaption}
\end{table}

Key features of sidecaption:

Caption placement: Caption appears alongside the content (figure/table), not above or below
Space efficiency: Better use of page width, especially for narrow images/tables
Improved readability: Caption and content are visually connected
Accessibility: Clear semantic separation between caption text and content
Consistent labeling: Label goes in optional second argument
```
[fig:label]
```

When to use sidecaption:

Medium-sized figures/tables that don't need full text width
Educational materials where caption-content proximity aids understanding
Documents using memoir class (Beamer presentations with memoir features)

Traditional caption alternative:

latex

\begin{figure}
  \centering
  \includegraphics[width=0.7\textwidth]{path/to/image}
  \caption{Description of image content}
  \label{fig:label}
\end{figure}

Use traditional

\caption

\label

when:

Not using memoir class
Figure/table spans full text width
Caption naturally belongs below content (e.g., wide tables)

Referencing figures and tables

Always use

\cref{fig:label}

(cleveref package) to reference figures and tables:

latex

As shown in \cref{fig:memory-hierarchy}, secondary memory is slower but non-volatile.

The results in \cref{tab:benchmark} demonstrate...

Never hard-code references like "Figure 1", "Table 3.2", or use manual prefixes like

Figure~\ref{fig:label}

—let cleveref handle both numbering and prefixes automatically.

Verbatim and Code

Use
```
listings
```
package for code with syntax highlighting
Use
```
\verb
```
for inline code snippets
Never paste code as normal text

Paths

Always use forward slashes in paths:
```
figures/diagram.pdf
```
not
```
figures\diagram.pdf
```
Use platform-independent path specifications

Workflow for Writing LaTeX

When writing or editing LaTeX content:

Check file type: Are you in a .nw literate programming file? If yes, use
```
[[code]]
```
notation, not
```
\texttt{...\_...}
```
Identify content structure: Is this a list of uniform items or term-definition pairs?
Choose semantic environment: Match the environment to the content meaning
Use proper commands: Leverage LaTeX's semantic commands rather than manual formatting
Verify cross-references: Ensure labels and references are descriptive and correct
Check for anti-patterns: Review for
```
\textbf{Label:}
```
in itemize,
```
\texttt{..._...}
```
in .nw files

When Reviewing LaTeX Code

Check for these common issues:

Lists using
```
\textbf{Label:}
```
instead of
```
description
```
environment
Hard-coded numbers instead of
```
\ref
```
Manual cross-reference prefixes (
```
\S\ref
```
,
```
Section~\ref
```
,
```
Figure~\ref
```
) instead of
```
\cref
```
Manual citation formatting instead of
```
\cite
```
commands
Manual quotes (
```
"..."
```
,
```
'...'
```
,
```
`...`
```
) instead of
```
\enquote{...}
```
Images without
```
figure
```
environment
Code without proper formatting (listings/verbatim)
Windows-style backslashes in paths

Additional checks for .nw literate programming files:

\texttt{..._...}

\texttt{...__...}

→ Should use

[[...]]

notation

Description labels with underscores
```
\item[FOO\_BAR behavior]
```
→ Use better label +
```
[[FOO_BAR]]
```
in text
Any manually escaped underscores in code references → Use
```
[[...]]
```
instead

Beamer: Presentation vs Article Mode

When creating Beamer presentations that also generate article versions, use

\mode<presentation>

and

\mode<article>

to provide appropriate content for each format.

When to Split Content

Verbose text environments: Semantic environments (definition, remark, example, block) with more than 2-3 lines of prose are too verbose for slides.

Solution: Provide concise versions for presentations and full explanations for articles:

latex

\begin{frame}
  \mode<presentation>{%
    \begin{remark}[Key Point]
      \begin{itemize}
        \item Concise point 1
        \item Concise point 2
        \item Concise point 3
      \end{itemize}
    \end{remark}
  }
  \mode<article>{%
    \begin{remark}[Key Point]
      Full explanatory paragraph with detailed reasoning and context
      that would overwhelm a slide but provides value in written form.

      Additional paragraphs can elaborate on nuances and implications.
    \end{remark}
  }
\end{frame}

Visual Elements

Side-by-side layouts using

\textbytext

Presentation:
```
\textbytext
```
(non-starred, column width, works in beamer frames)
Article:
```
\textbytext*
```
(starred, fullwidth, better for printed documents)

latex

\begin{frame}
  \mode<presentation>{%
    \textbytext{Left content}{Right content}
  }
  \mode<article>{%
    \textbytext*{Left content}{Right content}
  }
\end{frame}

Principle

Slides need visual clarity and conciseness (bullets, short phrases). Articles can provide depth and explanation (full sentences, paragraphs). Design content appropriate for each medium.

Standard Preamble

For new LaTeX documents, use the standard preamble from

references/preamble.tex

. Copy it verbatim to your project's

doc/preamble.tex

and include it with

\input{preamble}

after

\documentclass

Document structure:

latex

\documentclass[a4paper,oneside]{memoir}
\input{preamble}

\title{Document Title}
\author{Author Name}
\date{\today}

\begin{document}
\frontmatter
\maketitle
\tableofcontents

\mainmatter
% Content here

\backmatter
\end{document}

The standard preamble provides:

Language support (babel with swedish, british)
Bibliography (biblatex with alphabetic style)
Code highlighting (minted, noweb)
Mathematics (amsmath, amssymb, mathtools, amsthm)
Cross-references (cleveref with custom labels)
Quotations (csquotes)
Tables (booktabs)
Various utilities (enumitem, acro, siunitx, etc.)

This ensures consistent formatting across all documents and projects.

Remember

LaTeX is a document preparation system based on semantic markup, not a word processor. The goal is to describe what content is, not how it should look. Let LaTeX handle the formatting based on the semantic structure you provide.

latex-writing

NPX Install

Tags

SKILL.md Content

LaTeX Writing Best Practices

Core Principle: Semantic Markup

List Environments: When to Use What

Use
`description`
for Term-Definition Pairs

Common Use Cases for
`description`

Use
`itemize`
for Simple Lists

Use
`enumerate`
for Numbered Steps or Rankings

Recognition Patterns

Fixing Common Anti-Patterns

Anti-Pattern: Bold Labels in Itemize

Correct: Description Environment

Anti-Pattern: Manual Formatting Instead of Semantic Structure

Correct: Semantic Description

Literate Programming (.nw files)

Use
`[[code]]`
Notation, Not
`\texttt{...\_...}`

When to Use
`[[code]]`
vs
`\texttt`

Recognition Pattern for Review

Examples from Real Code

Additional Best Practices

Cross-References

Citations

Quotations (csquotes package)

Emphasis

Floats: Figures and Tables

Using sidecaption (memoir class)

Referencing figures and tables

Verbatim and Code

Paths

Workflow for Writing LaTeX

When Reviewing LaTeX Code

Beamer: Presentation vs Article Mode

When to Split Content

Visual Elements

Principle

Standard Preamble

Remember

latex-writing

NPX Install

Tags

SKILL.md Content

LaTeX Writing Best Practices

Core Principle: Semantic Markup

List Environments: When to Use What

Use description for Term-Definition Pairs

Common Use Cases for description

Use itemize for Simple Lists

Use enumerate for Numbered Steps or Rankings

Recognition Patterns

Fixing Common Anti-Patterns

Anti-Pattern: Bold Labels in Itemize

Correct: Description Environment

Anti-Pattern: Manual Formatting Instead of Semantic Structure

Correct: Semantic Description

Literate Programming (.nw files)

Use [[code]] Notation, Not \texttt{...\_...}

When to Use [[code]] vs \texttt

Recognition Pattern for Review

Examples from Real Code

Additional Best Practices

Cross-References

Citations

Quotations (csquotes package)

Emphasis

Floats: Figures and Tables

Using sidecaption (memoir class)

Referencing figures and tables

Verbatim and Code

Paths

Workflow for Writing LaTeX

When Reviewing LaTeX Code

Beamer: Presentation vs Article Mode

When to Split Content

Visual Elements

Principle

Standard Preamble

Remember

Use
`description`
for Term-Definition Pairs

Common Use Cases for
`description`

Use
`itemize`
for Simple Lists

Use
`enumerate`
for Numbered Steps or Rankings

Use
`[[code]]`
Notation, Not
`\texttt{...\_...}`

When to Use
`[[code]]`
vs
`\texttt`