guides/templates/Format/EndGuide.md

END-GUIDE-STIL (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)
• @page { size: A4; margin: 18mm; }
• Cover-Seite + automatisches Inhaltsverzeichnis
• Footer: Seitenzahl Mitte, " EndGuide" rechts

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.

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.

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

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

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.

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").

STRUKTUR

1. Cover: Logo, Titel " — Der EndGuide", Subtitle, Badge " Teile · 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

NUMMERIERUNG

• Teile und Kapitel sind GETRENNTE Zähler.
• Kapitel laufen über den ganzen Guide durch – sie starten NICHT je Teil neu.
• "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.

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.

CALLOUT-NUTZUNG

• tip (✓): Best Practice / Empfehlung.
• warn (!): Sicherheits- oder Stolperfalle.
• note (i): Hintergrund / Abgrenzung.

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: .
• Escaping im Code: < > & als < > & (z. B. ->, =>, &&).
• scrub() filtert beim Bauen personenbezogene Reste (Namen/Orte/Mails) heraus.

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 (page-break-inside: avoid).

GENERIERUNG & PRÜFUNG

1. Inventar lesen, STRUCTURE daraus ableiten.
2. python3 build.py → guide.html (meldet Kapitel/Teile + Sektionen)
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)
   • grep -c '' == 0
   • keine echten Namen/Orte/Mails
   • Seitenzahl (pdfinfo) im Rahmen 50–250
   • 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?

   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

   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: @media screen { html[data-theme="dark"] { ...dunkle Variablenwerte... } 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.