Metadata-Version: 2.4
Name: prl-wordcount
Version: 1.0.0
Summary: APS-compliant word count analyzer for Physical Review Letters LaTeX manuscripts
Author: Xingju Wang
Author-email: Lilun Zhang <zhanglilun@nudt.edu.cn>
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/USER/prl-wordcount
Project-URL: Repository, https://github.com/USER/prl-wordcount
Project-URL: Issues, https://github.com/USER/prl-wordcount/issues
Keywords: latex,tex,word-count,prl,physical-review,aps,manuscript
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# PRL Word Count

[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-GPLv3-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.0.0-orange.svg)](CHANGELOG.md)

**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

```bash
# 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](examples/example_report.html).

---

## 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)

```bash
pip install prl-wordcount
```

### From source

```bash
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

```bash
# 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](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](SKILL.md) for the complete skill definition.

---

## License

This project is licensed under the GNU General Public License v3.0 — see [LICENSE](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.
