Vai al contenuto

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:

  1. Container — […] (con box) oppure "…" (senza box).
  2. Stile di default — determinato dal costrutto ospitante (marker, comment-label, annotation, prosa, ecc.).
  3. 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.