# 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.

`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. Do not assume that a definition in one
movement is available in another. 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.

## 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. 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.

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.

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.