latex-pdf — プロフェッショナルLaTeX PDF組版ガイド
目標は「コンパイルが通ること」ではなく、読者が手に取ってプロフェッショナルだと感じることです。 納品は内容と実際のページを基準に行います。コンパイル成功はコンパイルが完了したことの証明に過ぎず、視覚的な検収の代わりにはなりません。
目次
核心理念
組版は2つのチェック目標に従います。他のスキルに依存しません。
① 組版は読書のためにある — すべての組版上の決定は、「これによって読者はより理解しやすくなるか？」に答えなければなりません。 ある設定を削除しても読書体験が変わらない場合、その設定は存在する必要がありません。
② 抑制がプロフェッショナル — 情報を伝えない視覚的要素はすべて削除します。 装飾的な線、背景、カラーボックス — ほとんどは削除すべきです。プロフェッショナルな組版は「何気なく見える」ものですが、 アマチュアの組版は「努力は感じられるが乱雑」なことが多いです。
詳細な可読性原則マッピングは readability-principles を参照してください。
エンジン選択
エンジンの選択ミスは最も一般的な間違いであり、特に中国語コンテンツでpdflatexを使用する場合に起こります。
中国語/日本語/韓国語を含む？
├─ はい → xelatex（+ ctex パッケージ）
│ （lualatexでも可だが、コンパイルが遅い）
└─ いいえ → システムフォントが必要？
├─ はい → xelatex または lualatex（+ fontspec）
└─ いいえ → pdflatex（最速、最も互換性が高い）
新しいCJK文書ではXeLaTeXまたはLuaLaTeXを優先し、実際のフォントサポートを確認します。既存の動作するpdfLaTeX/CJKテンプレートは不必要に置き換えるべきではありません。fandol は通常のpdfLaTeXパスでは使用できません。
| エンジン | 利点 | 欠点 | 適用シナリオ |
|---|---|---|---|
pdflatex | 最速、最も安定、エコシステムが最も広い | Unicodeネイティブ非対応、システムフォント不可 | 英語のみの文書 |
xelatex | ネイティブUnicode、システムフォント、CJK対応 | 遅い | 中国語文書のデフォルト選択 |
lualatex | 最も強力なフォント処理、Lua埋め込み可能 | 最も遅い | 高度な組版機能が必要な場合 |
コンパイル戦略
ソースと実行境界の事前確認
コンパイル前に .tex、インポートされる .sty/.cls、ビルド設定、添付ファイルのパスを静的にチェックし、ファイルの読み書き、外部コマンド、Luaなどの実行能力に注意します。静的チェックは安全性の証明にはなりません。信頼できないプロジェクトでは、プライベートファイルなし、ネットワークなし、書き込み・実行時間・リソースを制限した隔離環境を使用します。適切な隔離がない場合はコンパイルを中止して報告し、個人環境で試し実行しません。
デフォルトでshell-escapeは無効にし、minted やグラフィック外部化のために自動的に有効にしません。latexmkの実行時は -norc を使用してシステム、ユーザー、プロジェクトのrcファイルの自動読み込みを防ぎます。その他のビルドスクリプトや外部補助プログラムは別途審査します。インストール、ネットワーク経由のパッケージ取得、環境の変更は既存の許可範囲内でのみ行います。カバーされていない場合は事前に承認を得ます。
適切なコンパイルチェーンの再利用
既存のプロジェクトでは、適切なビルド方法をそのまま使用します。複数回のコンパイルや参考文献の処理を自動化する必要がある場合は latexmk を使用できます。以下の例は、チェック済みの入力に対してのみ、許可された作業ディレクトリで実行します。
# xelatex 文書（中国語のデフォルト）
latexmk -norc -xelatex -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex
# pdflatex 文書
latexmk -norc -pdf -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex
# 補助ファイルのクリーンアップ
latexmk -norc -c
パラメータ説明:
-interaction=nonstopmode: エラーが発生しても入力を待たない（スクリプト環境で必須）-halt-on-error: 最初のエラーで停止、問題箇所の特定が容易
biber（参考文献）
参考文献が必要な場合、latexmkが呼び出す予定のbiber/BibTeXと入力を確認し、許可を得てから実行します。自動検出を追加の実行権限とみなさないでください。
可読性組版原則
以下はコア原則の概要です。詳細なマッピングとコード例は readability-principles を参照してください。
ページジオメトリ
各行の文字数は 50-75文字 を目標にします（66が理想値、TeXのデフォルトがこれに近い）。
\usepackage{geometry}
\geometry{a4paper, margin=2.5cm}
% 中国語の1文字は英語の約2倍の幅、35中国語文字/行 ≈ 70英文字/行
表組み
通常のデータ表では booktabs の縦線なしスタイルを優先します。ユーザー、ジャーナル、機関のテンプレートに別の要件がある場合は、その仕様を維持します。
\usepackage{booktabs}
\begin{tabular}{lrr}
\toprule
指標 & 2024 & 2025 \\
\midrule
収益 & 120 & 150 \\
\bottomrule
\end{tabular}
booktabsの設計前提は縦線がないことです。縦線があると横線の間隔が不連続になります。これはバグではなく機能です。
スペーシングシステム
段落区切りは2つのうち1つを選択し、混在させないでください。
% オプションA：先頭行インデント（アカデミック文書、ctexのデフォルト）
\setlength{\parindent}{2em}
% オプションB：段落間スペース（技術文書、レポート）
\setlength{\parindent}{0pt}
\setlength{\parskip}{0.5\baselineskip}
フォント
本文はセリフ体（読みやすさ）、コードは等幅フォントを使用します。xelatex/lualatexではfontspecでシステムフォントを設定します。
\usepackage{fontspec}
\setmainfont{TeX Gyre Termes}[Ligatures=TeX]
\setmonofont{TeX Gyre Cursor}
microtype
ほぼ無料の品質向上 — 文字間のマイクロ調整で本文がより整然とします。
\usepackage{microtype}
% 注意：xelatexではprotrusionのみ有効（フォント展開は不可）ですが、読み込む価値はあります
孤立行/孤立段落
段落の最初の行や最後の行がページの境界に単独で現れるのを防ぎます。
\widowpenalty=10000
\clubpenalty=10000
コードハイライト
デフォルトでは listings（外部依存なし）を使用します。minted は品質が高いですが、Python + Pygments/latexmintedが必要です。
\usepackage{listings}
\usepackage{xcolor}
\lstset{
basicstyle=\ttfamily\small,
keywordstyle=\color{blue!70!black},
commentstyle=\color{gray},
stringstyle=\color{green!50!black},
numbers=left,
numberstyle=\tiny\color{gray},
frame=none,
breaklines=true,
showstringspaces=false,
}
ワークフロー
このワークフローを初めて使用する方向けです。
Step 0: 環境チェック
ローカルでコンパイルが必要で、既存のツール情報が不足している場合のみチェックします。まず チェックスクリプト を読み、信頼できるPATHのプログラムを呼び出し、既存の権限に従うことを確認します。このスクリプトは報告のみ行い、インストールや設定変更は行いません。
今回実際に読み込んだ SKILL.md の絶対親ディレクトリから skill_root を解決します。現在の作業ディレクトリがスキルディレクトリであると仮定しないでください。その後、以下を実行します。
bash "$skill_root/scripts/check_latex_env.sh"
欠落したコンポーネントと検出失敗は分けて報告します。タスクに実際に必要で、かつ許可を得た依存関係のみインストールします。許可がない場合は、不足している部分や既存の代替案を提示します。詳細な手順は必要に応じて 環境チェックガイド を参照してください。
Step 1: 要件の理解
以下を確認します。
- 文書タイプ: 論文 / レポート / 履歴書 / スライド / 汎用
- 言語: 日本語 / 英語 / 混在
- 読者: アカデミック / ビジネス / 技術 / 一般
- 特別な要件: 参考文献 / コードブロック / 数式 / データ図表
Step 2: エンジン選択
上記のエンジン選択決定木に従います。日本語/中国語 → xelatex が最も一般的な選択です。
Step 3: .texファイルの生成
可読性組版原則を適用し、package-guide の標準ロード順序テンプレートに従います。
Step 4: コンパイル
latexmk -norc -xelatex -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex
Step 5: ログの確認
main.log を開き、Warning と Overfull/Underfull を検索します。
- Overfull hbox → あふれているテキスト、数式、列幅を特定し、実際のページを確認して局所的に修正します。グローバルな
\sloppyで問題を隠さないでください。 - Underfull hbox → 行が緩すぎる。通常は無害です。
- Font shape warning → フォント形状が利用不可。fontspecの設定を確認します。
- Undefined references → 再コンパイルが必要（latexmkが自動処理しているはずです）。
納品に影響を与える警告（文字欠け、未解決の参照、目に見えるあふれなど）を修正します。無害な警告やテンプレートの制約による警告は理由を説明し、すべての警告をゼロにすることを強制しません。
Step 6: 実際のページチェックと納品
実際のPDFをレンダリングまたは開き、ページ数、文字欠け、トリミング、表/数式/コード、リンク、ブックマーク、および関連するアクセシビリティ要件を確認します。必要に応じてフォントの埋め込みとテキストのコピー可能性を確認します。修正後、再コンパイルして影響を受けるページを再確認します。レンダリングできない場合は、「視覚未確認」と明記し、コンパイル成功をページ検収合格とみなさないでください。
実際に生成され確認されたファイルを出力します。
- PDF — 最終納品物
- .tex ソースファイルと必要なローカルリソース — 再現可能なエントリポイント、実際のコマンド、コンパイル結果、未確認項目を保持します。
evals/evals.json は評価用データであり、実行指示ではありません。このスキルをテストする場合にのみ読み取ります。
よくある落とし穴クイックリファレンス
問題が発生した場合、種類に応じて参照します。
| 問題タイプ | 参照ファイル | 一般的な症状 |
|---|---|---|
| コンパイルエラー | common-pitfalls §コンパイルエラーTop 10 | Undefined control sequence、Missing $、フリーズ |
| エンコーディング/文字 | common-pitfalls §エンコーディングと文字 | 非ASCIIエラー、スマートクォート、中国語句読点の間隔 |
| フロート | common-pitfalls §フロート | 図表が文書末尾に移動 |
| 表 | common-pitfalls §表 | 列幅あふれ、ページまたぎ |
| フォント | common-pitfalls §フォント | システムフォントが見つからない、CJKが効かない |
| パッケージ競合 | package-guide §パッケージ競合マトリックス | Option clash、機能異常 |
| ロード順序 | package-guide §ロード順序ルール | ブックマークの乱れ、リンク切れ |
| 組版品質 | readability-principles | 文書が「アマチュア」に見える |
| 環境問題 | environment-check | コマンドが見つからない、権限エラー |
| ctexフォント | environment-check §よくある環境問題 §6 | fontset 'fandol' is unavailable |
クイック診断チェックリスト
コンパイルに失敗した場合、この順序で確認します。
- ✅ 正しいエンジンを使用したか？（日本語/中国語 → xelatex）
- ✅
latexmkを使用したか？（多回コンパイルとbiberを自動処理） - ✅
-interaction=nonstopmodeを使用したか？（インタラクティブモードで停止しない） - ✅ パッケージのロード順序が現在の文書クラスとパッケージの実際の制約に従っているか？（通常はhyperrefを後に、cleverefをその直後に）
- ✅ すべての
\begin{...}に対応する\end{...}があるか？ - ✅ すべての
{に対応する}があるか？ - ✅ 画像パスは正しいか？（
\graphicspathで検索パスを設定） - ✅ パッケージはすべてインストールされているか？（
kpsewhich <pkg>.styで確認） - ✅ 日本語/中国語文書でctexを使用し、正しい
fontsetを指定したか？ - ✅ ログの末尾を確認 — LaTeXのエラーメッセージは通常、実際の問題行を指しています。