Vai al contenuto

Specifica formale

1. Scopo del documento

Questo documento definisce la specifica formale del linguaggio neumaRk.

Stabilisce in modo normativo:

  • quali costrutti sono validi
  • come devono essere interpretati
  • quali regole devono essere rispettate da parser, validatori e strumenti di rendering

Tutto ciò che è descritto in questo documento è da considerarsi vincolante, salvo il livello informativo di resa di riferimento (§2).

2. Livelli della specifica

La specifica neumaRk è organizzata in più livelli, ciascuno con responsabilità precise:

  1. Livello sintattico

  2. definisce la grammatica testuale

  3. stabilisce quali sequenze di caratteri sono valide

  4. Livello strutturale

  5. definisce la struttura logica del documento

  6. stabilisce le relazioni tra le varie sezioni

  7. Livello semantico

  8. definisce il significato musicale dei costrutti

  9. chiarisce ambiguità e casi limite

  10. Livello di validazione

  11. definisce le condizioni di validità

  12. stabilisce gli errori e gli stati non validi

  13. Livello di resa di riferimento (informativo)

  14. descrive come l'implementazione di riferimento disegna i costrutti: glifi e codepoint, font, fattori di scala, corpi, colori, distanze
  15. non è vincolante: un'implementazione conforme rispetta le regole di notazione, non questi parametri

Le regole di notazione restano normative anche quando stanno in una sezione intitolata «Resa» o «Render»: quali segni compaiono, dove rispetto al rigo e alle note, a cosa si ancorano, con quale cornice. I passaggi che descrivono soltanto la resa di riferimento sono marcati Resa di riferimento (informativa); dove una regola normativa cita un parametro di disegno (un codepoint, un font, un fattore), quel parametro è informativo.

Resa di riferimento (informativa). La partitura è disegnata con un inchiostro unico: note, sigle, label, cornici, linee e testi hanno lo stesso colore. Fanno eccezione i link (neumaRk_text_markup.md §3quater), distinti a schermo; in stampa tutto esce in nero.

2.1 Contesto musicale persistente

Il parsing di un documento neumaRk avviene all’interno di un contesto musicale persistente.

Il contesto musicale conserva le ultime informazioni esplicite rilevanti (altezze, durate, stato metrico) e persiste lungo l’intero documento, attraversando:

  • righe;
  • misure;
  • datapack consecutivi.

Il contesto musicale non viene automaticamente resettato all’inizio di un nuovo datapack.

Un datapack rappresenta un’unità strutturale e di sincronizzazione verticale, ma non costituisce un confine semantico per la deduzione musicale.

In assenza di valori espliciti, le regole di deduzione fanno sempre riferimento allo stato corrente del contesto musicale.

3. Terminologia normativa

In questo documento si utilizzano i seguenti termini con significato normativo:

  • deve / non deve: requisito obbligatorio
  • può / può non: comportamento opzionale
  • non è valido: il documento deve essere rifiutato
  • viene interpretato come: comportamento deterministico

4. Uso contestuale dei simboli

Alcuni simboli testuali di neumaRk hanno una semantica contestuale, determinata dal tipo di riga musicale in cui compaiono. L'algoritmo normativo con cui il tipo di riga stesso viene dedotto (in assenza di marcatore esplicito) è in neumaRk_datapack.md §3.bis.

In particolare:

  • il simbolo . (punto)
  • il simbolo ! (punto esclamativo)

assumono significati differenti a seconda che compaiano in:

  • righe di note (N));
  • righe di accordi (C)).

Essi assumono significati differenti, anche all'interno delle stesse righe, a seconda della loro posizione.

Il contesto di riga e la posizione in relazione agli altri elementi della riga sono sempre sufficienti a risolvere la semantica del simbolo in modo deterministico.

Non esiste alcun caso valido in cui un simbolo possa essere ambiguo all’interno dello stesso contesto di riga.

5. Identificazione del documento e estensione

Un documento neumaRk è un file di testo codificato in UTF-8.

L’estensione di file raccomandata per i documenti neumaRk è:

.nrk

L’uso dell’estensione .nrk consente a strumenti, editor e sistemi operativi di riconoscere in modo affidabile i documenti neumaRk.

L’estensione è raccomandata ma non obbligatoria.
Un documento è considerato valido in quanto documento neumaRk in base al suo contenuto, e non in base al nome del file o alla sua estensione.

Gli strumenti possono assumere l’estensione .nrk come predefinita in fase di lettura o scrittura di file neumaRk.

6. Struttura generale di un documento neumaRk

Un documento neumaRk può contenere, in ordine:

  1. Header (metadati)
  2. Contenuto musicale e contenuto di formattazione

L’ordine delle sezioni è significativo e deve essere rispettato.

Delimitazione strutturale

In neumaRk, un rigo vuoto ha valore strutturale.

I righi vuoti delimitano blocchi logici del documento, in particolare:

  • la fine dell’header;
  • la separazione tra datapack musicali consecutivi.

Un blocco strutturale (header o datapack) è sempre costituito da una o più righe non vuote consecutive.

7. Riferimenti ai documenti correlati

La presente specifica fa riferimento ai seguenti documenti:

  • neumaRk_overview.md
  • neumaRk_formats.md
  • neumaRk_header.md
  • neumaRk_datapack.md
  • neumaRk_markers.md
  • neumaRk_chords.md
  • neumaRk_notes_and_durations.md
  • neumaRk_grace_notes.md
  • neumaRk_voices.md
  • neumaRk_articulations.md
  • neumaRk_fingering.md
  • neumaRk_lyrics.md
  • neumaRk_flow_and_repeats.md
  • neumaRk_dynamics.md
  • neumaRk_text_markup.md
  • neumaRk_play_and_form.md
  • neumaRk_text_line.md
  • neumaRk_play_directive.md
  • neumaRk_versions.md
  • neumaRk_collections.md
  • neumaRk_footnotes.md

Ciascun documento approfondisce in modo normativo un aspetto specifico del linguaggio.

8. Compatibilità e versioning

Ogni file neumaRk scambiato (esportato, importato, condiviso) deve dichiarare esplicitamente la versione del linguaggio utilizzata. La prima riga del file deve riportare la sequenza nrk: seguita dalla versione di riferimento nella forma major.minor (dettagli in neumaRk_header.md §2)

esempio

nrk:0.6

Le regole di compatibilità tra versioni e l'evoluzione del linguaggio sono documentate nel neumaRk_changelog.md.

9. Estensioni

Il linguaggio neumaRk può essere esteso solo nei limiti esplicitamente consentiti dalla specifica.

Un costrutto non definito o non riconosciuto non è valido e il parser lo segnala con un diagnostico. La lettura però prosegue: il costrutto si scarta o si ripara nel modo descritto dal documento che lo riguarda, e il resto del brano resta leggibile.

I diagnostici sono di due severità. Un errore (E###) segnala un costrutto non valido, che il parser ripara o scarta prima di proseguire; un avviso (W###) segnala un costrutto ammesso ma probabilmente non voluto, o un valore ignorato. Nessuno dei due interrompe la lettura del documento. L'elenco completo dei codici è nel neumaRk_changelog.md.