Skip to main content

historica_remark/
lib.rs

1//! Remarks on somebody else's history, and the layer that carries them back.
2//!
3//! Two halves, and a caller may want either alone.
4//!
5//! **The remark** ([`annotation`]) is the W3C Web Annotation Data Model,
6//! flattened into a metadata block: a target, a selector quoting the passage
7//! with a little of its context, a motivation, a body, and the revision the
8//! reader was looking at. [`anchor`] finds the quoted passage again in text
9//! that has since changed, and says how sure it is. One motivation, `editing`, is
10//! a patch rather than a note — the quoted passage and what should stand in
11//! its place — and [`apply`] is the pure half of taking one.
12//!
13//! **The layer** ([`layer`]) is the transport. A layer is a companion
14//! chain — somebody else's single-writer history, fetched into a directory
15//! beside your own, kept current by fetching again, and carried onward when
16//! your own history leaves.
17//!
18//! # The loop
19//!
20//! ```text
21//!   author ──── publishes ────▶ reader
22//!                                 │ remarks, in a chain of their own
23//!   author ◀─── publishes ────────┘
24//!     │ keeps that chain as a layer, and carries it
25//!     └──────── publishes ────▶ every other reader
26//! ```
27//!
28//! Nothing about the mechanism knows which direction it is running in: the
29//! reader who remarks on the author's letters does exactly what the author
30//! did — writes, snapshots, publishes — and the author receives it the same
31//! way the reader received the letters. "Comment access" is not a permission
32//! anywhere in this; it is the machinery run the other way.
33//!
34//! And a remark reaching a third reader is still the remark's author's. It
35//! travels as their own chain, digest-verified end to end, with the author's
36//! own signed claims carried alongside it — so the store in the middle is a
37//! courier rather than a witness. That is the property the whole shape
38//! is for, and it is why a layer is a chain and not a pile of copied
39//! documents.
40//!
41//! # Reading one
42//!
43//! ```no_run
44//! use historica_remark::{Reader, layer::Layers};
45//!
46//! let layers = Layers::at("vault/history/remarks");
47//! let reader = Reader::new();
48//! for name in layers.names()? {
49//!     let layer = layers.layer(&name)?;
50//!     let who = layers.sender(&name);
51//!     for remark in layer.remarks(&reader, &who, None)? {
52//!         println!("{who} on {}: {}", remark.annotation.target, remark.annotation.body);
53//!     }
54//! }
55//! # Ok::<(), historica_remark::Error>(())
56//! ```
57//!
58//! # Writing one
59//!
60//! A remark is content, and content is the caller's. This crate does not
61//! record, snapshot or publish — historica does that, and a caller that keeps
62//! documents already has its own way of writing one. So the writing side here
63//! is [`Annotation::fields`], which hands back the metadata in order for a
64//! caller to write with its own document machinery, and
65//! [`Annotation::render`] for a caller that has none.
66//!
67//! # Features
68//!
69//! `default-features = false` leaves the annotation model and `fig`: no
70//! historica, no store, no filesystem. What a renderer, a viewer or an
71//! importer takes.
72//!
73//! - `layer` — the transport. Everything that touches a store.
74
75#![cfg_attr(docsrs, feature(doc_cfg))]
76
77pub mod annotation;
78mod document;
79mod error;
80
81#[cfg(feature = "layer")]
82#[cfg_attr(docsrs, doc(cfg(feature = "layer")))]
83pub mod layer;
84
85pub use annotation::{
86    AT_FIELD, Anchor, Annotation, AnyTarget, Applied, COLOR_FIELD, CREATOR_FIELD, EXACT_FIELD,
87    FIELDS, Fields, MOTIVATION_FIELD, Motivation, PREFIX_FIELD, REPLACEMENT_FIELD, Reader,
88    SUFFIX_FIELD, Selector, TARGET_FIELD, TargetCheck, VIA_FIELD, anchor, apply,
89};
90pub use error::{Error, Result};
91
92#[cfg(feature = "layer")]
93pub use layer::{Export, Layers, Received, Remark, Repo};