# Build a reusable method book

Keep the complete musical edition in one `.scorescript` file. Define a passage
once, return to it by name in other keys, and give genuinely different exercises
their own definitions. Use movements for independently metered studies and
exercise identities for the divisions within them. The same source supplies
notation, playback, parts, and export.

## One octave and two octaves are separate exercises

This trumpet example has a two-measure one-octave scale and a four-measure
two-octave scale. Both return a semitone lower. Their different sequences,
breaths, double bars, and line lengths belong to the definitions. Editing a
definition changes its returns too.

```scorescript
scorescript 0.3
score "Scale variants — structure proof" {
  meter none

  key {F, m7 E}

  exercises {
    exercise =one-octave {
      title "Standard Scale (1 Octave)"
      section m1-2
    }

    exercise =two-octaves {
      title "Standard Scale (2 Octaves)"
      section m3-6
    }

    exercise =one-octave-next-key {
      title "Standard Scale (1 Octave)"
      section m7-8
    }

    exercise =two-octaves-next-key {
      title "Standard Scale (2 Octaves)"
      section m9-12
    }
  }

  parts {
    tpt
  }

  tpt3 {
    system-map {m1 2, m3 4}
    m1-2=one-octave {
      4F3 G3 A3 Bb3 C4 D4 E4 F4 (,) | F4 E4 D4 C4 Bb3 A3 G3 F3 ||
    }
    m3-6=two-octaves {
      4F3 G3 A3 Bb3 C4 D4 E4 F4 (,) | F4 G4 A4 Bb4 C5 D5 E5 F5 (,)
      4F5 E5 D5 C5 Bb4 A4 G4 F4 (,) | F4 E4 D4 C4 Bb3 A3 G3 F3 ||
    }
    m7-8 = one-octave -m2
    m9-12 = two-octaves -m2
  }
}
```

The source pitches are concert pitches. Written B-flat trumpet export shows
G major followed by F-sharp major. The first scale spans written G3–G4;
the second spans G3–G5. Changing the key and choosing a register are distinct
decisions. Neither operation turns the first sequence into the second.

When the one- and two-octave versions are the SAME scale and only the
player's range decides which they read, define the scale once as a
[music object](objects.md) and let `first { … }` choose per player:

```scorescript
scorescript 0.3
score "Scales by range" {
  meter 4/4
  key open

  one = {
    4C4 8D E F G A B | 4C 8B A G F E D | 1C ||
  }

  two = {
    4C4 8D E F G A B | 4C 8D E F G A B | 4C 8B A G F E D | 4C 8B A G F E D | 1C ||
  }

  parts {
    fl C4-C7
    tpt F#3-C6
    tba E1-Bb3
  }

  all written fit {
    first { @two C, @one C }
    first { @two F, @one F }
    first { @two Bb, @one Bb }
  }
}
```

The flute reads two octaves of every key, the trumpet two of C and one of
F and B-flat, the tuba one of C and two of the rest — each from the lowest
tonic inside its declared range, each labelled with its own octave count.
An All-State packet is this head with fifteen keys and a `@scale-chromatic`
line under it.

`meter none` hides the meter and accepts free-length divisions. Keep the bars
that organize the lesson. Each `system-map` entry collects an exact number of
measures on one line: `m3 4` collects m3 through m6. The inclusive spelling
`m3-m6` means the same thing; formatting writes the count form. Placing these
collectors inside the shared reader body lets named returns inherit them.
Choose a page width and staff size at which the collected music remains readable.

## Organize the complete edition

Use [movements and collections](collections.md) to place scales, warmups, and
independently metered etudes in the same file. Stable movement and exercise IDs
allow titles and numbering to change without redefining the music. Exercise
sections describe a musical range; book sections group exercise identities.
Use one heading for each actual level of the lesson instead of repeating a
movement title in every exercise label.

Named returns currently resolve inside their containing reader body. Keep the
definition and its returns together. For a vocabulary reused by several
movements, define a [music object](objects.md) at book scope, before the
movements collection; every movement can apply it while retaining its own
roster, local bar numbers and layout. A movement-local object deliberately
shadows a book object with the same name. Separate movements can still be
retained in one authoritative file. Optional linked exercises require a
filesystem-aware reader and are described in the collections chapter.

For another instrument, use the native [reader and register](reuse.md) controls.
Review the whole exercise's lowest and highest written notes, its spelling,
clef, and intended teaching range. Preserve deliberately distinct upper and
lower variants. Practical-range diagnostics inform this review; clearing them
by folding notes into a single octave can destroy the lesson.

