feat: comment categories; emend, relink and resolve corrections
scienting-layer/1: an optional, fixed category on comment, caveat and question bodies (comment, context, critique, question, correction, feedback, resource). Corrections: emend fixes the authors' own slip and keeps what was printed (a run's printed), never lowering fidelity or a witness match; relink sets or removes what a citation names; resolve sets a reference's resolution. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017R7sgDNvUGWY2zFPCq2JH6
This commit is contained in:
33 files changed
+726
-80
No files matched your search
+9
-1
@@ -112,7 +112,10 @@ No other kind carries `attrs`, and each kind carries only its own attributes.
|
||||
| `link` | `url`, `text`. | The text. |
|
||||
| `equation` | `node`: the ID of an equation child of the sentence. | `$$` + that equation's source + `$$` |
|
||||
|
||||
Runs are canonical: no `text` run is empty, and no two adjacent `text` runs have the same style list.
|
||||
A `text`, `link`, `cite`, `xref` or `fnmark` run MAY carry `printed`: its text as the paper prints it, where an `emend` corrected the authors ([11.6](11-corrections.md#116-emendations)).
|
||||
The run's `text` is then the emended text, and only an emend writes `printed`.
|
||||
|
||||
Runs are canonical: no `text` run is empty, no two adjacent `text` runs have the same style list unless one of them carries `printed`, and no run's `printed` equals its `text`.
|
||||
A sentence's `equation` runs name its `equation` children, each once, in the children's order, and a sentence has no other children.
|
||||
A display equation the sentence runs through is thus part of the sentence, while keeping its own ID and hashes.
|
||||
|
||||
@@ -125,3 +128,8 @@ That of any other node is the plain projections of its text leaves joined with o
|
||||
A node's text leaves are found by walking its subtree in document order and stopping at `sentence`, `cell`, `reference`, `authors`, `keywords`, `code` and `algorithm` nodes, and at `equation` nodes whose parent is not a sentence; an `equation-line` is never a text leaf.
|
||||
|
||||
Offsets, quotations and the text hash are all defined on the plain projection as stored, before normalization.
|
||||
|
||||
A node's runs as printed are its runs with each run's `printed` in place of its `text`, and each `text` run that carried one joined with the adjacent `text` runs of the same style list, as the run was before an emend split it.
|
||||
Its projection as printed is the plain projection of its runs as printed; an equation's or a verbatim node's is its plain projection, and any other node's joins its text leaves' projections as printed with one U+0020.
|
||||
It is the text a witness of the paper holds, recovered from `nodes.jsonl` alone; for a node no emend touched it is the plain projection.
|
||||
The strict and lossy projections are taken over the runs as printed ([5.3](05-hashes.md#53-the-strict-projection)), and `projections.jsonl` gives an emended sentence's projections with its projection as printed.
|
||||
+5
-1
@@ -17,6 +17,9 @@ In this chapter *H* is SHA-256 written as hexadecimal; under a keyed scheme, *H*
|
||||
| `node_hash` | *H*(canonical JSON of `{"own": own_hash, "children": [each child's node_hash, in order]}`) | Pins on leaves; the root hash; knowing that something below has changed. |
|
||||
|
||||
Normalization is that of [1.4](01-conventions.md#14-text-normalization-for-hashing).
|
||||
The plain projection is of the runs as stored, and the strict and lossy projections of the runs as printed ([3.6](03-nodes.md#36-the-plain-projection)).
|
||||
So an `emend`, which corrects the authors' own slip ([11.6](11-corrections.md#116-emendations)), changes a leaf's `text_hash`, `own_hash` and `node_hash`, because the text that is read, quoted and pinned is the emended one.
|
||||
It leaves the leaf's `match_hash` and `align_key` as they were, because the witnesses they compare the leaf with hold the printed text, and a value computed from the emended text would report every emendation as a disagreement.
|
||||
Because each `node_hash` covers its children's, the root's `node_hash` covers the whole tree (it is a hash over canonical JSON of `{own, children}`, not an RFC 6962 Merkle root, which [8.5](08-fidelity.md#85-merkle-roots) defines for receipts): a correction to one sentence changes that sentence's values and the `node_hash` of each ancestor, and nothing else.
|
||||
`hashes.jsonl` gives every value for every node of a small document, with each node's own content.
|
||||
|
||||
@@ -42,7 +45,7 @@ A table's columns name header cells by ID, so fixing a header cell changes that
|
||||
## 5.3 The strict projection
|
||||
|
||||
The strict projection folds notation to one canonical linear form and keeps structure, so that it can certify agreement.
|
||||
It is computed over a node's runs, or its math, as follows; for other nodes it is the strict projections of the text leaves joined with U+0020, then step 3.
|
||||
It is computed over a node's runs as printed ([3.6](03-nodes.md#36-the-plain-projection)), or its math, as follows; for other nodes it is the strict projections of the text leaves joined with U+0020, then step 3.
|
||||
|
||||
1. Apply NFC to every string, then project each run:
|
||||
|
||||
@@ -142,6 +145,7 @@ A node's prose length is the number of code points in its lossy projection other
|
||||
|
||||
Two readings of a document are aligned as whole sentence sequences, never paragraph by paragraph, because backends disagree about paragraphs at page and column breaks.
|
||||
Each reading is a list of sentences in document order, each with its strict projection, lossy projection, complex keys, container and context (the kind of its container: paragraph, heading, caption and so on).
|
||||
Those projections are of the runs as printed ([5.3](#53-the-strict-projection)), so a corrected document aligned with a witness again shows no emendation as a suspect.
|
||||
|
||||
1. **Anchors.** A sentence is a candidate when its lossy projection occurs exactly once in each reading and its prose length is at least 20.
|
||||
Take the candidates in the order of the first reading, and choose the longest subsequence whose positions in the second reading increase; among equally long ones, the one whose sequence of positions in the first reading is lexicographically smallest.
|
||||
|
||||
@@ -105,6 +105,8 @@ The result is `{result, node, node_hash?, span?, drift?, via?, reason?}`: the ou
|
||||
A `moved` or `reattached` anchor is re-pinned to the live node, and the move is recorded.
|
||||
|
||||
Checks are stricter than readers: an extract is a span or leaf anchor and never accepts `changed-below`, because a check is about exact words.
|
||||
An `emend` changes a leaf's `node_hash` and plain projection as a `replace` does ([11.6](11-corrections.md#116-emendations)), so an anchor on the leaf is judged as after a replace: a quote outside the emended text that occurs once is `reattached` with its new position, and a quote that spans the emended text is `stale`.
|
||||
A `relink` changes the leaf's `node_hash` but not its plain projection, so an anchor on it is `reattached` by its quote; a `resolve` changes no node, so an anchor on the reference stays `current`.
|
||||
`resolve.jsonl` resolves seventeen anchors made at revision 0 against `fixtures/packages/hale2026harmonic-damb` at revision 12, with every outcome.
|
||||
|
||||
## 6.6 Drift
|
||||
|
||||
+8
-1
@@ -12,10 +12,16 @@
|
||||
Levels apply to leaves.
|
||||
The pipeline records F0, F1 or F2 in a leaf's `fidelity`; F3 comes only from receipts.
|
||||
A correction that changes a leaf drops it back: the gate's crop evidence makes it F1 at most, until it is corroborated or proofread again.
|
||||
An `emend`, `relink` or `resolve` ([11.1](11-corrections.md#111-operations)) never does, because a level measures the reading against its witnesses and the page.
|
||||
An emend corrects the authors, not the reading, and leaves the leaf as printed ([3.6](03-nodes.md#36-the-plain-projection)) as it was; a relink or a resolve changes no text, and the references a citation names are not text a witness corroborates.
|
||||
|
||||
Whatever compares a leaf with a witness or with the page compares the leaf as printed: alignment and its suspects ([5.6](05-hashes.md#56-alignment)), corroboration by `match_hash`, a proofreader who signs a receipt, and a spot-check's `errors`.
|
||||
So an emendation is never reported as a misreading.
|
||||
|
||||
## 8.2 Levels
|
||||
|
||||
A leaf's level is the highest of its recorded `fidelity` and the levels of every valid receipt ([8.6](#86-receipt-status)) that lists it at its current `node_hash`.
|
||||
A leaf's level is the highest of its recorded `fidelity` and the levels of every valid receipt ([8.6](#86-receipt-status)) that lists it at its current `node_hash`, or at a `node_hash` that only `emend`, `relink` and `resolve` corrections of the leaf have changed since.
|
||||
To find those hashes, walk the document's corrections back from the last: one of those three that targets the leaf and whose `after` is the hash reached so far leads back to its `before`, and any other correction that names the leaf, as its `target` or in `touched`, `path`, `to_path`, `created` or `retired`, ends the walk.
|
||||
A receipt at a lower level never lowers a node; only a revocation, a failed spot-check or a correction does.
|
||||
A spot-check's `qa:` receipt ([8.8](#88-spot-checks)) raises the nodes it sampled, except those its `errors` name.
|
||||
A document reports, in `document.json`, the lowest level among its leaves and the count at each level.
|
||||
@@ -45,6 +51,7 @@ A paper has thousands of nodes, and nobody signs thousands of times, so people s
|
||||
|
||||
A receipt lists nodes, records, or both.
|
||||
A correction invalidates a receipt for the corrected node only, because the node's `node_hash` no longer matches; the rest still counts.
|
||||
An emend, relink or resolve invalidates none ([8.2](#82-levels)).
|
||||
|
||||
A receipt shared outside the team cannot carry plain node hashes, which would leak short texts, and its signature covers them.
|
||||
So an export re-issues it: a new receipt with `export_of`, values under the export's key, signed by the original reviewer or a team key with the `export` purpose.
|
||||
|
||||
@@ -9,7 +9,11 @@ Each reference is a `reference` node holding its printed runs, exactly as printe
|
||||
| `{type: "document", doc}` | It names a document in the same store, by key. |
|
||||
| `{type: "none"}` | Nothing yet. |
|
||||
|
||||
A reference without a record has the resolution `none`.
|
||||
A `resolve` correction sets a reference's resolution, and its record keeps the one before ([11.7](11-corrections.md#117-citations-and-references)).
|
||||
|
||||
Every `cite` run links a sentence to one or more references.
|
||||
A `relink` correction changes the references a run names, makes a text run a cite run, or makes a cite run text again, without changing its text ([11.7](11-corrections.md#117-citations-and-references)).
|
||||
The citation graph is therefore sentence-level: for any reference, the format gives every sentence that cites it, which is the citation's context.
|
||||
The database derives a `citations` table from the runs ([13](13-database.md)).
|
||||
An article's references and its Supporting Information's are separate documents' references and never mix.
|
||||
+62
-7
@@ -18,9 +18,14 @@ Each has an `index`, counted from 1 in the order corrections are applied, and th
|
||||
| `reclassify` | `target`, `kind` | Changes a node's kind, such as a paragraph that is really a caption, to a kind with the same content shape. | Unchanged. |
|
||||
| `relabel` | `target`, `label` | Changes a printed label. | Unchanged. |
|
||||
| `set` | `target`, `attr`, `value` | Sets one structural attribute: a section's `level`, a table's `columns`, a cell's `column`, `rowspan`, `colspan` or `role`, a row's `header_path`, a list's `ordered`, an item's `marker` or a theorem's `variant`. | Unchanged. |
|
||||
| `emend` | `target`, `find`, `replace`, `kind`, optional `run` and `note` | Corrects the authors' own slip, where the reading matches the page and the page is wrong: replaces the one occurrence of `find` among the target's prose strings with `replace`, a non-empty string, and keeps what was printed ([11.6](#116-emendations)). `kind` is `typo`, `spelling`, `grammar`, `punctuation`, `wording` or `other`. | Unchanged. |
|
||||
| `relink` | `target`, `run`, `refs` | Makes run `run` of the target a `cite` run naming `refs`, a non-empty list of reference nodes, or with `refs` null makes a `cite` run a `text` run, keeping its text ([11.7](#117-citations-and-references)). | Unchanged. |
|
||||
| `resolve` | `target`, `resolution` | Sets a reference node's resolution in `references.jsonl` ([11.7](#117-citations-and-references)). | Unchanged. |
|
||||
|
||||
A leaf's editable strings are the `text` of its `text`, `link`, `cite`, `xref` and `fnmark` runs and the `source` of its `math` runs, each searched on its own; an equation's `source`; a verbatim node's `text`.
|
||||
Its prose strings, which an emend searches, are the `text` of those five run kinds alone: never a math or equation source, and never a verbatim node's text.
|
||||
`set` exists because readings drop spans, roles and header paths; see the [rationale](../docs/rationale.md#corrections).
|
||||
`emend` exists because a faithful reading of a wrong page is not a misreading: it corrects the paper while keeping what was printed ([11.6](#116-emendations)).
|
||||
Runs are made canonical after every operation, and the result MUST satisfy every rule of [3](03-nodes.md).
|
||||
|
||||
## 11.2 Every correction records
|
||||
@@ -43,9 +48,9 @@ When a correction is applied, its record gains:
|
||||
| `before`, `after` | The target's `node_hash` before and after, or null; for an inserted subtree, `target` is its root. |
|
||||
| `path` | The target's ancestors when it was applied, root first; for an insert, the new subtree's. |
|
||||
| `to_path` | For a move, the new ancestors. |
|
||||
| `touched` | The leaves whose content the correction changed, sorted: the target of a `replace`, text `insert`, `relabel` or `set` on a leaf; the new leaves of a node `insert`; the deleted leaves of a `delete`; both parts of a `split`; both nodes of a run `merge`, or the moved-in leaves of a container `merge`; the moved leaves of a `move`; the leaves of a reclassified node. |
|
||||
| `touched` | The leaves whose content the correction changed, sorted: the target of a `replace`, text `insert`, `relabel` or `set` on a leaf, and of an `emend` or `relink`; the new leaves of a node `insert`; the deleted leaves of a `delete`; both parts of a `split`; both nodes of a run `merge`, or the moved-in leaves of a container `merge`; the moved leaves of a `move`; the leaves of a reclassified node; none for a `resolve`. |
|
||||
| `created`, `retired` | IDs minted or retired. |
|
||||
| `from` | The label, kind or attribute value before a `relabel`, `reclassify` or `set`. |
|
||||
| `from` | The label, kind or attribute value before a `relabel`, `reclassify` or `set`; the references the run named before a `relink`, or null for a text run; the resolution before a `resolve`. |
|
||||
|
||||
Retirements are also entered in `ids.jsonl` with the correction's index as `rev`.
|
||||
Drift ([6.6](06-anchors.md#66-drift)) is computed from `path`, `to_path` and `touched` alone, so it needs no replay.
|
||||
@@ -58,19 +63,22 @@ A correction is refused, naming the rule ([22](22-conformance.md)), when:
|
||||
2. a target, parent or sibling is not live, or the root would be deleted, moved, merged or reclassified;
|
||||
3. `find` is empty or does not occur exactly once;
|
||||
4. an `insert` has no crop evidence, or names a run or offset its target does not have;
|
||||
5. a digit changes without crop evidence: in a `replace` whose `find` and replacement have different digits, a `delete` of leaves that hold digits, or a `relabel` whose labels have different digits;
|
||||
5. a digit changes without crop evidence: in a `replace` whose `find` and replacement have different digits, a `delete` of leaves that hold digits, or a `relabel` whose labels have different digits; or an `emend` changes, adds or removes a digit, or edits beside one, whatever its evidence ([11.6](#116-emendations));
|
||||
6. any leaf outside `touched` has different digits afterwards;
|
||||
7. a `split` falls outside the sentence, inside a run other than text, or leaves a part empty;
|
||||
7. a `split` falls outside the sentence, inside a run other than text or inside an emended run, or leaves a part empty;
|
||||
8. a `merge` joins nodes that differ in kind, are not mergeable, or are not adjacent siblings;
|
||||
9. a `move` would put a node inside itself;
|
||||
10. a `reclassify` changes the content shape, or a `relabel` or `set` targets a kind that does not take it; or
|
||||
11. the result breaks a rule of [3](03-nodes.md).
|
||||
10. a `reclassify` changes the content shape, or a `relabel` or `set` targets a kind that does not take it;
|
||||
11. the result breaks a rule of [3](03-nodes.md);
|
||||
12. an `emend` targets a node without runs, or finds its text only in a math or equation source or only across runs; or a `replace` or text `insert` would change an emended run, or a correction other than an emend writes `printed`;
|
||||
13. a `relink` names a run that is neither text nor a cite, or unlinks a run that is not a cite; or
|
||||
14. a `resolve` names a node that is not a reference.
|
||||
|
||||
The gate needs only the document's current state, so a tool can run it on a proposal before applying anything, and get back the record the correction would append or the rule it breaks.
|
||||
`paperspec validate --correction` does this against a package.
|
||||
|
||||
Digits are characters of General Category Nd in the plain projection.
|
||||
A package's corrections are also checked as a whole: indexes run from 1 without gaps, each `id` derives from its record, `rev` equals their number, every retired ID is in `ids.jsonl`, and the last correction of each leaf ends at its current `node_hash`.
|
||||
A package's corrections are also checked as a whole: indexes run from 1 without gaps, each `id` derives from its record, `rev` equals their number, every retired ID is in `ids.jsonl`, the last correction of each leaf ends at its current `node_hash`, and the last `resolve` of each reference ends at its resolution in `references.jsonl`.
|
||||
`corrections.jsonl` in the vectors applies each operation, and each refusal, to a small document.
|
||||
|
||||
## 11.5 The history root
|
||||
@@ -80,3 +88,50 @@ Because corrections are only appended, a consistency proof (RFC 9162 §2.1.4) be
|
||||
The proof is a `scienting-proof/1` with `kind` `consistency`, holding the `doc`, `from_rev`, `to_rev`, `from_root`, `to_root` and the `path` as hex hashes; a verifier applies RFC 9162 §2.1.4.2.
|
||||
A checks-only package carries no corrections, so its history is the empty root.
|
||||
`proofs.jsonl` gives consistency proofs for every prefix of small trees and for the example paper between revisions 8 and 12; `fixtures/records/proof-consistency.json` is the latter.
|
||||
|
||||
## 11.6 Emendations
|
||||
|
||||
A `replace` fixes the reading: the converter misread the page, and the page is right.
|
||||
An `emend` fixes the paper: the reading matches the page, and the authors printed a typo, a misspelling, a slip of grammar or punctuation, or a wording an editor corrects for readers.
|
||||
The two claim different things, so different things follow from them.
|
||||
|
||||
**What is kept.**
|
||||
In a `text` run, the found text becomes a run of its own, with the style of the run it was in, whose `text` is the replacement and whose `printed` is the found text.
|
||||
In a `link`, `cite`, `xref` or `fnmark` run, or a text run emended before, the run's text changes and `printed` keeps its whole text as it was first printed.
|
||||
The record keeps `find`, the printed string, and `replace`, the emended one, so the history says what each emendation was, while the runs say where it is after any later split, merge or move.
|
||||
A leaf as printed ([3.6](03-nodes.md#36-the-plain-projection)) is therefore recovered from `nodes.jsonl` alone: each run's `printed` in place of its text.
|
||||
|
||||
**The gate.**
|
||||
An emend searches the target's prose strings for exactly one occurrence, as a `replace` searches its editable strings, but never a math or equation source, which `replace` corrects.
|
||||
The replacement is a string, never runs, and is not empty; to delete a word, an editor finds it with a neighbor and keeps the neighbor.
|
||||
The edit stays inside one run, so a `find` that occurs only across runs is refused.
|
||||
No digit may change, be added or removed, and the edit may not touch one: setting aside the longest common prefix of the run's string before and after, and then the longest common suffix of the rest, what remains holds no digit in either string, and the unchanged character on each side of it is not a digit.
|
||||
So an emend never turns "3,5" into "3.5": a number is data, corrected by `replace` with crop evidence, even where the authors printed it wrong.
|
||||
Only an emend writes `printed`.
|
||||
A `replace` or text `insert` that would change an emended run, a `split` inside one, and replacement runs or inserted nodes that carry `printed` are refused, and a second emend of an emended run keeps what was first printed.
|
||||
|
||||
**What follows.**
|
||||
|
||||
1. The leaf keeps its level ([8.1](08-fidelity.md#81-levels-of-fidelity), [8.2](08-fidelity.md#82-levels)): a level measures the reading against its witnesses and the page, and the leaf as printed is what it was.
|
||||
2. Whatever compares the leaf with a witness or the page compares it as printed, so an emendation is never reported as a misreading ([8.1](08-fidelity.md#81-levels-of-fidelity)).
|
||||
3. The leaf's `text_hash`, `own_hash` and `node_hash` change, as for any change of text, because the text read, quoted and pinned is the emended one; its `match_hash` and `align_key`, which are of the runs as printed, do not ([5.1](05-hashes.md#51-the-five-values)).
|
||||
4. Anchors on the leaf relocate by their quote, as after a `replace` ([6.5](06-anchors.md#65-resolution)).
|
||||
|
||||
`corrections.jsonl` emends a word and a cross-reference's printed form, and refuses a changed digit, a `find` across runs, a `find` in math, an emend of a node without runs and a `replace` of an emended run; each emend's expectation adds the leaf as printed.
|
||||
|
||||
## 11.7 Citations and references
|
||||
|
||||
A `relink` changes what a citation names, never its text, so it needs no crop.
|
||||
With `refs` a non-empty list of reference nodes, run `run` becomes a `cite` run naming them, or stays one, and keeps its text: a text run's whole text becomes the cite's printed form, and its style is dropped, since a cite run has none ([3.5](03-nodes.md#35-inline-runs)).
|
||||
With `refs` null, a cite run becomes a text run with the same text.
|
||||
Anything an emend kept in `printed` stays.
|
||||
Every reference must be a `reference` node, as for any cite run (rule 11 of [11.4](#114-the-gate)), and `from` keeps the references the run named before, or null for a text run.
|
||||
A relink changes no plain projection, so the leaf keeps its level.
|
||||
Turning a text run into a cite, or back, still changes the leaf's `match_hash` and `align_key`, because the strict projection marks a citation ([5.3](05-hashes.md#53-the-strict-projection)); changing only which references a cite run names changes neither.
|
||||
To cite part of a text run, a `replace` gives that part as runs that include the cite run ([11.1](#111-operations)).
|
||||
|
||||
A `resolve` sets a reference node's resolution in `references.jsonl` ([10](10-references.md)) to any valid one: `doi`, `document` or `none`.
|
||||
The record keeps the resolution before in `from`, which is `{type: "none"}` for a reference without a record; the resolve then adds the record, in document order.
|
||||
No content value covers `references.jsonl`, so a resolve changes no node's values: its `before` and `after` are the reference's unchanged `node_hash`, and `touched` is empty.
|
||||
It changes `references.jsonl`, that file's entry in the manifest, the revision and the history root, as every correction does ([11.5](#115-the-history-root)).
|
||||
`corrections.jsonl` links a citation printed as a superscript, unlinks a cite run, resolves a reference to a DOI, and refuses a relink of a cross-reference, a cite of a node that is not a reference and a resolve of a sentence.
|
||||
+1
-1
@@ -39,7 +39,7 @@ Unloading gives the package back byte for byte, and its manifest hash with it; t
|
||||
## 13.4 The store tables
|
||||
|
||||
`store.sql` adds what a team adds to its documents: `roster_keys`, `projects`, `members`, `project_documents`, `reading_paths`, `layers`, `annotations`, `annotation_targets` (derived, so a reader finds the annotations on a node), `datasets`, `dataset_values`, `digitizations`, `views`, `policies`, `submissions` and `grades`.
|
||||
Each keeps its record whole in a `record` or `descriptor` column, with the columns a query needs beside it.
|
||||
Each keeps its record whole in a `record` or `descriptor` column, with the columns a query needs beside it, such as an annotation's `body_kind` and its `category`, which is NULL when the body has none.
|
||||
|
||||
## 13.5 The bundle
|
||||
|
||||
|
||||
+21
-4
@@ -45,9 +45,9 @@ Replies are annotations that target annotations, so discussions are threads anch
|
||||
| `gloss` | `TextualBody` | `audience` | An explanation at `novice`, `student` or `expert` level. |
|
||||
| `claim-link` | `SpecificResource` | `source` (`lode:<tag>`), `pin`, `role` | That the span `states`, `uses` or `disputes` a claim. |
|
||||
| `symbol` | `SpecificResource` | `source`, `pin`, `symbol` | That this occurrence of a symbol is a symbol claim. |
|
||||
| `comment` | `TextualBody` | | A remark, opinion or interpretation. |
|
||||
| `caveat` | `TextualBody` | | A warning a reader should see. |
|
||||
| `question` | `TextualBody` | `for` | A question for a `reader`, a `group` or the `authors`. |
|
||||
| `comment` | `TextualBody` | `category` | A remark, opinion or interpretation. |
|
||||
| `caveat` | `TextualBody` | `category` | A warning a reader should see. |
|
||||
| `question` | `TextualBody` | `for`, `category` | A question for a `reader`, a `group` or the `authors`. |
|
||||
| `exercise` | `TextualBody` | `exercise` | A task with a key and a rule ([19](19-exercises.md)). |
|
||||
| `citation-context` | `TextualBody` | `reference`, `verdict`, `reason` | Why a sentence cites a reference, and whether it supports it. |
|
||||
| `prerequisite` | `SpecificResource` | `source` | What to read or know first. |
|
||||
@@ -57,7 +57,24 @@ Replies are annotations that target annotations, so discussions are threads anch
|
||||
| `generated` | `TextualBody` | `generator` | Text a model wrote about the span; never mistaken for source. `generator` is `{model, run}` as a correction's model author is ([11.2](11-corrections.md#112-every-correction-records)). |
|
||||
|
||||
A textual body has a `value`, and optionally a `format` (`text/plain` or `text/markdown`) and a `language`.
|
||||
|
||||
A `comment`, `caveat` or `question` body MAY carry a `category`, which says what it is about, from a fixed list:
|
||||
|
||||
| `category` | Says |
|
||||
| --- | --- |
|
||||
| `comment` | A general remark. |
|
||||
| `context` | Background, related work, or what a reader should know to follow the span. |
|
||||
| `critique` | A flaw in the method, the analysis or the argument. |
|
||||
| `question` | A question. |
|
||||
| `correction` | An error of fact, number, citation or reference in the paper. |
|
||||
| `feedback` | A suggestion addressed to the authors. |
|
||||
| `resource` | Data, code or a related paper. |
|
||||
|
||||
A producer that supports categories SHOULD set one on every comment, caveat and question; the property is optional only so that layers written before it stay valid.
|
||||
The category is independent of the kind, so a caveat may be a `correction` and a question a `critique`.
|
||||
A `correction` category says that a reader found an error in the paper; correcting the document's reading of it is a correction of [11](11-corrections.md).
|
||||
The store's `annotations` table keeps the category beside the body's kind ([13.4](13-database.md#134-the-store-tables)).
|
||||
Nothing a model writes is ever stored as source text.
|
||||
A model may propose a `description`, and like any annotation it stays `proposed` until a person confirms it; an accessible export uses confirmed descriptions only, and a figure with none has no description.
|
||||
Other text a model writes about a span, such as a summary, is a `generated` annotation, which names its `generator`.
|
||||
`fixtures/records/layer/` holds a layer with one annotation of each common kind and the receipt that confirms some of them.
|
||||
`fixtures/records/layer/` holds a layer with one annotation of each common kind, each comment, caveat and question with its category, and the receipt that confirms some of them.
|
||||
Reference in new issue
Block a user