latex-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LaTeX Writing Best Practices

LaTeX文档编写最佳实践

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

本指南遵循既定最佳实践，指导创建结构清晰、语义正确的LaTeX文档。

Core Principle: Semantic Markup

核心原则：语义标记

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

使用与内容语义含义匹配的LaTeX环境，而非仅追求视觉外观。

List Environments: When to Use What

列表环境：场景选择

Use

description

for Term-Definition Pairs

术语-定义配对使用

description

环境

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}

当内容为标签加解释、定义或描述时，使用

description

环境：

latex

\begin{description}
\item[Term] 术语的定义或解释
\item[Label] 与标签关联的内容
\item[Property] 属性的描述
\end{description}

绝对不要这样做：

latex

\begin{itemize}
\item \textbf{Term:} 定义或解释
\item \textbf{Label:} 与标签关联的内容
\end{itemize}

Common Use Cases for

description

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

API参数：
```
\item[username] 用户登录名
```

配置选项：

\item[timeout] 最大等待时间（秒）

词汇表条目：
```
\item[LaTeX] 一种文档排版系统
```
通过/失败示例：
```
\item[Passes] 正确实现...
```

功能描述：

\item[Auto-save] 每5分钟自动保存一次

Use

itemize

for Simple Lists

简单列表使用

itemize

环境

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}

当列表项为无标签的统一元素时，使用

itemize

环境：

latex

\begin{itemize}
\item 第一个统一列表项
\item 第二个统一列表项
\item 第三个统一列表项
\end{itemize}

Use

enumerate

for Numbered Steps or Rankings

有序步骤或排名使用

enumerate

环境

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}

当列表项顺序重要时，使用

enumerate

环境：

latex

\begin{enumerate}
\item 流程的第一步
\item 流程的第二步
\item 流程的第三步
\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

编写或审查LaTeX时，若发现以下模式，应使用

description

环境：

\item \textbf{SomeLabel:}

→ 应改为

\item[SomeLabel]

```
\item \emph{SomeLabel:}
```
→ 应改为
```
\item[SomeLabel]
```
```
\item SomeLabel ---
```
→ 应改为
```
\item[SomeLabel]
```
所有列表项均以粗体/斜体文本开头的列表

Fixing Common Anti-Patterns

常见反模式修正

Anti-Pattern: Bold Labels in Itemize

反模式：Itemize环境中使用粗体标签

latex

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

latex

% 错误示例
\begin{itemize}
\item \textbf{Passes:} \verb|\documentclass{article}|
\item \textbf{Fails:} 无documentclass声明
\end{itemize}

Correct: Description Environment

正确做法：使用Description环境

latex

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

latex

% 正确示例
\begin{description}
\item[Passes] \verb|\documentclass{article}|
\item[Fails] 无documentclass声明
\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.

latex

% 错误示例
\noindent\textbf{Configuration:} 将timeout设置为30秒。\\
\textbf{Performance:} 针对大型数据集优化。

Correct: Semantic Description

正确做法：语义化Description

latex

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

latex

% 正确示例
\begin{description}
\item[Configuration] 将timeout设置为30秒
\item[Performance] 针对大型数据集优化
\end{description}

Literate Programming (.nw files)

Literate编程（.nw文件）

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

[[code]]

notation for quoting code, not

\texttt

with manual escaping.

关键注意事项：在literate编程文件（.nw）中编写LaTeX时，使用noweb的

[[code]]

标记引用代码，而非手动转义的

\texttt

。

Use

[[code]]

Notation, Not

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

使用

[[code]]

标记，而非

\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

noweb literate编程系统提供了专门的代码引用标记，可自动处理下划线等特殊字符。

反模式：使用

\texttt

手动转义下划线

latex

% .nw文件中的错误示例
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.

正确做法：使用

[[code]]

标记

latex

% .nw文件中的正确示例
The [[get_submission()]] method calls [[__getattribute__]].
We store [[_original_get_submission]] in the closure.
The [[NOREFRESH_GRADES]] constant defines final grades.

为什么这很重要：

自动转义特殊字符（下划线、反斜杠等）
源代码可读性更高（无需手动转义）
遵循literate编程约定
避免因遗忘转义导致的LaTeX错误
清晰区分代码与正文

When to Use

[[code]]

\texttt

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

在.nw文件中使用
[[code]]
：

