# Source arrangements and output views

## Choose the axis you actually want to change

Source organization, musical reuse, and printed layout are separate choices.
A measures-first file can print a full score or one player's pages. A
parts-first file can do both as well. Neither arrangement means “Score Page”
or “Parts Page.”

| Choice | Forms | How to change it | Important boundary |
| --- | --- | --- | --- |
| Music organization | Parts-first; measures-first | `arrange=parts` or `arrange=measures` | Reorganizes code, not selected output |
| Source grouping | System or rehearsal groups | `arrange=systems` or `arrange=rehearsals` | Uses existing musical/layout boundaries; may decline unsupported structure |
| Repeated music | Written-out parts; shared reader heads and named returns | `consolidate`; supported `expand` operations | Actual reuse is not whitespace compression |
| Musical settings | Header maps; in-place settings | `maps=top` or `maps=inline` | Meter/key/tempo/transpose, not system/page cuts |
| Headings | Label maps; inline headings | `labels=top` or `labels=inline` | Keep heading identity and address |
| Exercise organization | Exercise index; exercise containers | `exercises=top` or `exercises=inline` | Different from naming a reusable music span |
| Book organization | Section index; section containers | `sections=top` or `sections=inline` | Book sections are not instrument sections |
| Engraved breaks | Inline cuts; addressed maps/layout block | Author in the correct scope; formatter chooses compact projection | No general `maps=inline` break switch |
| Duration spelling | Numeric; letter values | `durations=numbers` or `durations=letters` | `4G` and `qG` mean the same duration |
| Key presentation | Open key; signature; inferred choice | `key=open`, `key=signature`, or `key=auto` | Review the selected signature; this is not transposition |
| Chromatic pitch spelling | Authored spelling; directional chromatic spelling | `chromatic` | Changes enharmonic notation; inspect the musical context |
| Octave spelling | Relative contour; explicit digits | Current formatter uses its built-in relative ladder | `octaves=minimal|explicit` is reserved, not an available switch |
| Code spacing | Aligned/readable; compact | Alignment/compact selectors and presets | A source newline is not a printed system break |
| Output selection | Combined score; extracted part | Select output part/configuration | Does not require changing source orientation |
| Pitch view | Concert; written/transposed | Select the output pitch view | Not the same operation as rewriting musical pitches |
| Paper and engraving | Named score/part page configurations | Optional `.layouts.json` and host layout controls | Settings refine the selected view; source cuts still apply |

Text cleanup and linting are separate operations, not alternate music
arrangements. `strip-comments` and `strip-dev-text` deliberately remove text;
`jargon-lint` is advisory. Do not treat cleanup as lossless preservation of
everything an author wrote. The standalone `named-spans` menu entry is still
reserved even though `consolidate` already creates named spans inside shared heads.

These are supported choices, not a promise that every combination is
transformable. Check the [native option reference](normalization-options.md)
for this build's availability, and read [normalization](normalization.md)
for prerequisites, refusal conditions, and comment handling.

## Scope is a separate decision

| Fact belongs to | Place it in | Do not confuse it with |
| --- | --- | --- |
| Whole score | Score-level setting or layout map | A full-score-only page configuration; global source cuts also affect parts |
| One player | That part's body, or its row inside a measure block | Every player in an instrument section |
| Shared passage | Shared reader head and addressed body | A detached variable that occupies no measures |
| One voice | That voice's music | A setting inherited by unrelated voices |
| One musical time | Its addressed measure or inline point | The physical text line containing it |
| One printed view | The selected score/part layout configuration | Changing the underlying music |

For paired parts-first and measures-first break examples, see
[page and system layout](layout.md). For instrument sections, per-reader
registers, and named exercise returns, see [shared passages](reuse.md).

## Preview normalization before applying it

In Studio builds with the Normalize menu, choose the native options, preview
the source changes, then apply them when the result is what you want.
Optional normalization on save repeats the selected rewrite; it is not merely
a display filter. Use the host's layout/view controls when you only want a
different printed score or part page.

From the CLI, inspect the result without overwriting your file:

```sh
scorescript format piece.scorescript --normalize arrange=measures,maps=inline
scorescript format piece.scorescript --normalize arrange=parts,consolidate
```

Add `--write` only when you want to replace the source. Review diagnostics
and the diff, then check and render the result. Host controls depend on the
installed host version; the website's native menu is not proof that an older
application already exposes every option.