180 lines
8.5 KiB
Markdown
180 lines
8.5 KiB
Markdown
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, "<Thema> 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 "<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 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: <code class="inline">.
|
||
- 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 '<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?
|
||
|
||
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.
|