latex-writing

What this skill does

# 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`

### Exception: Pedagogical Meta-Commentary

Do not use a visible `description` list for instructor-facing pedagogical
annotations such as \enquote{What varies}, \enquote{What stays invariant},
or sequencing rationale in educational materials.  Those belong in
`\ltnote{...}` via the `didactic-notes` skill.  Use `description` only
when the labeled content is part of the student-facing document itself.

### 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]]` vs `\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]` → Either rephrase the label and put
  `[[SOME_CONSTANT]]` in the body, or wrap the constant in `[[...]]`
  inside the label — `\item[ [[SOME_CONSTANT]] behavior]`.  If you take
  the second option, separate the `]]` from the closing `]` with at
  least one character (usually a space) so you do not produce three
  brackets in a row, which triggers a runaway-argument error.

### 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