1Gegenstand

Dieses Dokument ist eine sinngemäße Übersetzung. Maßgeblich ist das Originaldokument auf Französisch; Erweiterungen und Änderungen werden stets dort eingepflegt.

Das Kit gibt sich als unabhängig von der künstlichen Intelligenz aus, die es ausführt. Das ist es nicht: seine Kette setzt Werkzeuge, eine Ordnerstruktur und Verhaltensweisen voraus, die sie nicht mitliefert. Dieses Dokument benennt, was sie verlangt.

Es nennt keine einzelne Intelligenz. Jede schreibt daneben ihren eigenen Befund, der Zeile für Zeile auf den Vertrag aus §2 antwortet und erklärt, was ihr fehlt. Der Vertrag gehört dem Kit und gilt überall; der Befund gehört der Intelligenz, und nur sie kann ihn messen.

Hinweis:Ein Befund altert, und das ist gewollt. Eine Umgebung, die sich ändert, zeigt sich im Abstand zwischen zwei Befunden. Deshalb wird die Prüfung aus §5 in jeder Sitzung wiederholt, statt in einem Dokument nachgelesen zu werden.

2Ausführungsvertrag

Jede Zeile nennt eine Fähigkeit, ihren Nutzen in der Kette und das, was ohne sie wegfällt. Die Reihenfolge der Zeilen liegt fest: sie macht zwei Befunde vergleichbar.

Fähigkeit	Nutzen	Ohne sie	Grad
Node.js	Führt die Stylesheets und die Generatoren aus.	Nichts wird erzeugt.	Erforderlich
Modul docx	Baut das Dokument und schreibt es.	Kein Dokument.	Erforderlich
Python 3	Werkzeuge zum Auslesen, Prüfen und Rendern.	Keine Prüfung, kein Deckblatt.	Erforderlich
pandoc	Wandelt ein Dokument in eine Webseite und liest das Cover Sheet.	Keine Webseite.	Bedingt
LibreOffice	Wandelt ein Dokument in PDF.	Die Website erscheint ohne PDF.	Bedingt
zip	Erzeugt das Projektarchiv, wenn projectShareable im Registry true ist.	Der Durchlauf bricht ab: Der von projectZip.downloadUrl angekündigte Link zeigte auf ein fehlendes Archiv.	Erforderlich, wenn projectShareable true ist
Pillow	Setzt das PNG des Deckblatts.	Kein gerendertes Deckblatt.	Bedingt
Modul adm-zip	Baut das Archiv der Website.	Die Website entsteht ohne Archiv.	Bedingt

Hinweis:Seit General v1.83 ist kein externes Modul mehr nötig, um ein Dokument zu erzeugen: der Fingerabdruck wird durch Lesen des zentralen Verzeichnisses des Archivs geprüft, ohne Bibliothek. adm-zip dient nur noch der Veröffentlichung der Website.

3Grade der Anforderung

Drei Grade, und sie bestimmen das Verhalten, wenn eine Fähigkeit fehlt.

–Erforderlich: die Kette hält an. Es gibt keine ehrliche abgespeckte Fassung eines Dokuments: ohne den Baustein entsteht kein ärmeres Dokument, es entsteht keines.

–Bedingt: ein Erzeugnis entfällt, der Rest entsteht. Eine Website ohne PDF ist besser als keine Website. Das entfallene Erzeugnis wird angesagt.

–Geduldet: ein Umweg besteht und wird samt seinem Preis angesagt. Eine Installation zu Sitzungsbeginn ist einer: sie überlebt nicht.

Hinweis:Man erzeugt, was man kann, solange das Erzeugte richtig bleibt. Der Unterschied ist keiner des Gewichts, sondern der Art: eine fehlende bedingte Fähigkeit nimmt ein Erzeugnis weg, eine fehlende erforderliche macht das Ergebnis falsch. Ein Dokument mit leerem Rumpf öffnet sich ohne Warnung und besteht die Prüfung — Quality Control §3.14.

4Regeln unabhängig von der Intelligenz

Sie folgen aus dem Vertrag und gelten in jeder Umgebung. Ihr Wohnsitz liegt anderswo; sie stehen hier, weil ein Befund auf sie antwortet.

