Markers

1. Cos’è un Marker

Un marker è un elemento strutturale non musicale che identifica un punto significativo nel flusso del brano. I marker non si riferiscono a un evento musicale, non hanno durata musicale propria e non influiscono direttamente sul contenuto musicale (note, accordi, ritmi), ma servono a:

• segmentare il brano in sezioni logiche;
• facilitare la lettura e l’orientamento umano;
• fornire ancoraggi semantici per il rendering, la navigazione e l’esecuzione;
• supportare forme musicali, ripetizioni e riferimenti.

I marker fanno parte del datapack musicale, ma appartengono alla sfera della struttura, non della notazione musicale.

Appartenenza semantica

Un marker appartiene semanticamente a una misura.

Esso identifica, etichetta o qualifica una misura come unità strutturale del brano e non è legato al flusso musicale o all’ordine di esecuzione.

---

2. Riga dei Markers

I marker sono contenuti in una riga di markers, che può essere:

• dichiarata esplicitamente con il marcatore di riga M);
• dedotta implicitamente dal contenuto della riga.

2.1 Posizione nel datapack

• La riga dei markers, se presente, è la prima riga del datapack.
• È opzionale.
• Può comparire una sola riga di markers per datapack. Se ne compaiono due, il parser le fonde senza diagnostici, campo per campo, e per ciascun campo (sezione, annotazione) vale l'ultima: M) [A] seguita da M) "poco;a poco" [B] dà la sezione B con l'annotazione. Il documento riscritto ne fa una riga sola, con la sezione prima dell'annotazione (M) | [B] "poco;a poco" |).

Best practice: collocare nella riga dei markers anche i decoratori di misura (volta, segno, coda, ecc.), per concentrare la struttura formale in un unico punto.

Un decoratore scritto sulla riga dei markers si applica alla stessa misura della barline allineata, esattamente come se fosse sulla riga note/accordi: l'effetto su rendering ed esecuzione è identico. È ammessa anche una barline di solo flusso a inizio sezione, senza altro testo sulla riga — es. M) |@ (coda) o M) |$ (segno). Se due righe portano decoratori divergenti sulla stessa misura, vince la riga scritta prima nel datapack — la riga dei markers, che sta in testa — e il parser emette il warning W159 sulla riga che perde (neumaRk_datapack.md §7.3); decoratori identici sulle due righe (allineamento visivo) non producono alcun warning.

---

3. Sintassi dei Markers

Un marker è espresso in due forme container, che differiscono per il ruolo strutturale e per la presenza del box grafico:

• [<testo>] — sezione: unità strutturale del brano, con box;
• "<testo>" — annotazione: testo descrittivo, senza box.

[Intro]            sezione (con box)
[A]                sezione
"freely"           annotazione
"swing feel"       annotazione

Il marker ammette il markup testuale definito in neumaRk_text_markup.md. Lo stile di default è bold, size body, in entrambe le forme.

3.1 Sezione vs annotazione

I due container hanno valore semantico diverso:

Forma	Tipo	Valore strutturale	Target PLAY/FORM	Chiude scope collapsible
[…]	sezione	sì (unità del brano)	sì	sì
"…"	annotazione	no (testo descrittivo)	no	no

La sezione si può scrivere anche ["NOME"]: vale [NOME], le virgolette delimitano il nome e non ne fanno parte (né del target di PLAY)/FORM)), e non aprono un'annotazione.

Una sezione identifica un'unità strutturale ricorribile e referenziabile (Intro, Verse, Chorus, A, B, …). Le sezioni sono i target di PLAY) / FORM) (vedi neumaRk_play_and_form.md §3.1) e delimitano lo scope delle sezioni collassabili (vedi §4).

Un'annotazione è un testo libero senza valore strutturale (es. "freely", "swing feel", "con feeling"). Le annotazioni non sono referenziabili da PLAY) / FORM) e non chiudono lo scope di una sezione collassabile.

Un ; nell'annotazione va a capo (neumaRk_text_markup.md §3bis): la pila sta sopra il rigo e cresce verso l'alto, l'ultima riga resta dove sarebbe la riga singola, allineata a sinistra.

M) | "poco;a poco" |      // →   poco
//                            a poco

Il nome di sezione […] è escluso: lì il ; resta letterale.

Nel nome di sezione \] è una ] letterale e non chiude il box, come nelle label e nelle annotazioni (neumaRk_text_markup.md §4):