## State the set-up once

The pieces of a method book share their set-up: the players, the credits, a
subtitle that names the key. Say it once in the book's head, before the
movements, and every movement that does not say it itself uses it:

```scorescript
scorescript 0.3
score "Etudes in every key" {
  composer "Brandon Dicks"
  subtitle "{written-key} (Concert {concert-key})"

  parts {
    fl
    tpt
    hn
  }

  band = readers { fl +P8, tpt, hn -P8 }

  movements none {
    movement =march {
      title "March"

      meter 4/4

      band {
        at m1 { key Bb }
        m1-2 {
          4Bb3 D4 F Bb | 1Bb3 |||
        }
      }
    }

    movement =lullaby {
      title "Lullaby"
      subtitle none

      meter 3/4

      band {
        at m1 { key Eb }
        m1-2 {
          2Eb4 4G | 2.Eb |||
        }
      }
    }
  }
}
```

Both etudes are for flute, trumpet and horn, both are by Brandon Dicks, and
both read the head `band` names. The march's heading carries the book's
subtitle, so each player sees the key they read; the lullaby writes
`subtitle none`, so its heading is its title alone. Neither writes `number`: a
movement is numbered by its place in the book, and one that writes `number 7`
is number 7.

A statement in the book's head stands in every movement that has no statement
of its own of that kind, exactly as if the movement had written it:

| In the book's head | A movement uses it when |
| --- | --- |
| `composer`, `arranger`, `lyricist`, `translator` | it names none of its own; `composer none` keeps it empty |
| `title`, `subtitle` | it writes none; `subtitle none` keeps it empty |
| `meter`, `key`, `tempo`, `partial`, `clef`, `spell`, `solfege`, `rehearsal`, `prefer`, `highlight` | it writes no statement of that name |
| `parts { … }` | it declares no players (`parts { … }` or `part`); its own part bodies are read by the book's players |
| `range written { … }` | always: the movement's own entries follow the book's, and the later entry for a player wins |
| `range catalog`, `range none` | it writes no `range` statement of its own |
| music objects, rhythms, `use`, reader sets | always; a movement's own definition of one name is used in that movement |

Statements addressed by bar — `at m5 { … }`, `meter {m9 3/4}`,
`system-map`, `page-map` — and the book's own `book { … }`, `text-page`,
`sections` and `numbering` belong to one timeline or to the volume, and no
movement takes them. A chapter written as another in a new key takes its
set-up from the chapter it is, and a chapter pulled with `movement from` brings
the set-up of the book it was written in.

A chapter written as another **cannot keep an inherited slot empty**:
`movement =g-scales = c-scales in F { subtitle none }` is refused
(`chapter.slot-inherited`), and so are `lyricist none` and `translator none`
there. `none` in the SOURCE is not the answer either — it would empty the slot
for the source and for every other chapter written as it. A chapter that needs
a heading of its own is written out in full, where every head statement is its
own to write.

`band = readers { fl +P8, tpt, hn -P8 }` names a reader head. Write the name
wherever a head is written — `band { … }`, `band written fit { … }`, or beside
other readers as `band, pno { … }` — and it reads exactly as the head it names.
The readings stay in the head: the roster still says only who plays. A set is
seen after its definition, in the book or movement that defines it. A second
set of one name (`reader-set.duplicate`), a name that is already a music
object or rhythm (`reader-set.name-taken`), an empty set (`reader-set.empty`),
`all` or a set inside a set (`reader-set.nested`), a register or interval on
the set's name (`reader-set.modified`), and `title` or `subtitle` in a score
with no movements (`setup.without-movements`) are refused by name.

### What a set's readers open with

The chapters of a book are held to the written ranges its head states; its
etudes are not. Say how the etude band reads where the band is named:

```scorescript
scorescript 0.3
score "Etudes in every key" {
  range written { fl C4-C6, tpt F#3-C5 }

  parts {
    fl
    tpt
  }

  band = readers { fl +P8, tpt } with { transpose 0 range catalog }

  movements none {
    movement =march {
      title "March"

      meter 4/4
      key Bb

      band {
        m1-2 {
          4Bb4 D5 F Bb | 1Bb4 |||
        }
      }
    }
  }
}
```

