prl-wordcount 1.0.0

APS-compliant word count analyzer for Physical Review Letters LaTeX manuscripts

PRL Word Count

Automated word-count analysis for Physical Review Letters (PRL) LaTeX manuscripts.

Runs texcount, parses displayed equations and figure references, applies APS conversion formulas, and generates a self-contained HTML report — all in one command.

---

Quick Start

# Install
pip install prl-wordcount

# Analyze your paper
prl-wordcount manuscript.tex --open

Output:

============================================================
  PRL Word Count Summary — manuscript.tex
============================================================
  Body text:           3,232 words
  Captions:              179 words
  Displayed eqs:         240 words  (15 rows × 16)
  Figures:               641 words  (3 figures)
  ──────────────────────────────────────────────────
  PRL TOTAL:           4,292 words
  PRL LIMIT:           3,750 words
  Status:              OVER by 542 words (14%)
============================================================

Plus an HTML report like this.

---

What It Does

Stage	Description
[1/5] texcount	Runs the TeXcount Perl script, parses per-section word counts
[2/5] Equations	Splits main body from appendix, counts rows in equation, align, aligned, gathered, split
[3/5] Figures	Resolves \includegraphics paths, reads PNG/JPEG dimensions from binary headers (no Pillow needed)
[4/5] APS formula	Converts to PRL word-equivalents: 16 words/eq-row, (150/aspect)+20 per 1-col figure
[5/5] HTML report	Self-contained HTML with stat cards, per-section table, equation inventory, bar charts

---

Installation

Via pip (recommended)

pip install prl-wordcount

From source

git clone https://github.com/USER/prl-wordcount.git
cd prl-wordcount
pip install -e .

Dependencies

Dependency	Required?	Install
Python 3.8+	Yes	https://python.org
texcount (Perl)	Yes	tlmgr install texcount (TeX Live)
pdfinfo	No	apt install poppler-utils / brew install poppler

No Python packages beyond the standard library are required.

---

Usage

# Basic analysis
prl-wordcount paper.tex

# Specify output path
prl-wordcount paper.tex -o my_report.html

# Auto-open report in browser after generation
prl-wordcount paper.tex --open

# Custom word limit (for non-PRL journals)
prl-wordcount paper.tex --limit 4000

# Machine-readable JSON output
prl-wordcount paper.tex --json

# Show version
prl-wordcount --version

---

PRL Counting Rules

Counted toward the 3,750-word limit

Component	Conversion
Body text	Words between Introduction and Acknowledgments
Section/subsection headers	Word count of titles
Figure/table captions	Word count of caption text
Displayed equations	16 words/row (single-column), 32 words/row (two-column wide)
Single-column figures	(150 / aspect_ratio) + 20 words
Two-column (wide) figures	(300 / aspect_ratio) + 40 words
Tables (single-column)	13 + 6.5 × lines words
Footnotes	Word count of footnote text

Not counted

• Title, author byline, affiliations
• Abstract
• Acknowledgments
• References / bibliography
• Appendix / End Matter (up to ~2 extra pages allowed)

---

FAQ

Q: How are displayed equations counted? Each row of an equation, align, eqnarray, aligned, gathered, or split environment counts as 16 words (single-column width). Two-column wide equations count as 32 words/row.

Q: How are figures counted? The APS formula uses the figure's rendered aspect ratio (width/height), which is read directly from the PNG or JPEG binary header. The formula estimates how much text the figure displaces.

Q: What if my figure is a PDF? The script tries pdfinfo (from poppler-utils). If unavailable, it falls back to an assumed 4:3 aspect ratio. Install poppler for accurate results.

Q: How does appendix handling work? Everything after \appendix is automatically detected and excluded from the PRL total. Appendix content appears in the "Not counted" section of the report.

Q: Can I use this for other APS journals? Yes. Use --limit N to set a custom word limit (e.g., --limit 7000 for PRX). The same APS conversion rules apply to all Physical Review journals.

---

Claude Code Integration

A Claude Code skill definition is included in SKILL.md. When placed in ~/.claude/skills/prl-wordcount/, the AI assistant can analyze documents by saying:

"Check if paper.tex meets the PRL word limit"

See SKILL.md for the complete skill definition.

---

License

This project is licensed under the GNU General Public License v3.0 — see LICENSE for details.

GPLv3 requires that any derivative works also be distributed under the same license terms.

---

Contributing

Contributions are welcome. Please open an issue or submit a pull request on GitHub.