linked-rolls 0.39.1 → 0.40.0

package/README.md

@@ -58,7 +58,7 @@ end of the end` on the `E52 Time-Span` the event has. `assignDate`,
 `notBefore` and `notAfter` build the three shapes, and `dateOf`,
 `earliestOf` and `latestOf` read them.
 
-Note that `before` and `after` mean something else on a perforation,
+Note that `before` and `after` mean something else on a command,
 where they order two onsets. The context defines them for a date
 within the date itself, so the two never meet.
 
@@ -223,25 +223,25 @@ repository.
 
 ### Alignment, order and pairing
 
-A perforation takes its place from the holes that carry it. Four fields
-on a perforation let an editor state where the measurement should give
-way. `alignedWith` names another perforation whose onset this one takes
+A command takes its place from the holes that carry it. Four fields
+on a command let an editor state where the measurement should give
+way. `alignedWith` names another command whose onset this one takes
 in the performance, as a "crescendo off" is meant to fall on the note
-it belongs to. `before` and `after` name a perforation whose onset this
+it belongs to. `before` and `after` name a command whose onset this
 one precedes or follows, without saying by how much: where the copies
 disagree on which side of a note an expression falls, the statement
-settles the order. A perforation the measurement already has on the
+settles the order. A command the measurement already has on the
 stated side keeps its place. One it does not is put on that side, as
 far from the reference as the copies that agree with the statement put
-it, and a punch diameter away where none does. A perforation makes one
+it, and a punch diameter away where none does. A command makes one
 of these three statements at most. `pairedWith` names a partner whose
 distance to this one is fixed, as a "forzando on" belongs with its
 "forzando off": whatever displaces the one displaces the other. Any two
-perforations may be paired, the relation is symmetric, and it is stated
+commands may be paired, the relation is symmetric, and it is stated
 on one side only. All are applied when a version is emulated.
 `constraintProblems` lists, version by version, the cases in which the
 statements cannot hold: a reference or partner that is absent, a
-perforation placed relative to itself or in several ways at once, one
+command placed relative to itself or in several ways at once, one
 claimed by several pairs, or a pair whose members are both placed.
 
 ## Building

package/lib/Emulation.d.ts

@@ -26,7 +26,7 @@ export declare class Emulation<Options extends object> {
     /**
      * Moves the negotiated events to where their statements put them.
      * The view supplies the copies, whose measurements decide how far
-     * before or after its reference a perforation goes, and a punch
+     * before or after its reference a command goes, and a punch
      * diameter, or a millimetre, where no copy agrees with a statement.
      */
     applyConstraints(view: EditionView): void;

package/lib/Emulation.js

@@ -1,6 +1,6 @@
 import { MIDIControlEvents } from "midifile-ts";
 import { idOf } from "./Assumption";
-import { isPerforation, pairsAmong, placementsOf } from "./Symbol";
+import { isCommand, pairsAmong, placementsOf } from "./Symbol";
 import { add, mean, mm, seconds, subtract } from "./Quantity";
 /** The punch diameter the edition's copies report, where any of them does. */
 const punchDiameterOf = (view) => {
@@ -137,7 +137,7 @@ export class Emulation {
     /**
      * Moves the negotiated events to where their statements put them.
      * The view supplies the copies, whose measurements decide how far
-     * before or after its reference a perforation goes, and a punch
+     * before or after its reference a command goes, and a punch
      * diameter, or a millimetre, where no copy agrees with a statement.
      */
     applyConstraints(view) {
@@ -154,7 +154,7 @@ export class Emulation {
         const inScope = (event) => !range || event.type !== 'note' || (event.horizontal.from > range[0] && event.horizontal.from < range[1]);
         this.negotiatedEvents =
             view.snapshot(version.id)
-                .filter(isPerforation)
+                .filter(isCommand)
                 .map(symbol => view.simplifySymbol(symbol, this.system.trackerBar))
                 .filter(event => event !== null)
                 .filter(inScope);
@@ -199,8 +199,8 @@ export class Emulation {
         });
         // both pedals start at rest
         events.push(controller(MIDIControlEvents.SUSTAIN, 0), controller(MIDIControlEvents.SOFT_PEDAL, 0));
-        // a pedal step is labelled with its perforation only where that
-        // perforation changes, so the file is not swamped with labels
+        // a pedal step is labelled with its command only where that
+        // command changes, so the file is not swamped with labels
         const lastCause = {};
         let currentTick = 0;
         for (const event of this.midiEvents) {

package/lib/ReproducingSystem.d.ts

@@ -49,8 +49,8 @@ export interface PerformedNoteOffEvent extends PerformedNoteEvent<'noteOff'> {
 }
 /**
  * One step of a pedal. A pedal driven by a bellows takes time to travel,
- * so a single perforation results in a run of these; `performs` is the
- * perforation whose reading the step follows from.
+ * so a single command results in a run of these; `performs` is the
+ * command whose reading the step follows from.
  */
 export interface PerformedPedalEvent extends PerformedRollFeature<'damper' | 'hammerRail'> {
     /** 0 with the pedal up and 127 with it fully down. */

package/lib/Symbol.d.ts

@@ -19,52 +19,52 @@ export interface Symbol<T extends string> extends WithId {
     carriers: ReferenceAssumption[];
 }
 export declare const isSymbol: (object: any) => object is AnySymbol;
-export declare const isPerforation: (symbol: object | undefined) => symbol is AnyPerforation;
+export declare const isCommand: (symbol: object | undefined) => symbol is AnyCommand;
 /**
- * A perforation is a symbol that is typically encoded as a single punched
- * hole or a group of punched holes in the physical carrier.
- * However, it might also have different physical appearences.
- * @see reo:Perforation
+ * A command is what the tracker bar reads from a perforation, or from a
+ * group of them: the note it sounds, or the function it operates. It is
+ * typically carried by a single punched hole or a chain of them, but it
+ * might also have different physical appearences.
+ * @see reo:Command
  */
-export interface Perforation<T extends string> extends Symbol<T> {
+export interface Command<T extends string> extends Symbol<T> {
     /**
-     * In piano rolls, perforations are often aligned with other
-     * perforations, e.g. a "crescendo off" might be logically
-     * aligned to the start of a note perforation. This points
-     * to the perforation by its `@id`.
+     * In piano rolls, commands are often aligned with other commands,
+     * e.g. a "crescendo off" might be logically aligned to the start of
+     * a note. This points to the command by its `@id`.
      * @see reo:alignedWith
      */
     alignedWith?: ReferenceAssumption;
     /**
-     * A perforation whose onset this one precedes when the roll is
+     * A command whose onset this one precedes when the roll is
      * performed, without saying by how much: a "crescendo off" ends
      * before the note it leads to begins, even where the copies
      * disagree on it. Where the measurement has it so, nothing moves;
      * where it does not, this one is placed before the reference as
-     * far as the copies that agree put it. This points to the
-     * perforation by its `@id`.
+     * far as the copies that agree put it. This points to the command
+     * by its `@id`.
      * @see reo:before
      */
     before?: ReferenceAssumption;
     /**
-     * A perforation whose onset this one follows when the roll is
+     * A command whose onset this one follows when the roll is
      * performed, the counterpart of `before`. This points to the
-     * perforation by its `@id`.
+     * command by its `@id`.
      * @see reo:after
      */
     after?: ReferenceAssumption;
     /**
-     * The perforation this one forms a pair with, e.g. a "forzando on"
-     * with its "forzando off". Any two perforations may be paired.
+     * The command this one forms a pair with, e.g. a "forzando on"
+     * with its "forzando off". Any two commands may be paired.
      * The distance between the two is fixed: whatever displaces the
      * one displaces the other. The relation is symmetric and is stated
-     * on one side only. This points to the perforation by its `@id`.
+     * on one side only. This points to the command by its `@id`.
      * @see reo:pairedWith
      */
     pairedWith?: ReferenceAssumption;
 }
 export declare const placementRelations: readonly ['alignedWith', 'before', 'after'];
-/** The ways a perforation may be placed relative to another. */
+/** The ways a command may be placed relative to another. */
 export type PlacementRelation = typeof placementRelations[number];
 type Placeable = Partial<Record<PlacementRelation, ReferenceAssumption>>;
 export type Placement = {
@@ -72,25 +72,25 @@ export type Placement = {
     reference: ReferenceAssumption;
 };
 /**
- * The statements placing a perforation relative to others, alignment
- * first. A perforation is meant to make one at most; the first is the
- * one a performance applies.
+ * The statements placing a command relative to others, alignment first.
+ * A command is meant to make one at most; the first is the one a
+ * performance applies.
  */
-export declare const placementsOf: (perforation: Placeable) => Placement[];
+export declare const placementsOf: (command: Placeable) => Placement[];
 type Pairable = WithId & {
     pairedWith?: ReferenceAssumption;
 };
 /**
- * The pairs among the given perforations, each once and in the order
- * the pairing is stated. A pair whose partner is absent is left out.
+ * The pairs among the given commands, each once and in the order the
+ * pairing is stated. A pair whose partner is absent is left out.
  */
-export declare const pairsAmong: <S extends Pairable>(perforations: readonly S[]) => [S, S][];
+export declare const pairsAmong: <S extends Pairable>(commands: readonly S[]) => [S, S][];
 /**
  * A note symbol, representing a single pitched musical event on the roll.
  * The pitch is encoded via the tracker bar position (track number).
  * @see reo:Note
  */
-export interface Note extends Perforation<'note'> {
+export interface Note extends Command<'note'> {
     /**
      * The MIDI pitch number of the note (e.g. 60 for middle C).
      * @see reo:pitch
@@ -98,29 +98,29 @@ export interface Note extends Perforation<'note'> {
     pitch: number;
 }
 /**
- * The scope of an expression perforation, indicating whether it
- * applies to the bass or treble register of the piano.
+ * The scope of an expression command, indicating whether it applies to
+ * the bass or treble register of the piano.
  * @see reo:scope
  */
 export type ExpressionScope = 'bass' | 'treble';
 /**
- * An expression symbol, representing a perforation on the roll
- * that governs dynamics, pedaling, or mechanical functions of the
- * reproducing piano. Each expression has a scope (bass or treble)
+ * An expression symbol, representing a command that governs dynamics,
+ * pedaling, or mechanical functions of the reproducing piano rather
+ * than sounding a note. Each expression has a scope (bass or treble)
  * and a specific expression type.
  * @see reo:Expression
  */
-export interface Expression extends Perforation<'expression'> {
+export interface Expression extends Command<'expression'> {
     /**
      * Whether this expression applies to the bass or treble register.
      * @see reo:scope
      */
     scope: ExpressionScope;
     /**
-     * The command the perforation gives, named as the reproducing
-     * system of the roll names it: "SustainPedalOn", "ForzandoOff"
-     * and so on for the Welte-Mignon T-100. The tracker bar of the
-     * system lists the values it reads.
+     * The kind of command, named as the reproducing system of the roll
+     * names it: "SustainPedalOn", "ForzandoOff" and so on for the
+     * Welte-Mignon T-100. The tracker bar of the system lists the
+     * values it reads.
      * @see crm:P2 has type
      */
     expressionType: string;
@@ -139,8 +139,8 @@ export interface Text extends Symbol<'text'> {
 }
 /**
  * A symbol can be either a note, an expression, or a text.
- * Notes and expressions are perforations; texts are carried by writings.
+ * Notes and expressions are commands; texts are carried by writings.
  */
 export type AnySymbol = Note | Expression | Text;
-export type AnyPerforation = Note | Expression;
+export type AnyCommand = Note | Expression;
 export {};

package/lib/Symbol.js

@@ -3,24 +3,24 @@ export const isSymbol = (object) => {
     return ('type' in object
         && (object.type === 'note' || object.type === 'expression' || object.type === 'text'));
 };
-export const isPerforation = (symbol) => symbol !== undefined && 'type' in symbol && (symbol.type === 'note' || symbol.type === 'expression');
+export const isCommand = (symbol) => symbol !== undefined && 'type' in symbol && (symbol.type === 'note' || symbol.type === 'expression');
 export const placementRelations = ['alignedWith', 'before', 'after'];
 /**
- * The statements placing a perforation relative to others, alignment
- * first. A perforation is meant to make one at most; the first is the
- * one a performance applies.
+ * The statements placing a command relative to others, alignment first.
+ * A command is meant to make one at most; the first is the one a
+ * performance applies.
  */
-export const placementsOf = (perforation) => placementRelations.flatMap(relation => {
-    const reference = perforation[relation];
+export const placementsOf = (command) => placementRelations.flatMap(relation => {
+    const reference = command[relation];
     return reference ? [{ relation, reference }] : [];
 });
 /**
- * The pairs among the given perforations, each once and in the order
- * the pairing is stated. A pair whose partner is absent is left out.
+ * The pairs among the given commands, each once and in the order the
+ * pairing is stated. A pair whose partner is absent is left out.
  */
-export const pairsAmong = (perforations) => {
-    const byId = new Map(perforations.map(p => [p.id, p]));
-    return perforations
+export const pairsAmong = (commands) => {
+    const byId = new Map(commands.map(p => [p.id, p]));
+    return commands
         .filter((p) => p.pairedWith !== undefined)
         .map((p) => [p, byId.get(idOf(p.pairedWith))])
         .filter((pair) => pair[1] !== undefined);

package/lib/constraints.d.ts

@@ -6,7 +6,7 @@ export type ConstraintProblem = {
 };
 /**
  * Where the edition cannot hold as stated, version by version: a
- * placement or pairing reference absent from the version, a perforation
+ * placement or pairing reference absent from the version, a command
  * placed relative to itself or in several ways at once, one claimed by
  * several pairs, a pair whose members are both placed and so cannot
  * keep their distance and follow their references at once, an

package/lib/constraints.js

@@ -1,5 +1,5 @@
 import { idOf } from "./Assumption";
-import { isPerforation, pairsAmong, placementsOf } from "./Symbol";
+import { isCommand, pairsAmong, placementsOf } from "./Symbol";
 import { keyOf } from "./TrackerBar";
 import { trackerBarOf } from "./systems";
 import { barOf } from "./RollCopy";
@@ -8,30 +8,30 @@ const missingReference = {
     before: 'before-reference-missing',
     after: 'after-reference-missing'
 };
-const problemsIn = (version, perforations) => {
-    const ids = new Set(perforations.map(p => p.id));
+const problemsIn = (version, commands) => {
+    const ids = new Set(commands.map(p => p.id));
     const report = (symbol, problem) => ({ version, symbol, problem });
-    const missingReferences = perforations
+    const missingReferences = commands
         .flatMap(p => placementsOf(p)
         .filter(({ reference }) => !ids.has(idOf(reference)))
         .map(({ relation }) => report(p.id, missingReference[relation])));
-    const selfPlaced = perforations
+    const selfPlaced = commands
         .filter(p => placementsOf(p).some(({ reference }) => idOf(reference) === p.id))
         .map(p => report(p.id, 'placed-relative-to-itself'));
-    const placedSeveralWays = perforations
+    const placedSeveralWays = commands
         .filter(p => placementsOf(p).length > 1)
         .map(p => report(p.id, 'placed-several-ways'));
-    const missingPartners = perforations
+    const missingPartners = commands
         .filter(p => p.pairedWith && !ids.has(idOf(p.pairedWith)))
         .map(p => report(p.id, 'partner-missing'));
-    const selfPaired = perforations
+    const selfPaired = commands
         .filter(p => p.pairedWith && idOf(p.pairedWith) === p.id)
         .map(p => report(p.id, 'paired-with-itself'));
-    const pairs = pairsAmong(perforations);
+    const pairs = pairsAmong(commands);
     const pairsPerId = pairs
         .flatMap(([one, other]) => one === other ? [one] : [one, other])
         .reduce((counts, p) => counts.set(p.id, (counts.get(p.id) ?? 0) + 1), new Map());
-    const inSeveralPairs = perforations
+    const inSeveralPairs = commands
         .filter(p => (pairsPerId.get(p.id) ?? 0) > 1)
         .map(p => report(p.id, 'in-several-pairs'));
     const placedOnBothSides = pairs
@@ -74,7 +74,7 @@ const typesNotOnTheBar = (version, snapshot) => {
  * out says 59. Collation across systems consults only the place, so
  * without this nothing checks the tracks at all.
  */
-const carriersOffTheirMeaning = (view, version, perforations) => {
+const carriersOffTheirMeaning = (view, version, commands) => {
     const misread = (carrier, symbol) => {
         const copy = view.copyOf(carrier.id);
         if (!copy)
@@ -84,7 +84,7 @@ const carriersOffTheirMeaning = (view, version, perforations) => {
         return !barOf(copy).meaningsOf(carrier.vertical)
             .some(meaning => keyOf(meaning) === keyOf(symbol));
     };
-    return perforations
+    return commands
         .filter(symbol => view.carriersOf(symbol).some(carrier => misread(carrier, symbol)))
         .map(symbol => ({ version, symbol: symbol.id, problem: 'carrier-on-another-track' }));
 };
@@ -102,7 +102,7 @@ const paperDisagreed = (view, version) => view.speedScalesIn(version).length > 1
     : [];
 /**
  * Where the edition cannot hold as stated, version by version: a
- * placement or pairing reference absent from the version, a perforation
+ * placement or pairing reference absent from the version, a command
  * placed relative to itself or in several ways at once, one claimed by
  * several pairs, a pair whose members are both placed and so cannot
  * keep their distance and follow their references at once, an
@@ -111,11 +111,11 @@ const paperDisagreed = (view, version) => view.speedScalesIn(version).length > 1
  */
 export const constraintProblems = (view) => view.edition.versions.flatMap(version => {
     const snapshot = view.snapshot(version.id);
-    const perforations = snapshot.filter(isPerforation);
+    const commands = snapshot.filter(isCommand);
     return [
-        ...problemsIn(version.id, perforations),
+        ...problemsIn(version.id, commands),
         ...typesNotOnTheBar(version, snapshot),
-        ...carriersOffTheirMeaning(view, version.id, perforations),
+        ...carriersOffTheirMeaning(view, version.id, commands),
         ...paperDisagreed(view, version)
     ];
 });

package/lib/editionOps.d.ts

@@ -199,11 +199,11 @@ export declare const mergeEdits: (view: EditionView, versionId: string, toMerge:
 /** Replaces the edit with one edit per inserted and one per deleted symbol. */
 export declare const splitEdit: (versionId: string, toSplit: Edit) => EditionOp;
 /** States how the follower is placed relative to the reference, in place of any earlier statement. */
-export declare const placePerforation: (view: EditionView, followerId: string, referenceId: string, relation: PlacementRelation) => EditionOp;
-export declare const unplacePerforation: (view: EditionView, followerId: string) => EditionOp;
+export declare const placeCommand: (view: EditionView, followerId: string, referenceId: string, relation: PlacementRelation) => EditionOp;
+export declare const unplaceCommand: (view: EditionView, followerId: string) => EditionOp;
 /** The pair is stated on `statingId` only, as the format asks. */
-export declare const pairPerforations: (view: EditionView, statingId: string, partnerId: string) => EditionOp;
-export declare const unpairPerforation: (view: EditionView, statingId: string) => EditionOp;
+export declare const pairCommands: (view: EditionView, statingId: string, partnerId: string) => EditionOp;
+export declare const unpairCommand: (view: EditionView, statingId: string) => EditionOp;
 /** Annotates the assumption at the path with a belief held true, for reasons to be added. */
 export declare const createBelief: (path: Path) => EditionOp;
 export declare const clearBelief: (path: Path) => EditionOp;

package/lib/editionOps.js

@@ -1,7 +1,7 @@
 import { current, isDraft } from "immer";
 import { v4 } from "uuid";
 import { getAt } from "./EditionView";
-import { isPerforation, placementRelations } from "./Symbol";
+import { isCommand, placementRelations } from "./Symbol";
 import { collationsOf, defaultCollationTolerance } from "./Collation";
 import { collationToleranceOf, editsOf, insertedBy, principalDerivationOf } from "./Version";
 import { asSymbols, barOf, featuresByAct, featuresOf, isPaperStretch, statesNothing } from "./RollCopy";
@@ -216,15 +216,15 @@ export const symbolsCarriedOnlyBy = (edition, copyId) => {
     return copy ? insertedIn(edition.versions).filter(carriedOnlyOn(featureIdsOf(copy))) : [];
 };
 const references = [...placementRelations, 'pairedWith'];
-/** The perforation without its references to the dropped symbols, or the very same one where it makes none. */
-const forgettingReferences = (perforation, dropped) => {
+/** The command without its references to the dropped symbols, or the very same one where it makes none. */
+const forgettingReferences = (command, dropped) => {
     const stale = references.filter(relation => {
-        const reference = perforation[relation];
+        const reference = command[relation];
         return reference !== undefined && dropped.has(idOf(reference));
     });
     if (stale.length === 0)
-        return perforation;
-    const kept = { ...perforation };
+        return command;
+    const kept = { ...command };
     stale.forEach(relation => { delete kept[relation]; });
     return kept;
 };
@@ -232,7 +232,7 @@ const forgettingReferences = (perforation, dropped) => {
 const forgettingCarriers = (features, dropped) => (symbol) => {
     const carriers = without(symbol.carriers, carrier => features.has(idOf(carrier)));
     const relieved = carriers === symbol.carriers ? symbol : { ...symbol, carriers };
-    return isPerforation(relieved) ? forgettingReferences(relieved, dropped) : relieved;
+    return isCommand(relieved) ? forgettingReferences(relieved, dropped) : relieved;
 };
 /** The edit without the dropped symbols and the features, or the very same edit where it had none of them. */
 const forgettingFeatures = (features, dropped) => {
@@ -667,7 +667,7 @@ export const connectVersions = (view, childId, parentId, tolerance = defaultColl
     const collated = new Set(collations.map(({ symbol }) => symbol.id));
     const matched = new Set(collations.map(({ counterpart }) => counterpart.id));
     /**
-     * Where the child is coded for another system, a held perforation of
+     * Where the child is coded for another system, a held command of
      * its own often stands for a latched pair of the parent's. Saying so
      * as one edit is the transfer being carried out, and leaving the two
      * apart would make the apparatus a list of unexplained losses beside
@@ -872,29 +872,29 @@ export const splitEdit = (versionId, toSplit) => {
     });
 };
 /**
- * Runs the change on the perforation the view locates by id, in whichever
+ * Runs the change on the command the view locates by id, in whichever
  * version inserted it. A statement made there holds in every version
- * that carries the perforation.
+ * that carries the command.
  */
-const onPerforation = (view, id, op) => draft => {
+const onCommand = (view, id, op) => draft => {
     const path = view.getPath(id);
     const symbol = path && getAt(path, draft);
-    if (isPerforation(symbol))
+    if (isCommand(symbol))
         op(symbol);
 };
-const clearPlacement = (perforation) => placementRelations.forEach(relation => { delete perforation[relation]; });
+const clearPlacement = (command) => placementRelations.forEach(relation => { delete command[relation]; });
 /** States how the follower is placed relative to the reference, in place of any earlier statement. */
-export const placePerforation = (view, followerId, referenceId, relation) => onPerforation(view, followerId, perforation => {
-    clearPlacement(perforation);
-    perforation[relation] = assignReference(referenceId);
+export const placeCommand = (view, followerId, referenceId, relation) => onCommand(view, followerId, command => {
+    clearPlacement(command);
+    command[relation] = assignReference(referenceId);
 });
-export const unplacePerforation = (view, followerId) => onPerforation(view, followerId, clearPlacement);
+export const unplaceCommand = (view, followerId) => onCommand(view, followerId, clearPlacement);
 /** The pair is stated on `statingId` only, as the format asks. */
-export const pairPerforations = (view, statingId, partnerId) => onPerforation(view, statingId, perforation => {
-    perforation.pairedWith = assignReference(partnerId);
+export const pairCommands = (view, statingId, partnerId) => onCommand(view, statingId, command => {
+    command.pairedWith = assignReference(partnerId);
 });
-export const unpairPerforation = (view, statingId) => onPerforation(view, statingId, perforation => {
-    delete perforation.pairedWith;
+export const unpairCommand = (view, statingId) => onCommand(view, statingId, command => {
+    delete command.pairedWith;
 });
 const onAssumptionAt = (path, op) => draft => {
     const assumption = getAt(path, draft);

package/lib/notes.js

@@ -4,7 +4,7 @@
  * `{{<id>}}`, where the id is the entity's, and is resolved when the note
  * is shown.
  *
- * An entity the edition gives no name to, a perforation or an edit, needs
+ * An entity the edition gives no name to, a command or an edit, needs
  * the note's own words to stand in the sentence: `{{<id>|die Stanzung bei
  * 7364,7 mm}}`. The name wins where the edition has one, so a siglum
  * still follows the stemma and a written-out label cannot freeze it.

package/lib/schema.json

@@ -101,7 +101,7 @@
                     "$ref": "#/definitions/Text"
                 }
             ],
-            "description": "A symbol can be either a note, an expression, or a text. Notes and expressions are perforations; texts are carried by writings."
+            "description": "A symbol can be either a note, an expression, or a text. Notes and expressions are commands; texts are carried by writings."
         },
         "Argumentation": {
             "description": "An argumentation provides reasons for a belief and may be associated with a person carrying out that argumentation.",
@@ -622,21 +622,21 @@
             "type": "string"
         },
         "Expression": {
-            "description": "An expression symbol, representing a perforation on the roll that governs dynamics, pedaling, or mechanical functions of the reproducing piano. Each expression has a scope (bass or treble) and a specific expression type.",
+            "description": "An expression symbol, representing a command that governs dynamics, pedaling, or mechanical functions of the reproducing piano rather than sounding a note. Each expression has a scope (bass or treble) and a specific expression type.",
             "properties": {
                 "after": {
                     "$ref": "#/definitions/ReferenceAssumption",
-                    "description": "A perforation whose onset this one follows when the roll is performed, the counterpart of `before`. This points to the perforation by its `@id`.",
+                    "description": "A command whose onset this one follows when the roll is performed, the counterpart of `before`. This points to the command by its `@id`.",
                     "ontology": "reo:after"
                 },
                 "alignedWith": {
                     "$ref": "#/definitions/ReferenceAssumption",
-                    "description": "In piano rolls, perforations are often aligned with other perforations, e.g. a \"crescendo off\" might be logically aligned to the start of a note perforation. This points to the perforation by its `@id`.",
+                    "description": "In piano rolls, commands are often aligned with other commands, e.g. a \"crescendo off\" might be logically aligned to the start of a note. This points to the command by its `@id`.",
                     "ontology": "reo:alignedWith"
                 },
                 "before": {
                     "$ref": "#/definitions/ReferenceAssumption",
-                    "description": "A perforation whose onset this one precedes when the roll is performed, without saying by how much: a \"crescendo off\" ends before the note it leads to begins, even where the copies disagree on it. Where the measurement has it so, nothing moves; where it does not, this one is placed before the reference as far as the copies that agree put it. This points to the perforation by its `@id`.",
+                    "description": "A command whose onset this one precedes when the roll is performed, without saying by how much: a \"crescendo off\" ends before the note it leads to begins, even where the copies disagree on it. Where the measurement has it so, nothing moves; where it does not, this one is placed before the reference as far as the copies that agree put it. This points to the command by its `@id`.",
                     "ontology": "reo:before"
                 },
                 "carriers": {
@@ -648,13 +648,13 @@
                     "ontology": "crm:P128i is carried by"
                 },
                 "expressionType": {
-                    "description": "The command the perforation gives, named as the reproducing system of the roll names it: \"SustainPedalOn\", \"ForzandoOff\" and so on for the Welte-Mignon T-100. The tracker bar of the system lists the values it reads.",
+                    "description": "The kind of command, named as the reproducing system of the roll names it: \"SustainPedalOn\", \"ForzandoOff\" and so on for the Welte-Mignon T-100. The tracker bar of the system lists the values it reads.",
                     "type": "string",
                     "ontology": "crm:P2 has type"
                 },
                 "pairedWith": {
                     "$ref": "#/definitions/ReferenceAssumption",
-                    "description": "The perforation this one forms a pair with, e.g. a \"forzando on\" with its \"forzando off\". Any two perforations may be paired. The distance between the two is fixed: whatever displaces the one displaces the other. The relation is symmetric and is stated on one side only. This points to the perforation by its `@id`.",
+                    "description": "The command this one forms a pair with, e.g. a \"forzando on\" with its \"forzando off\". Any two commands may be paired. The distance between the two is fixed: whatever displaces the one displaces the other. The relation is symmetric and is stated on one side only. This points to the command by its `@id`.",
                     "ontology": "reo:pairedWith"
                 },
                 "scope": {
@@ -684,7 +684,7 @@
             "ontology": "reo:Expression"
         },
         "ExpressionScope": {
-            "description": "The scope of an expression perforation, indicating whether it applies to the bass or treble register of the piano.",
+            "description": "The scope of an expression command, indicating whether it applies to the bass or treble register of the piano.",
             "enum": [
                 "bass",
                 "treble"
@@ -1646,17 +1646,17 @@
             "properties": {
                 "after": {
                     "$ref": "#/definitions/ReferenceAssumption",
-                    "description": "A perforation whose onset this one follows when the roll is performed, the counterpart of `before`. This points to the perforation by its `@id`.",
+                    "description": "A command whose onset this one follows when the roll is performed, the counterpart of `before`. This points to the command by its `@id`.",
                     "ontology": "reo:after"
                 },
                 "alignedWith": {
                     "$ref": "#/definitions/ReferenceAssumption",
-                    "description": "In piano rolls, perforations are often aligned with other perforations, e.g. a \"crescendo off\" might be logically aligned to the start of a note perforation. This points to the perforation by its `@id`.",
+                    "description": "In piano rolls, commands are often aligned with other commands, e.g. a \"crescendo off\" might be logically aligned to the start of a note. This points to the command by its `@id`.",
                     "ontology": "reo:alignedWith"
                 },
                 "before": {
                     "$ref": "#/definitions/ReferenceAssumption",
-                    "description": "A perforation whose onset this one precedes when the roll is performed, without saying by how much: a \"crescendo off\" ends before the note it leads to begins, even where the copies disagree on it. Where the measurement has it so, nothing moves; where it does not, this one is placed before the reference as far as the copies that agree put it. This points to the perforation by its `@id`.",
+                    "description": "A command whose onset this one precedes when the roll is performed, without saying by how much: a \"crescendo off\" ends before the note it leads to begins, even where the copies disagree on it. Where the measurement has it so, nothing moves; where it does not, this one is placed before the reference as far as the copies that agree put it. This points to the command by its `@id`.",
                     "ontology": "reo:before"
                 },
                 "carriers": {
@@ -1669,7 +1669,7 @@
                 },
                 "pairedWith": {
                     "$ref": "#/definitions/ReferenceAssumption",
-                    "description": "The perforation this one forms a pair with, e.g. a \"forzando on\" with its \"forzando off\". Any two perforations may be paired. The distance between the two is fixed: whatever displaces the one displaces the other. The relation is symmetric and is stated on one side only. This points to the perforation by its `@id`.",
+                    "description": "The command this one forms a pair with, e.g. a \"forzando on\" with its \"forzando off\". Any two commands may be paired. The distance between the two is fixed: whatever displaces the one displaces the other. The relation is symmetric and is stated on one side only. This points to the command by its `@id`.",
                     "ontology": "reo:pairedWith"
                 },
                 "pitch": {

package/lib/substitution.d.ts

@@ -3,40 +3,40 @@ import { AnySymbol, Expression } from "./Symbol";
 import { Millimeters, Track } from "./Quantity";
 import { TrackerBar } from "./TrackerBar";
 /**
- * How a scale spells a command: as a perforation that turns a function
- * on, one that cancels it, or one that holds it for as long as it lasts.
+ * How a scale words a function: as a command that turns it on, one that
+ * cancels it, or one that holds it for as long as it lasts.
  */
 export type Spelling = 'on' | 'off' | 'held';
 /**
- * A command as what it operates rather than as the word a scale uses
- * for it, so that two scales can be compared at all.
+ * What a word of a scale operates, rather than the word itself, so that
+ * two scales can be compared at all.
  */
-export interface Command {
+export interface Operation {
     /** The function operated, named the same wherever a scale has it. */
     operates: string;
     spelling: Spelling;
     /**
      * Whether the half of the keyboard the valve serves is part of the
-     * command. The dynamics are per half; the pedals are not, and the
-     * two Welte scales put them on opposite edges of the paper, so a
-     * rule that compared sides would leave every pedal unpaired.
+     * function operated. The dynamics are per half; the pedals are not,
+     * and the two Welte scales put them on opposite edges of the paper,
+     * so a rule that compared sides would leave every pedal unpaired.
      */
     sided: boolean;
 }
-/** What a command operates, or nothing for a word no scale here knows. */
-export declare const commandOf: (expressionType: string) => Command | undefined;
+/** What an expression type operates, or nothing for a word no scale here knows. */
+export declare const operationOf: (expressionType: string) => Operation | undefined;
 /**
- * A latched function of the older version and the held perforation of
- * the newer one that stands for it.
+ * A latched function of the older version and the held command of the
+ * newer one that stands for it.
  */
 export interface Substitution {
-    /** The perforation that turned the function on, and the one that cancelled it. */
+    /** The command that turned the function on, and the one that cancelled it. */
     replaced: readonly [Expression, Expression];
     /**
-     * The perforations that say the same thing in the other scale's
-     * words. Usually one, but a held command is punched as a chain of
-     * round holes with paper bridges rather than as a slot, and a scan
-     * whose analysis reports those singly gives one symbol per punch.
+     * The commands that say the same thing in the other scale's words.
+     * Usually one, but a held command is punched as a chain of round
+     * holes with paper bridges rather than as a slot, and a scan whose
+     * analysis reports those singly gives one symbol per punch.
      */
     by: readonly Expression[];
 }
@@ -51,23 +51,23 @@ export declare const defaultChainGap: import("./Quantity").Quantity<"mm">;
  * The position a bar reads its own command for the same function on,
  * where it has no word for this one.
  *
- * A version keeps the perforations it does away with in its deletions,
- * and those may be a scale the version is not coded for: a green
- * version deletes the red `SlowCrescendoOn` it inherits. That has no
- * position on the green bar, so drawing it as a perforation is out of
- * the question, but an edit still has to be shown somewhere, and the
- * lane the green scale gives the same function is where it belongs.
+ * A version keeps the commands it does away with in its deletions, and
+ * those may be a scale the version is not coded for: a green version
+ * deletes the red `SlowCrescendoOn` it inherits. That has no position on
+ * the green bar, so drawing it as a perforation is out of the question,
+ * but an edit still has to be shown somewhere, and the lane the green
+ * scale gives the same function is where it belongs.
  */
 export declare const positionOfSameFunction: (bar: TrackerBar, symbol: Expression) => Track | undefined;
 /**
- * Where a held perforation of the newer version stands for a latched
+ * Where a held command of the newer version stands for a latched
  * function of the older one: the same function, on the same side where
  * the side counts, spanning the same stretch of the roll.
  *
- * Only unambiguous correspondences are reported. Where two held
- * perforations answer one latched interval, or one answers two, none of
- * them is reported and the editor is left to say what happened. Nothing
- * is invented either: both sides are perforations somebody punched, and
- * all this asserts is which stands for which.
+ * Only unambiguous correspondences are reported. Where two held commands
+ * answer one latched interval, or one answers two, none of them is
+ * reported and the editor is left to say what happened. Nothing is
+ * invented either: both sides are perforations somebody punched, and all
+ * this asserts is which stands for which.
  */
 export declare const substitutionsBetween: (own: readonly AnySymbol[], inherited: readonly AnySymbol[], locate: Locate, tolerance?: CollationTolerance, chainGap?: Millimeters) => Substitution[];

package/lib/substitution.js

@@ -1,7 +1,7 @@
 import { defaultCollationTolerance } from "./Collation";
 import { distance, mm, track } from "./Quantity";
 /**
- * What each Welte command operates.
+ * What each Welte expression type operates.
  *
  * This cannot be read off the names. The T-100 latches a function on
  * with one perforation and cancels it with a second, while the T-98
@@ -10,8 +10,8 @@ import { distance, mm, track } from "./Quantity";
  * between the scales: the red `SlowCrescendo` is the green `Crescendo`,
  * and the red's single `Forzando` valve answers to two green ones that
  * name the end they pull towards. So the correspondence is stated here
- * rather than derived, and only two commands that operate one function
- * can stand for each other.
+ * rather than derived, and only two types that operate one function can
+ * stand for each other.
  *
  * The T-100's `MotorOn`/`MotorOff`, `Rewind` and `ElectricCutOff` are
  * left out on purpose: the green scale has no word for any of them, its
@@ -19,7 +19,7 @@ import { distance, mm, track } from "./Quantity";
  * and its rewind riding on the bass sforzando-piano line. A red command
  * of those kinds has no counterpart and stays a plain deletion.
  */
-const commands = {
+const operations = {
     MezzoforteOn: { operates: 'mezzoforte', spelling: 'on', sided: true },
     MezzoforteOff: { operates: 'mezzoforte', spelling: 'off', sided: true },
     SlowCrescendoOn: { operates: 'crescendo', spelling: 'on', sided: true },
@@ -37,8 +37,8 @@ const commands = {
     SustainPedal: { operates: 'sustainPedal', spelling: 'held', sided: false },
     SoftPedal: { operates: 'softPedal', spelling: 'held', sided: false }
 };
-/** What a command operates, or nothing for a word no scale here knows. */
-export const commandOf = (expressionType) => commands[expressionType];
+/** What an expression type operates, or nothing for a word no scale here knows. */
+export const operationOf = (expressionType) => operations[expressionType];
 /**
  * How wide a paper bridge may be for two held perforations to be one
  * command. The T-98 punches a hold as a chain of round holes on a
@@ -48,20 +48,20 @@ export const commandOf = (expressionType) => commands[expressionType];
 export const defaultChainGap = mm(3);
 const isExpression = (symbol) => symbol.type === 'expression';
 /** The key a command is matched on: the function, and the side where the side counts. */
-const functionKey = (symbol, command) => command.sided ? `${command.operates} ${symbol.scope}` : command.operates;
+const functionKey = (symbol, operation) => operation.sided ? `${operation.operates} ${symbol.scope}` : operation.operates;
 /**
  * The position a bar reads its own command for the same function on,
  * where it has no word for this one.
  *
- * A version keeps the perforations it does away with in its deletions,
- * and those may be a scale the version is not coded for: a green
- * version deletes the red `SlowCrescendoOn` it inherits. That has no
- * position on the green bar, so drawing it as a perforation is out of
- * the question, but an edit still has to be shown somewhere, and the
- * lane the green scale gives the same function is where it belongs.
+ * A version keeps the commands it does away with in its deletions, and
+ * those may be a scale the version is not coded for: a green version
+ * deletes the red `SlowCrescendoOn` it inherits. That has no position on
+ * the green bar, so drawing it as a perforation is out of the question,
+ * but an edit still has to be shown somewhere, and the lane the green
+ * scale gives the same function is where it belongs.
  */
 export const positionOfSameFunction = (bar, symbol) => {
-    const wanted = commandOf(symbol.expressionType);
+    const wanted = operationOf(symbol.expressionType);
     if (!wanted)
         return undefined;
     const positions = Array.from({ length: bar.trackCount }, (_, index) => track(index + 1));
@@ -69,26 +69,26 @@ export const positionOfSameFunction = (bar, symbol) => {
         const meaning = bar.meaningOf(position);
         if (meaning?.type !== 'expression')
             return false;
-        const command = commandOf(meaning.expressionType);
-        return command !== undefined
-            && command.operates === wanted.operates
-            && functionKey(meaning, command) === functionKey(symbol, wanted);
+        const operation = operationOf(meaning.expressionType);
+        return operation !== undefined
+            && operation.operates === wanted.operates
+            && functionKey(meaning, operation) === functionKey(symbol, wanted);
     });
 };
 /**
- * The intervals the older version latches: each perforation that turns
- * a function on, with the one that cancels it next on the same line.
+ * The intervals the older version latches: each command that turns a
+ * function on, with the one that cancels it next on the same line.
  */
 const latchedIn = (symbols, locate) => {
     const byFunction = new Map();
     symbols.filter(isExpression).forEach(symbol => {
-        const command = commandOf(symbol.expressionType);
+        const operation = operationOf(symbol.expressionType);
         const at = locate(symbol)?.from;
-        if (!command || command.spelling === 'held' || at === undefined)
+        if (!operation || operation.spelling === 'held' || at === undefined)
             return;
-        const key = functionKey(symbol, command);
+        const key = functionKey(symbol, operation);
         const group = byFunction.get(key) ?? [];
-        group.push({ symbol, at, spelling: command.spelling });
+        group.push({ symbol, at, spelling: operation.spelling });
         byFunction.set(key, group);
     });
     return [...byFunction.values()].flatMap(group => {
@@ -109,7 +109,7 @@ const latchedIn = (symbols, locate) => {
                             off: entry.symbol,
                             from: state.open.from,
                             to: entry.at,
-                            key: functionKey(state.open.on, commandOf(state.open.on.expressionType))
+                            key: functionKey(state.open.on, operationOf(state.open.on.expressionType))
                         }]
                 }
                 : state;
@@ -117,17 +117,17 @@ const latchedIn = (symbols, locate) => {
     });
 };
 /**
- * The commands the newer version holds, a chain of punches counting as
+ * The functions the newer version holds, a chain of punches counting as
  * the one command the paper shows rather than as a run of them.
  */
 const heldRunsIn = (symbols, locate, chainGap) => {
     const byFunction = new Map();
     symbols.filter(isExpression).forEach(symbol => {
-        const command = commandOf(symbol.expressionType);
+        const operation = operationOf(symbol.expressionType);
         const place = locate(symbol);
-        if (!command || command.spelling !== 'held' || !place)
+        if (!operation || operation.spelling !== 'held' || !place)
             return;
-        const key = functionKey(symbol, command);
+        const key = functionKey(symbol, operation);
         const group = byFunction.get(key) ?? [];
         group.push({ symbol, from: place.from, to: place.to });
         byFunction.set(key, group);
@@ -147,15 +147,15 @@ const heldRunsIn = (symbols, locate, chainGap) => {
 /** The only item of the list, or nothing where there is none or a rival. */
 const theOnly = (items) => items.length === 1 ? items[0] : undefined;
 /**
- * Where a held perforation of the newer version stands for a latched
+ * Where a held command of the newer version stands for a latched
  * function of the older one: the same function, on the same side where
  * the side counts, spanning the same stretch of the roll.
  *
- * Only unambiguous correspondences are reported. Where two held
- * perforations answer one latched interval, or one answers two, none of
- * them is reported and the editor is left to say what happened. Nothing
- * is invented either: both sides are perforations somebody punched, and
- * all this asserts is which stands for which.
+ * Only unambiguous correspondences are reported. Where two held commands
+ * answer one latched interval, or one answers two, none of them is
+ * reported and the editor is left to say what happened. Nothing is
+ * invented either: both sides are perforations somebody punched, and all
+ * this asserts is which stands for which.
  */
 export const substitutionsBetween = (own, inherited, locate, tolerance = defaultCollationTolerance, chainGap = defaultChainGap) => {
     const latched = latchedIn(inherited, locate);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.39.1",
+  "version": "0.40.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {