§ 2 — Notation and conventions
2. Notation and conventions
Normative. This chapter defines the typographic, grammatical, and structural conventions used throughout the Standard. Conforming implementations and Standard authors rely on these conventions for correct interpretation.
2.1. Normative keywords
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL, when appearing in all capitals in this Standard, are to be interpreted as described in RFC 2119 and RFC 8174.
A paragraph that does NOT contain one of these all-caps keywords is descriptive, not normative. Lowercase spellings of any RFC 2119 keyword are not normative — such wording MUST be either promoted to all-caps (making the clause normative) or rephrased (keeping the clause descriptive).
2.2. Section numbering and citation.
Chapters are cited as § N. Sections within a chapter are cited as § N.M, subsections as § N.M.K, and deepest-level subsections as § N.M.K.P. Nesting deeper than four levels MUST NOT appear in this Standard.
Appendices share the § sigil: § A.1, § A.2.3. The rendered form of every citation is the live section number; the source form is a stable slug (see § 2.7).
Examples within a section are numbered locally: Example N.M.1, Example N.M.2, and so on. Numbering restarts at 1 within each section.
Authors write cross-references in source as §{chapter.leaf}. The build replaces each with the linked numeric at render time. Bare numeric forms (§ 2.3) in prose are rejected by the build.
2.3. Normative and informative blocks
Each chapter and appendix begins with a single-line banner:
> **Normative.** …— the chapter establishes binding requirements.> **Informative.** …— the chapter is non-binding commentary.
Within a normative chapter:
- Example blocks are informative. They illustrate, but do not define, language behavior.
- Note blocks are informative unless explicitly marked otherwise.
- Rationale blocks are informative.
- All other prose is normative when it contains an RFC 2119 keyword.
2.4. Grammar notation
The Standard uses a W3C-style EBNF variant. The full formal grammar is in Appendix A. The productions in § 4, § 5, § 6, and § 8 are prose walkthroughs of the productions in Appendix A; where the two disagree, Appendix A is authoritative and the prose is a bug.
The notation is:
| Symbol | Meaning |
|---|---|
::= | Production definition |
| | Alternation |
* | Zero or more |
+ | One or more |
? | Optional (zero or one) |
( ) | Grouping |
"literal" | Terminal string |
/regex/ | Terminal regular-expression class |
Production names use lower_snake_case. Terminal classes defined by regular expression use UPPER_SNAKE_CASE. Whitespace between tokens is significant where § 3 says it is; elsewhere, whitespace between tokens is ignored.
Example 2.4.1
gather_step ::= "gather" input+ NEWLINEinput ::= STRING | "!" STRINGThis defines gather_step as the keyword gather followed by one or more inputs and a newline. Each input is either a bare string (include) or ! followed by a string (exclude).
2.5. Precedence on grammar disagreements
Where the normative prose in any chapter disagrees with a production in Appendix A, Appendix A is authoritative. The prose is then a defect in the Standard and MUST be corrected to match Appendix A.
This rule applies only to grammar productions. Where a chapter’s prose defines a semantic property not expressed in Appendix A (for example, the ordering constraint “use declarations MUST precede any recipe”), that prose is the normative source.
2.6. Amendment markers
When a normative clause is materially revised, an inline marker [amended CS-NNNN] MUST be appended to the clause, linking to the corresponding entry in E-changes.mdx. Additions do not require a marker. When a clause is removed, it is struck through (~~...~~) with an [amended CS-NNNN] marker; the struck-through form is retained for one release cycle and then purged.
2.7. Stable anchors.
Every numbered chunk in this Standard carries a stable slug so that cross-references survive renumbering and retitling. Slugs match the grammar chapter.leaf, where each segment is [a-z][a-z0-9-]* and the chapter prefix is drawn from the following fixed set:
| Chapter | Prefix |
|---|---|
| 0. Introduction | intro |
| 1. Conformance | conf |
| 2. Notation and conventions | notation |
| 3. Lexical structure | lexical |
| 4. Top-level structure | toplevel |
| 5. Declarations | decl |
| 6. Recipes | recipes |
| 7. Chores | chores |
| 8. Step kinds | steps |
| 9. Placeholders | phl |
| 10. Cross-recipe references | xref |
| 11. Cross-Cookfile composition | comp |
| 12. Modules | mods |
| 13–20. Execution model | exec (sub-prefixes) |
| 21–26. Cook Lua API | lua (sub-prefixes) |
| 27. Catalogue governance | cat |
| 28. cc — C-family build module | cat.cc |
| A. Grammar (normative appendix) | grammar-appendix |
| B. Worked examples (informative) | examples |
| C. Rationale (informative) | rationale |
| D. Pre-1.0 checklist | pre-v1 |
| E. Changes | changes |
| F. Conformance corpus | corpus |
Authors declare the slug on a numbered heading with a trailing [#<slug>] marker:
## 3.3. Identifiers. [#lexical.identifiers]The build extracts the marker, applies it as the heading’s HTML id, and strips it from the rendered text. Unresolved refs, duplicate slugs, missing markers, and invalid slug grammar all fail the build.
Authors MUST NOT change a slug without recording the change in E-changes.mdx. Renumbering a section does NOT require an E-changes entry — the slug is the stable identity, not the number.