update

templates/Format/EndGuide.md

@@ -1,179 +1,190 @@
-END-GUIDE-STIL (HTML/CSS → PDF via WeasyPrint)
+END-GUIDE STYLE (HTML/CSS → PDF via WeasyPrint)
 
 FORMAT
-- A4 Hochformat, 50–250 Seiten (themenabhängig — kleines Thema kurz,
-  großes Thema lang; die Seitenzahl folgt aus dem Inventar)
+- A4 portrait, 50–250 pages (topic-dependent — small topic short,
+  large topic long; the page count follows from the inventory)
 - @page { size: A4; margin: 18mm; }
-- Cover-Seite + automatisches Inhaltsverzeichnis
-- Footer: Seitenzahl Mitte, "<Thema> EndGuide" rechts
+- Cover page + automatic table of contents
+- Footer: page number center, "<Topic> EndGuide" right
 
-ABDECKUNG (höchste Guide-Stufe)
-- ALLE Bausteine des Themas — vollständig, "lieber zu viel als zu wenig".
-- Von der ersten Zeile bis zu Experten-Themen (Architektur, Interna, Betrieb —
-  was immer beim Thema die Expertenstufe ist).
-- Aktuelle Version des Themas als Zielversion nennen.
+COVERAGE (highest guide tier)
+- ALL building blocks of the topic — complete, "rather too much than too little".
+- From the very first line up to expert topics (architecture, internals,
+  operations — whatever the expert tier is for the topic).
+- Name the current version of the topic as the target version.
 
-THEMENINVENTAR (verbindlich)
-- Das Inventar wird vorab von einem Recherche-Agenten erstellt und mitgeliefert.
-  Es ist die verbindliche Stoffliste: 1 Inventar-Punkt = 1 EIGENE H2-Sektion
-  nach dem Muster Titel·Erklärung·Beispiel.
-- Punkte beim Schreiben NICHT zusammenfassen, kürzen oder eindampfen — wirkt
-  das Pensum zu groß, Teil für Teil abarbeiten statt komprimieren.
-- Teile und Kapitel aus dem Inventar ableiten: verwandte Punkte zu Kapiteln
-  gruppieren, Kapitel zu Teilen. Es gibt KEINE Vorgabe-Zahl für Teile/Kapitel.
+TOPIC INVENTORY (binding)
+- The inventory is produced beforehand by a research agent and supplied with
+  the task. It is the binding list of material: 1 inventory item = 1 OWN H2
+  section following the pattern Title·Explanation·Example.
+- Do NOT merge, trim, or condense items while writing — if the workload feels
+  too large, work part by part instead of compressing.
+- Derive parts and chapters from the inventory: group related items into
+  chapters, chapters into parts. There is NO default number of parts/chapters.
 
-ZIELGRUPPE — VOM ANFÄNGER ZUM EXPERTEN
-- Beginnt bei null, steigert sich progressiv über die Teile
-- Frühe Teile erklären jeden Begriff; spätere setzen Vorheriges voraus
-- Verweise nach hinten ("eigener Teil") erlaubt – der Guide wird durchgelesen
-  oder nachgeschlagen
+TARGET AUDIENCE — FROM BEGINNER TO EXPERT
+- Starts at zero, progresses step by step across the parts
+- Early parts explain every term; later ones assume what came before
+- Forward references ("own part") are allowed — the guide is read cover to
+  cover or used for lookup
 
