alexmandClaude
88379d152c
The six console scripts (paperspec-check, -build, -validate, -load, -stress, -site) become subcommands of a single `paperspec` command: paperspec validate, load, check, build, stress and site. `python -m paperspec COMMAND` runs the same thing. - paperspec/cli/main.py builds the whole parser, apart from the commands, so `paperspec --help` and `paperspec COMMAND --help` work without a checkout or the tools extra; a command's module is imported only when it runs. - `paperspec` with no command prints the overview: what each command does, examples, and which work anywhere (validate, load) and which need a checkout (check, build, stress, site). Each command's help has a description with advice, and worked examples; a misspelled command gets a suggestion (argparse suggest_on_error); `--version` prints the version and the pinned Unicode version. - Each command module exposes run(args) and returns the exit status. Arguments that parse but do not fit together raise UsageError, which prints the command's usage and exits 2: load now also refuses --built-from or --store without --bundle. - The failure messages say what to do: install paperspec[tools], clone the repository, rerun stress with the printed seed, or run paperspec build when the rebuild check differs. check and stress say how many failures they did not list. - check runs the rebuild as `python -m paperspec build`. - pyproject installs one script, `paperspec`; the pixi tasks and the docs use the subcommands. pixi run check passes (run here as `python -m paperspec check` with src/ on the path); the rebuild is byte-identical. pixi.lock still needs `pixi lock`. 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.