函数和方法名：
```
[[get_submissions()]]
```
,
```
[[__init__]]
```
变量名：
```
[[_includes]]
```
,
```
[[user_id]]
```
类名：
```
[[LazySubmission]]
```
,
```
[[Assignment]]
```
常量：
```
[[NOREFRESH_GRADES]]
```
,
```
[[MAX_RETRIES]]
```
模块名：
```
[[pickle]]
```
,
```
[[Canvas]]
```
任何包含下划线或特殊字符的标识符

在.nw文件中使用
\texttt
：

无特殊字符的简短非代码技术术语
文件扩展名：
```
\texttt{.py}
```
,
```
\texttt{.nw}
```
无下划线的简单命令

在常规.tex文件中（非literate程序）：

使用带正确转义的
```
\texttt
```
，因为
```
[[...]]
```
不可用
或使用
```
minted
```
或
```
listings
```
等包处理代码

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

审查.nw文件时，注意以下反模式：

```
\texttt{..._...}
```
→ 应改为
```
[[...]]
```
```
\texttt{...__...}
```
→ 应改为
```
[[...]]
```

\item[SOME\_CONSTANT behavior]

→ 应优化标签并在正文中使用

[[SOME_CONSTANT]]

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.

文档化方法：

latex

% 错误示例
The \texttt{\_\_getstate\_\_} method excludes \texttt{\_original\_get\_submission}.

% 正确示例
The [[__getstate__]] method excludes [[_original_get_submission]].

文档化常量：

latex

% 错误示例
\item[NOREFRESH\_GRADES behavior] Submissions with final grades...

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

文档化属性：

latex

% 错误示例
The decorator adds a \texttt{\_\_cache} dictionary and \texttt{\_\_all\_fetched} flag.

% 正确示例
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.

始终使用
```
\cref{...}
```
（cleveref包）进行所有交叉引用
绝对不要使用
```
\S\ref{...}
```
或手动输入章节/图前缀
使用描述性标签：
```
\label{sec:introduction}
```
而非
```
\label{s1}
```
示例：
- 章节：
```
\cref{sec:background}
```
  → “第2.1节”
- 图片：
```
\cref{fig:diagram}
```
  → “图3”
- 表格：
```
\cref{tab:results}
```
  → “表1”
- 多个引用：
```
\cref{sec:intro,sec:conclusion}
```
  → “第1节和第4节”

反模式：手动添加前缀

latex

% 错误示例
Section~\ref{sec:intro} shows...
\S\ref{sec:background} discusses...
Figure~\ref{fig:plot} demonstrates...

% 正确示例
\cref{sec:intro} shows...
\cref{sec:background} discusses...
\cref{fig:plot} demonstrates...

原因：cleveref包会自动添加正确的前缀（Section、Figure等），并处理复数、范围和特定语言格式。

Citations

引用

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

使用正确的引用命令（
```
\cite
```
,
```
\citep
```
,
```
\citet
```
）而非手动引用
绝对不要手动编写
```
[1]
```
或
```
(Smith 2020)
```

Quotations (csquotes package)

引用（csquotes包）

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.

始终使用
```
\enquote{...}
```
添加引用，而非手动引号
自动处理嵌套引用：
```
\enquote{outer \enquote{inner} quote}
```
支持语言适配：瑞典语使用»...«或"..."，英语使用"..."或'...'

块引用使用

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

反模式：手动添加引号

latex

% 错误示例
"This is a quote"
``This is a quote''
'single quotes'

正确做法：使用csquotes

latex

% 正确示例
\enquote{This is a quote}
\enquote{outer \enquote{inner} quote}

原因：手动引号无法适配语言设置，会导致排版不一致。csquotes包会根据文档语言正确处理所有引用样式。

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.

绝对不要在正文中使用全大写字母强调
使用
```
\emph{...}
```
强调单词或短语
如需强强调，使用
```
\textbf{...}
```
或嵌套
```
\emph{\emph{...}}
```
让LaTeX处理排版样式

反模式：全大写字母强调

latex

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

正确做法：语义化强调

latex

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

原因：正文中的全大写字母被视为“大喊大叫”，排版效果差，可读性低，显得不专业。使用

\emph{...}

提供语义化强调，LaTeX会根据上下文和文档样式适当渲染（通常为斜体，可配置）。

例外情况：常规使用全大写的首字母缩略词和专有名词（如NASA、USA、PDF）不受此限制，无需强调。

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.

核心原则：图片不等于图，但图可以包含图片。使用带标题和标签的正确figure和table环境。

Using sidecaption (memoir class)