-KERNPRINZIP — TITEL · ERKLÄRUNG · BEISPIEL (das definierende Muster)
-- JEDES Konzept in genau dieser Reihenfolge:
-  1. Titel: reiner Konzept-/Verb-/Typname. Nichts sonst.
-  2. Erklärung: 1–3 Sätze Prosa. Nennt die Funktionen/Bausteine und was sie tun.
-  3. Beispiel: lauffähiger Code (bzw. konkretes Beispiel) mit sichtbarem
-     Ergebnis als Kommentar.
-- Die Überschrift trägt NIE die Funktionsliste oder die Definition:
-  - schlecht: "Ersetzen: str_replace & substr_replace"
-              "object – Instanz einer Klasse"
-  - gut:      "Ersetzen"  + Erklärung nennt die Funktionen + Beispiel
-              "object"     + Erklärung "Instanz einer Klasse" + Beispiel
+CORE PRINCIPLE — TITLE · EXPLANATION · EXAMPLE (the defining pattern)
+- EVERY concept in exactly this order:
+  1. Title: pure concept/verb/type name. Nothing else.
+  2. Explanation: max. 3 short main clauses, simply worded, no nested
+     sentences. Names the functions/building blocks and what they do.
+     Recommendations, real-world problems, and warnings do NOT belong in the
+     explanation — that is what callouts (tip/warn/note) are for.
+  3. Example: runnable code (or a concrete example) with the visible result
+     as a comment.
+- The heading NEVER carries the function list or the definition:
+  - bad:  "Ersetzen: str_replace & substr_replace"
+          "object – Instanz einer Klasse"
+  - good: "Ersetzen"  + explanation names the functions + example
+          "object"     + explanation "Instanz einer Klasse" + example
 
-INHALTLICHE PRINZIPIEN
-- Vollständigkeit: aufzählbare Mengen IMMER komplett (alle Operatoren, alle
-  Varianten, alle Modi …). Nur sehr große Mengen (z. B. hunderte
-  Formatzeichen) als Auswahl + Verweis auf die Doku.
-- Mechanik zeigen: Beispiele sind echte, lauffähige Mini-Demos MIT Ausgabe –
-  nicht nur Signaturen oder leere Interfaces. Bei Mustern/Interfaces:
-  Vertrag + konkrete Implementierung + Aufruf mit sichtbarem Ergebnis.
-- Tiefe vor Aufzählung: erst erklären warum/wann, dann zeigen.
-- Keine Performance-Zahlen ohne Quelle.
+CONTENT PRINCIPLES
+- Completeness: enumerable sets ALWAYS complete (all operators, all variants,
+  all modes …). Only very large sets (e.g. hundreds of format characters) as
+  a selection + reference to the docs.
+- Show the mechanics: examples are real, runnable mini-demos WITH output —
+  not just signatures or empty interfaces. For patterns/interfaces:
+  contract + concrete implementation + call with visible result.
+- Depth before enumeration: explain why/when first, then show.
+- No performance numbers without a source.
 
-CODE-KONVENTIONEN (bei technischen Themen)
-- Bezeichner englisch: Variablen, Funktionen, Klassen, Methoden, Konstanten.
-- Deutsch bleibt: Fließtext, Überschriften, Code-Kommentare, Ausgabetexte,
-  Beispieldaten ("Anna", "Köln", "Hallo Welt").
-- Unverändert: themen-/spracheigene Namen (Built-ins, Standard-APIs);
-  Tabellen-/Spaltennamen in Strings (= Daten, keine Bezeichner).
-- Ergebnis-Kommentar an jedem Beispiel:  // 19.99 €
-- Neutrale Daten: Namen Anna/Ben/Tom, Orte Köln/Hamburg, mail@example.com.
-  Keine personenbezogenen oder echten Daten.
-- Moderne Syntax der aktuellen Zielversion bevorzugen; Versionsabhängiges
-  kennzeichnen ("seit Version X").
+CODE CONVENTIONS (for technical topics)
+- Identifiers in English: variables, functions, classes, methods, constants.
+- German stays: prose, headings, code comments, output strings,
+  sample data ("Anna", "Köln", "Hallo Welt").
+- Unchanged: topic-/language-native names (built-ins, standard APIs);
+  table/column names in strings (= data, not identifiers).
+- Result comment on every example:  // 19.99 €
+- Neutral data: names Anna/Ben/Tom, places Köln/Hamburg, mail@example.com.
+  No personal or real data.
+- Prefer modern syntax of the current target version; mark version-dependent
+  features ("seit Version X").
 
