From c4abd24ce8d60f859ea08274a45376baeca27c7b Mon Sep 17 00:00:00 2001 From: mhoennig Date: Sat, 22 Aug 2026 18:33:23 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20Knotenbeschreibungen=20entschieden=20?= =?UTF-8?q?=E2=80=94=20`"`-Zeilen=20und=20`---`-Beschreibungsteil=20(D34-N?= =?UTF-8?q?achtrag)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Kurzform (Nutzer-Entscheidung): eine neue Zeile mit `"` unter dem Knoten — eigenes Zeichen statt Einrückung, weil Einrückung Hierarchie bedeutet; Leerraum-Regel wie bei =, >/<, damit "Zitat"-Labels unberührt bleiben. Langform (Nutzer-Entscheidung): hinter einem `---`-Trenner nach YAML-/Frontmatter-Vorbild eröffnen ID-Zeilen (#auth) Blöcke, deren eingerückte Zeilen der Text sind — kein Schlusszaun, der vergessen werden könnte; die Wurzelknoten-Regel endet am Trenner, darum braucht dort keine Zeile ein Zeichen. Fehlertoleranz: verwaiste/uneingerückte Zeilen im Beschreibungsteil warnen zeilengenau — ein versehentlicher Trenner macht sich laut bemerkbar. SPEC §11, TASKS, ROADMAP und Plan nachgezogen; damit ist die letzte offene Schreibweise der fünf D34-Erweiterungen fest. Co-Authored-By: Claude Fable 5 --- docs/DECISIONS.md | 35 +++++++++++++++++ docs/ROADMAP.md | 3 +- docs/SPEC.md | 68 +++++++++++++++++++++++++++++---- docs/TASKS.md | 3 ++ docs/examples/werkbaum.werkbaum | 6 +-- 5 files changed, 103 insertions(+), 12 deletions(-) diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 3457955..8d6723c 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -1656,6 +1656,41 @@ eingeklappter Knoten sichtbar gekennzeichnet (etwa „▸“ oder die Anzahl der verborgenen Kinder); die genaue Form entscheidet sich beim Bauen, die SPEC-Aussage ist nur: sichtbare Struktur, Einklappung gekennzeichnet. +**Nachtrag — die Knotenbeschreibungen sind entschieden: `"`-Zeilen und ein +`---`-Beschreibungsteil.** Die letzte offene Schreibweise der fünf +Erweiterungen. Entschieden vom Nutzer in zwei Schritten: + +**Kurzform: eine neue Zeile mit `"`.** Ein eigenes einleitendes Zeichen war +die einzige Möglichkeit — Einrückung bedeutet Hierarchie (§2), eine +eingerückte Folgezeile ist ein Kindknoten. `"` liest sich als Zitat („was der +Autor dazu sagt“), ist auf DE- (Shift+2) wie US-Layout direkt tippbar und an +dieser Position frei. Die Leerraum-Regel (wie `=`, `>`/`<`) hält gequotete +Labels (`"Zitat"`) heraus; auf Zeilen mit Zerlegungszeichen gilt das Zeichen +nicht, ein `- " Zitat" …`-Label bleibt also unberührt. + +**Langform: hinter einem `---`-Trenner, nur mit Einrückung — ohne weitere +Zeichen.** Vorgeschlagen waren zeilenweise `"`-Präfixe (robust, aber lästig +beim Einfügen längerer Texte) und ein `"""`-Zaun (einfügefreundlich, aber ein +vergessener Schlusszaun verschluckte den Rest des Dokuments — der hässlichste +Fehlermodus in einem bis dahin zeilenlokalen Format). Der Nutzer wählte die +dritte, bessere Form: **ein `---`-Trenner nach YAML-/Frontmatter-Vorbild** +beendet den Baumteil; dahinter eröffnen ID-Zeilen (`#auth`) Blöcke, deren +eingerückte Zeilen der Text sind. Das nimmt dem Zaun beide Schwächen +zugleich: Es gibt **keinen Schlusszaun, den man vergessen könnte** (der +Beschreibungsteil läuft planmäßig bis zum Dateiende), und der Parser-Zustand +ist ein einziger Einweg-Schalter statt offen/zu. Die Wurzelknoten-Regel gilt +hinter dem Trenner nicht mehr — darum braucht dort keine Zeile ein Zeichen. + +Der Fehlermodus „versehentlicher Trenner mitten im Plan“ ist bewusst laut +gemacht: Uneingerückte Nicht-ID-Zeilen und verwaiste eingerückte Zeilen im +Beschreibungsteil geben je eine Warnung mit Zeilennummer — verschluckte +Knotenzeilen melden sich also zeilengenau selbst, statt still zu +verschwinden (dieselbe Haltung wie bei `unknownStatus`, §4). + +Zwei bewusste Verhaltensänderungen, beide dokumentiert (§11): `---` ergab +bisher einen Knoten mit Label `--`, und eine zeichenlose Zeile, die mit +`" ` beginnt, war bisher ein Wurzelknoten mit `"`-Label. + ## D35 — XOR (`=`) umgesetzt: „realisiert“ definiert, „1“-Plakette, keine neue Linienart Das in D34 entschiedene XOR-Gate ist gebaut (SPEC §1/§3/§9); beim Bauen waren drei Dinge zu entscheiden, die die SPEC bis dahin offen ließ: diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 5a0b5bc..99aba5a 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -142,7 +142,8 @@ Pfad, der die Wahrheit sagt. - **Knotenbeschreibungen** — Erläuterungstext zum Knoten, im Diagramm als Tooltip oder Pop-up: kurz direkt beim Knoten, lang als Block am Dokumentende über die ID zugeordnet. Die Arbeit steckt nicht im Anzeigen, sondern in der - Schreibweise: Einrückung bedeutet hier bereits Hierarchie. + Schreibweise: Einrückung bedeutet hier bereits Hierarchie. Die Schreibweise + ist entschieden (D34-Nachtrag): `"`-Zeilen bzw. ID-Blöcke hinter `---`. **Was daraus folgt.** diff --git a/docs/SPEC.md b/docs/SPEC.md index a99f9e1..6c6c283 100644 --- a/docs/SPEC.md +++ b/docs/SPEC.md @@ -711,17 +711,69 @@ ist, damit der gewählte Knoten effektiv fertig werden kann. Gemeinsam benötigte Abhängigkeiten werden dabei **nur einmal** gezählt. Genau das macht die Rechnung schwerer als heute — siehe D34. -### Knotenbeschreibungen +### Knotenbeschreibungen (`"` und `---`) Erläuternder Text zu einem Knoten, im Diagramm als Tooltip oder Pop-up. -Vorgesehen sind zwei Formen: ein **kurzer Text unmittelbar beim Knoten** und -ein **längerer Block am Ende des Dokuments**, über die Knoten-ID zugeordnet. +Beide Schreibweisen sind **entschieden** (D34-Nachtrag), noch nicht gebaut. +Der Kern des Problems war: Einrückung bedeutet Hierarchie (§2) — eine +eingerückte Folgezeile **ist** ein Kindknoten, und jede Zeile ohne Zeichen ist +ein Wurzelknoten. Die Kurzform löst das mit einem eigenen Zeichen, die +Langform, indem sie den Geltungsbereich dieser Regeln beendet. -**Offen — und hier liegt die eigentliche Arbeit:** Die kurze Form kann nicht -einfach eine eingerückte Folgezeile sein. Einrückung bedeutet in dieser -Notation Hierarchie (§2); eine eingerückte Zeile **ist** ein Kindknoten. Die -kurze Form braucht deshalb ein eigenes einleitendes Zeichen, die lange Form -eine Blockform, die sich nicht mit einem Wurzelknoten verwechseln lässt. +**Kurzform — `"`-Zeile unter dem Knoten:** + +``` +- [~] Auth-Dienst #auth (L) + " Kapselt Login, Tokens und Rollen. +``` + +- Eine Zeile, deren erstes Zeichen nach der Einrückung `"` ist (**mit + folgendem Leerraum**, Leerraum-Regel wie bei `=` und `>`/`<` — ein Label wie + `"Zitat"` bleibt damit ein Label), ist **Beschreibung, kein Knoten**. +- Sie gehört zum **vorangehenden Knoten**; mehrere `"`-Zeilen hintereinander + setzen dieselbe Beschreibung fort. Die Einrückung der `"`-Zeile hat keine + Bedeutung (Konvention: wie ein Kind eingerückt). Eine `"`-Zeile ohne + vorangehenden Knoten ist eine Warnung mit Zeilennummer. +- Der Inhalt ist **Freitext**: Die §1-Extraktion (Größe, Tags, IDs, URL …) + findet darin nicht statt. Nur `%%`-Kommentare werden weiterhin entfernt — + der Kommentar fällt als Erstes (§1), einheitlich im ganzen Dokument. +- Nur auf Zeilen **ohne** Zerlegungszeichen: `- " Zitat" als Label` bleibt ein + gewöhnlicher Knoten. + +**Langform — Beschreibungsteil hinter `---`:** + +``` +[~] Auth-Dienst #auth (L) + - [ ] Login + +--- +#auth + Hintergrund, Entscheidungen, Verweise — freier Text, + zeilenweise eingerückt. Leerzeilen trennen Absätze. +#api + Der nächste Block. +``` + +- Eine Zeile aus **drei oder mehr `-`** (nur Bindestriche, umgebender Leerraum + erlaubt) trennt den Baumteil vom **Beschreibungsteil**; alles danach gehört + zu ihm (YAML-/Frontmatter-Konvention: „ab hier etwas anderes“). Es gibt + keinen Schlusszaun — er kann also nicht vergessen werden. +- Im Beschreibungsteil eröffnet eine **uneingerückte Zeile mit genau einer + Knoten-ID** (`#auth`, allein) einen Block; die **eingerückten** Zeilen + darunter sind sein Text (um den Einzug gekürzt; Leerzeilen bleiben als + Absatztrenner erhalten). Anführungszeichen braucht es hier nicht — die + Wurzelknoten-Regel (§2) gilt hinter dem Trenner nicht mehr. +- **Fehlertoleranz:** Eine ID ohne zugehörigen Knoten → Warnung (wie + `unknownDep`). Eine uneingerückte Zeile, die keine ID-Zeile ist, oder + eingerückte Zeilen ohne eröffneten Block → Warnung mit Zeilennummer. Ein + versehentlicher Trenner mitten im Plan fällt dadurch sofort auf: Die + verschluckten Knotenzeilen werden zeilengenau gemeldet. +- Mehrere Blöcke zur selben ID werden in Dokumentreihenfolge aneinander- + gehängt; Kurz- und Langform zum selben Knoten dürfen koexistieren + (Anzeige-Details werden beim Bauen festgelegt). Weitere `---`-Zeilen im + Beschreibungsteil haben keine Bedeutung. +- Bewusste Verhaltensänderung: Eine Zeile `---` ergab bisher einen Knoten mit + Label `--`; sie ist jetzt der Trenner. ## 12. Dateiendung diff --git a/docs/TASKS.md b/docs/TASKS.md index ca17d0a..4e678d6 100644 --- a/docs/TASKS.md +++ b/docs/TASKS.md @@ -113,3 +113,6 @@ entscheiden, **bevor** Code entsteht. `tests/xor.test.js`. - [ ] Knotenbeschreibungen: Schreibweise für kurze und lange Form festlegen (Einrückung ist bereits Hierarchie), dann Tooltip/Pop-up. + → Schreibweise entschieden (D34-Nachtrag): Kurzform als `"`-Zeile unter + dem Knoten (Leerraum-Regel), Langform als eingerückte ID-Blöcke hinter + einem `---`-Trenner (SPEC §11). Zu bauen: Parser + Anzeige. diff --git a/docs/examples/werkbaum.werkbaum b/docs/examples/werkbaum.werkbaum index 237ffa9..72b641c 100644 --- a/docs/examples/werkbaum.werkbaum +++ b/docs/examples/werkbaum.werkbaum @@ -18,9 +18,9 @@ - [x] Cycles are legal — they mean "finished together" (XS) - [x] An id with no node behind it is a warning (XS) - [x] XOR, = — exactly one alternative, not at least one (S) - - [?] Node descriptions, shown as a tooltip or pop-up (M) - - [?] A short text right at the node (S) %% indentation already means hierarchy - - [?] A long block at the end, addressed by its id (S) + - [ ] Node descriptions, shown as a tooltip or pop-up (M) + - [ ] A short text right at the node (S) %% decided: a " line below the node + - [ ] A long block at the end, addressed by its id (S) %% decided: behind a --- separator - [-] A separate storage format for the structure (L) %% the text is the format - [ ] Ticket references (#123) (S) - [?] Benefit per node, not only cost (M)