update

templates/Format/EndGuide.md

@@ -1,16 +1,26 @@
 END-GUIDE-STIL (HTML/CSS → PDF via WeasyPrint)
 
 FORMAT
-- A4 Hochformat, ~120–150 Seiten
+- 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, "PHP EndGuide" rechts
+- Footer: Seitenzahl Mitte, "<Thema> EndGuide" rechts
 
-UMFANG (höchste Guide-Stufe)
-- 17 Teile, 97 durchnummerierte Kapitel
-- Anspruch: vollständig, "lieber zu viel als zu wenig"
-- Von der ersten Zeile bis zu Experten-Themen (Architektur, Async, Betrieb)
-- Zielversion PHP 8.5
+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
@@ -22,46 +32,46 @@ 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 mit sichtbarem Ergebnis als Kommentar.
+  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 str_replace/substr_replace + Beispiel
-              "object"     + Erklärung "Instanz einer Klasse"          + Beispiel
+  - 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
-  Zuweisungs-Kurzformen, alle Vergleiche, alle Sortiervarianten …). Nur sehr
-  große Mengen (z. B. Datums-Formatzeichen) als Auswahl + Verweis auf die Doku.
+  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
-- Bezeichner englisch: Variablen, Funktionen, Klassen, Methoden, Konstanten,
-  Enum-Fälle.
+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: PHP-eigene Namen (count, $_GET, int …); SQL-Tabellen-/
-  Spaltennamen in Strings (= Daten, kein PHP-Bezeichner).
+- 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 bevorzugen (match, Enums, Constructor Promotion, readonly,
-  Property Hooks, Pipe |> …). Versionsabhängiges kennzeichnen ("seit 8.4",
-  "PHP 8.5").
+- Moderne Syntax der aktuellen Zielversion bevorzugen; Versionsabhängiges
+  kennzeichnen ("seit Version X").
 
 STRUKTUR
-1. Cover: Logo, Titel "PHP — Der EndGuide", Subtitle, Badge "17 Teile · 97 Kapitel"
+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
 
 NUMMERIERUNG
-- Teile (1–17) und Kapitel (durchlaufend 1–97) sind GETRENNTE Zähler.
+- Teile und Kapitel sind GETRENNTE Zähler.
 - Kapitel laufen über den ganzen Guide durch – sie starten NICHT je Teil neu.
 - "Teil 7" ≠ "Kapitel 7".
 
@@ -76,30 +86,38 @@ ELEMENTE
   Erklärung + Beispiel inline.
 
 TYPOGRAFIE & FARBEN (max 3 + Neutrals)
-- Hauptfarbe: PHP-Violett; dunkle Code-Blöcke (#1e2a3a-Familie).
+- 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 (SQL-Injection, Session-Fixation,
-            ungeprüfte Uploads …).
-- note (i): Hintergrund / Abgrenzung ("ORM oder pures PDO?", "nebenläufig ≠
-            parallel").
+- 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]). Daraus entstehen
-  Reihenfolge, Nummern, Inhaltsverzeichnis und Trennseiten automatisch.
+  (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/Enum-Fall, v=Variable, a=Attribut.
+  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.
 
 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.
@@ -111,21 +129,20 @@ VERMEIDEN
   (page-break-inside: avoid).
 
 GENERIERUNG & PRÜFUNG
-1. python3 build.py            → guide.html (meldet Kapitel/Teile + Fortschritt %)
-2. weasyprint guide.html guide.pdf
-3. Auslieferung nach /mnt/user-data/outputs: cp html und cp pdf als GETRENNTE
-   Befehle ausführen – NICHT mit && nach einem grep verketten (grep gibt bei 0
-   Treffern Exit 1, bricht die Kette ab → eine Datei würde stillschweigend fehlen).
-4. In /outputs verifizieren:
-   - pdfinfo PHP-EndGuide-Neu.pdf | grep Pages          (Seitenzahl)
-   - grep -c 'toc-part'                                 (= 17 Teile)
-   - grep -c 'chapter-num'                              (= 97 Kapitel)
-   - grep -c '<table>'                                  (= 0)
-   - grep -coE 'echte Namen/Orte/Mails'                 (= 0)
+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 '<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?
-   - SQL-Strings als Daten unverändert?
    - Codeblöcke/Callouts nicht über Seitenumbruch zerrissen?
    - Cover, Inhaltsverzeichnis und Teil-Trennseiten korrekt?