-STRUKTUR
-1. Cover: Logo, Titel "<Thema> — Der EndGuide", Subtitle, Badge
-   "<N> Teile · <M> Kapitel" (Zahlen aus dem Inventar)
-2. Inhaltsverzeichnis (automatisch aus der Struktur erzeugt)
-3. Pro Teil: Trennseite (Teil-Nummer · Titel · Beschreibung · Kapitel-Liste)
-4. Pro Kapitel: Kapitel-Nummer + Titel, kurzer Lead-Satz, dann H2-Sektionen
-   nach dem Muster Titel·Erklärung·Beispiel
+STRUCTURE
+1. Cover: logo, title "<Topic> — Der EndGuide", subtitle, badge
+   "<N> Teile · <M> Kapitel" (numbers taken from the inventory)
+2. Table of contents (generated automatically from the structure)
+3. Per part: divider page (part number · title · description · chapter list)
+4. Per chapter: chapter number + title, short lead sentence, then H2 sections
+   following the pattern Title·Explanation·Example
 
-NUMMERIERUNG
-- Teile und Kapitel sind GETRENNTE Zähler.
-- Kapitel laufen über den ganzen Guide durch – sie starten NICHT je Teil neu.
+NUMBERING
+- Parts and chapters are SEPARATE counters.
+- Chapters run through the whole guide — they do NOT restart per part.
 - "Teil 7" ≠ "Kapitel 7".
 
-ELEMENTE
-- Fließtext: justify; Erklärungen als Prosa, Aufzählungen sparsam.
-- Codeblöcke: dunkler Hintergrund, Syntax-Highlighting, mit Ergebnis-Kommentaren.
-- Inline-Code: heller Hintergrund, Hauptfarbe – für jeden Fachbegriff und
-  Funktionsnamen im Fließtext.
-- Callouts in 3 Varianten: tip (✓), warn (!), note (i). Sparsam, höchstens
-  einer pro Sektion.
-- KEINE Übersichts- oder Referenztabellen. Jede Funktion/jedes Feature bekommt
-  Erklärung + Beispiel inline.
+ELEMENTS
+- Body text: justify; explanations as prose, bullet lists sparingly.
+- Code blocks: dark background, syntax highlighting, with result comments.
+- Inline code: light background, accent color — for every technical term and
+  function name in prose.
+- Callouts in 3 flavors: tip (✓), warn (!), note (i). Sparingly, at most
+  one per section.
+- NO overview or reference tables. Every function/feature gets
+  explanation + example inline.
 
