latex-writing

LaTeX 執筆のベストプラクティス

このスキルでは、確立されたベストプラクティスに従い、構造が整った意味的に正しい LaTeX 文書を作成する方法を説明します。

基本原則：意味的なマークアップ

見た目だけでなく、内容の意味に合った LaTeX 環境を使用してください。

リスト環境：使い分け

用語と定義の組み合わせには description を使用する

ラベルに続けて説明、定義、解説を書く場合は、description 環境を使用してください。

\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}

絶対に次のようにしないでください：

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

description の一般的な使用例

• API パラメーター：\item[username] The user's login name
• 設定オプション：\item[timeout] Maximum wait time in seconds
• 用語集の項目：\item[LaTeX] A document preparation system
• 合格／不合格の例：\item[Passes] Correct implementation...
• 機能の説明：\item[Auto-save] Automatically saves every 5 minutes

例外：教育上のメタ解説

\enquote{何が変化するか}、\enquote{何が不変か}といった、講師向けの教育上の注釈や、教材の順序に関する根拠には、目に見える description リストを使用しないでください。これらはdidactic-notes スキルの \ltnote{...} に記述します。description は、ラベル付きの内容が学生向け文書そのものの一部である場合にのみ使用してください。

単純なリストには itemize を使用する

各項目がラベルのない同種のリスト要素である場合は、itemize を使用してください。

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

番号付きの手順や順位には enumerate を使用する

順序が重要な場合は、enumerate を使用してください。

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

項目が1つだけのリストは、リストではなく散文です

\item がちょうど1つのリストは、決して適切ではありません。列挙する他の項目がないため、孤立した箇条書きとして表示されます。内容を散文の文として記述してください。意味的な環境（exercise、definition、remark、example、block）の中で、質問が1つだけ、あるいは1行の記述だけなのに、不要に 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}

短い文2つを箇条書き2つにするよりも、散文として記述するほうが適切な場合も多くあります。本当に複数の項目があり、並列で列挙できる場合にのみ itemize／enumerate を使用してください。beamer と article の両方で使うスライドでは、これは特に重要です。孤立した箇条書きはスライド上で見栄えが悪く、ノートの文章の流れも損ないます（didactic-notes スキルを参照）。

リストやコードブロックで環境を始めない — 先に散文を置く

複数項目からなる本物のリストであっても、意味的な環境（example、exercise、remark、definition、block）の中で最初に置いてはいけません。いきなり \begin{enumerate}、\begin{itemize}、または \inputminted／\begin{minted} で始めると、環境のインラインラベルと衝突します。最初のリスト項目（またはコード行）が \enquote{Example 1.} と同じ行に置かれ、文字が重なります。リストやコードの前に、必ず短くてもよいので導入文を置いてください。

% 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}

したがって、ルールは \enquote{箇条書き禁止} ではありません。箇条書きやコードは、先に散文の文があれば問題ありません。禁止されているのは、リストやコードブロックを環境内の最初の要素にすることです。

番号付き項目の間に解説を挟む（enumitem resume）

設問（アンケート／クイズの質問、要件、試験問題）など、列挙された各項目に解説が必要な場合は、\item のテキストだけを項目にし、単一項目の環境の間に解説を散文として記述して、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...

• 同じ解説を共有する項目は、同じ環境にまとめてください。
• \usepackage{enumitem} が必要です。beamer と article の両方でビルドする場合は、enumitem が beamer のリスト内部処理と競合するため、article ドライバーのみで読み込み、こうしたリストは article モードの散文内に置いてください。そうすれば、スライドのジョブでは \mode* によってスキップされます。
• アンチパターン：質問文の後に解説を \item の中に付け足すこと。質問とその根拠が曖昧に混ざってしまいます。

認識パターン

LaTeX をレビューまたは記述する際は、description を使用すべきことを示す次のパターンに注目してください。

• \item \textbf{SomeLabel:} → \item[SomeLabel] を使用してください
• \item \emph{SomeLabel:} → \item[SomeLabel] を使用してください
• \item SomeLabel --- → \item[SomeLabel] を使用してください
• すべての項目が太字または強調表示されたテキストで始まるリスト

