Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Authoring units

A specification unit is one explanation that can be compared with a named formalization. Keep its definition, qualifications, notation, and explanatory text inside the same fence. The reader should understand the mathematical account without opening Lean; the Lean view makes the associated formalization inspectable.

Use the Writing style tenets to organize the explanation: start with intent, use examples to make distinctions concrete, and introduce notation before relying on it.

Identity, formalization, and context

The opening argument is the unit ID. Source citations and dependencies are options, followed by a blank line and the body:

```{definition} unique.syntax.place
:lean: Unique/Syntax:Place
:uses: unique.syntax.variable unique.syntax.field

A *place expression* \\(p\\) identifies a variable or a field reached through another place.

\\[
p ::= x \mid p.f
\\]
```

This is an authoring illustration; it does not assert that these example modules already exist. unique.syntax.place is the public unit identity. Unique/Syntax:Place is a source selector relative to the configured Lean root. They serve different purposes and need not have matching names.

A citation can select an inductive member of a top-level mutual group. The group delimiters and member headers must start at column zero; each header ends with where on its first line, and its body is indented. The Lean view shows the selected declaration; the evidence packet retains its enclosing source. Nested groups and mutual definitions of other kinds are unsupported.

Use :uses: for definitions and notation needed to interpret a unit. Link new terminology to the unit that introduces it with {anchor-ref}. A visible link supports the reader; an explicit dependency also records context that is used without being quoted. The inventory includes unit references in the review dependency set. Keep dependencies specific enough that a reviewer can explain why each is needed.

Unit IDs share the book’s global namespace. They use ASCII letters, digits, dots, underscores, and hyphens and begin with a letter or digit. Keep an ID stable when moving a unit between chapters. A second identifying {anchor} inside a structured unit is unnecessary.

Choosing a kind

KindBodyFormalization
definitionMarkdown introducing a concept, including delimited mathOne or more Lean definitions or a Rust implementation citation for a meta requirement
grammarRaw display LaTeXOne or more Lean type declarations
judgmentRaw display LaTeXOne inductive declaration
ruleRaw display LaTeXOne inductive constructor
theoremMarkdown stating a result and its assumptionsOne named Lean theorem
lemmaMarkdown stating a supporting result and its assumptionsOne named Lean theorem
exampleMarkdown explaining a concrete caseOne anchored anonymous Lean example
future-noteMarkdown exploring a possible future design, outside the current specificationForbidden

Theorem and lemma reviews compare the intended proposition with Lean’s statement, including hidden parameters and assumptions. Leave the proof to Lean. A prose proof outline is not required. Definitions introduce concepts and judgments; they do not require proofs.

Kind and readiness are separate. During a Markdown-first review, add :status: draft to retain the intended kind with a separate Draft indicator:

```{definition} unique.evaluation
:status: draft
:uses: unique.syntax.place

The following rules define expression evaluation.
```

A draft may omit source citations. Any supplied citations must still select the right declaration kind. A draft theorem states a proposed result, not an established one; a draft example describes a scenario awaiting its formal case. Evidence validation fails while a unit is draft, and no affirmative correspondence decision can be recorded for it. Add the matching formalization and remove :status: draft before preparing a correspondence review.

Future notes

Use a Future note for exploratory ideas that are not part of the current specification. Unlike a draft specification, a future note is publishable without formalization:

```{future-note} future.generic_views
:uses: given.typing.views

A future design could preserve partial views through constructors.
```

Future notes reject :lean:, :rust:, :tests:, and :status: draft. Place future notes at chapter top level, outside lists and blockquotes. They have stable IDs, Markdown bodies, and optional :uses: context; links and dependencies must resolve as usual. Nested specification units and legacy citation blocks are forbidden. The header says Future note, with no source selector. Evidence status is future note / not applicable; preparation and recording of correspondence reviews are rejected. Once an idea has an associated formalization, change it to the appropriate specification kind and review it. These checks reject declared source associations; they do not discover uncited implementations elsewhere in the repository.

Checking the formalization

Check Lean with just test-lean; its lake build --wfail rejects warnings, including those emitted by sorry. Do not use sorry to complete a formalization or suppress warn.sorry. Any future allowance for admissions must require an explicit opt-in.

