Versioni del brano

Questo documento definisce la sintassi e la semantica delle versioni in neumaRk: meccanismo per rappresentare nello stesso file più varianti dello stesso brano (arrangiamenti alternativi, riarmonizzazioni di singole sezioni, intere riscritture).

Chi legge sceglie quale variante visualizzare/eseguire; la scelta è una preferenza conservata dall'host e non nel file NRK (§6).

---

1. Definizione

Una versione è una variante alternativa di una porzione del brano, delimitata da un blocco named della forma:

%%NAME
// … contenuto …
%%end

Esistono due classi di blocchi:

• Default — blocco %%NAME senza label, fa parte del flusso lineare del brano (è la versione "canonica" che il lettore vede di base);
• Variante — blocco %%NAME "label" con label, vive a lato del flusso. Si attiva esplicitamente dall'utente.

Una variante sostituisce tutte le occorrenze del blocco default omonimo durante l'esecuzione/rendering.

1.1 Esempio minimale

M) [Intro]
// … intro originale …

%%BRIDGE
M) [Bridge]
// … bridge originale …
%%end

M) [A]
// … A finale originale …

%%BRIDGE "Bill Evans version"
M) [Bridge]
// … bridge Bill Evans …
%%end

Chi legge apre il brano e vede la versione canonica. Scegliendo "Bill Evans version", il blocco %%BRIDGE viene sostituito dalla variante; il resto del brano (Intro, A) resta invariato.

---

2. Sintassi

2.1 Apertura del blocco

%%NAME                       blocco default
%%NAME "label"               blocco variante

• %% deve essere all'inizio della riga (eventualmente preceduto da soli spazi, secondo le regole generali di whitespace di neumaRk).
• NAME è un identificatore: una o più lettere/cifre/underscore, case-sensitive. Niente spazi interni.
• "label" (opzionale, presente solo nelle varianti) è un container testuale "…" adiacente al NAME, con uno spazio di separazione. Ammette il markup unificato (neumaRk_text_markup.md).

2.2 Chiusura del blocco

%%end

• Anche %%end deve essere all'inizio della riga.
• %%end chiude la regione di versioni e riporta al tronco comune.
• Un nuovo %%NAME chiude implicitamente il blocco aperto: in una catena di alternative si scrive un solo %%end, in fondo.
• Un %%end senza blocco aperto produce warning W148.
• Un blocco %%NAME non chiuso entro la fine del documento produce warning W147: tutto ciò che segue fino a fine file viene trattato come parte del blocco.

%%INTRO "standard"
// … intro standard …
%%INTRO "adams"          ← chiude implicitamente il blocco precedente
// … intro Adam's Apple …
%%end                    ← chiude la regione: si torna al tronco comune

2.3 Contenuto del blocco

Un blocco contiene uno o più datapack validi (vedi neumaRk_datapack.md). Tutte le regole musicali (marker, accordi, note, dinamiche, ecc.) si applicano normalmente dentro il blocco.

2.4 Annidamento non ammesso

Un blocco %%NAME non può essere aperto dentro un altro blocco. Poiché l'annidamento non esiste, un %%X incontrato mentre un blocco è aperto ha una sola lettura possibile: il blocco precedente è finito (§2.2, chiusura implicita).

Il warning W149 ("nested block") è ritirato: il codice resta riservato e non va riusato.

2.4.1 default è parola riservata

default non è utilizzabile né come NAME (%%default) né come etichetta (%%INTRO "default"), maiuscole/minuscole indifferenti: è il nome con cui il selettore presenta il blocco canonico ed è il valore speciale di HV) … default=. Un omonimo produrrebbe due voci indistinguibili nel selettore. Violazione → warning W151 (il blocco resta funzionante: la diagnostica chiede di rinominarlo).

2.4.2 Blocco vuoto

Un blocco può non contenere nessun datapack:

%%INTRO "senza intro"
%%end

Significa: in questa versione la sezione non c'è. Selezionandola, la sezione sparisce dal flusso.

2.4.3 Che cos'è questa versione: INFO)

Per dire che cos'è una versione si usa INFO) (neumaRk_datapack.md §11.1), scritta in testa al blocco, prima di qualunque riga musicale:

%%INTRO "live78"
INFO) "Live a Montreux" Trascrizione fedele del live del 4 giugno 1978.
Particolare attenzione all'articolazione del tema.
M) [Intro]
// … musica …
%%end

Vale il primo INFO) del blocco, in testa al primo datapack o da solo subito sotto %%NAME; uno più avanti nel blocco è un'informazione sulla partitura e non riguarda la scelta della versione. Vale anche per il blocco canonico.