よくあるアンチパターンの修正

アンチパターン：itemize 内の太字ラベル

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

正しい例：description 環境

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

アンチパターン：意味的な構造ではなく手動で書式設定する

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

正しい例：意味的な description

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

文芸的プログラミング（.nw ファイル）

重要：文芸的プログラミングファイル（.nw）で LaTeX を記述する場合、コードを引用するには \texttt と手動のエスケープではなく、noweb の [[code]] 記法を使用してください。

\texttt{...\_...} ではなく [[code]] 記法を使用する

noweb の文芸的プログラミングシステムには、アンダースコアなどの特殊文字を自動的に処理する、コード参照用の特別な記法が用意されています。

アンチパターン：\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.

正しい例：[[code]] 記法を使用する

% 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.

重要な理由：

• 特殊文字（アンダースコア、バックスラッシュなど）を自動的にエスケープします
• ソースコードが読みやすくなります（手動でのエスケープが不要です）
• 文芸的プログラミングの慣習に従えます
• エスケープの忘れによる LaTeX エラーを防ぎます
• コードと文章を明確に区別できます

[[code]] と \texttt の使い分け

.nw ファイルでは、次のものに**[[code]] を使用してください**。

• 関数名とメソッド名：[[get_submissions()]]、[[__init__]]
• 変数名：[[_includes]]、[[user_id]]
• クラス名：[[LazySubmission]]、[[Assignment]]
• 定数：[[NOREFRESH_GRADES]]、[[MAX_RETRIES]]
• モジュール名：[[pickle]]、[[Canvas]]
• アンダースコアや特殊文字を含むすべての識別子

.nw ファイルでは、次のものに**\texttt を使用してください**。

• 特殊文字を含まない短いコード以外の技術用語
• ファイル拡張子：\texttt{.py}、\texttt{.nw}
• アンダースコアを含まない単純なコマンド

通常の .tex ファイル（文芸的プログラムではないファイル）では：

• [[...]] は使用できないため、適切にエスケープした \texttt を使用してください
• または、コードには minted や listings などのパッケージを使用してください

レビュー時の認識パターン

.nw ファイルをレビューする際は、次のアンチパターンに注目してください。

• \texttt{..._...} → [[...]] を使用してください
• \texttt{...__...} → [[...]] を使用してください
• \item[SOME\_CONSTANT behavior] → ラベルを言い換えて本文に [[SOME_CONSTANT]] を入れるか、ラベル内の定数を [[...]] で囲んでください — \item[ [[SOME_CONSTANT]] behavior]。2つ目の方法を使う場合は、 ]] と閉じる ] の間に少なくとも1文字（通常はスペース）を入れてください。 これにより、角括弧が3つ連続して引数が暴走するエラーが発生するのを防げます。

実際のコード例

メソッドの説明：

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

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

定数の説明：

% 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.

属性の説明：

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

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

その他のベストプラクティス

相互参照

• すべての相互参照には、必ず \cref{...}（cleveref パッケージ）を使用してください
• \S\ref{...} を使用したり、セクションや図の接頭辞を手動で入力したりすることは禁止です
• 内容がわかるラベルを使用してください： \label{sec:introduction} ではなく \label{s1} のようなラベルを使用しないでください
• 例：
  • セクション：\cref{sec:background} → 「Section 2.1」
  • 図：\cref{fig:diagram} → 「Figure 3」
  • 表：\cref{tab:results} → 「Table 1」
  • 複数：\cref{sec:intro,sec:conclusion} → 「Sections 1 and 4」

アンチパターン：接頭辞を手動で入力する

% 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...

理由：cleveref パッケージは適切な接頭辞（Section、Figure など）を自動的に付与し、複数形、範囲、言語固有の書式にも対応します。

