Metadata-Version: 2.5
Name: persread
Version: 0.0.1
Summary: Perspective Reading: reading a large literature through one author's theoretical perspective, with every passage counted and page-mapped.
Author: Toni Prug
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: close reading,corpus,digital humanities,page numbers,pdf,text analysis
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Sociology
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# persread — Perspective Reading

Reading a large literature through one author's theoretical perspective. Language-model
sessions read the sources, guided by that author's work, and point to the ones still
missing. Scripts establish, count and locate every passage, so each reading can be checked,
including what an author leaves out.

The analysis stays the researcher's own. The software reads, and only the scripts' counted,
page-mapped output is meant to be cited.

## Status

This is an early release. The software has been in daily use on a research corpus since
August 2026 and is being packaged for others. This release carries two of its utilities, the
ones that are useful on their own. The rest follows in later releases.

## Install

```sh
pipx install persread        # or: uv tool install persread
```

Requires Python 3.9 or later, and nothing else.

## What it does now

### `persread fold` — compare spellings of a name

Searching a library for an author goes wrong when the same name is stored with and without
accents, or in different Unicode forms. macOS, for instance, returns some file names in
decomposed form. `fold` gives the form two strings should be compared in: accents stripped,
case folded, and letters that have no accent to strip (đ, ł, ø, ß, æ, œ) mapped by hand.

```sh
$ persread fold "Korač" "KORAC" "Korac"
Korač	korac
KORAC	korac
Korac	korac
✓ all match
```

The exit status is 0 when all forms match, so it can be used in scripts. Folding is for
matching only. Never display a folded name in place of the original.

### `persread offset` — printed page numbers from a PDF's text

A quotation is cited by its printed page, but a PDF counts its own pages. `offset` reads the
page numbers printed in the running heads or at the foot of each page, and reports the most
common difference between the PDF page and the printed page:

```sh
$ pdftotext book.pdf book.txt          # pages are separated by form feeds
$ persread offset book.txt
book.txt                                         412 pp · printed = pdf -14 (91% of 388 folio reads)
```

If the offset changes partway through a volume, rival offsets are listed too. It is a
heuristic: check the result against a page you have read.

## Licence

Copyright (c) 2026 Toni Prug. Licensed under the GNU General Public License, version 3 or
later (GPL-3.0-or-later); see `LICENSE`.
