Back to Details

latex-compile-qa

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

LaTeX Compile + QA

LaTeX编译 + QA检查

Compile the LaTeX project and produce a PDF (when the toolchain is available), plus a short build report.
This step is deterministic; if compilation fails, record actionable diagnostics rather than guessing.
编译LaTeX项目并生成PDF（当工具链可用时），同时生成一份简短的构建报告。
此步骤是确定性的；如果编译失败，记录可执行的诊断信息而非猜测原因。

Inputs

输入文件

  • latex/main.tex
  • citations/ref.bib
  • latex/main.tex
  • citations/ref.bib

Outputs

输出文件

  • latex/main.pdf
    (if compilation succeeds)
  • output/LATEX_BUILD_REPORT.md
    (recommended)
  • latex/main.pdf
    （编译成功时生成）
  • output/LATEX_BUILD_REPORT.md
    （推荐生成）

Workflow

工作流程

  1. Run a LaTeX build (e.g., 
    latexmk
    ) if available.
  2. Fix missing packages, missing bib entries, and unresolved references.
  3. Record remaining issues in a build report.
  1. 若工具可用，运行LaTeX构建（例如
    latexmk
    ）。
  2. 修复缺失的包、缺失的Bib条目以及未解析的引用。
  3. 将剩余问题记录到构建报告中。

Quality checklist

质量检查清单

  • Either 
    latex/main.pdf
    exists, or 
    output/LATEX_BUILD_REPORT.md
    explains why compilation failed.
  • For 
    arxiv-survey-latex
    deliverables: 
    latex/main.pdf
    is >= 8 pages and has no undefined citations/references (strict gate).
  • 要么存在
    latex/main.pdf
    ，要么
    output/LATEX_BUILD_REPORT.md
    中说明编译失败的原因。
  • 对于
    arxiv-survey-latex
    交付物：
    latex/main.pdf
    页数≥8，且无未定义的引用（严格检查项）。

Script

脚本使用

Quick Start

快速开始

  • python .codex/skills/latex-compile-qa/scripts/run.py --help
  • python .codex/skills/latex-compile-qa/scripts/run.py --workspace <workspace_dir>
  • python .codex/skills/latex-compile-qa/scripts/run.py --help
  • python .codex/skills/latex-compile-qa/scripts/run.py --workspace <workspace_dir>

All Options

所有选项

  • See 
    --help
    (inputs/outputs are taken from the unit runner when used via pipeline)
  • 查看
    --help
    （通过流水线使用时，输入/输出由单元运行器获取）

Examples

示例

  • Compile + produce report: 
    • python .codex/skills/latex-compile-qa/scripts/run.py --workspace <ws>
  • 编译并生成报告： 
    • python .codex/skills/latex-compile-qa/scripts/run.py --workspace <ws>

Notes

注意事项

  • Uses 
    latexmk -xelatex -bibtex
    when available.
  • Always writes 
    output/LATEX_BUILD_REPORT.md
    (success or failure).
  • Report includes page count + warning summary when available.
  • 若可用，将使用
    latexmk -xelatex -bibtex
    命令。
  • 无论成功或失败，都会生成
    output/LATEX_BUILD_REPORT.md
    。
  • 若条件允许，报告将包含页数统计和警告摘要。

Troubleshooting

故障排除

Common Issues

常见问题

Issue: 
latexmk
not found

问题：
latexmk
未找到

Symptom:
  • Build report says “latexmk not found in PATH”.
Causes:
  • LaTeX toolchain is not installed.
Solutions:
  • Install a TeX distribution that includes 
    latexmk
    .
  • If you can’t install tools, still use 
    latex-scaffold
    to generate 
    latex/main.tex
    and compile elsewhere.
症状：
  • 构建报告显示“latexmk not found in PATH”。
原因：
  • 未安装LaTeX工具链。
解决方案：
  • 安装包含
    latexmk
    的TeX发行版。
  • 若无法安装工具，仍可使用
    latex-scaffold
    生成
    latex/main.tex
    ，并在其他环境编译。

Issue: Build fails with bib/ref errors

问题：构建因Bib/引用错误失败

Symptom:
  • Report shows missing citations/refs or BibTeX errors.
Causes:
  • citations/ref.bib
    missing/miswired, or draft contains invalid cite keys.
Solutions:
  • Ensure 
    latex/main.tex
    points to 
    ../citations/ref.bib
    (or the correct relative path).
  • Ensure all citation keys exist in 
    citations/ref.bib
    .
症状：
  • 报告显示缺失引用或BibTeX错误。
原因：
  • citations/ref.bib
    文件缺失或路径错误，或草稿中包含无效的引用键。
解决方案：
  • 确保
    latex/main.tex
    指向
    ../citations/ref.bib
    （或正确的相对路径）。
  • 确保所有引用键都存在于
    citations/ref.bib
    中。

Recovery Checklist

恢复检查清单

  • Read 
    output/LATEX_BUILD_REPORT.md
    tail for the first actionable error.
  • Confirm 
    latex/main.tex
    exists and bibliography path is correct.
  • 查看
    output/LATEX_BUILD_REPORT.md
    末尾的第一个可执行错误。
  • 确认
    latex/main.tex
    存在且参考文献路径正确。