feat: rename to paperspec and add the website

- Rename manuspec to paperspec everywhere outside pixi.toml: prose, the
  tools, provenance tool names and the fixture key derivations, so every
  fixture and vector is rebuilt.
- Move the namespace addresses under the site, mirroring the repository:
  schema $id https://paperspec.scient.ing/schemas/<file>, the JSON-LD
  context https://paperspec.scient.ing/context/scienting-1.jsonld, and
  term IRIs https://paperspec.scient.ing/vocab#<term>. Format
  identifiers (scienting-*) and URNs (urn:scienting:) are unchanged.
- tools/site.py (standard library only) builds _site/: every file of the
  repository at its own path, each Markdown file rendered as a page with
  sidebar navigation, heading anchors matching the forge's, folder
  listings, a vocabulary page for the context's IRIs, a heading search
  and a 404 page; light and dark themes.
- check.py builds the site and checks that every Markdown file has a
  page, every internal link and fragment resolves, no Markdown is left
  unrendered, and every $id, the context address and the vocabulary IRIs
  are files of the site.
- deploy/: a Caddyfile with the media types and CORS the data needs, and
  a guide; .gitea/workflows/site.yml builds on main and publishes with
  rsync when the SITE_* secrets are set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
alexmandClaude committed 2026-10-14 21:27:21 -04:00
1 parent ea0a7efa78
commit 76d76353d9
213 files changed
+1233 -386

No files matched your search

+7 -7
View File
@@ -1,4 +1,4 @@
# The manuspec formats
# The paperspec formats
This page serves three readers.
A student new to the problem will find each term defined where it first appears.
@@ -15,7 +15,7 @@ Scientists who rely on a paper keep asking two questions.
Where did this number come from, and how far was it checked? A force constant in a table, a value read off a plot, a parameter in a model: each should lead back to the cell or sentence it came from, with a record of who compared it with the page.
Most tools for scientific literature aggregate.
They index hundreds of millions of papers and answer questions over all of them, shallowly. manuspec does the opposite.
They index hundreds of millions of papers and answer questions over all of them, shallowly. paperspec does the opposite.
A team working on a focused question cares more about fifty papers it understands completely than about the world's literature.
Those fifty papers deserve to be converted once, corrected once, split down to the sentence, annotated by the people who know them, linked to checked claims, and kept.
@@ -24,8 +24,8 @@ A model can summarize a paper.
It cannot give you a signed statement that a named person checked a passage, IDs that never move, or a store its owner controls.
The formats supply those three, and they are worth most at the scale of one team.
manuspec is a set of file formats for scientific papers that have been converted, split into addressable pieces and checked.
The repository is at <https://git.scient.ing/infra/manuspec>.
paperspec is a set of file formats for scientific papers that have been converted, split into addressable pieces and checked.
The repository is at <https://git.scient.ing/infra/paperspec>.
It is version 0.1.0 and defines 29 formats; in [registry/formats.json](../registry/formats.json), 18 are `candidate` and 11 are `provisional`.
## Who it is for
@@ -130,12 +130,12 @@ The [specification's reading paths](../spec/README.md) say which chapters each r
## How it compares
manuspec adds to existing standards and replaces none of them. [The comparison page](comparison.md) has the full account; five points follow.
paperspec adds to existing standards and replaces none of them. [The comparison page](comparison.md) has the full account; five points follow.
- JATS is the NISO standard by which [publishers and archives exchange journal content](https://www.niso.org/publications/z3996-2024-jats).
Its [version 1.4 element list](https://jats.nlm.nih.gov/archiving/tag-library/1.4/) shows no sentence element.
A JATS file is an input here (witness kind `jats`).
- TEI has a [sentence-like element](https://tei-c.org/release/doc/tei-p5-doc/en/html/ref-s.html) and [markup that keeps both readings of a correction](https://tei-c.org/release/doc/tei-p5-doc/en/html/ref-corr.html), and recommends `xml:id` pointers ["for durability in the presence of editing"](https://tei-c.org/release/doc/tei-p5-doc/en/html/SA.html). manuspec mints and retires IDs by rule and keeps corrections as a separate, evidence-gated record.
- TEI has a [sentence-like element](https://tei-c.org/release/doc/tei-p5-doc/en/html/ref-s.html) and [markup that keeps both readings of a correction](https://tei-c.org/release/doc/tei-p5-doc/en/html/ref-corr.html), and recommends `xml:id` pointers ["for durability in the presence of editing"](https://tei-c.org/release/doc/tei-p5-doc/en/html/SA.html). paperspec mints and retires IDs by rule and keeps corrections as a separate, evidence-gated record.
TEI is built for encoding scholarly text in general, including correction markup within a text.
- GROBID [converts PDFs to TEI](https://grobid.readthedocs.io/en/latest/Introduction/) and [reports F1 scores](https://grobid.readthedocs.io/en/latest/Introduction/) for its automatic reading.
Its output can be held as one reading, under witness kind `xml`.
@@ -144,7 +144,7 @@ manuspec adds to existing standards and replaces none of them. [The comparison p
The W3C model calls the `TextPositionSelector` ["very brittle"](https://www.w3.org/TR/annotation-model/) against changes to the resource, and the anchors here pin a hash instead.
For annotation in general, use the W3C model.
- Docling's [document schema](https://raw.githubusercontent.com/docling-project/docling-core/main/docs/DoclingDocument.json) refers to items by position (`#/texts/12`) and lists no per-item hash field.
Docling is a conversion toolkit that, [by its own abstract](https://arxiv.org/abs/2501.17887), uses AI models for layout analysis and table structure recognition. manuspec defines no converter.
Docling is a conversion toolkit that, [by its own abstract](https://arxiv.org/abs/2501.17887), uses AI models for layout analysis and table structure recognition. paperspec defines no converter.
The formats are at version 0.1.0, the repository names no outside adopter, and the reference tools belong to the same repository.
The formats do not replace publisher interchange formats.