`with { transpose 0 range catalog }` opens every head that names `band` with
those statements at its first bar, exactly as if the head had written
`at m1 { transpose 0 range catalog }` — `m0` in a movement that opens with a
pickup. The march's flute reads up to written B-flat 6, past the book's C4–C6,
because `range catalog` hands its range back to the catalog's advice. A
statement of the same name the head writes at that bar is its own and stands
instead. The book's head could not say this: a player's own `range` outranks
the book's map, so a range stated for every movement would release the
chapters too.

A set opens its readers with what a player carries from bar to bar — `key`,
`clef`, `transpose`, `range`, `highlight`, `spell`, `solfege` and `prefer`;
`meter`, `tempo` and `partial` belong to the score (`context.scope`). A head's
opening statements govern every reader in it, so a set that carries some is
written in a head of its own (`reader-set.opening-shared`).

### Write the set-up out, or state it once

```text
scorescript format book.scorescript --normalize setup=explicit,numbers=explicit,readers=explicit
scorescript format book.scorescript --normalize setup=shared,numbers=derived,readers=named
```

`setup=explicit` writes every statement a movement uses from the book into the
movement; `setup=shared` states once in the book's head what every written-out
movement repeats, and takes it out of the movements. With
`setup-quorum=most`, a credit or subtitle most movements repeat is stated once
too, and the movements that have none write `none`; so is the title the most
movements repeat, and the movements with another title keep their own.
`numbers=derived` leaves out every `number` that equals the movement's place
and `numbers=explicit` writes them all. `readers=named` writes a set's name
wherever a head holds its readers and, for a set that opens them `with { … }`,
opens with exactly those statements; `readers=explicit` spells every head out,
statements and all. A set of ONE reader is written out as that reader alone
(`pno { … }`) and read back as the head it is, not as a part body, so both
doors cross for it as well. Each result compiles to the same MusicXML and
pages as the file it came from.

## Write a chapter once and print it in every key

A method book often prints one chapter of exercises in twelve keys. Write the
chapter once as an ordinary movement, then write every other key as that
chapter in a new key:

```scorescript
scorescript 0.3
score "Scales in every key" {
  range written { tpt F#3-G5, hn C3-G5 }

  parts {
    tpt
    hn
  }

  one-octave = {
    4C4 D E F G A B C5 | C5 B4 A G F E D C |||
  }

  two-octaves = {
    4C4 D E F G A B C5 | C5 D E F G A B C6 | C6 B5 A G F E D C | C5 B4 A G F E D C |||
  }

  book { independent-parts }

  movements none {
    movement =c-scales {
      title "{written-key} Scales (Concert {concert-key})"

      meter none
      key open

      page before =again { tpt }

      exercise "Scale" =scale {
        all fit {
          first { @two-octaves Bb, @one-octave Bb }
        }
      }

      exercise "Scale Again" =again {
        all fit {
          @one-octave Bb
        }
      }
    }

    movement =f-scales = c-scales in Eb {
      range written { tpt F#3-C6 }

      page before =again { hn }
    }
  }
}
```

`movement =f-scales = c-scales in Eb` reads like an assignment: the chapter
`f-scales` is `c-scales` in E-flat. Its own id is required, and it stays the
address books, layouts and links use. The key of a chapter is the tonic of its
first object application — here `@two-octaves Bb`, the key `{concert-key}`
prints — and every application in the chapter moves by the interval from that
key to the new one. Choices made by range (`fit`, `first { }`, `fits { }`,
`if range contains`) are made again in the new key: the horn reads two octaves
of concert B-flat and one of concert E-flat. Titles that use `{written-key}`
and `{concert-key}` follow the new key.

The block after the key says what is different about this key, and nothing else:

- **Head statements** — `number`, `title`, `subtitle`, credits,
  `meter`, `tempo` and `range written { … }`. A statement stands after the
  source chapter's statement of the same name, the way a chapter's statements
  stand after the book's.
- **Ranges start from the book.** A range the source chapter states for its
  own key (its `range written`, a `range` statement, a bound on a roster line)
  stays with that chapter. The instance holds its players to the book's ranges,
  plus the `range written { … }` it writes itself; write there only what is
  genuinely different about this key.
- **`page before =exercise { readers }`** — who turns the page before one of
  the source's exercises in this key. The named readers open that exercise on
  a new page and every other reader does not; `{ }` names nobody. The turn
  lands where each reader opens that exercise — its first body there — and a
  later body the same reader reads inside the exercise keeps what it wrote.
  One line names every exercise the same readers turn before:
  `page before =again, =finale { hn }`. The source's own turns carry to its
  instances, and an instance's line for an exercise replaces them.