使用sidecaption（memoir类）

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)

使用memoir文档类时，优先使用

sidecaption

而非传统

\caption

，以获得更好的布局和可访问性：

图片示例：

latex

\begin{figure}
  \begin{sidecaption}{图片内容的清晰描述}[fig:label]
    \includegraphics[width=0.7\textwidth]{path/to/image}
  \end{sidecaption}
\end{figure}

表格示例：

latex

\begin{table}
  \begin{sidecaption}{表格内容的描述}[tab:label]
    \begin{tabular}{lcc}
      \toprule
      Header1 & Header2 & Header3 \\
      \midrule
      Data1 & Data2 & Data3 \\
      \bottomrule
    \end{tabular}
  \end{sidecaption}
\end{table}

sidecaption的关键特性：

标题位置：标题与内容（图片/表格）并排显示，而非上下方
空间效率：更好地利用页面宽度，尤其适合窄图片/表格
可读性提升：标题与内容视觉关联紧密
可访问性：清晰区分标题文本与内容的语义
标签一致性：标签放在可选的第二个参数
```
[fig:label]
```
中

sidecaption的使用场景：

中等大小的图片/表格，无需占满整个文本宽度
标题与内容的近距离关联有助于理解的教育材料
使用memoir类的文档（带memoir功能的Beamer演示文稿）

传统caption替代方案：

latex

\begin{figure}
  \centering
  \includegraphics[width=0.7\textwidth]{path/to/image}
  \caption{图片内容的描述}
  \label{fig:label}
\end{figure}

在以下场景使用传统

\caption

\label

：

未使用memoir类
图片/表格占满整个文本宽度
标题自然位于内容下方（如宽表格）

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.

始终使用

\cref{fig:label}

（cleveref包）引用图片和表格：

latex

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

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

绝对不要硬编码引用，如“Figure 1”、“Table 3.2”，或使用

Figure~\ref{fig:label}

等手动前缀——让cleveref自动处理编号和前缀。

Verbatim and Code

代码与原样文本

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

使用
```
listings
```
包实现带语法高亮的代码
使用
```
\verb
```
添加行内代码片段
绝对不要直接粘贴代码为普通文本

Paths

文件路径

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

路径中始终使用正斜杠：
```
figures/diagram.pdf
```
而非
```
figures\diagram.pdf
```
使用平台无关的路径规范

Workflow for Writing LaTeX

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

编写或编辑LaTeX内容时：

检查文件类型：是否在.nw literate编程文件中？若是，使用
```
[[code]]
```
标记，而非
```
\texttt{...\_...}
```
识别内容结构：是统一列表项还是术语-定义配对？
选择语义环境：根据内容含义匹配环境
使用正确命令：利用LaTeX的语义命令而非手动格式化
验证交叉引用：确保标签和引用具有描述性且正确
检查反模式：审查itemize环境中的
```
\textbf{Label:}
```
、.nw文件中的
```
\texttt{..._...}
```
等问题

When Reviewing LaTeX Code

LaTeX代码审查要点

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

检查以下常见问题：

使用
```
\textbf{Label:}
```
而非
```
description
```
环境的列表
硬编码编号而非
```
\ref
```
手动交叉引用前缀（
```
\S\ref
```
,
```
Section~\ref
```
,
```
Figure~\ref
```
）而非
```
\cref
```
手动格式化引用而非
```
\cite
```
命令
手动引号（
```
"..."
```
,
```
'...'
```
,
```
`...`
```
）而非
```
\enquote{...}
```
未使用
```
figure
```
环境的图片
未正确格式化的代码（无listings/verbatim）
路径中使用Windows风格的反斜杠

针对.nw literate编程文件的额外检查：

\texttt{..._...}

或

\texttt{...__...}

→ 应改为

[[...]]

标记

带下划线的描述标签
```
\item[FOO\_BAR behavior]
```
→ 优化标签并在正文中使用
```
[[FOO_BAR]]
```
代码引用中手动转义下划线 → 使用
```
[[...]]
```
替代

Beamer: Presentation vs Article Mode

Beamer：演示文稿与文章模式

When creating Beamer presentations that also generate article versions, use

\mode<presentation>

and

\mode<article>

to provide appropriate content for each format.

创建可同时生成文章版本的Beamer演示文稿时，使用

\mode<presentation>

和

\mode<article>

为每种格式提供合适的内容。

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}

冗长文本环境：超过2-3行的语义环境（definition、remark、example、block）在幻灯片中过于冗长。

