# Consolidation and normalization Normalization changes how existing music is represented. Choose the operation by what you want to change; “shorter source” can mean several different things. | Operation | What changes | | --- | --- | | Formatting | Canonical spelling and layout of the chosen source arrangement | | Compaction | Indentation, padding, and unnecessary blank lines | | Consolidation | Repeated musical material becomes shared readers and named returns | | Expansion | Shared music becomes separately written-out player parts | | Orientation | Parts-first versus measures-first, systems, or rehearsal groups | | Map placement | Settings or collection structure at the top versus beside the music | The source language for defining and reusing an exercise is in [named exercises and shared passages](reuse.md). The operations below can discover that structure in existing written-out music. They do not require rewriting every part by hand. ## Find the options in your installed engine ```text scorescript format --list scorescript docs normalization ``` The [normalization option reference](normalization-options.md) is generated from the native engine's menu, including presets and unavailable entries. Use the names shown by your installed engine. If an older installed CLI lacks an option, update that CLI; a `scorescript 0.3` file header alone does not establish which implementation features are installed. ### Updated option names Current builds use the shorter names below. Earlier names are refused with replacement guidance; they are not additional aliases. Update saved commands and application selections when updating the engine. This does not rename keywords inside your music or require rewriting your score files. | Earlier name | Current name | | --- | --- | | `orientation` | `arrange` | | `compression` | `preset` | | `maps-labels` | `labels` | | `maps-exercises` | `exercises` | | `maps-sections` | `sections` | | `chromatic-spelling` | `chromatic` | The measure-first choice is `arrange=measures`, formerly `orientation=grid`. `maps=top|inline` is unchanged and still covers musical context placement, not every map or every kind of layout break. ## Automatic musical consolidation ```sh scorescript check piece.scorescript scorescript format piece.scorescript --normalize consolidate > piece.review.scorescript scorescript check piece.review.scorescript ``` Review the new source and rendered parts before replacing the original. Never redirect output onto the input filename: the shell truncates it before the formatter can read it. `--write` is the explicit in-place alternative. Consolidation recognizes identical part material, constant spelled transpositions, octave-related readings, and repeated ranges that can become named transposed returns. It can produce both `fl5, ob4 { ... }` and `m17-32 = primary +P4`: actual reuse, not merely fewer line breaks. It re-analyzes the proposed music and abandons a rewrite if its musical comparison changes. This is not permission to discard a saved revision: printed layout and editorial text still need review. ### When consolidation leaves music alone - Fewer than two eligible parts: automatic discovery needs parts to share. It is not a general solo repetition finder. Manually authored named ranges still work for one reader. - Already-shared source: the current pass leaves a score with reader heads alone, including mixed source with additional written-out parts. - Measure-first source: first request `arrange=parts`. - Exercise containers: first request `exercises=top` if a flat collection is appropriate. The current pass acts on the score's own parts, not nested movement programs. Preserve movement boundaries. - Different musical material: a genuine variant stays written out; the pass does not approximate it to make it fit a shared line. - Independent voices, implicit parts, unaddressable names, or unsafe repeated instrument selection can prevent a part from joining. - Player-specific state and layout can require retaining a part block. `hoist-breaks` moves only matching per-part system/page maps to score scope; do not manually globalize one player's distinct page breaks. Read the operation notes on standard error. A successful command can report that a requested transformation was refused and leave that structure unchanged. Do not treat exit status alone as proof that consolidation happened. Comments attached to bodies that consolidation folds are removed. Comments in surviving bodies and at file level remain. This is separate from `strip-comments`, which explicitly removes all `//` comments. Keep important editorial commentary in a saved revision before folding its owning body. ## Presets and deliberate combinations ```text scorescript format piece.scorescript --normalize preset=readable scorescript format piece.scorescript --normalize preset=condensed scorescript format piece.scorescript --normalize preset=max ``` `readable` aligns columns and puts maps at the top. `condensed` also requests compact spacing, numeric durations, and matching-break hoisting. `max` adds actual consolidation and removal of recognized development text. It is **not** just a whitespace setting, and it is not a promise that every score can be reduced to one body. The generated reference lists each exact expansion. For an eligible written-out grid or exercise collection, an explicit request is: ```text scorescript format piece.scorescript --normalize arrange=parts,exercises=top,consolidate ``` Passes run in the engine's defined pipeline order, not as a left-to-right sequence of arbitrary rewrites. For repeated choices of the same option, the last written value wins, including across repeated `--normalize` flags. A preset expands where it appears, so `preset=max,align=on` restores alignment while keeping that preset's other selections. Do not select `expand` and `consolidate` together: they are opposing operations and the request is refused. Prefer one preset plus explicit overrides: a later preset does not cancel an earlier action that its own expansion does not mention. Spaces around `=` are allowed inside a quoted selection, such as `--normalize 'preset = condensed'`. A preset requires a value: bare `preset` is an error. Switches use `on` or `off`; bare `align` and `compact` mean `on`. Argumentless actions such as `strip-comments` do not take `=off` or any other value. To leave comments alone, omit the action; `strip-comments=off` is refused. ## Readability without changing musical ownership ```text scorescript format piece.scorescript --durations numbers scorescript format piece.scorescript --durations letters scorescript format piece.scorescript --compact scorescript format piece.scorescript --normalize arrange=measures,maps=top scorescript format piece.scorescript --normalize arrange=systems scorescript format piece.scorescript --normalize arrange=rehearsals ``` Choose part-first source to follow one player's line, and measure-first source to compare players at the same bars. System and rehearsal orientations group around those landmarks. Orientation changes can be refused when the current structure cannot be safely represented; inspect the operation notes. Use the native formatter for compaction. Newlines can separate measures or simultaneous voices; arbitrary whitespace removal can change or invalidate the music. Canonical compact source preserves the required boundaries. ## Maps, exercises, and book sections `maps=top|inline` controls meter, key, tempo, and transpose placement. It does **not** select inline versus mapped system/page cuts. The formatter chooses break-map emission separately; see [page and system layout](layout.md). It does not mean “convert every kind of map.” Written headings have `labels=top|inline`; exercises have `exercises=top|inline`; book sections have `sections=top|inline`. ```text scorescript format piece.scorescript --normalize exercises=inline,sections=inline scorescript format piece.scorescript --normalize exercises=top,sections=top ``` At the inline door, each exercise owns its music and starts locally at m1. At the top/index door, the timeline is numbered continuously. Book sections need exercise containers before they can hold them inline; request both inline operations together. See [collections](collections.md) for both forms. ## Implemented reuse versus reserved menu entries Named passage definitions and assignments are implemented. So is automatic `consolidate`, including its named returns inside shared heads. The separate `named-spans` normalization option is still marked coming: it is not the switch required to use existing named exercises. Likewise `octaves=minimal|explicit` is a reserved option, not an available setting. The formatter's current octave anchoring operates without that selector. For key-signature and accidental-spelling normalization, inspect the native menu's `key` and `chromatic` options and check both the sounding and written results. These change notation choices, not just visual padding. ## Expand before an independent rewrite ```text scorescript format piece.scorescript --normalize expand ``` This writes shared music out for its readers. Expansion preserves music, not the ongoing edit-once relationship: independently edited copies no longer follow a named source. Keep the shared original when that relationship matters. Use selective `scorescript expand --part ... --bars ...` for an individual player, with the whole-head override precautions in [shared passages](reuse.md).