Only music applied through objects moves. A chapter that writes notes
directly, anchors a pattern to a register (`@scale-major C4a {q8}`) or states a
key signature cannot be printed in another key this way
(`chapter.literal-music`): moving written notes would mean guessing their
octave. A chapter written as an instance of another instance is the source's
chapter moved twice, and carries both blocks' statements. An id no chapter has
(`chapter.unknown-source`), an instance of itself or a loop of instances
(`chapter.cycle`), music inside the block (`chapter.instance-body`) and a
`page before` name the source does not have (`chapter.page-before-unknown`)
are refused by name. Two movements with one id (`movement.duplicate-id`) and
two exercises with one id in a movement (`exercise.duplicate-id`) are refused
too.

Any movement says its own turns the same way. The C chapter above writes its
second exercise once, for everyone, and `page before =again { tpt }` puts the
trumpet alone on a new page; writing the exercise twice — once under the
trumpet with `\p` at the head of its body, once under everyone else — prints
the same pages.

### Write it out, or write it as an instance

The two forms are the same music, and the formatter crosses between them:

```text
scorescript format book.scorescript --normalize chapters=explicit
scorescript format book.scorescript --normalize chapters=instances
```

`chapters=explicit` writes every instance out as the full chapter it stands
for — the way to give one key music of its own — with that chapter's range
exceptions against the book. `chapters=instances` finds each chapter that
equals an earlier chapter in another key, differing only in head statements,
ranges and page turns, and writes it as an instance whose `range written`
names only the ranges that differ from the book's. A chapter with
any other difference stays written out, and every exercise the same readers
turn before is named on one `page before` line. Either result compiles to the
same MusicXML and the same printed pages as the file it came from.

```text
scorescript format book.scorescript --normalize page-turns=heads
scorescript format book.scorescript --normalize page-turns=lines
scorescript format book.scorescript --normalize page-turns=combined
```

`page-turns=heads` writes every turn a written-out movement can hold as `\p` at
the head of the bodies that turn; `page-turns=lines` writes an exercise whose
heads differ only in who opens it with `\p` once, with one `page before` line
per exercise; `page-turns=combined` also names every exercise the same readers
turn before on one line. An instance keeps its lines, one per exercise under
`heads`.

## Check, format, and export the native source

When complete native scores already exist, import them once with `scorescript
book`. An empty volume template owns the title, book furniture, and instructional
pages. Each standalone input needs the stable movement ID it will have in the
master. A multi-movement input keeps its own IDs and order. For example:

```text
scorescript book --template volume.scorescript --input warmups warmups.scorescript --input scales scales.scorescript --input etudes etudes.scorescript -o method-book.scorescript
```

The command uses the native AST and formatter, preserves comments and named
returns, and writes one self-contained master. Edit that master from then on.
It does not create ongoing links to the input files. Duplicate movement IDs,
inputs with volume-owned furniture/text, and shared outer musical context in
multi-movement inputs are refused. Place that context inside each movement
before importing. An explicit standalone `movement-title` becomes the movement
title; a distinct original score title becomes its subtitle. Move an imported
volume's outer extensions into the template or their owning movement before
combining it. Template credits and extensions survive formatting. An existing
output file is refused rather than replaced.

Save the complete example as `method-book.scorescript`. The native CLI workflow
is:

```text
scorescript check method-book.scorescript --format json
scorescript format method-book.scorescript --write
scorescript check method-book.scorescript --format json
scorescript pdf method-book.scorescript --part tpt --transposed -o method-book.pdf
```

For a multi-movement file, native CLI PDF export includes all movements by
default. Add `--movement ID` to select one. MusicXML export selects an individual
movement with the same option. Check the host's export scope explicitly;
seeing a whole-book preview alone does not establish what its export selects.

Source owns notes, variants, headings, and musical line constraints. A native
layout file owns engraving choices such as paper and staff size. An external
assembly script or parallel music JSON file is unnecessary for this workflow.
See [layout](layout.md) for the supported controls.

Compile success establishes that the language accepts the book. Before printing,
inspect the exported pages: inventory every lesson and instruction against the
reference, confirm written pitch and registers, check repeats and navigation,
and inspect line breaks, headings, and clipping. Cover, contents, folios, and
running heads are supported book furniture. Write each rights notice beside
`composer` at the head of the score — `copyright "© 2026 The Author. All Rights
Reserved."`, and another `copyright` line for an arrangement or permission
notice; a movement that states none carries the volume's. By default a book
prints its title and author on its cover or, without a cover, in every running
head, and every notice in the foot of every page. Which lines print, where, and
in what case is the layout's `book_furniture` option.

