# Named exercises, shared passages, and transposition ## Define once; repeat and transpose A named passage is reusable music, not a pasted copy or a formatting shortcut. Give its first range an identity, then assign that identity to later ranges. Editing the original notes changes every derived occurrence when the source is compiled again. ```scorescript scorescript 0.3 score "Primary Exercises" { meter 4/4 parts { fl tpt } fl5, tpt4 { m1-3=primary { 1F4 | E | r } m4-6 = primary +P5 m7-9 = primary -P4 } } ``` | Source | Meaning | | --- | --- | | `m1-3` | The original occupies measures 1 through 3, inclusive | | `=primary` | Its reusable identity; later assignments refer to this name | | `{ 1F4 \| E \| r }` | Whole F, whole E, then a full-bar rest in 4/4 | | `m4-6 = primary +P5` | Those three bars again, up a perfect fifth | | `m7-9 = primary -P4` | The original again, down a perfect fourth | | `fl5, tpt4` | Both instruments read the music, starting in their stated registers | This is the language's variable-like reuse form. It is **not** a standalone `"Primary Exercises" = [...]` declaration: the definition has a real place in the score, and its music belongs in braces. Square brackets have other musical meanings, including chords. `wF4` is also accepted for a whole F; numeric durations are the default canonical spelling. Use a spelled interval such as `+P5`, not an ambiguous `+5`. The number is an interval size, not a count of semitones: `+P5` is seven semitones. `+P4` is five semitones. Each assignment is relative to the named original, never to the preceding assignment. Use the passage's exact identity, not a quoted display title. The definition and its references belong in the same shared-reader body. Keep source and target lengths equal and their measure ranges distinct. A plain `m4-6 = primary` repeats without transposition. An apostrophe or comma adjusts the derived register: `= primary'` raises an octave; `= primary +P4,` raises a fourth and then lowers an octave. Named reuse does not currently create printed exercise headings or book collection entries automatically. An optional quoted title after the name is accepted by the parser, but is currently dropped by formatting and does not print an exercise heading. Do not rely on that title form. Use explicit [collection metadata](collections.md) for displayed titles, variant ranges, numbering, book membership, and cross-file exercise identity. These shared-line and collection features are implemented but provisional. ## Share one line among instruments Declare the instruments, then name several readers in one head. A register digit says where the first note lands. A signed interval changes the reading in concert pitch. These shared-line forms are provisional. ```scorescript scorescript 0.3 score "Shared tune" { parts { fl ob } fl5, ob4 { m1-2 { 4C4 D E F | 1G } } } ``` The flute receives the line beginning in octave 5 and the oboe in octave 4. A head such as `fl5, ob4 +P5` gives the oboe a fifth-up reading as well. A repeated instrument key binds occurrences in source order; a key named once can select all instances of that instrument. Too many readers are an error, not extra implicitly created instruments. ## The band warm-up pattern There are two independent savings: several instruments share one musical body, and later exercises reuse a named range of that body. Neither reduces the number of measures the musicians receive. For example, a 16-bar primary exercise can supply a 48-bar sequence: ```text m1-16=primary { ...sixteen bars of music... } m17-32 = primary +P4 m33-48 = primary -P5 ``` This is a structural excerpt, not runnable music: replace the placeholder with the actual sixteen bars. A smaller complete example follows. ```scorescript scorescript 0.3 score "Sequence" { parts { fl } fl5 { m1-2=theme { 4C4 D E F | 1G } m3-4 = theme +P4 m5-6 = theme -P5 } } ``` Each interval is relative to the named original. The second derivation does not chain through the first. `+P4` raises a perfect fourth; `-P5` lowers a perfect fifth. The source and target lengths must agree. Apostrophe and comma can adjust the derived register, as in `= theme +P4,`. The old `expand` keyword is retired. Use the range assignment form above. Shared source reuse prints the derived music; it is different from a notated repeat sign that instructs a performer to return. Only the old **source keyword** is retired. The CLI's `scorescript expand` command and the normalization pass `expand` are available editing operations. See [normalization](normalization.md) for automatically finding shared parts and named returns in already-written music with `--normalize consolidate`. ## Instrument sections and individual changes The roster `parts { fl: 2, ob, tpt: 2 }` declares five players. In a shared head, `fl5, ob4, tpt4` addresses both flutes, the oboe, and both trumpets. To give the flutes different readings, write `fl5, fl4, ob4, tpt4` instead: the repeated `fl` entries bind the first and second flute in roster order. The digit is an octave anchor, **not** a player number. ```scorescript scorescript 0.3 score "Section readings" { parts { fl: 2, ob, tpt: 2 } fl5, fl4, ob4, tpt4 { m1-2=tones { 1C4 | D } m3-4 = tones +P4 } } ``` An instrument section shares music through its readers; a book `section` groups exercises. They are different concepts, not interchangeable block heads. An explicit individual part block overrides its shared reading. That override replaces the covered head's reading, not just one edited cell. To change one player safely, expand its shared passage first and retain all required bars in the resulting part. The selective CLI operation is: ```text scorescript expand piece.scorescript --part "Flute 1" --bars 1-16 ``` It prints the proposed source without replacing the file. It can materialize more than the requested bars to preserve the whole shared head. Read its diagnostics and the diff; targeting later repeated instances can be refused when they cannot be addressed independently. For a fully written-out editing view, use `scorescript format piece.scorescript --normalize expand`. ## Concert and written pitch Catalog instruments carry their transpositions. Ordinary score source can be authored in concert pitch and extracted as the player's written part. Do not add a manual interval merely because an instrument is transposing. A part-scoped `transpose` region can mark source already written for the player. Its two values are diatonic and chromatic displacement, not a pair of octave values. The explicit no-transposition value is `0`. ```scorescript scorescript 0.3 score "Written region" { parts { clarinet } clarinet { transpose {0, 2:-1 -2, 3:0} m1-3 { 1C5 | 1D | 1C } } } ``` This provisional feature changes how the region is read. Inspect both concert and extracted written output and listen before combining differently authored sources. A transposition map belongs to the player, while meter/key/tempo maps normally belong to the whole score.