2.4 KiB
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.