Il testo è uno solo e compare in due posti: nel selettore, per scegliere (l'etichetta fa da titolo, il corpo da testo), e sulla partitura, mentre si legge quella versione — dove l'etichetta è incisa e il corpo si apre su richiesta. Il selettore mostra l'INFO) di ogni variante, anche di quelle non selezionate: serve proprio a scegliere.

Una riga "…" scritta sotto %%NAME non è più una descrizione: apre un datapack e, con ogni probabilità, diventa un'annotazione incisa.

2.5 Riservato: %%

La sequenza %% ad inizio riga è riservata per i blocchi versions. Non è ammessa in altri contesti del linguaggio (i commenti NRK usano //, vedi neumaRk_datapack.md per la spec dei commenti single-line).

---

3. Posizione strutturale

3.1 Standalone fra datapack

I blocchi %%NAME vivono fra datapack musicali, non al loro interno. La struttura del documento è una sequenza alternata di:

• datapack normali (flusso comune a tutte le versioni);
• blocchi default %%NAME (sezioni named del flusso);
• blocchi variante %%NAME "label" (varianti delle sezioni named).

[datapack] [datapack] %%BRIDGE [datapack] %%end [datapack]
                     └─ default ─┘
[datapack] %%BRIDGE "Bill Evans" [datapack] %%end
          └─────────── variante ───────────┘

3.2 Posizione delle varianti

Le varianti %%NAME "label" possono apparire in qualsiasi posizione del documento (raccomandato: subito dopo il blocco default omonimo, o in coda al documento). Il matching è per nome, non per posizione.

---

4. Semantica della sostituzione

4.1 Regola fondamentale

Un NAME occupa uno o più slot nel flusso del brano. Lo slot è la posizione del blocco d'àncora: il blocco canonico %%NAME se il documento ne ha uno, altrimenti il primo blocco di quel NAME in ordine di sorgente. Gli altri blocchi sono dichiarazioni fuori flusso.

Quando l'utente attiva una variante, tutte le occorrenze di quel NAME mostrano il contenuto scelto.

Le porzioni del brano fuori da blocchi (datapack normali) restano invariate in tutte le versioni: appartengono al "tronco comune".

Conseguenza voluta: un brano in cui tutti i blocchi di un NAME sono etichettati (nessun canonico) funziona. Il primo è quello che si vede all'apertura, gli altri sono selezionabili. Il selettore, in quel caso, non offre la voce default: non avrebbe contenuto.

4.1.1 Il contesto di scrittura non dipende dalla selezione

Un blocco versione è ermetico rispetto allo stato di scrittura:

• tutte le alternative di uno slot partono dallo stesso contesto, quello in vigore appena prima della regione (ottava relativa, durata corrente, chiave, metro, tonalità, identità dei righi, armonia in vigore);
• dopo la regione, la musica prosegue col contesto prodotto dal blocco d'àncora, non da quello selezionato.

Senza questa regola l'ottava e la durata della musica che segue dipenderebbero da una variante che il lettore non sta vedendo, e selezionare una variante scritta un'ottava sopra trasporterebbe tutto il resto del brano.

L'armonia che permane (§1.1 di neumaRk_chords.md: la cella d'accordo vuota continua l'accordo precedente) segue la stessa regola, ed è l'unica parte del contesto che il lettore vede stampata. Se la misura dopo %%end ha la cella vuota, l'armonia che eredita è quella con cui finisce il blocco canonico, qualunque versione sia selezionata: le slash e la sigla ristampata a inizio rigo restano le stesse per tutti i lettori.

Quando i blocchi di una regione finiscono su armonie diverse, la scelta la fa l'autore e non la selezione — e proprio per questo è una scelta che va vista: in quel caso l'editor segnala W178, e basta scrivere la sigla nella misura dopo %%end, oppure dichiararla con l'oggetto di contesto ((@X)).

I numeri di misura seguono invece il blocco attivo: numerano ciò che si vede. Una variante di tre misure al posto di una di una sposta in avanti la numerazione successiva.

Un blocco può essere l'unico posto in cui la chiave di un rigo (o il metro, o la tonalità) è dichiarata. Se quel blocco non viene reso, la dichiarazione se ne va con lui. Per non dipendere da una variante, scrivi il contesto dove vale davvero, con l'oggetto di contesto di misura (neumaRk_datapack.md §7.3): è un costrutto a sé, che si può mettere anche in una misura senza musica.

Il blocco canonico come contratto

Il contesto che prosegue è quello del blocco d'àncora. Se il blocco canonico contiene solo un oggetto di contesto, non stampa nulla (una misura di solo contesto non si rende) e diventa una dichiarazione: il contesto che la regione garantisce al resto del brano, qualunque versione sia selezionata.

%%INTRO
N) (@F, g@3_8) |
%%INTRO "standard"
M) [Intro]
N) (@F) g,8 a b c d e f g |
%%end

