alexmandClaude
a4eecb4d5b
The oracle had two import names, `tools.oracle` for the tools and `paperspec` for other repositories, which could load the same code twice in one process and needed a gate keyed on the module name. It now lives in the standard src layout under its one name. - git mv tools/oracle -> src/paperspec; the 22 rule modules are unchanged. - The tools import `paperspec`. `tools/__init__.py` now holds the Python 3.14 and cryptography/jsonschema check and puts src/ first on sys.path, so the tools run this checkout's code with or without pixi. The package's own __init__ checks nothing and exposes __version__. - pyproject.toml: version from git tags via setuptools-scm (guess-next-dev, node-and-timestamp, src/paperspec/_version.py, gitignored). The packages stay listed rather than found because schemas/, sql/ and vectors/ stay at the root: the spec links to them and the site serves the schemas at their $id URLs. - pixi.toml: a `dev` feature and environment with setuptools, setuptools-scm and python-build, and `pixi run -e dev wheel`. - check.py scans src/paperspec for rule IDs; README, CONTRIBUTING, the FAQ, the overview, the vectors and tools READMEs and the changelog point at the new path. The FAQ no longer says the oracle is not a library. pixi.lock is not re-solved in this commit: with a dynamic version, pixi builds the package metadata to lock, which needs the conda environment installed. Run `pixi lock` and commit the result before pushing; the site workflow installs with --locked. pixi run check passes; no computed value, vector, fixture, schema or SQL file changed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Guides
These guides explain paperspec to someone meeting it for the first time. They serve three readers: a newcomer who has not seen the problem before, an implementer who will write a reader, writer, converter or checker, and an expert who knows the neighboring standards. The specification says exactly what each format is. The guides say what each format is for, with examples drawn from the fixtures.
| Guide | For |
|---|---|
| Overview | What paperspec is, who it serves, and how its parts fit together. |
| Concepts | The ideas behind the formats, one at a time, each with a real example. |
| Walkthrough | One paper, from a flawed first reading to a corrected, reviewed and signed document. |
| Examples | Things to run: checking hashes by hand, reading a package with a few lines of Python, querying a database. |
| Rationale | Why the formats look the way they do, and the questions they leave open. |
| Comparison | How paperspec compares with JATS, TEI, W3C Web Annotation and other schemas. |
| FAQ | Short answers to the questions people ask first. |
| Glossary | Every term, in a sentence. |
Reading orders
Newcomer. Spend a first afternoon on the overview, then the walkthrough with the fixture open beside it, then the examples. Read the concepts when a term in the walkthrough needs more than the glossary gives.
Implementer. Start with the specification's reading paths, which list the chapters to read for a reader, a converter, a store and a validator. Chapters 0, 1, 3, 4 and 5 are needed for any of them. Next, run the section "Test your implementation against a vector" in the examples. Check your work against the vectors and the fixtures. Chapter 22 of the specification defines conformance.
Expert. Read the overview for scope and for what paperspec is not, then the comparison for how it differs from existing standards.
After that, read the rationale for the reason behind each rule and the questions it leaves open.
It ends with a list of limits.
Section 0.4 of the specification and registry/formats.json give the status of each format: the version is 0.1.0, and each format is candidate or provisional.