END-GUIDE-STIL (HTML/CSS → PDF via WeasyPrint)

FORMAT
- A4 Hochformat, ~120–150 Seiten
- @page { size: A4; margin: 18mm; }
- Cover-Seite + automatisches Inhaltsverzeichnis
- Footer: Seitenzahl Mitte, "PHP 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

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 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

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

STRUKTUR
1. Cover: Logo, Titel "PHP — Der EndGuide", Subtitle, Badge "17 Teile · 97 Kapitel"
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.
- 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: PHP-Violett; 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").

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.
- Inhalt in Modulen content_partN.py:  CHAPTERS = { "Kapiteltitel": body_html }.
- Highlight-Span-Klassen im Code:
  c=Kommentar, k=Keyword, s=String/Zahl, f=Funktion,
  t=Typ/Klasse/Konstante/Enum-Fall, 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
- 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. 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)
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?

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.