M) [Theme]
N) a b c d |

• Nessuna selezione: l'intro non c'è, il canonico non produce system. Il Theme parte in chiave di basso, dal riferimento g@3, in ottavi.
• "standard": l'intro si stampa, e il Theme ha le stesse altezze e le stesse durate.

È il modo di scrivere la chiave di basso quando la versione di default non ha l'intro: la dichiarazione va nel canonico, non nella variante. La variante parte comunque dal contesto d'ingresso della regione, quindi dichiara la propria chiave per sé ((@F) in testa).

4.2 Multi-occorrenze

Se un NAME occupa più slot (es. AABA con tre %%A distinti), una singola variante %%NAME "label" sostituisce tutte le occorrenze.

%%A
// … A original …
%%end

%%B
// … B …
%%end

%%A
// … A original (seconda occorrenza, può essere musicalmente identica
// o variata) …
%%end

%%A "miles"
// … A Miles version …
%%end

Attivando "miles": entrambe le %%A default sono sostituite dalla versione Miles. Per varianti per posizione (es. solo la seconda A è diversa), usare nomi distinti: %%A1, %%A2.

Prestito fra occorrenze. Se un'occorrenza non ha il blocco dell'etichetta scelta, mostra una copia presa da un'altra occorrenza, letta nel contesto del punto in cui è scritta, non di quello in cui compare. Con l'oggetto di contesto l'autore fissa il contratto da sé: in testa alla variante la rende indipendente dal punto in cui è scritta, in testa al canonico (o alla musica che segue) dichiara il contesto con cui si riparte.

4.3 Marker M) ortogonali

I marker della riga M) interni a un blocco %%NAME sono indipendenti dal nome del blocco. Il parser non richiede che M) [Bridge] appaia dentro %%BRIDGE: convention dell'autore nominarli uguale, ma non è vincolato.

%%PEDAL
M) [A pedal]
// … …
%%end

PEDAL è il nome del blocco (per il selettore versioni); A pedal è il marker della sezione (per PLAY/FORM, render, navigazione).

4.4 Riscritture totali

Per arrangiamenti completi (es. "Round Midnight, arrangiamento Miles"), l'autore può racchiudere l'intero brano in un blocco %%NAME default (con nome a scelta: %%SONG, %%MAIN, ecc.) e fornire la riscrittura come variante.

%%SONG
M) [Intro]
// … brano completo originale …
M) [Outro]
// …
%%end

%%SONG "Miles Davis arrangement"
M) [Intro Miles]
// … arrangiamento completo Miles …
M) [Coda]
// …
%%end

Non esiste una keyword riservata per "tutto il brano": qualsiasi nome funziona, l'autore sceglie quello che preferisce.

---

5. Header opzionale HV)

L'header del documento (neumaRk_header.md) ammette una voce opzionale HV) per dichiarare esplicitamente le versioni di un blocco e quella di apertura. Una riga per NAME:

HV) INTRO: [standard, adams] default=standard
HV) BRIDGE: [default, miles] default=miles

5.1 Sintassi

HV) <NAME>: [<label1>, <label2>, …] [default=<label>]

• <NAME> è il nome di un blocco %%NAME, seguito da :.
• Lista di label fra parentesi quadre, separate da virgole.
• default=<label> opzionale: quale versione mostrare alla prima apertura, in assenza di una preferenza di chi legge. default=default indica il blocco canonico.
• Più righe HV) nello stesso header, una per NAME.

Forma vecchia rifiutata. HV) versions: [a, b] default=a aveva un default scalare: su un brano con due NAME non era esprimibile. Produce W150 con l'indicazione della forma nuova.

5.2 Funzioni dell'HV)

• Documentazione: rende esplicite le versioni del brano nell'header.
• Ordinamento: chi offre la scelta presenta i NAME nell'ordine delle righe HV); le label nell'ordine della lista.
• Versione d'apertura: default= sceglie quale blocco si vede all'apertura. Non sposta l'àncora, che è strutturale (§4.1): cambia solo cosa si vede.

5.3 HV) opzionale

In assenza di HV), le varianti sono dedotte dai blocchi %%NAME "label" presenti nel documento, nell'ordine di apparizione, e la versione d'apertura è quella d'àncora (§4.1).