M) | [Coda \] finale] |      // sezione «Coda ] finale»
N) | c4 d e f |

PLAY) e FORM) la referenziano con lo stesso nome escapato (neumaRk_play_and_form.md §3.1).

Nota normativa. […] (sezione) e "…" (annotazione) differiscono per due soli aspetti operativi: le annotazioni "…" non sono target di PLAY) / FORM) e non interagiscono con lo scope delle sezioni collassabili [? …] (§4). Per il resto restano entrambe testo formattabile.

3.2 Ancoraggio temporale

• Un marker si riferisce all'inizio della battuta in cui compare.
• Una misura ha una sola sezione […] e una sola annotazione "…": vale la prima, le altre della stessa misura si scartano con W186 (§7). Una […] scritta dentro un'annotazione è testo dell'annotazione, non una sezione.
• Se preceduto da una barline e nella forma con box […], deve essere separato da essa da almeno uno spazio, per evitare ambiguità con i decoratori di volta.
• La forma "…" non collide con i decoratori di volta e può essere adiacente alla barline; resta tuttavia raccomandato lo spazio per leggibilità.

Esempio valido:

M) | [A]

M) | "freely"

Senza il marcatore M) una riga che contiene un'annotazione "…" è dedotta come riga di accordi, con la "…" come label di riga: il predicato dei Markers impliciti ammette solo […], barre e spazi (neumaRk_datapack.md §3.bis.4). Le annotazioni di marker si scrivono quindi sulla riga M).

Esempio non valido:

M) |[A]   // letto come volta con l'etichetta A, non come sezione

---

4. Sezioni collassabili

Una sezione può essere dichiarata collassabile (anche detta opzionale) anteponendo il prefisso ? (carattere ? seguito da uno spazio) all'interno del marker:

[? Verse]
[? Solo 2]
[? Outro]

Una sezione collassabile è una proprietà di lettura del marker: una resa interattiva può permettere a chi legge di espandere o comprimere la sezione. Lo stato espanso/compresso è una preferenza di chi legge, conservata dall'host e non nel file NRK.

4.1 Scope della sezione collassabile

Lo scope di [? NAME] si estende dalla misura del marker fino al primo dei seguenti eventi:

• inizio di un'altra sezione […] (di qualsiasi nome, collassabile o no, incluso il marker anonimo [!] di §4.2);
• fine del documento.

Le annotazioni "…" interposte non chiudono lo scope: appartengono comunque alla sezione collassabile corrente.

M) [? Verse] | … | "freely" | … | [Chorus] | …
   └─────── scope di Verse ─────┘
                                  └ Chorus apre nuovo scope

4.2 Marker anonimo [!] (chiusura implicita di sezione opzionale)

Quando una sezione opzionale termina e non c'è un marker successivo che la chiude naturalmente (perché segue flusso "anonimo", non strutturato come sezione), si usa il token speciale [!] (parentesi quadre con un singolo !, senza spazi).

[!] è semanticamente un marker di apertura di sezione non-opzionale anonima: aderisce alla convenzione "marker = inizio-misura" (§3.2) e la chiusura dello scope precedente è il side-effect naturale della regola §4.1.

M) [? Coda] | … | … | [!] | … |
   └── scope di Coda ─┘
                       └ flusso non-collassabile, anonimo

Proprietà:

• Non renderizzato come marker (nessun box, nessuna etichetta).
• Non referenziabile da PLAY) / FORM): non ha NAME. Se usato come reference è reference-broken (vedi neumaRk_play_and_form.md §7.3).
• Ammesso ovunque: [!] non richiede una sezione opzionale aperta. Se non c'è scope da chiudere il token è ridondante (warning W146, non bloccante).

4.3 Niente annidamento

Una [? Inner] interna a un'altra [? Outer] chiude lo scope di Outer e apre quello di Inner, secondo la regola generale §4.1. Non esiste un meccanismo di sezioni collassabili annidate.

M) [? Outer] | … | [? Inner] | … |
   └ Outer ──┘   └─ Inner ─────…

4.4 Stato di default

All'apertura di un brano per la prima volta, le sezioni collassabili sono espanse. Chi legge le comprime esplicitamente; lo stato lo conserva l'host (§4).