Examples carry explanatory content too: describe the setup, the action, and the result that the cited Lean case actually states. A test of one small helper does not support an example claiming an entire execution. Use multiple units when different cases need independent explanation and review.

Mathematics and examples

Within Markdown bodies, use doubled-backslash delimiters: \\( and \\) for inline mathematics, \\[ and \\] for displays. Grammar, judgment, and rule bodies are already LaTeX displays and do not need those delimiters. Put distinct premises on separate lines. Group overbar expressions as {\overline f}; punctuation belongs outside the group.

Write source-language give expressions with the Unicode arrow, p→, and shared conversion as p→share. Introduce a concept with its italicized name and inline metavariable: “a statement \(t\)” or “a value expression \(e\).” Give each metavariable a grammar or domain before using it; state map domains and codomains explicitly. Define a judgment’s notation and inference rules before stating results about it. Use :uses: to identify earlier units that supply these definitions. This is a correspondence-review requirement, not an automatic notation check.

Abbreviating Lean syntax is useful when the omitted detail is explained; omitting a condition such as freshness or distinctness changes the claim.

An example citation uses the name between standalone Lean anchor comments:

```{example} unique.example.move
:lean: Unique/Examples:move
:uses: unique.operation.give

The example starts with one owner in `x`. Evaluating `x→` transfers that
reference and leaves `x` uninitialized.
```

The corresponding Lean region has exactly one anonymous example:

-- ANCHOR: move
example : True := by
  trivial
-- ANCHOR_END: move

This deliberately trivial snippet illustrates anchor syntax only. It does not check the move described above and would not pass a correspondence review of that example. Actual cases must state the relevant setup and result.

Use a longer outer fence for bodies containing fenced diagrams or code. Named units are top-level review boundaries; do not nest them. A diagram inside an example belongs to that example’s reviewed body. Legacy citation directives also cannot appear inside a structured unit: make them separate units with :lean: citations and connect them with :uses:.

Write reviewed text directly in its unit. mdBook include, playground, and rustdoc-include expansion is rejected in structured units, including inside literal code samples: mdBook can expand those samples too. This keeps the published claim equal to the text retained for review. To discuss an expansion command literally, split its opening braces so it is not a live mdBook directive.

book.toml supplies the book source directory and preprocessor.dada.lean-source for both rendering and evidence. It participates in review freshness. Source roots must stay inside the project; changing a configured root requires a new comparison with the declarations under that root.

Requirements on the tooling

Meta requirements use the same unit identity and body structure. Cite Rust implementation symbols and tests instead of a Lean formalization:

```{definition} meta.example.required_inputs
:rust: mdbook-dada/src/evidence.rs:validate
:tests: mdbook-dada/tests/evidence.rs:rejects_missing_input

Validation reports an error when a review omits a required source input.
```

These paths and names illustrate the option layout; select actual symbols when authoring a requirement. Its selector is Rendered/Rust; the Lean-backed forms use Rendered/Lean. Do not mix :lean: and :rust: on one unit. Split a requirement with independently reviewed implementations into separate units and connect their context with :uses:. A test citation identifies coverage to inspect; it does not assert that the test was executed or prove all cases.

Scope and migration

Every new-style unit under md/ participates in required evidence. spec.json additionally lists chapters subject to strict whole-chapter coverage. In those chapters, put semantic prose inside units and use headings for navigation. The authoring illustrations and workflow explanations in this repository section remain outside the initial strict pilot scope.

Existing chapters can retain the older opening-line citation syntax until they are migrated. Their inline anchors and working Rendered/Lean selectors are preserved, but do not by themselves provide complete review units. Migration means choosing boundaries, moving explanations inside them, adding IDs and dependencies, and preparing reviews. It is not a mass relabeling exercise.

After editing a covered unit, follow Correspondence review to prepare a fresh packet and retain the comparison evidence.

Link each referenced concept or equation where it is used, including MathJax rule premises. Ordinary Markdown links, anchor-reference roles, and MathJax \href{#claim-UNIT}{symbol} are inventoried automatically. Cross-chapter MathJax links use .html paths. Leave defining occurrences unlinked.

Run dada-spec links to inspect destinations and reading order. The link-review procedure explains coverage, target clarity, and forward-reference evidence. A link that resolves is only the start: it should land directly on the definition the reader needs.