latex-writing

name latex-writing description Guide LaTeX document authoring following best practices and proper semantic markup. Use proactively when: (1) writing or editing .tex files, (2) writing or editing .nw literate programming files, (3) literate-programming skill is active and working with .nw files, (4) user mentions LaTeX, BibTeX, Mentipy in a Beamer/article/PythonTeX context, interactive slide questions in LaTeX, or document formatting, (5) reviewing LaTeX code quality. Ensures proper use of semantic environments (description vs itemize), csquotes (\enquote{} not ``...''), and cleveref (\cref{} not \S\ref{}). 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: \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: \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: \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: \begin{enumerate} \item First step in the process \item Second step in the process \item Third step in the process \end{enumerate} A single-item list is prose, not a list A list with exactly one \item is never correct: it renders as an orphan bullet with no siblings to enumerate. Write the content as a prose sentence. This is rampant inside semantic environments ( exercise , definition , remark , example , block ) where a single question or one-line statement gets needlessly wrapped in itemize . % BAD — one bullet, nothing to list \begin{exercise} \begin{itemize} \item Describe your algorithm for sorting laundry. \end{itemize} \end{exercise} % GOOD — prose \begin{exercise} Describe your algorithm for sorting laundry. \end{exercise} Two short sentences dressed as two bullets are usually also better as prose. Reach for itemize / enumerate only when there are genuinely multiple, parallel, enumerable items. In dual beamer/article decks this matters doubly: a lone bullet is ugly on the slide and breaks the prose flow of the notes (see the didactic-notes skill). Never start an environment with a list or code block — lead with prose Even a genuine multi-item list must not be the first thing inside a semantic environment ( example , exercise , remark , definition , block ). Opening straight into \begin{enumerate} , \begin{itemize} , or \inputminted / \begin{minted} collides with the environment's inline label: the first list item (or the first code line) is set on the same line as \enquote{Example 1.}, and they overprint. Always precede the list or code with at least a short lead-in sentence. % BAD — enumerate/minted butts against the "Exempel 1." label \begin{example}[Att göra pannkakssmet] \begin{enumerate} \item Knäck tre ägg i en bunke. ... \end{enumerate} \end{example} \begin{example}[Hela programmet] \inputminted{python}{examples/pannkakor.py} \end{example} % GOOD — a lead-in sentence puts the list/code on its own line \begin{example}[Att göra pannkakssmet] Följ stegen: \begin{enumerate} \item Knäck tre ägg i en bunke. ... \end{enumerate} \end{example} \begin{example}[Hela programmet] Det ser ut så här: \inputminted{python}{examples/pannkakor.py} \end{example} So the rule is not \enquote{no bullets} — bullets and code are fine once a prose sentence leads into them. The prohibition is on a list or code block being the environment's opening token. Interleave Commentary Between Numbered Items (enumitem resume ) When enumerated items (survey/quiz questions, requirements, exam tasks) each need explanatory commentary, keep the \item text bare and put the commentary as prose between single-item environments, resuming the numbering with enumitem: \begin{enumerate} \item \enquote{Have you programmed before this course?} \end{enumerate} Commentary motivating the question, referencing what it serves. \begin{enumerate}[resume] \item \enquote{How do you plan to study in this course?} \end{enumerate} More commentary... Items sharing the same commentary share one environment. Requires \usepackage{enumitem} ; in dual beamer/article builds load it in the article driver only (enumitem conflicts with beamer's list internals) and keep such lists in article-mode prose, which \mode* skips in the slides job. Anti-pattern: appending the commentary inside the \item after the question text — the question and its rationale then blur together. 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 % INCORRECT \begin{itemize} \item \textbf{Passes:} \verb|\documentclass{article}| \item \textbf{Fails:} No documentclass declaration \end{itemize} Correct: Description Environment % CORRECT \begin{description} \item[Passes] \verb|\documentclass{article}| \item[Fails] No documentclass declaration \end{description} Anti-Pattern: Manual Formatting Instead of Semantic Structure % INCORRECT \noindent\textbf{Configuration:} Set timeout to 30 seconds.\\ \textbf{Performance:} Optimized for large datasets. Correct: Semantic Description % 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 % 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 % 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: % INCORRECT The \texttt{\_\_getstate\_\_} method excludes \texttt{\_original\_get\_submission}. % CORRECT The [[__getstate__]] method excludes [[_original_get_submission]]. Documenting constants: % 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: % 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 % 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. Reference-type names : the names \cref prints must match the words the prose itself uses, in any language — a document that says "steps" must not render "item 5" (override with \crefname , in an \AtBeginDocument hook registered after cleveref so a language option's own hook doesn't silently overwrite it). In non-English documents, cleveref additionally takes its language from its own package options or the global class options, not from babel. Several kinds in one document are handled per label ( \label[type]{...} ) or per environment (enumitem \newlist , one counter per list — not in beamer). Full guidance in references/cleveref-type-names.md (search: crefname , terminology , AtBeginDocument , label[type] , newlist , swedish , enumi , appendix ). 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 % INCORRECT "This is a quote" ``This is a quote'' 'single quotes' Correct : Use csquotes % CORRECT \enquote{This is a quote}