参照タイプ名：\cref が出力する名前は、どの言語でも本文で使われる語と一致させる必要があります。本文で「steps」としているものを「item 5」と表示してはいけません（\crefname で上書きしてください。言語オプション独自のフックでひそかに上書きされないよう、cleveref の後に登録する \AtBeginDocument フック内で設定します）。英語以外の文書では、cleveref は babel ではなく、自身のパッケージオプションまたはグローバルなクラスオプションから言語を取得します。文書内に複数の種類がある場合は、ラベルごと（\label[type]{...}）または環境ごとに処理します（enumitem の \newlist でリストごとにカウンターを設定します。beamer では使用できません）。詳しい説明は references/cleveref-type-names.md を参照してください（検索語：crefname、terminology、AtBeginDocument、label[type]、newlist、swedish、enumi、appendix）。

引用

• 手動で参照を記述せず、適切な引用コマンド（\cite、\citep、\citet）を使用してください
• [1] や (Smith 2020) を手動で記述しないでください

引用文（csquotes パッケージ）

• 引用には必ず \enquote{...} を使用し、引用符を手動で入力しないでください
• 入れ子の引用符も自動的に処理されます：\enquote{outer \enquote{inner} quote}
• 言語に対応しています：スウェーデン語では »...« または "..."、英語では "..." または '...' が使われます
• ブロック引用には \begin{displayquote}...\end{displayquote} を使用してください

アンチパターン：引用符を手動で入力する

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

正しい方法：csquotes を使用する

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

理由：引用符を手動で入力すると、言語設定に応じて書式が変わらず、組版に一貫性がなくなる場合があります。csquotes パッケージは、文書の言語に応じた適切な引用符の書式を処理します。

引用文と、出典を明記した言い換え

コマンドは、テキストが出典からの逐語的な引用かどうかによって使い分けます。

• 出典からの文章を逐語的に再掲する場合 → 引用自体に参照を含める統合型の引用コマンドを使用してください。\enquote{...} と切り離した \cite／\autocite を併用しないでください。
  • \textcquote[⟨prenote⟩][⟨postnote⟩]{key}{text} — インライン
  • \blockcquote[⟨postnote⟩]{key}{text} — ブロック（長い引用）
• 言い換え、再構成した会話、または再述した例 → 引用文ではありません。\textcite／\autocite を使って出典を文中に明記し、再現する発言がある場合は通常の \enquote で囲んでください。
• それ以外の通常の \enquote{...} の用途：皮肉を示す引用符、語句を語句として示す場合、すでに引用した文章への参照。

% INCORRECT — verbatim source text as \enquote + detached citation
The study reports \enquote{much higher (63\%)} results \autocite[p.~167]{NCOL}.
% CORRECT — verbatim quotation carries its own citation
The study reports \textcquote[p.~167]{NCOL}{much higher (63\%)} results.

% CORRECT — a paraphrased/recounted example is attributed, NOT \textcquote'd
\Textcite[pp.~24--25]{NCOL} reports a study in which a child answers
\enquote{five} for one hand and \enquote{ten} for the other.

重要な注意：\textcquote／\blockcquote は、波括弧内のテキストが出典からの逐語的な引用であることを示します。これらで囲む前に、その語句が実際に出典に記載されていることを確認してください。言い換え、再構成した会話、語句を語句として示す場合にはこれらのコマンドを使わず、代わりに \textcite／\autocite で出典を明記してください。（backing-claims スキルを参照してください。引用する前に出典を読み、内容を確認してください。）

強調

• 通常の文章では、強調のためにすべて大文字を\emph{決して}使わないでください
• 単語や語句の強調には \emph{...} を使います
• 強い強調には、\textbf{...} またはネストした \emph{\emph{...}} を使います
• 字体のスタイル設定は LaTeX に任せます

アンチパターン：強調のためにすべて大文字を使う

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

正しい例：意味的な強調

% CORRECT
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 など、慣例的に大文字で表記される頭字語や固有名詞は問題ありません。強調する必要もありません。

フロート：図と表

基本原則：画像は図ではありませんが、図に画像を含めることはできます。キャプションとラベルを付け、適切な図表環境を使ってください。

すべての表と図にキャプションを付けてください。例外はありません。 どんなに小さくても、キャプションのない tabular や \includegraphics を center 環境内や通常の文章中にそのまま置いてはいけません。table／figure フロートで囲み、キャプションとラベルを付けて、\cref で参照してください。キャプションでは、単にテーマを述べるのではなく、その表や図から読者が読み取るべき内容（表が示す規則や、図が示す要点）を説明します。ほかの場所から文章を移す際にも注意してください。元の文章にキャプションのない表があっても、それを前例にしてはいけません。

