Referenzen

Wie ein Block das Ergebnis eines anderen nennt

TippIn einem Satz

Ein Verweis nennt ein Artefakt über Projekt, Notebook, Block und Artefaktnamen, wahlweise mit einer Version; der Runner löst ihn vor dem Lauf auf und hält im Manifest fest, welche Version gelesen wurde.

1 Die volle Form

fam:<projekt>/<notebook>/<block>.<artefakt>[@<version>]

fam:karman-nachlass/korrespondenz/karman-roster.roster nennt das Artefakt roster des Blocks karman-roster im Notebook korrespondenz des Projekts karman-nachlass. roster ist der name aus der Liste artefacts des Blocks, nicht der Dateiname.

Wähler	liest
ohne, oder @latest	die aktuelle Version
@v3	genau Version 3
@sha:3e891ae0	die Version, deren Prüfsumme so beginnt
@locked	die Version, die famulus.lock für diesen Verweis verzeichnet

@latest folgt dem Erzeuger: erzeugt er eine neue Version, wird der lesende Block veraltet. @v3, @sha: und @locked bleiben stehen.

2 Kurzformen

Form	gilt für
<block>.<artefakt>	einen Block im selben Notebook
<notebook>/<block>.<artefakt>	ein anderes Notebook desselben Projekts
<kurzname>/<block>.<artefakt>	ein Notebook, das uses im Notebook oder imports in famulus.yml benennt
<block> (in depends_on)	einen Block ohne Artefakt: nur die Reihenfolge

famulus:
  id: vergleich
  uses:
    lex: fam:kepler-lex-naturae/lex-naturae@v1

Danach liest lex/lex-natura.kwic Version 1 des KWIC aus dem Kepler-Projekt. Trägt der Verweis selbst einen Wähler, gilt dieser; sonst gilt der des Kurznamens.

3 Wo ein Verweis stehen darf

In der Präambel als Wert:

input:
  roster:
    ref: briefpartner-roster.roster
depends_on: [briefpartner-zahl]

In der Instruktion als Platzhalter {{ref:briefpartner-roster.roster}}; der Runner ersetzt ihn vor ExecutionHarness.run durch den absoluten Pfad der Datei.

Im Fließtext als Shortcode:

{{< famulus briefpartner-roster roster >}}
{{< famulus fam:karman-nachlass/korrespondenz/karman-roster.roster >}}

Die gerenderte Form hängt am kind:

kind	Einbindung
roster-table, table, kwic, citation-list	Tabelle
markdown	der Markdown-Inhalt
andere	Art, Verweis, Version und ein Link auf die Datei

Fehlt der Lauf, nennt die Seite das, statt eine leere Tabelle zu zeigen. Ist der Verweis nicht auflösbar, steht der Grund auf der Seite.

4 Ferne Verweise

peer:<rechner>/fam:<projekt>/<notebook>/<block>.<artefakt> holt das Artefakt von einem Peer. Die ältere Form peer:<rechner>/<notebook>/<block>.<artefakt> gilt weiter. Die Kopie liegt unter _famulus/cache/extern/<rechner>/…, daneben <artefakt>.source.json mit Verweis, Adresse und Zeitpunkt; so bleibt nachweisbar, welche Fassung ein Lauf benutzt hat. Einzelheiten stehen unter Verknüpfung.

Ein Item einer Collection nennt ein Text nicht mit fam:, sondern mit seiner fr:-Adresse; wie das geht und wie die Prüfung sie auflöst, steht unter Zitieren mit fr:-Adressen.

5 Umbenennen

Wer ein Notebook oder einen Block umbenennt, trägt den alten Namen unter moved in famulus.yml ein:

moved:
  briefpartner: briefpartner-1520-1530
  briefpartner-1520-1530/netz: briefpartner-1520-1530/briefpartner-netz

Alte Verweise lösen sich weiter auf; famulus-notebook check meldet sie als verschoben, bis sie im Text nachgezogen sind.

6 Fehler

Meldung	Ursache
Verweis nicht lesbar: …	die Form passt zu keiner Zeile oben
…: Artefaktname fehlt (<block>.<artefakt>)	ein Verweis in input oder im Text ohne .name
…: fam:-Verweis braucht <projekt>/<notebook>/<block>.<artefakt>	die volle Form ist unvollständig
…: unbekannte Version @… (latest, vN, sha:…, locked)	ein anderer Wähler
Projekt … hat N Notebooks; uses muss <projekt>/<notebook> nennen	ein Kurzname auf ein Projekt ohne main mit mehreren Notebooks
Zyklus zwischen Notebooks: …, Zyklus zwischen Projekten: …	zwei Notebooks oder Projekte lesen einander