解决方案：为演示文稿提供简洁版本，为文章提供完整解释：

latex

\begin{frame}
  \mode<presentation>{%
    \begin{remark}[Key Point]
      \begin{itemize}
        \item 简洁要点1
        \item 简洁要点2
        \item 简洁要点3
      \end{itemize}
    \end{remark}
  }
  \mode<article>{%
    \begin{remark}[Key Point]
      包含详细推理和上下文的完整解释段落，这些内容会使幻灯片过载，但在书面形式中具有价值。

      额外段落可阐述细节和影响。
    \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}

使用

\textbytext

的并排布局：

演示文稿：
```
\textbytext
```
（非星号版本，列宽适配Beamer框架）
文章：
```
\textbytext*
```
（星号版本，全宽，更适合印刷文档）

latex

\begin{frame}
  \mode<presentation>{%
    \textbytext{左侧内容}{右侧内容}
  }
  \mode<article>{%
    \textbytext*{左侧内容}{右侧内容}
  }
\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.

对于新的LaTeX文档，使用

references/preamble.tex

中的标准导言区。将其原样复制到项目的

doc/preamble.tex

，并在

\documentclass

后使用

\input{preamble}

引入。

文档结构：

latex

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

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

\begin{document}
\frontmatter
\maketitle
\tableofcontents

\mainmatter
% 内容区域

\backmatter
\end{document}

标准导言区提供：

语言支持（babel，含瑞典语、英式英语）
参考文献（biblatex，字母顺序样式）
代码高亮（minted、noweb）
数学公式（amsmath、amssymb、mathtools、amsthm）
交叉引用（带自定义标签的cleveref）
引用（csquotes）
表格（booktabs）
各种工具包（enumitem、acro、siunitx等）

这确保所有文档和项目的格式一致性。

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是基于语义标记的文档排版系统，而非文字处理器。目标是描述内容的本质，而非其外观。让LaTeX根据你提供的语义结构处理格式。

latex-writing

Original

Translation

LaTeX Writing Best Practices

LaTeX文档编写最佳实践

Core Principle: Semantic Markup

核心原则：语义标记

List Environments: When to Use What

列表环境：场景选择

Use description for Term-Definition Pairs

术语-定义配对使用description环境

Common Use Cases for description

description环境的常见使用场景

Use itemize for Simple Lists

简单列表使用itemize环境

Use enumerate for Numbered Steps or Rankings

有序步骤或排名使用enumerate环境

Recognition Patterns

识别模式

Fixing Common Anti-Patterns

常见反模式修正

Anti-Pattern: Bold Labels in Itemize

反模式：Itemize环境中使用粗体标签

Correct: Description Environment

正确做法：使用Description环境

Anti-Pattern: Manual Formatting Instead of Semantic Structure

反模式：手动格式化而非语义结构

Correct: Semantic Description

正确做法：语义化Description

Literate Programming (.nw files)

Literate编程（.nw文件）

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

使用[[code]]标记，而非\texttt{...\_...}

When to Use [[code]] vs \texttt

[[code]]与\texttt的使用场景区分

Recognition Pattern for Review

审查时的识别模式

Examples from Real Code

真实代码示例

Additional Best Practices

其他最佳实践

Cross-References

交叉引用

Citations

引用

Quotations (csquotes package)

引用（csquotes包）

Emphasis

强调

Floats: Figures and Tables

浮动元素：图片和表格

Using sidecaption (memoir class)

使用sidecaption（memoir类）

Referencing figures and tables

引用图片和表格

Verbatim and Code

代码与原样文本

Paths

文件路径

Workflow for Writing LaTeX

LaTeX编写工作流

When Reviewing LaTeX Code

LaTeX代码审查要点

Beamer: Presentation vs Article Mode

Beamer：演示文稿与文章模式

When to Split Content

内容拆分场景

Visual Elements

视觉元素

Principle

原则

Standard Preamble

标准导言区

Remember

谨记

Use
`description`
for Term-Definition Pairs

术语-定义配对使用
`description`
环境

Common Use Cases for
`description`

`description`
环境的常见使用场景

Use
`itemize`
for Simple Lists

简单列表使用
`itemize`
环境

Use
`enumerate`
for Numbered Steps or Rankings

有序步骤或排名使用
`enumerate`
环境

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

使用
`[[code]]`
标记，而非
`\texttt{...\_...}`

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

`[[code]]`
与
`\texttt`
的使用场景区分