Expand description
Remarks on somebody else’s history, and the layer that carries them back.
Two halves, and a caller may want either alone.
The remark (annotation) is the W3C Web Annotation Data Model,
flattened into a metadata block: a target, a selector quoting the passage
with a little of its context, a motivation, a body, and the revision the
reader was looking at. anchor finds the quoted passage again in text
that has since changed, and says how sure it is. One motivation, editing, is
a patch rather than a note — the quoted passage and what should stand in
its place — and apply is the pure half of taking one.
The layer (layer) is the transport. A layer is a companion
chain — somebody else’s single-writer history, fetched into a directory
beside your own, kept current by fetching again, and carried onward when
your own history leaves.
§The loop
author ──── publishes ────▶ reader
│ remarks, in a chain of their own
author ◀─── publishes ────────┘
│ keeps that chain as a layer, and carries it
└──────── publishes ────▶ every other readerNothing about the mechanism knows which direction it is running in: the reader who remarks on the author’s letters does exactly what the author did — writes, snapshots, publishes — and the author receives it the same way the reader received the letters. “Comment access” is not a permission anywhere in this; it is the machinery run the other way.
And a remark reaching a third reader is still the remark’s author’s. It travels as their own chain, digest-verified end to end, with the author’s own signed claims carried alongside it — so the store in the middle is a courier rather than a witness. That is the property the whole shape is for, and it is why a layer is a chain and not a pile of copied documents.
§Reading one
use historica_remark::{Reader, layer::Layers};
let layers = Layers::at("vault/history/remarks");
let reader = Reader::new();
for name in layers.names()? {
let layer = layers.layer(&name)?;
let who = layers.sender(&name);
for remark in layer.remarks(&reader, &who, None)? {
println!("{who} on {}: {}", remark.annotation.target, remark.annotation.body);
}
}§Writing one
A remark is content, and content is the caller’s. This crate does not
record, snapshot or publish — historica does that, and a caller that keeps
documents already has its own way of writing one. So the writing side here
is Annotation::fields, which hands back the metadata in order for a
caller to write with its own document machinery, and
Annotation::render for a caller that has none.
§Features
default-features = false leaves the annotation model and fig: no
historica, no store, no filesystem. What a renderer, a viewer or an
importer takes.
layer— the transport. Everything that touches a store.
Re-exports§
pub use annotation::AT_FIELD;pub use annotation::Anchor;pub use annotation::Annotation;pub use annotation::AnyTarget;pub use annotation::Applied;pub use annotation::COLOR_FIELD;pub use annotation::CREATOR_FIELD;pub use annotation::EXACT_FIELD;pub use annotation::FIELDS;pub use annotation::Fields;pub use annotation::MOTIVATION_FIELD;pub use annotation::Motivation;pub use annotation::PREFIX_FIELD;pub use annotation::REPLACEMENT_FIELD;pub use annotation::Reader;pub use annotation::SUFFIX_FIELD;pub use annotation::Selector;pub use annotation::TARGET_FIELD;pub use annotation::TargetCheck;pub use annotation::VIA_FIELD;pub use annotation::anchor;pub use annotation::apply;pub use layer::Export;layerpub use layer::Layers;layerpub use layer::Received;layerpub use layer::Remark;layerpub use layer::Repo;layer
Modules§
- annotation
- The remark itself — a reader’s mark on somebody else’s document.
- layer
layer - Kept layers — somebody else’s chain, kept beside your own and carried with it.
Enums§
- Error
- What went wrong.
Type Aliases§
- Result
- The result of anything in this crate that can fail.