accessible-pdf

Files (1)

• SKILL.md

SKILL.md (first lines)

# accessible-pdf — Accessible PDF from LaTeX

Transform a LaTeX document to produce tagged, screen-reader-friendly PDFs compliant with PDF/UA-1 and PDF/A-2b. Applies preamble changes and switches the build to LuaLaTeX. The user chooses whether to edit the original file in place or create a `-accessible` copy with a separate Makefile target.

Reference: <https://yyahn.com/wiki/Accessible-PDF-from-LaTeX/>

## When to Use

- "make my PDF accessible", "tagged PDF", "PDF/UA", "screen reader"
- ADA/accessibility compliance for any LaTeX document (CV, syllabus, report, paper)

## Prerequisites

- **TeX Live 2025+** (the `\DocumentMetadata` tagging framework is recent)
- **LuaLaTeX** and **latexmk** (both ship with TeX Live)
- **pdfinfo** from poppler (for verification): `brew install poppler` on macOS
- **make** (optional) — used for the Makefile target; `latexmk` can be run directly instead

**Windows users**: `make` is not standard on Windows — run `latexmk -lualatex <basename>` directly instead of using the Makefile. Install poppler via `choco install poppler` or `scoop install poppler`.

Check early: run `lualatex --version` and `pdfinfo -v`. If either is missing, tell the user what to install and stop.

## Workflow

### Phase 1: Find, analyze, and plan

#### 1. Find the document

Use the user-provided path. If none given, glob for `**/*.tex` files containing `\begin{document}`. If multiple matches, ask the user to pick. No assumptions about directory structure — this could be a CV, syllabus, report, or paper.

#### 2. Read the preamble

Read everything before `\begin{document}`. Identify:

- `\documentclass` line and options
- All `\usepackage` lines
- Whether `\DocumentMetadata` already exists
- Whether `hyperref` / `\hypersetup` already exists
- Font-related packages: `inputenc`, `fontenc`, `fontspec`, `mathpazo`, `mathptmx`, `newtxtext`, `newtxmath`, `helvet`, `courier`, `libertine`, `libertinus`, `lmodern`, `inconsolata`, etc.
- Symbol packages: `marvosym`, `pifont`, `wasysym`, etc.
- `\title{...}` and `\author{...}` content (needed for hypersetup metadata)
- Language settings from `babel` or `polyglossia`

If the document already has `\DocumentMetadata` and uses `fontspec`, it may already be configured for accessibility. Note this in the questions below.

#### 3. Ask the user

Present all decisions as a single numbered list so the user can answer in one message:

1. **Edit in place or create a copy?** Edit the original `.tex` file, or create `<basename>-accessible.tex` alongside it? (Multi-file projects: only the main file changes either way.)
2. **Makefile?** Add a Makefile target, or just run `latexmk` directly? (If a Makefile already exists, note this.)
3. **Platform?** macOS, Linux, or Windows? (Affects install instructions for poppler and whether `make` is available.)
4. **Build and verify now?** Build the PDF and check tagging after applying changes, or stop after editing?

Use the answers to tailor Phases 2–4 below.

### Phase 2: Apply transformations

#### 4. Apply transformations

Apply these 5 ordered changes to the target file (either the original or the `-accessible` copy):

**a) Add `\DocumentMetadata` block**

Insert before the `\documentclass` line:

```latex
\DocumentMetadata{
  lang = en,
  pdfstandard = a-2b,
  pdfstandard = ua-1,
  pdfversion = 2.0,
  testphase = {phase-II},
}
```

If the document uses `babel` or `polyglossia` with a non-English language, use the appropriate language code instead of `en`.

**b) Replace Type1 font packages with OpenType equivalents**

Add `\usepackage{fontspec}` after `\documentclass` (if not already present). Then apply these replacements:

| Remove | Replace with |
|--------|-------------|
| `\usepackage[utf8]{inputenc}` (any options) | Remove entirely — LuaLaTeX handles UTF-8 natively |
| `\usepackage[T1]{fontenc}` (any options) | Remove entirely — fontspec handles encoding |
| `\usepackage{mathpazo}` or `\usepackage[sc]{mathpazo}` | `\setmainfont{TeX Gyre Pagella}` |
| `\usepackage{mathptmx}` | `\setmainfont{TeX Gyre Termes}` |
| `\usepackage{newtxtext}` | `\setmainfont{TeX Gyre Termes}` |
| `\usepackage{helvet}` (any options) | `\setsansfont{TeX Gyre Heros}` |
| `\usepackage{courier}` | `\setmonofont{TeX Gyre Cursor}` |
| `\usepackage{lmodern}` | Remove entirely — Latin Modern is the LuaLaTeX default |
| `\usepackage{inconsolata}` | `\setmonofont{Inconsolatazi4-Regular.otf}[BoldFont=Inconsolatazi4-Bold.otf]` |
| `\usepackage{libertine}` or `\usepackage{libertinus}` | `\setmainfont{Libertinus Serif}` |

**Math font packages** (`newtxmath`, `eulervm`, `mathpazo` with math features): flag these for the user to review rather than silently replacing. Math font compatibility with LuaLaTeX can be tricky. Add a `% TODO: review math font compatibility` comment.

For any font package not in the table above, add a `% TODO: find OpenType equivalent for <package>` comment and warn the user.

**c) Add/update hyperref accessibility metadata**

If `hyperref` is not loaded, add `\usepackage{hyperref}`.

Add or merge into the existing `\hypersetup`:

```latex
\hypersetup{
  pdftitle={<from \title{}>},
  pdfauthor={<from \author{}>},
  pdflang={en},
  pdfdisplaydoctitle=true,
}
```

Preserve any existing `\hypersetup` keys (like `colorlinks`, `linkcolor`, etc.) — only add the accessibility-specific keys that are missing. `pdfdisplaydoctitle=true` is required for PDF/UA.

**d) Replace symbol font packages**

| Remove | Add | Command mappings |

From yy/claude-scholar, MIT.

More from yy/claude-scholar