5.4 Discrepanze

Una label dichiarata in HV) ma assente nel documento (o viceversa) non è un errore: il selettore mostra solo le versioni effettivamente presenti, e un default= senza riscontro non si applica. È responsabilità dell'autore mantenere coerenza.

---

6. Preferenza di chi legge

Lo stato "versione corrente" è una preferenza di chi legge, conservata dall'host per quel brano.

• Alla prima apertura, il documento mostra il default (flusso senza blocchi %%NAME etichettati, oppure quanto dichiarato in HV) default=).
• Chi legge cambia versione con la scelta che l'host gli offre.
• La scelta vale per quel brano specifico e per quella persona.

Lo stato della versione non viene mai scritto nel file NRK: il file è immutabile rispetto alla preferenza di lettura.

---

7. Diagnostica

7.1 Codici diagnostici

Codice	Descrizione
W147	Blocco %%NAME non chiuso: il resto del file è trattato come parte sua
W148	%%end orfano (nessun blocco aperto)
~~W149~~	Ritirato — un nuovo %%NAME chiude implicitamente (§2.2/§2.4)
W150	HV) malformato, o forma vecchia HV) versions: […] (§5.1)
W151	default usato come NAME o come etichetta (parola riservata, §2.4.1)

7.2 Non-errori

• Blocchi tutti etichettati, nessun canonico: non è un errore — il primo blocco in ordine di sorgente è l'àncora (§4.1) e il selettore non offre la voce default.
• Default senza varianti (%%X solo): consentito; il blocco è una semplice sezione "preparata per future varianti".
• Label %%X "label" ripetuta più volte: l'ultima vince, senza diagnostico.

---

8. Esempi

8.1 Days of Wine and Roses con Bill Evans bridge

HT) Days of Wine and Roses
HC) Henry Mancini
HK) F
HM) 4/4
HV) BRIDGE: [default, bill_evans] default=default

M) [Intro]
// … intro …

M) [A]
// … A original …

%%BRIDGE
M) [Bridge]
// … bridge original …
%%end

M) [A]
// … A finale original …

%%BRIDGE "bill_evans"
M) [Bridge]
// … bridge ri-armonizzato Bill Evans …
%%end

8.2 Round Midnight, riscrittura totale Miles

HT) Round Midnight
HC) Thelonious Monk
HV) SONG: [default, miles] default=default

%%SONG
M) [Intro]
// … intro standard …
M) [A]
// … A originale …
M) [B]
// … B originale …
M) [A]
// … A finale …
%%end

%%SONG "miles"
M) [Intro Miles]
// … intro Miles …
M) [A]
// … A con accordi cambiati …
M) [B]
// … B con frase aggiunta …
M) [Coda]
// … coda Miles …
%%end

L'utente sceglie "miles" dal selettore → il blocco %%SONG originale è sostituito dalla riscrittura.

8.3 AABA con A "miles" che sostituisce tutte le A

%%A
// … A originale …
%%end

%%A
// … (seconda occorrenza, identica o variata) …
%%end

%%B
// … B …
%%end

%%A
// … A finale …
%%end

%%A "miles"
// … Miles version dell'A …
%%end

Attivando "miles": le tre %%A default sono sostituite dalla variante. Il %%B resta invariato.

8.4 Variante per posizione (nomi distinti)

%%A1
// … prima A …
%%end

%%B
// … B …
%%end

%%A2
// … seconda A (lievemente diversa) …
%%end

%%A2 "minor key"
// … A2 in minor mode …
%%end

Solo la seconda A è sostituibile dalla variante "minor key". La prima A non è coinvolta perché ha nome diverso (%%A1).

---

9. Riassunto

Concetto	Sintassi	Sezione
Blocco default	%%NAME … %%end	§2.1
Blocco variante	%%NAME "label" … %%end	§2.1
Chiusura blocco	%%end	§2.2
Posizione blocchi	standalone fra datapack, no annidamento	§3.1
Sostituzione	variante sostituisce tutte le %%NAME default	§4.1
Marker M)	ortogonali al nome del blocco	§4.3
Riscrittura totale	racchiudere il brano in un blocco unico (es. %%SONG)	§4.4
Header	HV) NAME: [list] default=label (una riga per NAME, opzionale)	§5
Preferenza di lettura	conservata dall'host, non nel file NRK	§6

---

Questo documento definisce le versioni del brano in neumaRk: meccanismo robusto e granulare per rappresentare arrangiamenti alternativi, ri-armonizzazioni puntuali e riscritture complete dello stesso brano dentro un singolo file.