-TYPOGRAFIE & FARBEN (max 3 + Neutrals)
-- Hauptfarbe: an offizielle Farbe des Themas anlehnen; dunkle Code-Blöcke
-  (#1e2a3a-Familie).
-- Body Serif; Überschriften Sans-Serif bold; Code Monospace.
-- max. 3 Schriftgrößen pro Sektion.
+TYPOGRAPHY & COLORS (max 3 + neutrals)
+- Accent color: lean on the topic's official color; dark code blocks
+  (#1e2a3a family).
+- Body serif; headings sans-serif bold; code monospace.
+- max. 3 font sizes per section.
 
-CALLOUT-NUTZUNG
-- tip (✓):  Best Practice / Empfehlung.
-- warn (!): Sicherheits- oder Stolperfalle.
-- note (i): Hintergrund / Abgrenzung.
+CALLOUT USAGE
+- tip (✓):  best practice / recommendation.
+- warn (!): security issue or pitfall.
+- note (i): background / distinction.
+- MANDATORY: sentences like "Empfehlung: …", "In der Praxis problematisch: …",
+  "Achtung: …" ALWAYS go into the matching callout, never into the running
+  prose of the explanation. This keeps the explanation short and the hints
+  scannable.
 
-BUILD-ARCHITEKTUR (strukturgetrieben)
-- Eine Quelle der Wahrheit: STRUCTURE in build.py = Liste aus
-  (Teil-Kicker, Titel, Beschreibung, [Kapiteltitel]) — direkt aus dem
-  Inventar abgeleitet. Daraus entstehen Reihenfolge, Nummern,
-  Inhaltsverzeichnis und Trennseiten automatisch.
-- Inhalt in Modulen content_partN.py:  CHAPTERS = { "Kapiteltitel": body_html }.
-  Teil für Teil schreiben — nie den ganzen Guide in einem Stück. Nach jedem
-  Teil: H2-Sektionen gegen die Inventar-Punkte des Teils zählen, Fehlendes
-  sofort ergänzen, erst dann den nächsten Teil beginnen.
-- build.py meldet am Ende die Gesamtzahl der H2-Sektionen; sie muss der
-  Anzahl der Inventar-Punkte entsprechen.
-- Highlight-Span-Klassen im Code:
-  c=Kommentar, k=Keyword, s=String/Zahl, f=Funktion,
-  t=Typ/Klasse/Konstante, v=Variable, a=Attribut.
-  Inline-Code im Text: <code class="inline">.
-- Escaping im Code: < > & als &lt; &gt; &amp; (z. B. -&gt;, =&gt;, &amp;&amp;).
-- scrub() filtert beim Bauen personenbezogene Reste (Namen/Orte/Mails) heraus.
+BUILD ARCHITECTURE (structure-driven)
+- One source of truth: STRUCTURE in build.py = list of
+  (part kicker, title, description, [chapter titles]) — derived directly from
+  the inventory. Order, numbers, table of contents, and divider pages are
+  generated from it automatically.
+- Content in modules content_partN.py:  CHAPTERS = { "chapter title": body_html }.
+  Write part by part — never the whole guide in one go. After each part:
+  count the H2 sections against that part's inventory items, add anything
+  missing immediately, only then start the next part.
+- build.py reports the total number of H2 sections at the end; it must match
+  the number of inventory items.
+- Highlight span classes in code:
+  c=comment, k=keyword, s=string/number, f=function,
+  t=type/class/constant, v=variable, a=attribute.
+  Inline code in prose: <code class="inline">.
+- Escaping in code: < > & as &lt; &gt; &amp; (e.g. -&gt;, =&gt;, &amp;&amp;).
+- scrub() filters out personal leftovers (names/places/emails) during build.
 
-VERMEIDEN
-- Feste Teile-/Kapitel-/Seitenzahlen als Ziel (der Umfang folgt aus dem
-  Inventar, nicht umgekehrt).
-- Inventar-Punkte zusammenfassen oder weglassen.
-- Funktionsliste oder Definition in der Überschrift (Titel bleibt rein).
-- Übersichts-/Referenztabellen ohne Erklärtext.
-- Deutsche Code-Bezeichner.
-- Personenbezogene oder echte Daten.
-- Unvollständige aufzählbare Mengen.
-- Reine Interface-/Signatur-Stubs ohne Aufruf + Ausgabe.
-- Performance-Zahlen ohne Quelle.
-- Codeblock oder Callout über einen Seitenumbruch zerrissen
+AVOID
+- Fixed part/chapter/page counts as a target (scope follows from the
+  inventory, not the other way around).
+- Merging or dropping inventory items.
+- Function list or definition in the heading (the title stays pure).
+- Explanations longer than 3 sentences or with nested sentences.
+- Recommendations/warnings in running prose instead of in a callout.
+- Overview/reference tables without explanatory text.
+- German code identifiers.
+- Personal or real data.
+- Incomplete enumerable sets.
+- Pure interface/signature stubs without call + output.
+- Performance numbers without a source.
+- Code block or callout torn across a page break
   (page-break-inside: avoid).
 
-GENERIERUNG & PRÜFUNG
-1. Inventar lesen, STRUCTURE daraus ableiten.
-2. python3 build.py            → guide.html (meldet Kapitel/Teile + Sektionen)
+GENERATION & VERIFICATION
+1. Read the inventory, derive STRUCTURE from it.
+2. python3 build.py            → guide.html (reports chapters/parts + sections)
 3. weasyprint guide.html guide.pdf
-4. Verifizieren — die Sollwerte kommen aus dem Inventar:
-   - grep -c 'toc-part'    == Anzahl Teile in STRUCTURE
-   - grep -c 'chapter-num' == Anzahl Kapitel in STRUCTURE
-   - grep -c '<h2'         == Anzahl Inventar-Punkte (1 Punkt = 1 Sektion;
-     bei Differenz: fehlende Punkte ausarbeiten — NICHT das Inventar kürzen)
+4. Verify — the target values come from the inventory:
+   - grep -c 'toc-part'    == number of parts in STRUCTURE
+   - grep -c 'chapter-num' == number of chapters in STRUCTURE
+   - grep -c '<h2'         == number of inventory items (1 item = 1 section;
+     on mismatch: write out the missing items — do NOT trim the inventory)
    - grep -c '<table>'     == 0
-   - keine echten Namen/Orte/Mails
-   - Seitenzahl (pdfinfo) im Rahmen 50–250
-5. Stichproben rendern (pdftoppm) und ansehen:
-   - Überschrift = reiner Titel, Erklärung darunter, dann Beispiel?
-   - Code englisch, Erklärung und Kommentare deutsch?
-   - Codeblöcke/Callouts nicht über Seitenumbruch zerrissen?
-   - Cover, Inhaltsverzeichnis und Teil-Trennseiten korrekt?
+   - no real names/places/emails
+   - page count (pdfinfo) within the 50–250 range
+5. Render samples (pdftoppm) and inspect:
+   - Heading = pure title, explanation below it, then the example?
+   - Code in English, explanation and comments in German?
+   - Code blocks/callouts not torn across page breaks?
+   - Cover, table of contents, and part dividers correct?
 
-CHECKLISTE PRO ABSCHNITT
-- [ ] Überschrift ist ein reiner Titel (keine Funktionsliste, keine Definition)
-- [ ] Erklärung in Prosa vorhanden, nennt die Bausteine
-- [ ] lauffähiges Beispiel mit Ergebnis-Kommentar
-- [ ] keine Tabelle
-- [ ] englische Bezeichner, deutsche Erklärung/Kommentare/Daten
-- [ ] aufzählbare Menge vollständig
-- [ ] neutrale Beispieldaten
+CHECKLIST PER SECTION
+- [ ] Heading is a pure title (no function list, no definition)
+- [ ] Explanation in prose present, names the building blocks
+- [ ] Explanation max. 3 short main clauses, no nested sentences
+- [ ] Recommendations/warnings as callout, not in running prose
+- [ ] runnable example with result comment
+- [ ] no table
+- [ ] English identifiers, German explanation/comments/data
+- [ ] enumerable set complete
+- [ ] neutral sample data
 
 INSTALLATION
 - pip install weasyprint
 - apt install poppler-utils   (pdfinfo, pdftoppm, pdftotext)
 
-DARKMODE (PFLICHT)
-- Alle Farben ausschließlich über :root-Variablen definieren
-  (--ink, --muted, --line, --bg-soft, Akzent-Variablen).
-- Zusätzlich einen Dunkelmodus-Block ausliefern:
+DARK MODE (REQUIRED)
+- Define all colors exclusively via :root variables
+  (--ink, --muted, --line, --bg-soft, accent variables).
+- Additionally ship a dark-mode block:
   @media screen {
-    html[data-theme="dark"] { ...dunkle Variablenwerte... }
+    html[data-theme="dark"] { ...dark variable values... }
     html[data-theme="dark"] body { background: #15171c; }
   }
-- Die App aktiviert ihn über data-theme="dark" auf <html>.
-  KEIN prefers-color-scheme verwenden.
-- Dunkle Werte: Hintergründe dunkel (#15171c / #23262e), Text hell (#e6e8ee),
-  Linien gedämpft (#2c3038). Akzentfarben so anheben, dass Überschriften und
-  Links auf dunklem Grund lesbar bleiben (Kontrast prüfen). Elemente mit hellem
-  Text auf Akzent-Hintergrund (z. B. Tabellenköpfe) dürfen ihre helle
-  Hintergrundfarbe behalten.
-- Callout-/Infobox-Hintergründe nicht hartkodieren oder im Dunkelmodus
-  explizit abdunkeln (z. B. auf var(--bg-soft)); farbige Border bleibt.
-- Nur innerhalb von @media screen — Druck/PDF bleibt unverändert hell.
+- The app enables it via data-theme="dark" on <html>.
+  Do NOT use prefers-color-scheme.
+- Dark values: dark backgrounds (#15171c / #23262e), light text (#e6e8ee),
+  muted lines (#2c3038). Lift accent colors so headings and links stay
+  readable on a dark background (check contrast). Elements with light text on
+  accent backgrounds (e.g. table headers) may keep their light background
+  color.
+- Do not hardcode callout/infobox backgrounds — or darken them explicitly in
+  dark mode (e.g. to var(--bg-soft)); the colored border stays.
+- Only inside @media screen — print/PDF stays light.