## Worksheets, instructions and notes on a page: `text-page`

Words that are not lyrics go on a `text-page`: a worksheet, the instructions
above an exercise, descriptions under the music, practice notes, a preface, a
blank page. With `excerpt` it is also how you print one page carrying the
music **and** its description together, which is what a worksheet usually is.

Native instructional pages use
`text-page =id { before =movement heading "Title" paragraph "Text" }` at volume
level. Each block owns one page; omit `before` to place it after all movements.
Equal anchors retain source order. An empty block deliberately creates a blank
page. Text that does not fit is refused instead of clipped.

Headings, paragraphs and hanging bullets can carry their own typography. Sizes
and before/after spacing are in points, so they keep their printed size when the
music's staff size changes. Use `align left`, `center` or `right`, and `style
regular`, `bold`, `italic` or `bold-italic`. Omitted properties use the book's text
roles. A page can set `vertical middle` or `vertical bottom` to position its ink
within the margins; contents pages retain top alignment.

```scorescript
scorescript 0.3
score "Creating a Sound" {
  text-page =opening {
    vertical middle
    heading "Creating a Sound" { size 36 align center style bold after 12 }
    paragraph "Make some noise!" { size 24 align center }
  }

  text-page =tips {
    heading "Helpful tips" { size 20.5 after 8 }
    columns {
      column {
        bullet "Make a steady sound." { size 12 after 0 }
        bullet "Rest, then repeat." { size 12 }
      }
      column {
        paragraph "Listen to a partner." { size 12 style italic }
      }
    }
    paragraph "Continue below both columns." { size 12 before 8 }
  }

}
```

A `columns` block has two to four equal-width prose columns with a 12-point
gutter. Each accepts headings, paragraphs and bullets. Columns begin together;
the next block starts below the tallest one. Music excerpts stay outside prose
columns. Text sizes must be positive, spacing nonnegative, and values no larger
than 10000 points. A word wider than its column or text taller than the page
produces a diagnostic instead of clipping.

Place `excerpt =study m1-4` between headings and paragraphs to show music from
the visible movement `=study`. The inclusive range must contain complete systems
in the selected layout. The example uses the same engraved notes, key, and slurs
as that movement and adds no measures to playback. Changing the music updates
the example. Missing references, partial systems, and overflowing pages are
refused with a diagnostic.

`book.excerpt-boundary` says the excerpt is **too wide** for the text page. The
measurement is the ink of the excerpted systems together with the text marks
attached to them, not the number of staves: a grand staff excerpts like any
other movement. The usual cause is one long attached text mark — a section
label such as `("PENTASCALE ASCENDING AND DESCENDING")` on a note — whose
ink runs past the page's content box while the music itself fits. Shorten that
mark, or move it out of the music: a label that names the section belongs in a
`heading` between excerpts, where the page can wrap it. An excerpt is drawn at
its own movement's staff size, so a page that is too **tall** is fitted by
lowering that movement's `staff_size_mm` in `movement_overrides`.

To make the instructional page the published form of its movement, add
`replace-music` beside `before =study`. Its excerpts must contain every retained
bar of that movement exactly once, in order. Several pages with the same anchor
can divide the music between them. ScoreScript then prints those composed pages
and points the contents at the first one. Without `replace-music`, the example
page and the movement's ordinary music pages both print. Missing, repeated or
reordered bars refuse the replacement; the music remains defined once.

For a boxed practice passage, name its first and last notes in the music and
write `excerpt =study m1-4 { box =trouble-start =trouble-end }`. The box uses
those notes' engraved bounds; use the same name twice for a single note. Names
must resolve uniquely within the excerpt. See [structure](structure.md) for note
names and [layout](layout.md) for the system and paper choices.

Named passage returns preserve the original note names and give copied notes
destination-qualified names, such as `trouble-start-m40` for a copy in m40.
An occupied name receives a numeric suffix. Original instructional references
therefore remain stable when the passage is reused in another key.

## Check which documentation a tool is using

The chapter source is shared by the native wiki, CLI, and MCP documentation.
`scorescript docs --manifest`, the MCP resource
`scorescript://docs/manifest`, and the website's `/reference/docs.json` expose
the documentation bundle fingerprint and engine version. Compare both when a
tool appears to teach an older spelling. The fingerprint checks content drift;
it is not an authenticity signature and does not update an installed client.