悪い例 — キャプションのない tabular を、その位置で参照する：

The slot length follows from the title:
\begin{center}
\begin{tabular}{lr}
  Title & Minutes \\ \hline
  Redovisning & 15 \\
  Redovisning spec & 30 \\
\end{tabular}
\end{center}
The table above is the specification.

良い例 — キャプション付きのフロートを、\cref で参照する：

The slot length follows from the title, see \cref{tab:slot-durations}.
\begin{table}
  \begin{sidecaption}{%
    The slot length that a title gives: 30 minutes for
    \enquote{Redovisning spec}, 15 for any other title.
  }[tab:slot-durations]
    \begin{tabular}{lr}
      \toprule
      \textbf{Title} & \textbf{Minutes} \\
      \midrule
      Redovisning & 15 \\
      Redovisning spec & 30 \\
      \bottomrule
    \end{tabular}
  \end{sidecaption}
\end{table}
\Cref{tab:slot-durations} is the specification.

フロートは移動するため、\enquote{上の}、\enquote{下の}、\enquote{次の表}といった表現で参照してはいけません。\cref を使ってください。

sidecaption の使用（memoir クラス）

memoir ドキュメントクラスを使用する場合は、レイアウトとアクセシビリティを向上させるため、従来の \caption ではなく sidecaption を使用してください。

図の場合：

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

表の場合：

\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}

sidecaption の主な機能：

• キャプションの配置：キャプションをコンテンツ（図／表）の上や下ではなく、横に表示します
• スペースの効率化：ページ幅をより有効に活用できます。特に幅の狭い画像や表で効果的です
• 可読性の向上：キャプションとコンテンツが視覚的につながります
• アクセシビリティ：キャプションのテキストとコンテンツを明確に意味的に分離します
• 一貫したラベル付け：ラベルは省略可能な第 2 引数 [fig:label] に指定します

コンテンツを sidecaption 側に寄せてください。 幅の狭い図や表は、キャプションのある側の余白にぴったり寄せて配置する必要があります。キャプションが右余白にある場合は右寄せ、左余白にある場合は左寄せにします。キャプションが右側の遠くにあるのに左寄せにしたり、中央に配置したりしないでください。memoir はこの処理を自動では行いません。本文を全幅のボックスに組み、左揃えで組版します。

• didactic ≥ 2.9 の場合（オプション sidecapalign=caption がデフォルト）：これは自動で行われます。本文に \centering、\raggedleft、\flushscap を記述しないでください。注意点：伸縮可能な空白は詰められます（A\hfill B は横並びになるため、\makebox[\linewidth]{A\hfill B} で間隔を広げてください）。また、本文の脚注によって varwidth が処理を断念することがあります（ログに \enquote{Failed to reprocess entire contents} と表示されます）。その場合、本文は memoir が配置する位置に残ります。
• sidecapalign=off または古い didactic の場合：sidecaption の本文の先頭に \flushscap を置いてください。2.9 より前のバージョンでは直前のフロートの側を読み取っていたため、外側／内側にキャプションを置く両面印刷のドキュメントで、誤った側に寄せられることがありました。
• didactic を使用しない場合：本文の \raggedleft が機能するのは、キャプションが常に右余白にある場合（oneside または \sidecapmargin{right}）に限られます。

生成した PDF で、フロートとキャプションの間に隙間がないか確認してください。まだ隙間がある場合は、ログで読み込まれている didactic.sty を確認してください（grep -n 'didactic.sty' *.log）。プロジェクトでは、古いバージョンに固定した didactic が git サブモジュールとして同梱されていることがよくあります（例：doc/didactic を doc/didactic.sty としてシンボリックリンク）。この場合、~/texmf にあるバージョンが上書きされます。サブモジュールを更新してください。

sidecaption を使用する場合：

• 全文幅を必要としない中サイズの図や表
• キャプションとコンテンツの近さが理解を助ける教材
• memoir クラスを使用するドキュメント（memoir の機能を使用する Beamer プレゼンテーション）

