Standards für die Organisation

Regeln und Briefpapier zusammen halten.

Ein Profilpaket enthält Schemas und Themes. Es beantwortet versioniert und ausdrücklich: Was ist bei uns ein gültiges Dokument, und wie sieht dieses gültige Dokument aus?

Saubere Trennung

Das Schema sagt «gültig». Das Theme sagt «gerendert».

Der Markdown-Text entscheidet nicht, wo die Empfängeradresse steht, welche Schrift eine Überschrift nutzt oder ob die erste Seite einen eigenen Kopf hat. Das sind feste Layoutentscheide. Umgekehrt darf ein Theme nicht die einzige Stelle sein, an der eine Pflichtangabe oder eine fachliche Regel bekannt ist.

SchemaTheme
Dokumentvertrag
Typen, Frontmatter, Überschriften, Blöcke, Spans, Felder und Regeln.
Dokumentbild
Seitengeometrie, Stile, Briefkopf, Rahmen, Kopf- und Fusszeilen, Listen und Formatierung.
«Ein Brief hat Absender, Empfänger und Betreff; Postleitzahlen haben dieses Format.»«Der Absender steht hier; der Empfänger in diesem Fenster; dies ist die Hausschrift.»
Praktische Folge: Ein neuer Briefkopf verlangt keine Änderung aller Briefe. Eine neue Pflichtangabe verlangt keine Suche durch Word-Vorlagen.
Die Verteilungseinheit

Ein Profilpaket ist ein kleines Git-Repository.

Profile halten Schemas und Themes zusammen, weil beides die Konventionen einer Organisation beschreibt. Ein Manifest benennt die Verzeichnisse; das Paket lässt sich als Einheit prüfen und versionieren.

mein-docc-profil/
├── docc-profile.yaml
├── schemas/
│   ├── _base.yaml
│   └── ch_letter.yaml
└── themes/
    ├── _base.yaml
    └── starter-letter.yaml

Auch das eingebaute Starterpaket folgt diesem Modell. docc init kopiert es als editierbaren Checkout, statt eine Sonderfall-Vorlage zu erzeugen.

# Starterprofil im aktuellen Projekt auschecken.
docc init

# Oder ein Git-Profil installieren und ans Projekt binden.
docc profile use ssh://git.example.ch/kanzlei/docc-profiles.git
Keine stille Ausweichwahl

Jeder Build kann sein verwendetes Profil nennen.

Bei einem Projektprofil speichert docc Bindung und Lockdatei. Der gewählte Commit—nicht der momentane Stand eines Remote-Repositories—baut das Dokument. Build und Check holen oder aktualisieren kein Profil heimlich.

docc profile status
# Quelle, Referenz und gepinnten Commit sehen.

docc profile update
# Neue Revision auflösen, Lockdatei prüfen und committen.

Die Auflösung folgt einer festen Reihenfolge: explizite Verzeichnisflags, DOCC_PROFILE, Projektbindung, Checkout, Benutzerstandard und erst dann das eingebaute Starterpaket. Eine ausdrückliche, aber unbrauchbare Wahl ist ein Fehler, keine Einladung zu einem fremden Fallback.

Teilen ohne Kopieren

Basis erweitern. Bewusst überschreiben.

Schemas und Themes unterstützen beide extends. Maps verschmelzen pro Schlüssel; geordnete Sequenzen werden ganz ersetzt, sobald das Kind sie erklärt. Namen mit _ sind Fragmente: erweiterbar, aber nicht als vollständiger Typ oder Theme auswählbar.

type: ch_letter
extends: base
theme: starter-letter
frontmatter:
  subject:
    type: string
    required: true
Erst prüfen, dann rendern

Das Theme hat das letzte Wort über Layout—nachdem es seine Renderbarkeit bewiesen hat.

Vor dem ersten Absatz prüft docc die Passung von Schema und Theme: deklarierte Stile, interpolierte Felder und Renderregeln müssen auflösbar sein. So entsteht kein fast fertiges Word-Dokument mit einer unverständlichen Lücke.

Der Writer erzeugt das .docx-Archiv ohne Word und ohne Vorlagendatei. Briefkopf, Kopf- und Fusszeilen, Tabellen, Bilder und positionierte Rahmen bleiben Definitionsbestandteile des Profils, nicht des einzelnen Dokuments.

Nächster kleiner Schritt

Mit dem Starter beginnen; ein Paket bauen, wenn Sie einen Standard besitzen.

Nur einen Brief schreiben? Das eingebaute Beispiel und Theme reichen für den Lernablauf.

Eine Büroadaption? docc init ausführen und das kopierte Starterpaket beim Projekt halten.

Gemeinsame Konvention? Das Paket in Git pflegen, mit docc profile use installieren und die Lockdatei committen.

Die vollständige Anleitung finden Sie bei Profilpaketen, Profilaufbau und in der Theme-Referenz.