Text lines (`TEXT)` — formatted prose positioned in the flow)¶

STATUS: SPEC. TEXT) is a global section, sibling of PLAY)/FORM) (neumaRk_play_and_form.md), LYRICS) (neumaRk_lyrics.md §8) and FOOT) (neumaRk_footnotes.md). Its content is markup-aware prose (neumaRk_text_markup.md).

The IT file is the source of truth; this EN version mirrors it (../it/neumaRk_text_line.md).

1. Definition¶

A text line TEXT) is a block of free multi-line prose rendered in the score at the position where it appears in the document (in the datapack flow, like PLAY)). It is meant for presentation lines, captions of musical examples, discursive section explanations.

Unlike PLAY)/FORM), TEXT) carries prose only: no [NAME|BARS] box, no performance tokens ($/@/fermata). Its semantics are purely descriptive (it takes no part in the musical content). Unlike FORM) (always at the end), TEXT) is positional.

TEXT) is WYSIWYG on line breaks (§3) and adds two controls:

horizontal alignment, changeable line by line (§2.2, §2.3);
vertical anchoring relative to the adjacent system (§2.4) — a new axis, at block level.

2. Syntax¶

TEXT) [<align-default>] [<vanchor>]
[<align>] <prose line 1>
[<align>] <prose line 2>
                          ← empty line = vertical space
[<align>] <prose line 3>

The TEXT) header is at the start of the line; following lines are continuation. The block ends at the first unescaped explicit line marker or at the end of the document: the single end rule of free-text blocks, neumaRk_datapack.md §13. An implicit marker row such as [Intro] does not end the block: to open a datapack with markers right after the prose, write M) [Intro].

Empty lines do NOT terminate the block (unlike PLAY)/FORM); as in LYRICS)): they are internal separators rendered as vertical space (§3.2). Leading and trailing empty lines are discarded.

2.1 Header prefix zone¶

Right after TEXT), on the header line itself, at most one <align-default> token and at most one <vanchor> token are consumed — only if consecutive and space-separated, in any order. They set the block's default alignment and the vertical anchor (which is unique for the whole block). At the first non-flag token, the prose of the first line begins.

2.2 Alignment `<align>` (vocabulary)¶

Same vocabulary as the F) format line:

Token	Alignment
`\\|*`	left
`*\\|`	right
`\\|*\\|`	center
`\\|**\\|`	justify — default

If no alignment is ever specified, the default is justify.

2.3 Inline alignment (per line, persistent)¶

Every prose line may begin with an <align> token: it changes the current alignment, which applies from that line onward until the next token (persistent behavior). A single block can thus alternate centered titles, justified body and left-aligned notes.

The flag must be a whole token at line start, followed by a space or end of line. **bold** and |pipe are NOT flags (markup is preserved).
If the line also carries a title (#/##/###), the flag must come before the hash: |*| # Title (in # |*| … the |*| would be title text).
A line containing only a flag (no prose) changes the alignment and counts as an empty line (vertical space).

2.4 Vertical anchor `<vanchor>` (per block)¶

Token	Anchor
(none)	normal flow — the block takes its own space, like `PLAY)`
`^`	top of next — anchored to the top edge of the following system
`_`	bottom of prev — anchored to the bottom edge of the preceding system

The <vanchor> lives only in the header prefix zone (§2.1) and applies to the whole block. If _ is on the first system (no predecessor) it silently degrades to normal flow (§5).

2.5 Example¶

TEXT) ^
|*| # EXAMPLE 1

|**| ### This long text is justified
and also long across several lines

|*| This one is centered

|* Back to the music:

M) [A]
C) | C7 | F7 |
N) | c1 | a1 |

^ anchors the whole block to the top of the following system; # EXAMPLE 1 is a centered H1 title; the ### … paragraph is justified H3 and breaks where written (and automatically when it exceeds the width); a centered line and a left line follow, separated by empty lines.

3. Content (prose)¶

The text reuses all of neumaRk_text_markup.md: sizes #/##/###, *italic*, **bold**, ***bold-italic***, __underline__, escape \. In the body the characters */^/_ are markup/text; alignment flags live only at line start (§2.3) and the <vanchor> only in the header (§2.4). The prose accepts footnote references [^…] (neumaRk_footnotes.md) and links [text=>url] (neumaRk_text_markup.md §3quater): since there is no [NAME] box in TEXT), they are always interpreted as such. A multi-word link wraps as a single block.

3.1 Line breaks respected (WYSIWYG)¶

Source line breaks are respected: every newline is a rendered line break. A line longer than the stave width wraps automatically (word-wrap) to stay visible. A line's size prefix (#/##/###) applies to all its wrapped lines.

3.2 Empty lines¶

An empty line renders as vertical space (paragraph separator). Multiple empty lines increase the space.

3.3 Justification¶

Justify (|**|) expands inter-word spaces to fill the width. Only lines broken automatically by word-wrap are stretched; a line closed by a source newline is not stretched (like text-align: justify with a <br>). Justification works with markup too (bold/italic/footnote marks preserved).

4. Prose that starts with a marker (escape)¶

A prose line that begins with a line marker (N), C+, HK), %%, …) would end the block (§2). To write it as prose, prefix it with \: the line stays in the block and the \ is removed when rendered (neumaRk_datapack.md §13.2).

TEXT) The reprise is played
\N) as before, but softly.

reads "The reprise is played / N) as before, but softly.". On round-trip the line is written back with the \.

5. Diagnostics¶

TEXT) emits no diagnostics. Silent cases (no warning):

empty TEXT) block (flags only, no prose) → ignored;
_ (bottom-of-prev) on the first system → degrades to normal flow;
a second alignment/anchor token in the header prefix zone → the second becomes prose, read as is (it is not a flag of the first line): the rewritten document writes it escaped (TEXT) |* |*| text → \|*| text under the header, §4).

6. Round-trip¶

The block round-trips losslessly at its position and is idempotent. Only the prefix tokens are re-emitted on the header (default alignment if ≠ justify, then <vanchor>); the prose — including inline flags and internal empty lines — goes below, verbatim. Defaults (justify, flow) are omitted. At the same position, positional blocks (PLAY)/TEXT)/LYRICS)/FOOT)) are re-emitted in file order; FORM) stays the absolute last.

7. Full example¶

nrk:0.6
HT) Yesterdays
HK) Dm
HM) 4/4

TEXT) ^
|*| # Yesterdays
|**| Ballad in Dm; the theme is stated on the first chorus,
then two improvisation choruses over the same changes.

C) Dm7 | G7
N) d4 e f g | a b c d

TEXT) _ Coda: rallentando to the last chord.

Text lines (TEXT) — formatted prose positioned in the flow)¶