# PDF Generation

> 周报MD转PDF流程,新增坑10:美元金额$数字会被pandoc当成LaTeX数学模式分隔符导致乱序丢字,需转义为\$。

- Skill: `soapwong/pdf-generation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add soapwong/pdf-generation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/soapwong/pdf-generation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: soapwong (https://skillmd.com/u/soapwong)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/soapwong/pdf-generation

---

在现有 pdf-generation SKILL.md 的"已知坑"清单末尾（坑9之后）追加以下条目，其余内容保持不变：

---

### 坑10（新增，2026-07-30）：正文出现多个美元金额（$760B、$5.71等）时，被pandoc/xelatex当成LaTeX数学模式分隔符，导致数字乱序/丢字

**现象：** 某一段落里连续出现2个以上`$数字`（如"资本开支约$760B,但当期只费用化约$211B,约$549B递延...五家合计净利润增长25%至约$506B,但合计自由现金流反而下降约91%至约$16B"），渲染后该段落内的数字全部错位、部分数字消失、单位字母(B)脱离原位置。用`image`工具做视觉检查最容易发现（表现为看起来像"乱码"，但pdftotext提取文本会更清楚地看出数字顺序被打乱、部分$金额整体消失）。类似地，单个孤立的`$数字`（如"布伦特原油+7.2%至$90.12"）本身不会立刻报错，但会和文档后面某处配对的下一个`$`一起组成一对数学模式分隔符，把中间大段正文都吞进数学模式渲染，导致下游多页出现同样的乱序问题——不能只查当前这一句，要查全文所有`$`出现的奇偶性。

**根因：** Markdown里的`$...$`会被pandoc转换为LaTeX的inline math模式（`$...$`包裹的内容按数学公式解析）。原始研报草稿里的美元金额（`$760B`、`$5.71`等）不是数学公式，但字符层面和LaTeX数学分隔符完全一样，pandoc/xelatex无法区分意图，只能按第一个`$`到下一个`$`之间的内容强制走数学排版规则，导致普通数字、单位字母被当成数学变量重新排列或丢弃。

**修复：** 生成PDF前，对markdown源文件里所有紧跟数字的美元符号做批量转义，把`$`替换成`\$`（反斜杠转义，pandoc会将其识别为字面美元符号，不触发数学模式）。可用如下检查+替换流程：
```bash
# 检查是否存在未转义的 $数字（正则要求$前面不是反斜杠）
grep -n '[^\\]\$[0-9]' report.md

# 用python批量转义（比sed更安全处理UTF-8中文上下文）
python3 -c "
import re
path = 'report.md'
with open(path, 'r', encoding='utf-8') as f:
    content = f.read()
new_content = re.sub(r'(?<!\\\\)\\\$(?=[0-9])', r'\\\\\$', content)
with open(path, 'w', encoding='utf-8') as f:
    f.write(new_content)
"
```
渲染完成后必须用`pdftotext -f <页码> -l <页码> output.pdf -`核对含美元金额的段落，确认数字顺序和金额完整，不能只看xelatex编译有没有报错退出——这类问题编译时通常不会报错或只报无害的"Missing character"警告，容易被误判为字体fallback问题而忽略真正的数学模式吞字问题。

**教训：** 遇到`pdflatex`/`xelatex`渲染警告里出现"Missing character"，不能默认归因为"字体缺少中文字形做fallback"就跳过——先用`pdftotext`把对应页面的文本提取出来做逐字核对，确认是否存在数字/单位错位、消失、或大段文字被跳过，再决定是否是无害警告还是需要修复的实质性排版错误。视觉检查（`image`工具截图）配合`pdftotext`文本提取双重核验，比单独用`image`工具肉眼检查更容易发现"看起来像乱码但实际是数学模式吞字"这类问题。

---