Resa di riferimento (informativa). L'etichetta di una sezione collassabile espansa porta un chevron ▾ dopo il nome, perché la presenza di sezioni collassabili sia riconoscibile anche quando sono tutte espanse; una sezione compressa si riduce all'etichetta NAME ▸ su una riga propria. Il chevron è la maniglia che espande o comprime: appartiene alla resa interattiva, e le esportazioni statiche (PDF) non lo riportano: resta l'etichetta [NAME].

4.5 Riferimenti da PLAY/FORM

Una sezione [? NAME] è referenziata da PLAY) / FORM) usando il solo NAME, senza prefisso ?:

M) [? Verse] | … | [Chorus] | …
PLAY) [Verse] [Chorus]

Il prefisso ? è una proprietà di lettura della sezione, non parte del nome strutturale. Il binding fra PLAY) e M) è per text-equality sul NAME, ignorando il prefisso ?.

4.6 Esecuzione

Lo stato collassato/espanso riguarda solo la lettura: una sezione collassabile è eseguita esattamente come una sezione ordinaria, indipendentemente dal fatto che chi legge l'abbia collassata o espansa.

Una sezione collassata non viene "saltata" nell'esecuzione. Per omettere una sezione dall'esecuzione esistono altri meccanismi (versioni, PLAY) esplicita che la esclude).

4.7 Vincolo a inizio rigo

Una sezione collassabile deve iniziare e finire a inizio rigo (= a inizio di un system / datapack). Concretamente:

• il marker [? NAME] deve comparire nella prima misura del system in cui appare;
• la chiusura dello scope (qualsiasi altro […] o [!]) deve a sua volta comparire nella prima misura del system in cui appare;
• lo scope termina anche a EOF (caso valido).

Razionale: comprimere una sezione toglie righe intere; una sezione che inizia o finisce a metà rigo produrrebbe una resa ambigua (mezzo rigo sparirebbe, lasciando moncheria visiva).

In caso di violazione:

• emessa W151 (warning, non bloccante);
• la sezione non è collassabile: resta sempre espansa, anche in una resa interattiva.

---

5. Rilevanza identitaria

Il prefisso ~ su un marker di sezione la dichiara identitaria: ne segnala il tema come quello che caratterizza il brano ("la parte che fa riconoscere il pezzo"). È una proprietà strutturale e portabile della composizione — viaggia col file — non un dato dell'host.

M) [Intro] | … |
M) [~ Tema] | … |          ← sezione identitaria del brano
M) [Coda] | … |

~ non è renderizzato (nessun box, nessuna etichetta aggiuntiva: la sezione si disegna come una [Tema] normale) ed è preservato in round-trip dal serializer.

La rilevanza identitaria è un'annotazione musicale, non un'etichetta host: indica quale musica caratterizza il brano. Il marker è agnostico alla dimensione d'analisi: l'host può derivarne ciò che serve sotto qualunque profilo — melodia, armonia, ritmo, ritmo armonico, ecc. (elenco non esaustivo). Lo spec definisce quale regione è identitaria; cosa se ne estrae e su quale dimensione è fuori dal linguaggio.

5.1 Scope della regione di rilevanza

Lo scope di [~ NAME] si estende dalla misura del marker fino al primo dei seguenti eventi:

• l'inizio di una nuova sezione […] priva del prefisso ~;
• la fine del documento.

Una sezione successiva che porta anch'essa ~ non chiude la regione: la continua. Sezioni ~ consecutive formano quindi un'unica area di rilevanza; solo una sezione senza ~ la chiude.

M) [~ A] | … | [~ B] | … | [C] | … | [~ D] | …
   └──── area di rilevanza 1 (A+B) ────┘        └ area 2 (D)
                              └ C non rilevante, chiude l'area 1

Le annotazioni "…" interposte non chiudono lo scope (come in §4.1).

5.2 Più aree per brano

Sono ammesse più aree di rilevanza melodica nello stesso brano (le ~ non consecutive sono aree distinte, vedi [~ D] sopra). Il modo in cui l'host usa una o più aree (es. quale considerare per quale scopo) non è materia di linguaggio.

5.3 Default (nessun marker ~)

In assenza di qualsiasi [~ …] nel brano, la regione melodicamente rilevante è implicitamente il tratto dall'inizio del brano fino alla prima sezione esclusa (o fino a EOF se non ci sono sezioni). I brani che non usano il marker hanno quindi una regione di rilevanza ben definita e host-independent.

