Markup testuale¶

Questo documento definisce la sintassi e la semantica del markup testuale in neumaRk: regole comuni di formattazione applicabili a tutti i container testuali del linguaggio (marker, end-decorator, comment-label, annotation note, label di sezione, prosa di forma).

L'obiettivo è fornire un sistema unificato e ortogonale in cui un primo asse decide il box grafico (container), un secondo asse decide lo stile di default (costrutto ospitante), e un terzo asse — opzionale — consente all'utente di applicare markup esplicito.

1. Tre assi ortogonali¶

Il rendering del testo in neumaRk è funzione di tre assi indipendenti:

Container — […] (con box) oppure "…" (senza box).
Stile di default — determinato dal costrutto ospitante (marker, comment-label, annotation, prosa, ecc.).
Markup utente — opzionale, definito tramite un sottoinsieme di Markdown applicato dentro il container.

Nessuno dei tre assi vincola gli altri. Lo stesso testo può essere espresso in qualunque combinazione di box/no-box, qualunque default semantico, con o senza markup esplicito.

Eccezione: marker M). Nei marker della riga M) (sezioni e annotazioni, vedi neumaRk_markers.md §3.1) il container […] vs "…" porta anche semantica strutturale, non solo box grafico: […] = sezione (target di PLAY/FORM, delimita scope collassabili), "…" = annotazione (testo descrittivo, non strutturale). La regola di "intercambiabilità sintattica" di §2.1 ha quindi un'eccezione normativa in M).

2. Container testuali¶

2.1 Forme¶

Un container testuale è una sequenza di caratteri delimitata da:

[ … ] → container con box;
" … " → container senza box.

Le due forme sono sintatticamente intercambiabili in ogni contesto che ammette uno dei due. La differenza è la presenza del box grafico nel rendering, fatta eccezione per i marker della riga M) dove le due forme portano anche semantica strutturale distinta (sezione vs annotazione, vedi neumaRk_markers.md §3.1).

2.2 Dove si applica il markup¶

Il markup definito in questo documento si applica a tutti i container testuali del linguaggio:

Costrutto	Container ammessi	Riferimento
Sezione `M)`	`[…]`	`neumaRk_markers.md` §3.1
Annotazione `M)`	`"…"`	`neumaRk_markers.md` §3.1
End-decorator testuale	`[…]`, `"…"`	`neumaRk_flow_and_repeats.md` §4.3
Comment-label chord / group / row	`[…]`, `"…"`	`neumaRk_chords.md` §7
Annotation note	`[…]`, `"…"`	`neumaRk_notes_and_durations.md` §8
Annotation dinamiche `D)`	`[…]`, `"…"`	`neumaRk_dynamics.md` §3.4
Label articolazione `A)` (onda, staffa)	`"…"`	`neumaRk_articulations.md` §10.2/§10.3
Top/bottom label box di sezione	`"…"`	`neumaRk_play_and_form.md` §3.3
Prosa libera in `PLAY)` / `FORM)`	tutta la prosa	`neumaRk_play_and_form.md` §5

Il markup non si applica a:

valori dell'header (titolo, credits, year, style, key, meter, BPM), che sono renderizzati in modo autonomo dal sistema;
nomi tecnici dei marker quando referenziati in PLAY) / FORM), dove il matching è per text-equality (il markup, se presente, è applicato in display ma stripped per il matching);
volta begin (|[1.]), che è un container simil-box predeterminato e non ammette markup interno.

3. Sintassi del markup¶

Il markup neumaRk è un sottoinsieme di Markdown, scelto per essere deterministico e single-line.

3.1 Dimensione del testo¶

I 3 prefissi #/##/### selezionano una dimensione relativa che dipende dal ruolo size del costrutto (vedi §5):

role reduced (default per: comment-label chord/group/row, annotation note, annotation D), label PLAY/FORM, annotation marker "…"): il default è la dimensione più piccola; i prefissi scalano solo SOPRA.
role body (default per: marker M) [NAME], prosa PLAY/FORM): il default è la dimensione media; i prefissi scalano SOPRA e SOTTO.