–Eine einzige Auflösung: alle Dateien einer Kette lösen das Baumodul gleich auf. Zwei Instanzen erzeugen ein gültiges und leeres Dokument. General Reference §1.3.

–Reihenfolge der Auflösung: gewöhnliche Auflösung, dann die in KIT_NODE_MODULES erklärte Wurzel, dann die vom Paketwerkzeug gemeldete. Kein Pfad wird im Voraus geschrieben.

–Örtlicher Zeitstempel: Dateinamen tragen die Luxemburger Zeit, nie die des Containers. Nur der Veröffentlichungsstempel der Registry steht in Weltzeit.

–Neu geschriebener Generator: kein Erzeugungsskript überlebt von einer Sitzung zur nächsten. Jede Sitzung geht vom aktiven Stylesheet und seiner Reference aus.

5Prüfung zu Sitzungsbeginn

Vor jeder Erzeugung wiederholt die Intelligenz die folgende Prüfung und sagt ihr Ergebnis an. Das ist keine Einladung: es ist das nullte Glied der Prüfkette und geht der ersten Prüfung aus Quality Control §3.13 voraus.

node --version
node -p "require.resolve('docx')"
node -p "Object.keys(require('docx')).length"
python3 --version
python3 -c "import PIL; print('Pillow', PIL.__version__)"
which pandoc soffice
node -e "require('adm-zip'); console.log('adm-zip')"

Die Ansage geht der Erzeugung voraus, nie umgekehrt. Die Intelligenz sagt an, was sie erzeugen wird und was nicht. Ein Fehlen am Ende eines Durchlaufs zu entdecken heißt, es zu spät zu entdecken.

–Eine erforderliche Fähigkeit fehlt: Abbruch, mit dem Namen der Fähigkeit und dem Befehl, der sie installiert.

–Eine bedingte Fähigkeit fehlt: das zugehörige Erzeugnis wird als fehlend angesagt, der Durchlauf geht weiter.

–Ein Umweg wird gegangen: er wird in der Ausgabe des Durchlaufs angesagt und in den Befund der Intelligenz eingetragen.

6Aufbau eines Befunds

Ein Befund trägt das Präfix der Intelligenz und die Kategorie Documentation — Namenskonvention §2. Er hat sechs Abschnitte, in dieser Reihenfolge.

#	Abschnitt	Inhalt
1	Gegenstand und Daten	Welche Umgebung, Datum der Abfassung und Datum der letzten Prüfung. Der Abstand zwischen beiden sagt etwas aus.
2	Antwort auf den Vertrag	Die Tabelle aus §2, gleiche Zeilenfolge, mit dem Gemessenen und seinem Ort.
3	Lücken	Was fehlt, und welchem Grad aus §3 es entspricht.
4	Umwege	Was dagegen getan wird, und was es kostet.
5	Besonderheiten	Was nicht im Vertrag steht und die Arbeitsweise dennoch ändert.
6	Rohbefund	Befehle und Ausgaben, wörtlich. Der Beleg für Abschnitt 2.

Hinweis:Abschnitt 5 ist der, den keine andere Intelligenz an ihrer Stelle schreiben kann. Er trägt, was sich durch keinen Befehl messen lässt: wie eine angehängte Datei zur Intelligenz gelangt, was eine Sitzung überlebt, was verloren geht.

7Was das Kit nicht zusichert

Zwei Annahmen fallen aus dem Vertrag, weil das Kit sie hinnimmt, ohne sie erzwingen zu können. Sie gehören in den Befund jeder Intelligenz, Abschnitt 5.

–Das Fortbestehen zwischen Sitzungen. Nichts sichert zu, dass eine Umgebung ihren Zustand wiederfindet. Darauf beruhen die Prüfung aus §5 und das Neuschreiben des Generators.

–Die Form einer angehängten Datei. Eine Intelligenz kann ein Dokument als Binärdatei oder als ausgelesenen Text liefern. Im zweiten Fall erzeugt das Ändern eines bestehenden Dokuments aus dem Gelesenen eine verarmte Datei, ohne dass etwas darauf hinweist — daher die Regel der zwingenden Binärdatei.