従来の caption を使用する場合：

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

次の場合は、従来の \caption + \label を使用してください。

• memoir クラスを使用していない
• 図／表が本文の幅いっぱいに広がる
• キャプションをコンテンツの下に置くのが自然（例：幅の広い表）

図と表の参照

図や表を参照する場合は、必ず \cref{fig:label}（cleveref パッケージ）を使用してください。

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 とコード

• コードブロックには minted（推奨、構文強調表示対応。-shell-escape が必要）または listings を使用してください
• インラインコードスニペットには \verb または \mintinline を使用してください
• コードを通常のテキストとして貼り付けないでください
• minted v3（TeX Live 2024+）の注意点 — references/minted-v3-and-floats.md を参照してください（検索語：outputdir、Pygments lexer）： パッケージオプション [outputdir=...] は削除されており（現在はエラーになります。通常の \usepackage{minted} を読み込んでください）、minted／\mintinline の言語引数が改行をまたいでいると、Pygments lexer " python" is unknown というエラーが発生します。各 minted 呼び出しの引数は 1 行に収めてください。文は \mintinline{...}{...} の呼び出しの間で折り返し、呼び出しの途中では改行しないでください。

! LaTeX Error: Float(s) lost. のデバッグ

この致命的で発生箇所が示されないエラー（\end{document} で報告されます）は、beamer/article の両形式で作成する didactic+memoir のビルドでは、通常、スライド専用の \begin{frame}<presentation> フレーム内にある引用または脚注が原因です（出力は抑制されますが本文は実行されるため、欄外脚注が孤立します）。通常のフレーム内の引用は問題ありません。latexmk/biber の出力ノイズを越えて実際のエラーを確認するには、pdflatex -halt-on-error を単独で実行し、最小限の再現例で原因を特定します。修正するには、スライド専用フレームを \mode<presentation>{...} で囲みます（または引用を \only<presentation>{...} で条件分岐します）。注意： [fragile] フレームには \mode<presentation>{...} による囲みを使用できません。グループを閉じる } が逐語的な .vrb のスキャン対象外になり、スライドのビルドで ! Extra }, or forgotten \endgroup エラーが発生します。fragile なスライド専用フレームでは、実際には不要（内部に verbatim/minted/listings がない）なら [fragile] を外します。必要な場合は \begin{frame}<presentation>[fragile] のままにして、各引用を \only<presentation>{\autocite{...}} で囲みます。詳しい診断については、references/minted-v3-and-floats.md と didactic-notes スキルの references/footnotes-and-citations.md を参照してください。

beamer/article の両形式のビルド（1つのソースから2つの出力）

同じコンテンツファイル（\mode* で始まるファイル）から論文を2回コンパイルする場合（memoir + beamerarticle の論文と beamer のスライドデッキ）、references/dual-beamer-article.md に従ってください（検索語：pyblock frame、ProvideSemanticEnv、restatable、biber root）。4つのルールの概要は次のとおりです。

• すべての PythonTeX pyblock は、両方のモードでレンダリングされる \begin{frame}[fragile] の中に置きます。 フレーム外の pyblock はスライドのジョブでスキップされ、共有 PythonTeX セッションデータの同期がずれます（症状：出力の入れ替わり、?? PythonTeX ??）。
• 研究課題と仮説は、cleveref のラベルが付いた意味的な環境に配置します（didactic の question。たとえば、\DeclareTranslation の後に \ProvideSemanticEnv を使って hypothesis を宣言します）。\begin{restatable}{question}{tag}（thm-restate）内で記述し、\tag* で再掲します。その際、共有プリアンブルに beamer 用のシムを追加します。参照には \cref{rq:*} を使用し、「RQ1」や「H2」と直接記述しないでください。
• スライド専用フレーム：\mode<presentation>{...} で囲みます（上記の fragile に関する注意を参照）。論文専用の文章はフレームの外に置きます。スライドの箇条書きと隣接する論文の文章が重複しないようにしてください。
• 出典表記は引用文と一緒に、フレーム内に置きます。 スライドに表示する逐語的な引用文には、その場で出典（脚注／引用文自体に付けた \footcite）を付ける必要があります。出典表記がフレームの後にある論文専用の文章内に置かれていると、スライドでは引用文に出典が付きません。引用文に出典を付けると、beamer ではスライドの下部に、論文では欄外または脚注に表示され、両方のジョブを1つのソースで処理できます。
• Biber の再実行はプロジェクトルートから行います（biber ltxobj/<jobname>）。出力ディレクトリ内からは実行しないでください。

