linked-rolls 0.70.0 → 0.71.0

package/lib/ops/copies.js

@@ -13,6 +13,7 @@ import { featureIdsOf, carriedOnlyOn, forgetFeatures } from "./forget.js";
  * inserts every symbol the copy's own tracker bar reads on it. The
  * version is a reading in that system's words, so it is coded for the
  * system the copy was cut for.
+ * @category Operations
  */
 export const createVersion = (copy) => draft => {
     const bar = barOf(copy);
@@ -28,6 +29,7 @@ export const createVersion = (copy) => draft => {
  * Puts the copy into the edition without a version of its own, as for a
  * copy whose features are not read into symbols: one known only from a
  * recording states instead which versions it carries.
+ * @category Operations
  */
 export const addCopy = (copy) => draft => {
     draft.copies.push(copy);
@@ -38,6 +40,7 @@ export const addCopy = (copy) => draft => {
  * copy, or where the copy is the reference itself. The copy is read at
  * its own places whatever alignment it has, and through its own bar,
  * which is what lets a copy cut for another system be aligned at all.
+ * @category Operations
  */
 export const alignmentFor = (edition, copy, date = new Date()) => {
     const reference = referenceCopyOf(edition);
@@ -62,6 +65,7 @@ export const alignmentFor = (edition, copy, date = new Date()) => {
  * its features and tears onto the axis by them, in place of any
  * alignment it had. A copy that shares no run of notes with the
  * reference copy is left as it was.
+ * @category Operations
  */
 export const alignCopy = (copyId, date = new Date()) => draft => {
     const state = stateOf(draft);
@@ -75,6 +79,7 @@ export const alignCopy = (copyId, date = new Date()) => draft => {
  * Aligns every copy that has features with the reference copy, as
  * `alignCopy` does one. The reference copy itself is taken off any
  * alignment it had, its places being the axis.
+ * @category Operations
  */
 export const alignCopies = (date = new Date()) => draft => {
     const reference = referenceCopyOf(stateOf(draft));
@@ -100,6 +105,7 @@ export const alignCopies = (date = new Date()) => draft => {
  * aligns every other copy onto it. Every place the edition gives along
  * the roll moves with this, which is why it is a choice and not
  * something worked out.
+ * @category Operations
  */
 export const chooseReferenceCopy = (copyId, date = new Date()) => draft => {
     if (!draft.copies.some(copy => copy.id === copyId))
@@ -111,6 +117,7 @@ export const chooseReferenceCopy = (copyId, date = new Date()) => draft => {
  * Puts the copy's features back where they were measured, off the
  * axis. What the alignments say about the paper goes with it, since
  * that is worked out from them.
+ * @category Operations
  */
 export const unalignCopy = (copyId) => onCopy(copyId, copy => {
     revertAlignment(copy);
@@ -119,19 +126,32 @@ export const unalignCopy = (copyId) => onCopy(copyId, copy => {
  * Takes the extension a pneumatic reader adds off the ends of the
  * copy's chains of holes, and records how much was taken, so that their lengths
  * can be compared with a scanned copy's at all.
+ * @category Operations
  */
 export const shortenCopy = (copyId, extension, leaving) => onCopy(copyId, copy => shortenChains(extension, copy, leaving));
-/** Puts the reader's extension back on the copy's chains of holes. */
+/**
+ * Puts the reader's extension back on the copy's chains of holes.
+ * @category Operations
+ */
 export const unshortenCopy = (copyId) => onCopy(copyId, copy => revertShortening(copy));
-/** States what the copy's features were read from, in place of any earlier statement. */
+/**
+ * States what the copy's features were read from, in place of any earlier statement.
+ * @category Operations
+ */
 export const stateSource = (copyId, source) => onCopy(copyId, copy => {
     copy.readFrom = source;
 });
-/** Takes back the statement, leaving the copy silent about its source again. */
+/**
+ * Takes back the statement, leaving the copy silent about its source again.
+ * @category Operations
+ */
 export const clearSource = (copyId) => onCopy(copyId, copy => {
     copy.readFrom = undefined;
 });
-/** Gives the copy the siglum it is referred to by, or takes it away where the siglum given is blank. */
+/**
+ * Gives the copy the siglum it is referred to by, or takes it away where the siglum given is blank.
+ * @category Operations
+ */
 export const nameCopy = (copyId, siglum) => onCopy(copyId, copy => {
     const trimmed = siglum.trim();
     if (trimmed)
@@ -156,6 +176,7 @@ export const dropStatements = (copy, matches) => {
  * one known only from a recording, and `carriageProblems` reports it
  * where features carry symbols already. A second statement about one
  * version is none.
+ * @category Operations
  */
 export const stateCarriage = (copyId, versionId, belief) => onCopy(copyId, copy => {
     const statements = stateOf(copy).carries ?? [];
@@ -163,13 +184,17 @@ export const stateCarriage = (copyId, versionId, belief) => onCopy(copyId, copy
         return;
     copy.carries = [...statements, referenceHeld(versionId, belief)];
 });
-/** Takes back the copy's statement that it carries the version. */
+/**
+ * Takes back the copy's statement that it carries the version.
+ * @category Operations
+ */
 export const clearCarriage = (copyId, versionId) => onCopy(copyId, copy => dropStatements(copy, statement => idOf(statement) === versionId));
 /**
  * Adds a general condition to the copy, beside whatever is stated of it
  * already. A paper stretch is added the same way, where one was
  * measured; what the alignments say of the paper is worked out from
  * them and stated nowhere.
+ * @category Operations
  */
 export const addGeneralCondition = (copyId, condition) => onCopy(copyId, copy => {
     copy.conditions.push(condition);
@@ -179,6 +204,7 @@ export const addGeneralCondition = (copyId, condition) => onCopy(copyId, copy =>
  * what was stated before; given nothing, it takes the statement away. A
  * copy has one paper, so it has one such condition, which may give a
  * strain in either direction.
+ * @category Operations
  */
 export const statePaperStretch = (copyId, stretch) => onCopy(copyId, copy => {
     copy.conditions = [...without(copy.conditions, isPaperStretch), ...(stretch ? [stretch] : [])];
@@ -187,11 +213,15 @@ export const statePaperStretch = (copyId, stretch) => onCopy(copyId, copy => {
  * Adds a tear to the copy, beside whatever is stated of it already. The
  * tear is given on the axis, where the copy's features stand, and moves
  * with them from then on.
+ * @category Operations
  */
 export const addTear = (copyId, tear) => onCopy(copyId, copy => {
     copy.conditions.push(tear);
 });
-/** The symbols of the versions that no other copy carries. */
+/**
+ * The symbols of the versions that no other copy carries.
+ * @category Operations
+ */
 export const symbolsCarriedOnlyBy = (edition, copyId) => {
     const copy = edition.copies.find(c => c.id === copyId);
     return copy ? insertedIn(edition.versions).filter(carriedOnlyOn(featureIdsOf(copy))) : [];
@@ -200,6 +230,7 @@ export const symbolsCarriedOnlyBy = (edition, copyId) => {
  * Takes the copy out of the edition together with the symbols only it
  * carries, and with every reference the versions and the argumentations
  * made to those symbols.
+ * @category Operations
  */
 export const removeCopy = (copyId) => onCopy(copyId, (copy, draft) => {
     forgetFeatures(draft, featureIdsOf(copy));

package/lib/ops/draft.d.ts

@@ -15,6 +15,7 @@ import { WithId } from "../shared/utils.js";
  * (`reading`) and does all its writing in the one function it builds
  * from that. Where operations run one after another on one draft, each
  * reads what the ones before it wrote.
+ * @category Operations
  */
 export type EditionOp = (draft: Draft<Edition>) => void;
 export declare const noChange: EditionOp;
@@ -33,6 +34,7 @@ export declare const reading: (build: (edition: Edition) => EditionOp) => Editio
  * The state a draft stands at, as plain data. Reading a draft proxies
  * everything it touches, so what is only read is read from this, and
  * what is looked up in an edition is looked up in this (`takenOf`).
+ * @category Lookups
  */
 export declare const stateOf: <T>(draft: Draft<T>) => T;
 /** The ids of the items the rewriting left out. */

package/lib/ops/draft.js

@@ -35,6 +35,7 @@ export const reading = (build) => draft => build(stateOf(draft))(draft);
  * The state a draft stands at, as plain data. Reading a draft proxies
  * everything it touches, so what is only read is read from this, and
  * what is looked up in an edition is looked up in this (`takenOf`).
+ * @category Lookups
  */
 export const stateOf = (draft) => isDraft(draft) ? takenOf(draft) : draft;
 /** The ids of the items the rewriting left out. */

package/lib/ops/edits.d.ts

@@ -3,7 +3,11 @@ import { EditionOp } from "./draft.js";
 /**
  * Replaces the edits with a single one carrying all their insertions
  * and deletions, classified by a guess at what the exchange does.
+ * @category Operations
  */
 export declare const mergeEdits: (versionId: string, toMerge: readonly Edit[]) => EditionOp;
-/** Replaces the edit with one edit per inserted and one per deleted symbol. */
+/**
+ * Replaces the edit with one edit per inserted and one per deleted symbol.
+ * @category Operations
+ */
 export declare const splitEdit: (versionId: string, toSplit: Edit) => EditionOp;

package/lib/ops/edits.js

@@ -63,6 +63,7 @@ const guessEditType = (edition, versionId, edit) => {
 /**
  * Replaces the edits with a single one carrying all their insertions
  * and deletions, classified by a guess at what the exchange does.
+ * @category Operations
  */
 export const mergeEdits = (versionId, toMerge) => reading(edition => {
     if (toMerge.length === 0)
@@ -79,7 +80,10 @@ export const mergeEdits = (versionId, toMerge) => reading(edition => {
         version.edits = [...editsOf(version).filter(edit => !mergedIds.has(edit.id)), merged];
     });
 });
-/** Replaces the edit with one edit per inserted and one per deleted symbol. */
+/**
+ * Replaces the edit with one edit per inserted and one per deleted symbol.
+ * @category Operations
+ */
 export const splitEdit = (versionId, toSplit) => {
     const parts = [
         ...(toSplit.insert ?? []).map(insertion),

package/lib/ops/features.d.ts

@@ -6,6 +6,7 @@ import { EditionOp } from "./draft.js";
  * States the condition of the feature, in place of any earlier
  * statement. Throws where the kind of feature is in no such condition;
  * `conditions` says which conditions each kind of feature may be in.
+ * @category Operations
  */
 export declare const stateFeatureCondition: (copyId: string, featureId: string, condition: FeatureConditionAssignment) => EditionOp;
 /**
@@ -13,6 +14,7 @@ export declare const stateFeatureCondition: (copyId: string, featureId: string,
  * copy, the act that brought another feature about, or, where neither
  * is said, an act of its own for the purpose given. A patch is never
  * punched, being glued on, so `punched` says nothing of one.
+ * @category Operations
  */
 export interface FeatureAct {
     /** The copy came from its punching with it, which is where a reading of a scan puts every chain of holes. */
@@ -28,12 +30,14 @@ export interface FeatureAct {
  * produced, by the punching or by a later act. Which act, `FeatureAct`
  * says; a `beside` that names nothing the copy bears is passed over and
  * the feature goes into an act of its own.
+ * @category Operations
  */
 export declare const addFeature: (copyId: string, feature: FeatureOrPatch, act?: FeatureAct) => EditionOp;
 /**
  * States that the patch bears the feature. What a patch bears came onto
  * the copy with the patch, so it belongs to no act of its own and
  * states no place: it stands where the patch stands.
+ * @category Operations
  */
 export declare const addBorneFeature: (copyId: string, patchId: string, feature: NestedFeature) => EditionOp;
 /**
@@ -42,9 +46,13 @@ export declare const addBorneFeature: (copyId: string, patchId: string, feature:
  * a patch goes with everything glued onto it, and a feature of a patch
  * may be taken back on its own, the patch staying where it is. An act
  * left having produced or added nothing goes as well.
+ * @category Operations
  */
 export declare const removeFeatures: (copyId: string, featureIds: readonly string[]) => EditionOp;
-/** Why several features cannot be replaced by one. */
+/**
+ * Why several features cannot be replaced by one.
+ * @category Operations
+ */
 export type MergeObstacle = 'fewer-than-two' | 'different-types' | 'different-tracks' | 'differing-conditions' | 'unlike-features' | 'different-acts';
 /**
  * What stands in the way of reading the features as one, or nothing
@@ -53,6 +61,7 @@ export type MergeObstacle = 'fewer-than-two' | 'different-types' | 'different-tr
  * condition at most one of them states. How far apart they lie is not
  * asked: whether a gap is a bridge of the perforator, a tear or two
  * perforations of their own is the editor's reading.
+ * @category Operations
  */
 export declare const mergeObstacle: (features: readonly FeatureOrPatch[]) => MergeObstacle | undefined;
 /**
@@ -61,6 +70,7 @@ export declare const mergeObstacle: (features: readonly FeatureOrPatch[]) => Mer
  * features themselves say, which cannot reach `different-acts`: one
  * feature is the work of one act, and where the features stand is the
  * edition's business rather than theirs.
+ * @category Operations
  */
 export declare const mergeObstacleIn: (edition: Edition, featureIds: readonly string[]) => MergeObstacle | undefined;
 /**
@@ -80,5 +90,6 @@ export declare const mergeObstacleIn: (edition: Edition, featureIds: readonly st
  *
  * Throws where the features cannot stand for one; `mergeObstacle`
  * says beforehand whether they can.
+ * @category Operations
  */
 export declare const mergeFeatures: (copyId: string, featureIds: readonly string[]) => EditionOp;

package/lib/ops/features.js

@@ -20,6 +20,7 @@ const allows = (feature, condition) => {
  * States the condition of the feature, in place of any earlier
  * statement. Throws where the kind of feature is in no such condition;
  * `conditions` says which conditions each kind of feature may be in.
+ * @category Operations
  */
 export const stateFeatureCondition = (copyId, featureId, condition) => onFeature(copyId, featureId, feature => {
     if (!allows(feature, condition)) {
@@ -108,6 +109,7 @@ const actFor = (copy, patch, act) => {
  * produced, by the punching or by a later act. Which act, `FeatureAct`
  * says; a `beside` that names nothing the copy bears is passed over and
  * the feature goes into an act of its own.
+ * @category Operations
  */
 export const addFeature = (copyId, feature, act = {}) => onCopy(copyId, copy => {
     actFor(copy, isPatch(feature), act).push(feature);
@@ -116,6 +118,7 @@ export const addFeature = (copyId, feature, act = {}) => onCopy(copyId, copy =>
  * States that the patch bears the feature. What a patch bears came onto
  * the copy with the patch, so it belongs to no act of its own and
  * states no place: it stands where the patch stands.
+ * @category Operations
  */
 export const addBorneFeature = (copyId, patchId, feature) => onCopy(copyId, copy => {
     const patch = featuresOf(copy).flatMap(withBorneFeatures).find(borne => borne.id === patchId);
@@ -131,6 +134,7 @@ export const addBorneFeature = (copyId, patchId, feature) => onCopy(copyId, copy
  * a patch goes with everything glued onto it, and a feature of a patch
  * may be taken back on its own, the patch staying where it is. An act
  * left having produced or added nothing goes as well.
+ * @category Operations
  */
 export const removeFeatures = (copyId, featureIds) => onCopy(copyId, (copy, draft) => {
     const named = new Set(featureIds);
@@ -172,6 +176,7 @@ const conditionsOf = (features) => features.flatMap(feature => feature.condition
  * condition at most one of them states. How far apart they lie is not
  * asked: whether a gap is a bridge of the perforator, a tear or two
  * perforations of their own is the editor's reading.
+ * @category Operations
  */
 export const mergeObstacle = (features) => {
     if (features.length < 2)
@@ -209,6 +214,7 @@ const obstacleIn = (copy, featureIds) => {
  * features themselves say, which cannot reach `different-acts`: one
  * feature is the work of one act, and where the features stand is the
  * edition's business rather than theirs.
+ * @category Operations
  */
 export const mergeObstacleIn = (edition, featureIds) => {
     const copy = featureIds.map(id => copyOfFeature(edition, id)).find(copy => copy !== undefined);
@@ -277,6 +283,7 @@ const carryOver = (draft, replaced, mergedId) => {
  *
  * Throws where the features cannot stand for one; `mergeObstacle`
  * says beforehand whether they can.
+ * @category Operations
  */
 export const mergeFeatures = (copyId, featureIds) => onCopy(copyId, (copy, draft) => {
     const state = stateOf(copy);

package/lib/ops/versions.d.ts

@@ -7,17 +7,25 @@ export declare const hypothesesBeside: (version: Readonly<Version>, parentId: st
  * Makes the version stand on its own: what it inherited becomes its
  * own insertions, and its derivations go, the hypotheses among them,
  * with the motivations that belonged to them.
+ * @category Operations
  */
 export declare const detachVersion: (versionId: string) => EditionOp;
 /**
  * Takes the version out. Whatever read its text against it comes to
  * stand on its own, a hypothesis that something derives from it goes,
  * and so does a copy's statement that it carries the version.
+ * @category Operations
  */
 export declare const removeVersion: (versionId: string) => EditionOp;
-/** Takes the symbols out of the version's own insertions, and the edits that had nothing else. */
+/**
+ * Takes the symbols out of the version's own insertions, and the edits that had nothing else.
+ * @category Operations
+ */
 export declare const removeSymbols: (versionId: string, symbolIds: readonly string[]) => EditionOp;
-/** Moves the edits into a new version based on this one. */
+/**
+ * Moves the edits into a new version based on this one.
+ * @category Operations
+ */
 export declare const deriveVersion: (versionId: string, editIds: readonly string[]) => EditionOp;
 /**
  * States that the version may also derive from the parent, beside what
@@ -26,7 +34,11 @@ export declare const deriveVersion: (versionId: string, editIds: readonly string
  * unless the belief holds this one more certain. A version derives from
  * itself, twice from one parent, or from one of its own descendants in
  * no statement.
+ * @category Operations
  */
 export declare const stateDerivation: (versionId: string, parentId: string, belief?: Belief) => EditionOp;
-/** Takes back the hypothesis that the version derives from the parent; the principal derivation goes with `detachVersion`. */
+/**
+ * Takes back the hypothesis that the version derives from the parent; the principal derivation goes with `detachVersion`.
+ * @category Operations
+ */
 export declare const clearDerivation: (versionId: string, parentId: string) => EditionOp;

package/lib/ops/versions.js

@@ -30,6 +30,7 @@ const dropDerivations = (version, matches) => {
  * Makes the version stand on its own: what it inherited becomes its
  * own insertions, and its derivations go, the hypotheses among them,
  * with the motivations that belonged to them.
+ * @category Operations
  */
 export const detachVersion = (versionId) => reading(edition => {
     const edits = snapshotOf(edition, versionId).map(insertion);
@@ -43,6 +44,7 @@ export const detachVersion = (versionId) => reading(edition => {
  * Takes the version out. Whatever read its text against it comes to
  * stand on its own, a hypothesis that something derives from it goes,
  * and so does a copy's statement that it carries the version.
+ * @category Operations
  */
 export const removeVersion = (versionId) => reading(edition => {
     const detachments = edition.versions
@@ -56,9 +58,15 @@ export const removeVersion = (versionId) => reading(edition => {
         draft.versions = without(draft.versions, version => version.id === versionId);
     };
 });
-/** Takes the symbols out of the version's own insertions, and the edits that had nothing else. */
+/**
+ * Takes the symbols out of the version's own insertions, and the edits that had nothing else.
+ * @category Operations
+ */
 export const removeSymbols = (versionId, symbolIds) => onVersion(versionId, version => dropInsertions(version, new Set(symbolIds)));
-/** Moves the edits into a new version based on this one. */
+/**
+ * Moves the edits into a new version based on this one.
+ * @category Operations
+ */
 export const deriveVersion = (versionId, editIds) => onVersion(versionId, (version, draft) => {
     const chosen = new Set(editIds);
     const moved = editsOf(version).filter(edit => chosen.has(edit.id));
@@ -79,6 +87,7 @@ export const deriveVersion = (versionId, editIds) => onVersion(versionId, (versi
  * unless the belief holds this one more certain. A version derives from
  * itself, twice from one parent, or from one of its own descendants in
  * no statement.
+ * @category Operations
  */
 export const stateDerivation = (versionId, parentId, belief) => onVersion(versionId, (version, draft) => {
     const derivations = stateOf(version).basedOn ?? [];
@@ -88,7 +97,10 @@ export const stateDerivation = (versionId, parentId, belief) => onVersion(versio
         return;
     version.basedOn = [...derivations, referenceHeld(parentId, belief)];
 });
-/** Takes back the hypothesis that the version derives from the parent; the principal derivation goes with `detachVersion`. */
+/**
+ * Takes back the hypothesis that the version derives from the parent; the principal derivation goes with `detachVersion`.
+ * @category Operations
+ */
 export const clearDerivation = (versionId, parentId) => onVersion(versionId, version => {
     if (readsAgainst(stateOf(version), parentId))
         return;

package/lib/readers/phillipsEroll.d.ts

@@ -49,8 +49,15 @@ import { Millimeters, Seconds } from "../model/Quantity.js";
  * The two rules collide on one number, the lowest note of the T-100
  * sharing 24 with the tenth position. Notes win there, the note block
  * being the larger claim; none of his samples uses the number at all.
+ * @category Sources
  */
 export declare const CONTROL_OFFSET: Readonly<Record<string, number>>;
+/**
+ * How `readFromPhillipsEroll` reads a file: the bar it numbers its
+ * positions by, where its expression numbers sit, how time is put back
+ * onto the paper, and what the reader added to the chains.
+ * @category Sources
+ */
 export interface PhillipsErollOptions {
     /**
      * The bar the file numbers its positions by, which is the bar of
@@ -87,7 +94,11 @@ export interface PhillipsErollOptions {
  * Reads one of his e-roll files as a copy of the roll, in millimetres
  * of paper, on the bar it was cut for and in that bar's numbering. A
  * position the bar does not read is left out, as the bar would leave it.
+ * @category Sources
  */
 export declare function readFromPhillipsEroll(buffer: ArrayBuffer, { system, controlOffset, placeAt, extension }?: PhillipsErollOptions): RollCopy;
-/** The bars his files are known to be numbered by. */
+/**
+ * The bars his files are known to be numbered by.
+ * @category Sources
+ */
 export declare const phillipsSystems: readonly TrackerBar[];

package/lib/readers/phillipsEroll.js

@@ -54,6 +54,7 @@ import { inMetersPerMinute, mm, seconds, track } from "../model/Quantity.js";
  * The two rules collide on one number, the lowest note of the T-100
  * sharing 24 with the tenth position. Notes win there, the note block
  * being the larger claim; none of his samples uses the number at all.
+ * @category Sources
  */
 export const CONTROL_OFFSET = {
     'welte-t100': 14,
@@ -133,6 +134,7 @@ const controlOffsetOf = (system, given) => {
  * Reads one of his e-roll files as a copy of the roll, in millimetres
  * of paper, on the bar it was cut for and in that bar's numbering. A
  * position the bar does not read is left out, as the bar would leave it.
+ * @category Sources
  */
 export function readFromPhillipsEroll(buffer, { system = welteT100, controlOffset, placeAt, extension } = {}) {
     const file = read(new Uint8Array(buffer));
@@ -173,5 +175,8 @@ export function readFromPhillipsEroll(buffer, { system = welteT100, controlOffse
         shortenChains(extension, copy);
     return copy;
 }
-/** The bars his files are known to be numbered by. */
+/**
+ * The bars his files are known to be numbered by.
+ * @category Sources
+ */
 export const phillipsSystems = [welteT100, welteLicensee];

package/lib/readers/spencerBar.d.ts

@@ -6,8 +6,14 @@ import { TrackerBar } from "../systems/TrackerBar.js";
  * 640 Hz), and the tempo counts tenths of a foot per minute, which puts
  * 400 rows on an inch. This is the file's own calibration; whether the
  * scanner kept it is for an alignment with other copies to tell.
+ * @category Sources
  */
 export declare const SPENCER_ROWS_PER_INCH = 400;
+/**
+ * How `readFromSpencerBar` reads a file: the rows of its image on an
+ * inch of paper, and the bar it numbers its positions by.
+ * @category Sources
+ */
 export interface SpencerBarOptions {
     /** Rows of the image on an inch of paper. */
     rowsPerInch?: number;
@@ -21,13 +27,18 @@ export interface SpencerBarOptions {
  * Reads the copy on the bar it was cut for, whose numbering it keeps.
  * A chain on a position that bar does not read is left out, as the bar
  * would leave it.
+ * @category Sources
  */
 export declare function readFromSpencerBar(buffer: ArrayBuffer, { rowsPerInch, system }?: SpencerBarOptions): RollCopy;
 /**
  * The `.ann` file beside a `.bar` holds the player's settings for the
  * roll as lines of "/key:   value": title, composer, pianist, roll
  * number and class, and the tempo the roll is played at.
+ * @category Sources
  */
 export declare const readSpencerAnn: (text: string) => ReadonlyMap<string, string>;
-/** The paper speed a `.ann` states through its roll tempo, where it states one. */
+/**
+ * The paper speed a `.ann` states through its roll tempo, where it states one.
+ * @category Sources
+ */
 export declare const paperSpeedOfSpencerAnn: (ann: ReadonlyMap<string, string>) => PaperSpeed | undefined;

package/lib/readers/spencerBar.js

@@ -22,6 +22,7 @@ const END_OF_EVENTS = 0xFF;
  * 640 Hz), and the tempo counts tenths of a foot per minute, which puts
  * 400 rows on an inch. This is the file's own calibration; whether the
  * scanner kept it is for an alignment with other copies to tell.
+ * @category Sources
  */
 export const SPENCER_ROWS_PER_INCH = 400;
 const byteAt = (bytes, at) => {
@@ -82,6 +83,7 @@ const holesOf = (events) => {
  * Reads the copy on the bar it was cut for, whose numbering it keeps.
  * A chain on a position that bar does not read is left out, as the bar
  * would leave it.
+ * @category Sources
  */
 export function readFromSpencerBar(buffer, { rowsPerInch = SPENCER_ROWS_PER_INCH, system = welteLicensee } = {}) {
     const bytes = new Uint8Array(buffer);
@@ -121,6 +123,7 @@ export function readFromSpencerBar(buffer, { rowsPerInch = SPENCER_ROWS_PER_INCH
  * The `.ann` file beside a `.bar` holds the player's settings for the
  * roll as lines of "/key:   value": title, composer, pianist, roll
  * number and class, and the tempo the roll is played at.
+ * @category Sources
  */
 export const readSpencerAnn = (text) => new Map(text.split(/\r?\n/)
     .map(line => line.match(/^\/(\w+):\s*(.*?)\s*$/))
@@ -128,7 +131,10 @@ export const readSpencerAnn = (text) => new Map(text.split(/\r?\n/)
     .map(([, key, value]) => [key, value]));
 /** A roll tempo counts tenths of a foot per minute: tempo 83 runs the roll at 8.3 feet a minute. */
 const TEMPO_PER_FOOT_PER_MINUTE = 10;
-/** The paper speed a `.ann` states through its roll tempo, where it states one. */
+/**
+ * The paper speed a `.ann` states through its roll tempo, where it states one.
+ * @category Sources
+ */
 export const paperSpeedOfSpencerAnn = (ann) => {
     const tempo = parseFloat(ann.get('roll_tempo') ?? '');
     if (isNaN(tempo) || tempo <= 0)

package/lib/readers/stanfordAton.d.ts

@@ -1,6 +1,12 @@
 import { RollCopy } from "../model/RollCopy.js";
 import { TrackerBar } from "../systems/TrackerBar.js";
 import { Track } from "../model/Quantity.js";
+/**
+ * How `readFromStanfordAton` reads an analysis file: how its hole
+ * numbering is shifted onto the tracker bar, which bar the roll was cut
+ * for, and where its scan can be seen.
+ * @category Sources
+ */
 export interface StanfordAtonOptions {
     /**
      * Added to the scanning software's hole numbering to reach the
@@ -21,4 +27,13 @@ export interface StanfordAtonOptions {
      */
     scan?: string;
 }
+/**
+ * Reads a hole analysis of a scan, in the ATON format of Stanford's
+ * SUPRA collection, as a copy of the roll: its chains of holes in
+ * millimetres of paper on the bar it was cut for, its edge tears, its
+ * dimensions and hole separation as the analysis measured them, and how
+ * the scan relates to the bar. A position the bar does not read is left
+ * out, as the bar would leave it.
+ * @category Sources
+ */
 export declare function readFromStanfordAton(atonString: string, { trackShift, system, scan }?: StanfordAtonOptions): RollCopy;

package/lib/readers/stanfordAton.js

@@ -139,6 +139,15 @@ const measurementOf = (rollinfo) => {
 const takenBy = (measurement) => (value) => measurement
     ? { ...value, '@annotation': { id: v4(), belief: { type: 'belief', id: v4(), certainty: 'true', reasons: [measurement] } } }
     : value;
+/**
+ * Reads a hole analysis of a scan, in the ATON format of Stanford's
+ * SUPRA collection, as a copy of the roll: its chains of holes in
+ * millimetres of paper on the bar it was cut for, its edge tears, its
+ * dimensions and hole separation as the analysis measured them, and how
+ * the scan relates to the bar. A position the bar does not read is left
+ * out, as the bar would leave it.
+ * @category Sources
+ */
 export function readFromStanfordAton(atonString, { trackShift, system = welteT100, scan } = {}) {
     const parser = new AtonParser();
     const json = parser.parse(atonString);

package/lib/schema.json

@@ -490,6 +490,7 @@
             "ontology": "lrmoo:R76 is derivative of"
         },
         "DriveId": {
+            "description": "The IRI of a drive the type vocabulary declares.",
             "enum": [
                 "https://w3id.org/reo/type/drive/ram-head",
                 "https://w3id.org/reo/type/drive/asynchronous"
@@ -927,6 +928,14 @@
                     "description": "The person who carried out this activity.",
                     "ontology": "crm:P14 carried out by"
                 },
+                "applies": {
+                    "description": "The rules the inference draws its conclusion by, by IRI: a regularity of how the rolls were edited, such as that the same addition at the same place is not made twice independently, a default, such as that copies were not made from two exemplars, or a method, such as how the tolerance of a collation is found. The rules are stated once where they are published, and each inference names those it follows, so that a reader can see what a conclusion rests on besides its premises, and which conclusions rest on a rule.",
+                    "items": {
+                        "type": "string"
+                    },
+                    "type": "array",
+                    "ontology": "crminf:J3 applied"
+                },
                 "note": {
                     "description": "A free-text note providing additional context.",
                     "type": "string",
@@ -3396,6 +3405,7 @@
             "ontology": "crmdig:D14 Software"
         },
         "SourceKind": {
+            "description": "A kind of source a copy's features can be read from, from the paper itself to a sound recording of the copy being played.",
             "enum": [
                 "roll",
                 "scan",

package/lib/shared/utils.d.ts

@@ -1,4 +1,8 @@
 export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * An object that says by its type which kind of entity it is.
+ * @category Format types
+ */
 export type WithType<T extends string> = {
     /**
      * The type discriminator for this object.
@@ -6,6 +10,10 @@ export type WithType<T extends string> = {
      */
     readonly type: T;
 };
+/**
+ * An object the edition identifies, so that others can refer to it.
+ * @category Format types
+ */
 export type WithId = {
     /**
      * A unique identifier for this object.
@@ -16,6 +24,10 @@ export type WithId = {
 export declare const isDateString: (value: unknown) => value is string;
 /** The items by the key each of them gives, every group in the order its first item came in. */
 export declare const groupBy: <T>(items: readonly T[], keyOf: (item: T) => string) => Map<string, T[]>;
+/**
+ * An object that may carry a note in free text.
+ * @category Format types
+ */
 export type WithNote = {
     /**
      * A free-text note providing additional context.