Prefisso	role `reduced`	role `body`
`#`	grande (2.0× default)	grande (1.5× default)
`##`	medio (1.5× default)	medio (1.0× default = body)
`###`	default (1.0×, = no prefix)	piccolo (0.7× default)

Regole:

lo spazio dopo #/##/### è obbligatorio: #hashtag è letterale, # title apre lo span;
il prefisso compare solo all'inizio del testo del container o all'inizio di un run di prosa (in PLAY) / FORM), dopo un token strutturale o all'inizio del body);
lo span aperto da #/##/### si chiude al primo dei seguenti eventi: fine del container, prossimo token strutturale in PLAY) / FORM) ([…], &kw, $, @);
#### e oltre sono trattati come letterali;
### è ammesso per esplicitare il proprio livello size anche se è ridondante col default (es. in role reduced).

3.2 Enfasi¶

Tre forme di emphasis, attivate da delimitatori in coppia:

Sintassi	Effetto
`foo`	italic
`foo`	bold
`*foo*`	bold + italic

Regole:

gli span sono delimitatori chiusi: un * non chiuso è letterale (nessun render parziale);
l'asterisco chiudente deve essere preceduto da contenuto non vuoto;
gli span possono comparire in qualunque posizione del testo;
non è ammesso annidamento di emphasis (per esempio **foo *bar* baz** non è valido): la forma ***foo*** è atomica.

3.3 Underline¶

Sintassi attivata dal doppio underscore:

Sintassi	Effetto
`__foo__`	underline

Regole:

come gli span di emphasis, lo span è delimitatore chiuso: un __ non chiuso è letterale;
il __ chiudente deve essere preceduto da contenuto non vuoto;
lo span può comparire in qualunque posizione del testo;
underscore singolo _ è letterale: _x_ non è italic alternativo (NRK non adotta la convenzione Markdown di _ come alias di *);
___foo___ (tre o più underscore di apertura/chiusura) è trattato come letterale, analogamente a #### per i prefissi di dimensione.

Underline non è una forma di emphasis: è un asse ortogonale a bold/italic. La regola "non annidamento di emphasis" di §3.2 non si applica all'underline.

3.4 Combinazione¶

Più span di emphasis possono coesistere nello stesso testo, purché disgiunti:

*foo* and **bar**            ✓  italic + bold disgiunti
*foo and **bar***            ✗  annidamento non ammesso
***foo*** plain ***bar***    ✓  due span bold-italic disgiunti

L'underline è un asse ortogonale: può coesistere con bold e italic nello stesso span:

**__foo__**                  ✓  bold + underline
*__foo__*                    ✓  italic + underline
***__foo__***                ✓  bold + italic + underline
__**foo**__                  ✓  ordine delimitatori libero
__*foo* and **bar**__        ✓  underline su span con emphasis disgiunti interni

Uno span di emphasis o underline può coesistere con un prefisso di dimensione: il prefisso vale per l'intero span del testo, gli altri delimitatori modificano solo la porzione interna:

# Title with **bold** and __underline__ words

4. Escape¶

Il carattere \ (backslash) precede un meta-carattere per renderlo letterale.