エンコーディングとフォント（エンジン依存）

Unicode／フォントのビルドエラーは、pdfLaTeX と XeLaTeX／LuaLaTeX では対処方法が逆なので、まずエンジンを特定してください（grep 'This is' file.log）。 詳しいガイダンスは references/unicode-and-fonts.md を参照してください（検索語： DeclareUnicodeCharacter、iftex、newunicodechar、fontenc、pdffonts）。

• pdfLaTeX — ! LaTeX Error: Unicode character … (U+XXXX) not set up — マッピングされていない非 ASCII バイト（反転引用符、ダッシュの異体字、≈、罫線文字など）です。ソースを編集するのではなく、プリアンブルで \usepackage[utf8]{inputenc} を指定し、その後に \DeclareUnicodeCharacter{XXXX}{...} を追加して対処してください。 （inputenc は \DeclareUnicodeCharacter をポータブルに定義するために必要です。これがないと Undefined control sequence が発生することがあります。）
• XeLaTeX／LuaLaTeX — ネイティブ UTF-8 のため「not set up」エラーは発生せず、\DeclareUnicodeCharacter は未定義です（inputenc は無視されます）。pdfLaTeX 専用のマッピングは \ifpdftex … \fi（iftex パッケージ）で囲み、グリフの再マッピングには \newunicodechar を使用してください。
• pdfLaTeX — コードがプロポーショナルセリフ体で表示される（アンダースコアが ˙ として抽出され、引用符が曲がる）— \usepackage[T1]{fontenc} を指定しないと、T1 専用の等幅フォント（Bera Mono など）を選択できません。これを読み込んでください（\ifpdftex ブランチ内で）。
• ビルドシステムによってエンジンが切り替わることがあります。 latexmk -pdf と -xelatex の違いに加え、Makefile のルールが .nw から生成される場合があるため、make やサブモジュールの更新でエンジンが切り替わることがあります。.log のバナーを確認し、決めつけないでください。
• 推測せずに診断してください： pdffonts -f N -l N file.pdf でページに埋め込まれているフォントを確認できます。pdftotext -f N -l N では、グリフから Unicode へのマッピングを通じてエンコーディングを確認できます。

パス

• パスには常にスラッシュを使用してください：figures/diagram.pdf。figures\diagram.pdf は使用しないでください。
• プラットフォームに依存しないパス指定を使用してください。

LaTeX コンテンツを作成するワークフロー

LaTeX コンテンツを作成または編集する場合：

1. ファイル形式を確認する：.nw の文芸的プログラミングファイルですか？その場合は \texttt{...\_...} ではなく、[[code]] 記法を使用します。
2. コンテンツの構造を特定する：統一された項目のリストですか、それとも用語と定義の組み合わせですか？
3. 意味に合った環境を選ぶ：コンテンツの意味に合った環境を使用します。
4. 適切なコマンドを使用する：手作業で書式を設定するのではなく、LaTeX の意味的なコマンドを活用します。
5. 相互参照を確認する：ラベルと参照が具体的で正しいことを確認します。
6. アンチパターンを確認する：itemize 内の \textbf{Label:} や、.nw ファイル内の \texttt{..._...} がないか確認します。

LaTeX コードのレビュー時

次のよくある問題を確認してください：

