render-pdf-doc

Files (21)

• SKILL.md
• known_pitfalls.md · references/
• pandoc_korean_cheatsheet.md · references/
• check_deps.sh · scripts/
• infer_colwidths.py · scripts/
• render_pdf.sh · scripts/
• scan_glyph_coverage.py · scripts/
• skill.yml
• anchor-doc.md · templates/
• anchor-doc_ko.md · templates/
• briefing-handout.md · templates/
• briefing-handout_ko.md · templates/
• proposal-cover.md · templates/
• proposal-cover_ko.md · templates/
• reference-table.md · templates/
• reference-table_ko.md · templates/
• glyph_plain.md · tests/fixtures/
• glyph_risky.md · tests/fixtures/
• test_font_faces.py · tests/
• test_glyph_coverage.sh · tests/
• test_render_pdf.py · tests/

SKILL.md (first lines)

# Render-PDF-Doc Skill

This skill handles layout only (CJK fonts, table column widths) with raw pandoc + xelatex — no
Quarto, whose `tbl-colwidths` has reported PDF regressions (issues 6089/9200). Not for: a
manuscript with a bibliography (`/manage-refs` `scripts/render_pandoc.sh`), an institutional .docx
form (`/fill-protocol`), the ICMJE COI form (`/fill-icmje-coi`), figures or PPTX (`/make-figures`,
`/present-paper`).

## Dependencies

Python 3 is required by the wrapper. FontTools is optional for the font-file
coverage check (`python3 -m pip install fonttools`).

```bash
# macOS
brew install pandoc
brew install --cask mactex-no-gui          # xelatex + xeCJK (~5 GB)

# Linux
sudo apt-get install pandoc texlive-xetex texlive-lang-cjk fonts-noto-cjk

# Windows (PowerShell) — run in Git Bash afterwards
winget install --id JohnMacFarlane.Pandoc
winget install --id MiKTeX.MiKTeX          # xelatex; installs missing LaTeX packages on demand
# No CJK font download needed: Malgun Gothic ships with Windows 7+ and is the default here.
```

Detection:
```bash
bash scripts/check_deps.sh
```

On Windows / Git Bash, MiKTeX's bin directory
(`%LOCALAPPDATA%\Programs\MiKTeX\miktex\bin\x64`) is often not on `PATH`; both `check_deps.sh`
and `render_pdf.sh` probe it. If `xelatex` still reads `[MISS]`, add that directory to `PATH`.

## Workflow

### Step 1 — Author markdown with frontmatter

```yaml
---
title: "Paper 2 Calibration Anchor — Q&A Grid"
author: "<Author Group>"
date: "2026-05-01"
mainfont: "Apple SD Gothic Neo"        # macOS default
CJKmainfont: "Apple SD Gothic Neo"
geometry: "margin=0.85in"
fontsize: 11pt
linestretch: 1.25
colorlinks: true
---
```

- Set both `mainfont` and `CJKmainfont`: without `CJKmainfont`, Hangul falls back to Times New
  Roman (broken glyphs or blanks). Use `Noto Sans CJK KR` on Linux/CI and `Malgun Gothic` on
  Windows; the render script auto-detects the per-OS default when the fields are absent.
- Read every number in a table from the source CSV or analysis output. Do not retype a number
  from prose or carry one forward from an earlier draft — a table correct in v3 is not evidence
  it is correct in v4.
- A circulation PDF carries no change history, internal version numbers (e.g. v3.2.2) or PI
  attribution: put them in a separate circulation file or a supplementary. Keep the received
  primary source (the `.docx` or `.eml` a co-author sent) unmodified as its own artifact — the
  PDF is a derivative, and the next round is diffed against the source. If that source was
  AI-drafted by a collaborator, re-derive every number, denominator and author-year in it from
  the underlying paper or analysis output before it reaches the PDF.

### Step 2 — Infer column widths

Never split pipe-table columns equally: a column holding only short labels then gets the same
width as the data columns, which cramps them. Size from content instead:

```bash
python3 scripts/infer_colwidths.py input.md > input.colwidths.md
```

For each pipe table it computes per-column display width = `max(len(header), max(len(cell)))`
(CJK = 2 cells, ASCII = 1) and rewrites the separator row with proportional dash counts. To set
widths by hand, write the separator dashes yourself and render without `--infer-colwidths`.

### Step 3 — Render

```bash
bash scripts/render_pdf.sh -i input.colwidths.md -o output.pdf
```

Or one-shot:
```bash
bash scripts/render_pdf.sh -i input.md -o output.pdf --infer-colwidths
```

Frontmatter wins over wrapper defaults, including `--font` / `--cjk-font`.
Missing fields use the wrapper or OS defaults. This also applies to `geometry`,
`fontsize`, `linestretch` and `colorlinks` (including `false`). Explicit pandoc
`-V` / `-M` arguments after `--` still override frontmatter; for example,
`-- -V fontsize=10pt`. The wrapper logs font **fallbacks**, not the final fonts.

The standard `article` class honours only `10pt`, `11pt` and `12pt` and silently
ignores any other size. When the effective `fontsize` is anything else and no
`documentclass` is set, the wrapper switches to KOMA-Script `scrartcl` (pandoc's
documented route), adds `classoption: fontsize=<size>` when you set no
`classoption` (KOMA reads a fractional size such as `8.5pt` only that way), and
logs the switch. Set `documentclass` yourself to override it.

xeCJK's defaults are set for Chinese: they delete the space after curly quotes
and en/em dashes, and insert one wherever Latin letters or digits meet Hangul:

```text
typed:    “no difference” and      AI를 썼다    3개
printed:  “no difference”and       AI 를 썼다   3 개
```

The wrapper turns both off (`scripts/xecjk_korean.tex`) so the PDF keeps the spaces you typed. It is
appended to your `header-includes`; if you pass `-H` after `--` (which replaces
`header-includes`), the file is added as one more `-H`. Headers given another way (a `--defaults`
file with `include-in-header`, or `-V header-includes=...`) override the appended one, so pass
`-H "${CLAUDE_SKILL_DIR}/scripts/xecjk_korean.tex"` alongside them. `--xecjk-defaults` keeps
xeCJK's own spacing, e.g. for Chinese or Japanese text. Check with
`pdftotext -layout out.pdf - | grep -cE '[”’][A-Za-z]'` (0 apart from possessives).

From Aperivue/medsci-skills, MIT.

More from Aperivue/medsci-skills