Footnotes (reference `[^label]` + `FOOT)` block)¶

STATUS: SPEC. The [^label] reference is a markup construct (see also neumaRk_text_markup.md); the FOOT) block is a global section, twin of LYRICS) (neumaRk_lyrics.md §8) and FORM) (neumaRk_play_and_form.md).

The IT file is the source of truth (../it/neumaRk_footnotes.md); this EN file mirrors it.

1. Definition¶

A footnote links a point in the score to a reference text. It has two orthogonal parts:

the reference [^label] — a small superscript mark placed inside a text container (note annotation, chord comment-label, marker text, TEXT) prose, PLAY)/FORM) prose and box labels, L) syllable);
the definition — an entry of the global FOOT) block, keyed by label, carrying the reference text.

Reference rendering (informative). The superscript mark is drawn for: note annotations (voice 1 + 2), chord comment/group labels, TEXT) prose, and PLAY)/FORM) prose and box labels (top/name/bottom), including trailing and FORM) blocks. In marker M) text and L) lyric syllables the reference is parsed and validated but the mark is not drawn. In those containers the auto [^] counter skips the reference, so numbering stays self-consistent.

The syntax is view-mode independent: it anchors the reference to a musical point and defines the text; the renderer decides where to place the note (at the bottom of the page that references it in paper/strip mode; at the end of the piece — endnote — in scroll/papyrus mode).

2. Reference `[^label]`¶

The reference is a markup token (neumaRk_text_markup.md), so it lives inside text, not as a line token:

N) c4("sax;piano[^*]")          // note annotation
C) Cmaj7"voicing[^1]"           // chord comment-label
M) [A] "freely[^*]"             // marker text

2.1 Label¶

The label is the character sequence between [^ and ]. It determines the printed superscript mark:

Form	Rendered mark
`[^*]` `[^†]` `[^‡]` `[^§]` `[^#]`	the typographic symbol, as-is
`[^1]` … `[^999]`	the number
`[^]` (empty)	auto-numbered by the renderer in reading order

Reading order for auto-numbering is musical-positional (measure → beat → staff top-to-bottom), stable across view modes, continuous over the whole piece (no per-page reset).

2.2 Recognition and escaping¶

[^…] is recognized as a reference only inside quoted "…" text for the note/chord/marker containers and A)/D) texts (where [NAME] would otherwise be structural); in PLAY)/FORM)/TEXT) prose and L) syllables, which are unquoted, it applies to the whole text. The [^ … ] frame gives clean delimitation: word[^1]more is unambiguous, the label is 1. In the abbreviated box […] the reference's ] would close the box: c4[a[^1]] is invalid (E001), write c4["a[^1]"].

The \[ escape (already in neumaRk_text_markup.md) yields a literal bracket: piano\[^*] is text, not a reference. The reference does NOT collide with italic *…*: that is why the [^…] frame is used and not a bare *.

2.3 Multiple references¶

The same explicit label may be referenced from several points: all show the same mark and point to one definition. In paper/strip mode the definition is repeated at the bottom of every page that references it. With [^] (auto) each reference is a distinct (anonymous) note → the only way to reference the same note twice is an explicit label.

3. `FOOT)` block¶

A global section (outside datapacks), one or more occurrences, conventionally at the end of the piece. The lines following the FOOT) header are the entries. The block ends at a blank line or at the first explicit line marker (the single end rule of free-text blocks, neumaRk_datapack.md §13).

FOOT)
[^*] Piano plays all notes, sax plays top
[^1] Transcribed from the 1962 take; *ossia* in the coda

Entry grammar: [^label] <space> <text>.

The text reuses all of neumaRk_text_markup.md: line break ; (§3bis, the entry renders on multiple lines), *italic*, **bold**, __underline__, sizes #, escapes.
Multiple FOOT) blocks are joined in file order.
Reference↔definition matching is by label equality (position-independent, like PLAY/FORM [NAME] references).

3.1 Explicit vs auto labels¶

A document uses either explicit labels or auto-numbering [^], not mixed. Mixing produces W166 (non-blocking) and a deterministic renderer-side resolution.

4. Diagnostics¶

Code	Level	Meaning
`W162`	warning	`FOOT)` entry not starting with a `[^…]` label (ignored)
`W163`	warning	duplicate explicit label in `FOOT)`
`W164`	warning	reference `[^…]` with no matching `FOOT)` definition
`W165`	warning	`FOOT)` definition never referenced
`W166`	warning	mix of explicit and auto `[^]` labels in the same document

No blocking errors: footnotes never invalidate the document.

5. Round-trip¶

The FOOT) block is preserved verbatim (lossless round-trip). References [^…] travel inside the container text and round-trip naturally. The empty label [^] (auto) is re-emitted as [^], never as the resolved number (the number is rendering, not content).

6. Complete example¶

nrk:0.6
HT) Duet Sketch
HK) C
HM) 4/4

C) Cmaj7"voicing[^1]" | Dm7 G7
N) c4("sax;piano[^*]") d e f | g a b c

FOOT)
[^*] Piano plays all notes, sax plays top
[^1] rootless voicing

Rendered: a superscript asterisk after "piano" (note annotation) and a "1" after "voicing" (chord label); at the foot, the rule and the two entries.

Footnotes (reference [^label] + FOOT) block)¶