5.4 Marker anonimo [~]

[~] (parentesi quadre con un solo ~, senza spazi) è una sezione anonima identitaria: si comporta come il marker anonimo [!] (§4.2) — apre una sezione non-opzionale e chiude lo scope precedente — ma è flaggata ~. Serve a marcare "da qui è rilevante" quando il tema non è una sezione nominata. Specularmente, un [!] (senza ~) che segue una regione di rilevanza la chiude (è una sezione priva di ~, §5.1).

5.5 Composizione con ? (collassabile + rilevante)

Una sezione può essere insieme collassabile e identitaria. I due prefissi si accettano in ordine libero in input: [?~ NAME] e [~? NAME] sono equivalenti. Essendo semanticamente identiche, il serializer le normalizza alla forma canonica [?~ NAME] (come già normalizza spaziatura e altri aspetti dei marker).

M) [?~ Bridge] | … |     ≡     M) [~? Bridge] | … |

5.6 Riferimenti da PLAY/FORM

Come per ? (§4.5), una sezione [~ NAME] è referenziata da PLAY) / FORM) con il solo NAME, senza prefisso. Il binding è per text-equality sul NAME, ignorando i prefissi ~ e ?.

M) [~ Tema] | … |
PLAY) [Intro] [Tema] [Coda]

5.7 Ancoraggio

[~ NAME] / [~] seguono l'ancoraggio delle sezioni (§3.2, §4.7): compaiono a inizio misura; i confini di scope (sezione senza ~, o EOF) cadono a inizio rigo come ogni altro confine di sezione.

---

6. Play directive in riga M)

La riga M) ammette, oltre ai marker testuali […] / "…", anche play directive nella forma (=Style,Tempo) per cambiare lo style e/o il tempo del brano a partire da una misura specifica. Vedi neumaRk_play_directive.md per la spec completa.

La play directive convive liberamente con i marker testuali nella stessa misura. La disambiguazione fra i token è per delimitatori:

Token	Tipo
[…]	sezione (marker strutturale)
[? …]	sezione collassabile (vedi §4)
[~ …]	sezione identitaria (§5)
[!]	sezione anonima non-opzionale (§4.2)
[~]	sezione anonima identitaria (§5.4)
"…"	annotazione (testo descrittivo)
(=…)	play directive

Esempio:

M) | [Intro] (=Rock,120bpm) | | | [A] (=swing,140bpm) |

---

7. Regole di Validità

Una riga di markers è valida se:

• contiene solo sezioni […] / [? …] / [~ …], marker anonimi [!] / [~], annotazioni "…" e play directive (=…), separati da spazi e segni di battuta;
• non contiene pattern riconducibili a note o accordi;
• rispetta le regole di separazione da barline.

In caso di violazione:

• la riga non viene riconosciuta come riga di markers;
• il parsing del datapack prosegue secondo le regole di deduzione standard.

Una riga scritta col marcatore M) resta invece una riga di markers: ogni token che non è una sezione, un'annotazione, una play directive o un oggetto di contesto a un confine di misura (neumaRk_datapack.md §7.3) si scarta con W186. Una tonalità staccata ha il suo messaggio (W186.key_free_position): per cambiare tonalità la si incolla alla barra.

M) | [A] foo | (Bb) |     // W186 su `foo`, W186.key_free_position su `(Bb)`
N) | c4 d e f | g a b c |

Anche la seconda sezione o la seconda annotazione della stessa misura (§3.2) si scarta con W186 (W186.section_extra, W186.annotation_extra): vale la prima. Per più righe di testo si scrive una sola annotazione e si va a capo con ; (§3.1).

M) | [A] [B] "poco" "a poco" |   // W186 su `[B]` e su `"a poco"`
N) | c4 d e f |

M) | [A] "poco;a poco" |         // una sezione, un'annotazione su due righe
N) | c4 d e f |

7.1 Codici diagnostici

Codice	Severità	Descrizione
W146	WARNING	[!] ridondante: nessuna sezione opzionale da chiudere
W151	WARNING	Sezione opzionale non-collassabile: [? NAME] o la sua chiusura non a inizio rigo (§4.7)
W186	WARNING	Token fuori dal vocabolario della riga M) (W186.key_free_position per una tonalità staccata), seconda sezione o annotazione della stessa misura (W186.section_extra, W186.annotation_extra): scartato (§3.2, §7)