Editorial Style Guide (Vitte Book)

This guide is the editorial contract for the whole book. Its purpose is simple: every chapter must teach one coherent thing with one coherent example, without repetitive filler and without line-by-line paraphrase.

Core Rules

One chapter, one main problem, one main example.
Explain the whole flow before explaining local syntax.
Do not write line-by-line commentary unless the chapter is explicitly about parsing or debugging a single statement.
Every technical chapter must include a nominal path, an invalid path, and an observable result.
Every keyword page must show the keyword in Vitte and compare it briefly to C when that comparison clarifies intent.

Chapter Contract

Concrete Problem: name the real engineering problem.
Red Thread (Single Project): keep one scenario from start to finish.
For what: say what this chapter helps the reader build, debug, or decide.
What you are going to do: explain the proof path of the chapter.
Coherent example: one complete program or subsystem extract.
Global explanation: explain responsibilities, data flow, boundaries, and failure points.
Invalid case: show how the chapter fails and how the reader notices it.
Short exercise: ask for one modification that preserves the chapter invariant.

Keyword Contract

Definition: state what the keyword means in the language.
Syntax: show the canonical shape.
Example in Vitte: complete, runnable or near-runnable snippet.
Example in C: short comparison when it clarifies semantics.
Invalid example: show the misuse and the expected family of diagnosis.
Global explanation: explain what the keyword changes in the full flow.

Anti-Repetition Rules

Do not repeat generic filler such as “read the core idea first”.
Do not duplicate the same pitfall list across unrelated chapters.
Do not rename the same section three ways; keep one stable heading.
Do not comment each line if the reader really needs the architecture of the block.

Stdlib Policy

The stdlib must be documented by family, not by isolated minimal snippets only.
Each family must explain its responsibility, main submodules, integration boundaries, and realistic usage.
Examples should be complete enough to show where data enters, which library layer acts, and what comes out.

Length And Density

Prefer dense examples over decorative prose.
Keep bullets for inventories and contracts, not for replacing explanation.
If a chapter grows, add more evidence and scenarios, not more filler.

Paths And Links

Reference the book with the docs/book/ prefix when discussing repository paths.
Prefer stable repository-relative paths and stable chapter numbering.