guides/templates/Format/EndGuide.md

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

FORMAT

• 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 page + automatic table of contents
• Footer: page number center, " EndGuide" right

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.

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.

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

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

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

STRUCTURE

1. Cover: logo, title " — Der EndGuide", subtitle, badge " Teile · 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

NUMBERING

• Parts and chapters are SEPARATE counters.
• Chapters run through the whole guide — they do NOT restart per part.
• "Teil 7" ≠ "Kapitel 7".

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.

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 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 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: .
• Escaping in code: < > & as < > & (e.g. ->, =>, &&).
• scrub() filters out personal leftovers (names/places/emails) during build.

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

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. 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 '' == 0
   • no real names/places/emails
   • page count (pdfinfo) within the 50–250 range
   • 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?

   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)

   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"] { ...dark variable values... } html[data-theme="dark"] body { background: #15171c; } }
   • 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.