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

Conventions

This chapter describes the conventions used throughout this specification.

Paragraph References

Specification paragraphs use MyST directive syntax with the {spec} directive:

<div class="spec-paragraph" id="conventions.paragraph-references.local-name">
<div class="spec-label"><a href="#conventions.paragraph-references.local-name" class="spec-label-link">conventions.paragraph-references.local-name</a> <span class="spec-rfc-badge">rfc123</span></div>
<div class="spec-content">

Paragraph content.

</div>
</div>

ID Resolution

Paragraph IDs are resolved automatically from context:

  1. File path: syntax/string-literals.md contributes prefix syntax.string-literals
  2. Section headings: ## Escape Sequences contributes segment escape-sequences
  3. Local name: The name in the :::{spec} directive (e.g., invalid)

These combine to form the full ID: syntax.string-literals.escape-sequences.invalid

The local name is optional. A directive with only tags uses the heading context as its ID:

## Type

<div class="spec-paragraph" id="conventions.type">
<div class="spec-label"><a href="#conventions.type" class="spec-label-link">conventions.type</a> <span class="spec-rfc-badge">rfc0001</span> <span class="spec-rfc-badge spec-rfc-unimpl">unimpl</span></div>
<div class="spec-content">

String literals have type `my String`.

</div>
</div>

This paragraph’s ID is syntax.string-literals.type (file prefix + heading).

Inline Sub-paragraphs

List items within a :::{spec} block can be marked as individually referenceable sub-paragraphs using the {spec}`name` syntax:

<div class="spec-paragraph" id="conventions.type.inline-sub-paragraphs">
<div class="spec-label"><a href="#conventions.type.inline-sub-paragraphs" class="spec-label-link">conventions.type.inline-sub-paragraphs</a> <span class="spec-rfc-badge">rfc0001</span> <span class="spec-rfc-badge spec-rfc-unimpl">unimpl</span></div>
<div class="spec-content">

There are multiple forms of string literals:

* <span id="conventions.type.inline-sub-paragraphs.quoted" class="spec-sub-paragraph"><a href="#conventions.type.inline-sub-paragraphs.quoted" class="spec-sub-label">.quoted</a></span> Single-quoted string literals begin with `"` and end with `"`.
* <span id="conventions.type.inline-sub-paragraphs.triple-quoted" class="spec-sub-paragraph"><a href="#conventions.type.inline-sub-paragraphs.triple-quoted" class="spec-sub-label">.triple-quoted</a></span> Triple-quoted string literals begin with `"""` and end with `"""`.

</div>
</div>

Under ## Delimiters in syntax/string-literals.md, this creates:

  • syntax.string-literals.delimiters (parent paragraph)
  • syntax.string-literals.delimiters.quoted (sub-paragraph)
  • syntax.string-literals.delimiters.triple-quoted (sub-paragraph)

Each sub-paragraph gets its own linkable anchor in the rendered output.

RFC and Status Annotations

Paragraphs include tags after the optional local name:

<div class="spec-paragraph" id="conventions.type.rfc-and-status-annotations.local-name">
<div class="spec-label"><a href="#conventions.type.rfc-and-status-annotations.local-name" class="spec-label-link">conventions.type.rfc-and-status-annotations.local-name</a> <span class="spec-rfc-badge">rfc123</span> <span class="spec-rfc-badge spec-rfc-unimpl">unimpl</span></div>
<div class="spec-content">

Content added by RFC 123, not yet implemented.

</div>
</div>

Available tags:

  • rfcN — content added or modified by RFC N
  • !rfcN — content deleted by RFC N
  • unimpl — specified but not yet implemented

Multiple tags can be combined: :::{spec} local-name rfc123 rfc456 unimpl

Test Annotations

Tests reference spec paragraphs using #:spec comments with the fully-qualified ID:

#:spec syntax.string-literals.delimiters.quoted

These labels serve multiple purposes:

  • Cross-referencing within the specification
  • Linking from RFC documents
  • Test validation via #:spec annotations in .dada test files

Identifiers use semantic names rather than numbers to remain stable as the specification evolves.

EBNF Notation

This specification uses Extended Backus-Naur Form (EBNF) to describe syntax. Standard EBNF operators apply:

  • A* — zero or more repetitions of A
  • A+ — one or more repetitions of A
  • A? — optional A
  • A | B — A or B
  • `keyword` — a literal terminal
  • ε — the empty production

In addition, this specification uses the following shorthand for comma-separated lists with optional trailing commas:

  • A,* — zero or more comma-separated occurrences of A
  • A,+ — one or more comma-separated occurrences of A

Normative Language

This specification uses the following terms to indicate requirements:

  • must: An absolute requirement
  • must not: An absolute prohibition
  • should: A strong recommendation
  • should not: A strong recommendation against
  • may: An optional feature or behavior