• description 環境ではなく、\textbf{Label:} を使ったリスト
• \ref ではなく、ハードコードされた数値
• \cref ではなく、手動で付けた相互参照の接頭辞（\S\ref、Section~\ref、Figure~\ref）
• \cite コマンドではなく、手動で整形された引用
• \enquote{...} ではなく、手動で付けた引用符（"..."、'...'、`...`）
• 逐語的な原文を、\textcquote／\blockcquote ではなく、\enquote{...} と切り離された \cite／\autocite で記述している（逆に、逐語的ではない言い換えを \textcquote／\blockcquote で囲んでいる場合も）
• figure 環境を使っていない画像
• 適切にフォーマットされていないコード（listings／verbatim）
• パスに Windows 形式のバックスラッシュを使用
• iftex で条件分岐されていない、エンジン固有の Unicode／フォント設定 — 例：\DeclareUnicodeCharacter（pdfLaTeX 専用）を無条件に使うと、XeLaTeX／LuaLaTeX でエラーになります（references/unicode-and-fonts.md を参照）
• pdfLaTeX：\DeclareUnicodeCharacter によるマッピングのない非 ASCII 文字、または \usepackage[utf8]{inputenc} なしでの \DeclareUnicodeCharacter の使用
• pdfLaTeX：等幅フォント／コードがプロポーショナルなセリフ体で表示される — Bera Mono のような T1 専用フォントで \usepackage[T1]{fontenc} が不足
• beamer／article のデュアルビルド：両モード対応の \begin{frame}[fragile] の外側にある pyblock（PythonTeX セッションの同期がずれます）、または意味的な question／hypothesis 環境への \cref ではなく、本文にリテラルの「RQ1」／「H2」を記述（references/dual-beamer-article.md を参照）

.nw 文芸的プログラミングファイルの追加確認項目：

• \texttt{..._...} または \texttt{...__...} → [[...]] 記法を使用してください
• アンダースコアを含む説明ラベル \item[FOO\_BAR behavior] → より適切なラベルを使い、本文では [[FOO_BAR]] を使用してください
• コード参照で手動エスケープされたアンダースコア → 代わりに [[...]] を使用してください

Beamer：プレゼンテーションモードと論文モード

論文版も生成する Beamer プレゼンテーションを作成する場合は、各形式に適した内容を提供するために \mode<presentation> と \mode<article> を使用してください。

内容を分ける場合

冗長なテキスト環境：定義、注釈、例、ブロックなどの意味的な環境に、文章が 2～3 行を超えて含まれる場合、スライドには冗長すぎます。

解決策：プレゼンテーションには簡潔なバージョンを、論文には詳細な説明を用意してください：

\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}

視覚要素

\textbytext を使った左右並列レイアウト：

• プレゼンテーション：\textbytext（アスタリスクなし、カラム幅、beamer フレームで使用可能）
• 論文：\textbytext*（アスタリスク付き、全幅、印刷文書に適しています）

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

原則

スライドでは視覚的な明瞭さと簡潔さ（箇条書き、短い語句）が必要です。論文では深みと説明（完全な文、段落）を盛り込めます。それぞれの媒体に適した内容を設計してください。

Mentipy を使ったインタラクティブな質問

ライブ投票を埋め込むスライドデッキや教育用の論文には、PythonTeX ブロックまたは別の Python ブロックから mentipy.latex を使用してください。受講者向けの質問には mc、open_text、scale、word_cloud を優先し、その後 mentipy serve を実行して投票を公開してください。URL を変更した後は再コンパイルし、更新された QR コードが埋め込まれるようにします。Beamer スライドには layout="slide" を、配布資料には layout="article" または layout="article+qr" を使用してください。

標準プリアンブル

新しい LaTeX 文書には、references/preamble.tex の標準プリアンブルを使用してください。これをプロジェクトの doc/preamble.tex にそのままコピーし、\documentclass の後に \input{preamble} で読み込んでください。

文書の構成：

\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}

標準プリアンブルには次の機能が含まれています：

• 言語サポート、参考文献、数学、引用
• コードのハイライトと noweb のサポート
• 相互参照と表
• enumitem、acro、siunitx などの一般的なユーティリティ

これにより、すべての文書とプロジェクトで一貫した書式を維持できます。

覚えておくこと

LaTeX は、ワードプロセッサではなく、セマンティックマークアップに基づく文書作成システムです。目指すのは、コンテンツがどのように見えるべきかではなく、コンテンツが何を表すかを記述することです。指定したセマンティックな構造に基づいて、LaTeX に書式設定を任せましょう。