Token	Forma escaped
`*`	`\*`
`_`	`\_`
`#`	`\#`
`[`	`\[`
`]`	`\]`
`"`	`\"`
`\`	`\\`

L'escape \_ serve quando si vuole inserire un __ letterale in un testo che dovrebbe esserne consumato dal markup (raro: i singoli _ sono già letterali by default).

Esempi:

M) | [The \*Real\* Book] |
c4"track \#3"

Un \ non seguito da un meta-carattere è letterale.

5. Stile di default per costrutto¶

Il container […] vs "…" decide solo la presenza del box. Lo stile di default (size, weight, italic) è proprietà del costrutto ospitante.

Costrutto	Default style
Marker `M)` `[NAME]`	bold, size body (role `body`, vedi §3.1)
Annotation marker `M)` `"…"`	plain, size ridotta (role `reduced`)
End-decorator testuale	plain, size body (role `body`)
Comment-label chord / group / row	italic, size ridotta (role `reduced`)
Annotation note	plain, size ridotta (role `reduced`)
Annotation dinamiche `D)`	plain, size ridotta (role `reduced`)
Top/bottom label box PLAY/FORM	plain, size ridotta (role `reduced`)
Prosa PLAY/FORM	plain, size body (role `body`)

Il role size decide come i prefissi #/##/### scalano sopra al default (vedi §3.1 tabella). I costrutti role body ammettono ### per scendere SOTTO il default; quelli role reduced no (### = default).

Il markup utente (§3) sovrascrive sempre il default. Per esempio in comment-label chord"*plain*" resta italic (default del costrutto) e applica * come override visivo addizionale.

6. Regole di parsing¶

6.1 Disambiguazione `[…]` per ruolo¶

In neumaRk il delimitatore […] è condiviso fra più costrutti (polychord, volta, end-decorator, comment-label, annotation note, grace block, ecc.). La disambiguazione è posizionale e definita nelle spec dei singoli costrutti. Una volta che il parser ha identificato il ruolo del […], il contenuto è interpretato secondo le regole di questo documento.

6.2 Single-line dentro container¶

I container […] e "…" sono single-line: non ammettono caratteri di nuova riga. Una ] o " non chiusa entro fine riga è errore di parsing.

La prosa di PLAY) / FORM) ammette continuazione di riga (vedi documenti correlati).

6.3 Container vuoti¶

[] e "" sono letterali: non vengono interpretati come container.

6.4 Prefissi riservati¶

In annotation note, se il primo carattere dopo l'apertura del container è $ seguito da una lettera maiuscola riservata ($F, $S, ecc., vedi neumaRk_notes_and_durations.md §8), il markup è disabilitato sull'intera annotation: il contenuto è interpretato come direttiva strutturale (fingering, string number, ecc.).

7. Casi limite¶

7.1 Markup nei nomi di reference¶

Dentro [NAME] di reference in PLAY) / FORM), il NAME è interpretato come testo. Il markup interno è applicato in display ma rimosso prima del matching con i marker definiti:

PLAY) [**Solo**] [A]

[**Solo**] cerca un marker chiamato "Solo" e lo rende in bold se trovato. Se il NAME contiene markup non chiuso o malformato, il fallback è il matching letterale comprensivo dei caratteri di markup.

7.2 Spazi attorno ai delimitatori di emphasis e underline¶

A differenza di Markdown standard, neumaRk non richiede che i delimitatori (*, __) siano "tight" rispetto al contenuto: * foo * è equivalente a *foo*, __ foo __ è equivalente a __foo__. La scelta riduce errori comuni e mantiene il markup più tollerante.

7.3 Mix di container in costrutti che ne ammettono entrambi¶

Sezioni che ammettono entrambi i container ([…] e "…") possono usarne liberamente in punti diversi dello stesso documento. La scelta è guidata dal significato grafico voluto (con o senza box).

M) | [Intro] | "freely" | [Verse 1] |

8. Riassunto¶

Asse	Valori	Decide
Container	`[…]` / `"…"`	box / no-box
Costrutto	marker, label, annotation, …	size + weight + italic di default
Markup utente	`…`, `…`, `__…__`, `# …`, ecc.	override esplicito

I tre assi sono ortogonali. Nessuno dei tre vincola gli altri.

Questo documento definisce il sistema di formattazione testuale unificato di neumaRk, applicabile a tutti i container testuali del linguaggio.

Markup testuale¶

1. Tre assi ortogonali¶

2. Container testuali¶

2.1 Forme¶

2.2 Dove si applica il markup¶

3. Sintassi del markup¶

3.1 Dimensione del testo¶

3.2 Enfasi¶

3.3 Underline¶

3.4 Combinazione¶

4. Escape¶

5. Stile di default per costrutto¶

6. Regole di parsing¶

6.1 Disambiguazione […] per ruolo¶

6.2 Single-line dentro container¶

6.3 Container vuoti¶

6.4 Prefissi riservati¶

7. Casi limite¶

7.1 Markup nei nomi di reference¶

7.2 Spazi attorno ai delimitatori di emphasis e underline¶

7.3 Mix di container in costrutti che ne ammettono entrambi¶

8. Riassunto¶

6.1 Disambiguazione `[…]` per ruolo¶