The outside-staff-priority property (LilyPond 学习手册)

#### The `outside-staff-priority` property

Objects with the lower value of the `outside-staff-priority` property are placed nearer to the staff, and other outside-staff objects are then raised as far as necessary to avoid collisions. The `outside-staff-priority` is defined in the `grob-interface` and so is a property of all layout objects. By default it is set to `#f` for all within-staff objects, and to a numerical value appropriate to each outside-staff object when the object is created. See Default values for outside-staff-priority for an exhaustive table.

Note the unusual names for some of the objects: spanner objects are automatically created to control the vertical positioning of grobs which (might) start and end at different musical moments, so changing the `outside-staff-priority` of the underlying grob will have no effect. For example, changing `outside-staff-priority` of the `Hairpin` object will have no effect on the vertical positioning of hairpins – you must change `outside-staff-priority` of the associated `DynamicLineSpanner` object instead. This override must be placed at the start of the spanner, which might include several linked hairpins and dynamics.

Here is an example showing the default placement of some of these.

>     % set details for later TextSpanner
>     \override TextSpanner.bound-details.left.text =
>       \markup { \small \bold Slower }
>     % place dynamics above staff
>     \dynamicUp
>     % start ottava bracket
>     \ottava 1
>     c''4 \startTextSpan
>     % add dynamic text and hairpin
>     c''4\pp\<
>     c''4
>     % add text script
>     c''4^Text |
>     c''4 c''
>     % add dynamic text and terminate hairpin
>     c''4\ff c'' \stopTextSpan |
>     % stop ottava bracket
>     \ottava 0
>     c'4 c' c' c' |

This example also shows how to create text spanners – text with extender lines above a section of music. The spanner extends from the `\startTextSpan` command to the `\stopTextSpan` command, and the format of the text is defined by the `\override TextSpanner` command. For more details see Text spanners.

It also shows how ottava brackets are created.

If the default values of `outside-staff-priority` do not give you the placing you want, the priority of any of the objects may be overridden. Suppose we would like the ottava bracket to be placed below the text spanner in the example above. All we need to do is to look up the priority of `OttavaBracket` in the table at Default values for outside-staff-priority or in the IR, and reduce it to a value lower than that of a `TextSpanner`, remembering that `OttavaBracket` is created in the `Staff` context:

>     % set details for later text spanner
>     \override TextSpanner.bound-details.left.text =
>       \markup { \small \bold Slower }
>     % place dynamics above staff
>     \dynamicUp
>     % place following ottava bracket below text spanners
>     \once \override Staff.OttavaBracket.outside-staff-priority = 340
>     % start ottava bracket
>     \ottava 1
>     c''4 \startTextSpan
>     % add dynamic text
>     c''4\pp
>     % add dynamic line spanner
>     c''4\<
>     % add text script
>     c''4^Text |
>     c''4 c''
>     % add dynamic text
>     c''4\ff c'' \stopTextSpan |
>     % stop ottava bracket
>     \ottava 0
>     c'4 c' c' c' |

Note that some of these objects, in particular bar numbers, metronome marks, and rehearsal marks, live by default in the `Score` context, so be sure to use the correct context when these are being overridden.

Slurs by default are classed as within-staff objects, but they often appear above the staff if the notes to which they are attached are high on the staff. This can push outside-staff objects such as articulations too high, as the slur will be placed first. The `avoid-slur` property of the articulation can be set to `'inside` to bring the articulation inside the slur, but the `avoid-slur` property is effective only if the `outside-staff-priority` is also set to `#f`. Alternatively, the `outside-staff-priority` of the slur can be set to a numerical value to cause it to be placed along with other outside-staff objects according to that value. Here’s an example showing the effect of the two methods:

>     \relative c'' {
>       c4( c^\markup { \tiny \sharp } d4.) c8 |
>       c4(
>         \once \override TextScript.avoid-slur = #'inside
>         \once \override TextScript.outside-staff-priority = ##f
>         c4^\markup { \tiny \sharp } d4.) c8 |
>       \once \override Slur.outside-staff-priority = 500
>         c4( c^\markup { \tiny \sharp } d4.) c8 |
>     }

Changing the `outside-staff-priority` can also be used to control the vertical placement of individual objects, although the results may not always be desirable. Suppose we would like “Text3” to be placed above “Text4” in the example under Automatic behavior, above (see Automatic behavior). All we need to do is to look up the priority of `TextScript` in the IR or in the tables above, and increase the priority of “Text3” to a higher value:

>     c''2^"Text1"
>     c''2^"Text2" |
>     \once \override TextScript.outside-staff-priority = 500
>     c''2^"Text3"
>     c''2^"Text4" |

This certainly lifts “Text3” above “Text4” but it also lifts it above “Text2”, and “Text4” now drops down. Perhaps this is not so good. What we would really like to do is to position all the annotation at the same distance above the staff. To do this, we clearly will need to space the notes out horizontally to make more room for the text. This is done using the `\textLengthOn` command.

#### LilyPond 学习手册 v2.26.0 (stable-branch).

- 1 Installing
  - 1.1 Graphical setup
  - 1.2 Command line setup
- 2 教程
  - 2.1 编译文件
  - 2.2 如何写输入文件
    - 2.2.1 简单记谱法
      - 音高
      - 时值 (节奏)
      - 休止符
      - 拍子记号
      - 速度记号
      - 谱号（音部记号）
      - 所有的都放在一起
    - 2.2.2 处理输入文件
  - 2.3 处理报错
    - 2.3.1 一般解决问题的方法
    - 2.3.2 常见的错误
  - 2.4 如何阅读教程
    - 2.4.1 忽略掉的内容
    - 2.4.2 可以点开的例子
    - 2.4.3 手册概览
- 3 Common notation
  - 3.1 Single-staff notation
    - 3.1.1 Bar lines and bar checks
      - Bar lines
      - Bar checks
    - 3.1.2 Pitches and key signatures
      - Pitch alterations
      - Key signatures
      - Warning: key signatures and pitches
    - 3.1.3 Ties and slurs
      - Ties
      - Slurs
      - Phrasing slurs
      - Warnings: slurs vs. ties
    - 3.1.4 Articulations and dynamics
      - Articulations
      - Fingerings
      - Dynamics
    - 3.1.5 Adding text
    - 3.1.6 Automatic and manual beams
    - 3.1.7 Advanced rhythmic commands
      - Partial measure
      - Tuplets
      - Grace notes
  - 3.2 Multiple notes at once
    - 3.2.1 Music expressions explained
      - Analogy: mathematical expressions
      - Simultaneous music expressions: multiple staves
      - Simultaneous music expressions: single-staff
    - 3.2.2 Multiple staves
    - 3.2.3 Staff groups
    - 3.2.4 Combining notes into chords
    - 3.2.5 Single-staff polyphony
  - 3.3 Songs
    - 3.3.1 Setting simple songs
    - 3.3.2 Aligning lyrics to a melody
    - 3.3.3 Lyrics to multiple staves
  - 3.4 Final touches
    - 3.4.1 Organizing pieces with variables
    - 3.4.2 Adding titles
    - 3.4.3 Absolute note names
    - 3.4.4 After the tutorial
- 4 Fundamental concepts
  - 4.1 How LilyPond input files work
    - 4.1.1 Introduction to the LilyPond file structure
    - 4.1.2 A score is a (single) compound musical expression
    - 4.1.3 Nesting music expressions
    - 4.1.4 Structure of a note entry
    - 4.1.5 On the un-nestedness of brackets and ties
  - 4.2 Voices contain music
    - 4.2.1 I’m hearing voices
    - 4.2.2 Explicitly instantiating voices
    - 4.2.3 Voices and vocals
  - 4.3 Contexts and engravers
    - 4.3.1 Contexts explained
    - 4.3.2 Creating contexts
    - 4.3.3 Engravers explained
    - 4.3.4 Modifying context properties
    - 4.3.5 Adding and removing engravers
  - 4.4 Extending the templates
    - 4.4.1 Soprano and cello
    - 4.4.2 Four-part SATB vocal score
    - 4.4.3 Building a score from scratch
    - 4.4.4 Saving typing with variables and functions
    - 4.4.5 Scores and parts
- 5 Tweaking output
  - 5.1 Tweaking basics
    - 5.1.1 Objects and interfaces
    - 5.1.2 Naming conventions of objects and properties
    - 5.1.3 Tweaking methods
      - The `\override` command
      - The `\revert` command
      - The `\once` prefix
      - The `\tweak` and `\offset` commands
      - The `\single` prefix
  - 5.2 The Internals Reference manual
    - 5.2.1 Properties of layout objects
    - 5.2.2 Properties found in interfaces
    - 5.2.3 Types of properties
  - 5.3 Appearance of objects
    - 5.3.1 Visibility and color of objects
      - The `stencil` property
      - The `break-visibility` property
      - The `transparent` property
      - The `color` property
    - 5.3.2 Size of objects
    - 5.3.3 Length and thickness of objects
  - 5.4 Offsets and alignments
  - 5.5 Placement of objects
    - 5.5.1 Automatic behavior
    - 5.5.2 Within-staff objects
      - The `direction` property
      - Fingering
    - 5.5.3 Outside-staff objects
      - The `outside-staff-priority` property
      - The `\textLengthOn` command
      - Dynamics placement
      - Grob sizing
  - 5.6 Vertical spacing
  - 5.7 Collisions of objects
    - 5.7.1 Moving objects
    - 5.7.2 Fixing overlapping notation
      - The `padding` property
      - The `right-padding` property
      - The `staff-padding` property
      - The `self-alignment-X` property
      - The `staff-position` property
      - The `extra-offset` property
      - The `positions` property
      - The `force-hshift` property
    - 5.7.3 Real music example
  - 5.8 Further tweaking
    - 5.8.1 Other uses for tweaks
      - Tying notes across voices
      - Simulating a fermata in MIDI
    - 5.8.2 Using variables for layout adjustments
    - 5.8.3 Style sheets
    - 5.8.4 Other sources of information
    - 5.8.5 Advanced tweaks with Scheme
- Appendix A Templates
  - A.1 Built-in templates
    - A.1.1 SATB template
    - A.1.2 SSAATTBB template
  - A.2 Single staff templates
    - A.2.1 Notes only
    - A.2.2 Notes and lyrics
    - A.2.3 Notes and chords
    - A.2.4 Notes, lyrics, and chords
  - A.3 Piano templates
    - A.3.1 Solo piano
    - A.3.2 Piano and melody with lyrics
    - A.3.3 Piano-centered lyrics
  - A.4 String quartet templates
    - A.4.1 String quartet
    - A.4.2 String quartet parts
  - A.5 Vocal ensembles templates
    - A.5.1 SATB vocal score
    - A.5.2 SATB vocal score and automatic piano reduction
    - A.5.3 SATB with aligned contexts
    - A.5.4 SATB on four staves
    - A.5.5 Solo verse and two-part refrain
    - A.5.6 Hymn tunes
    - A.5.7 Psalms
  - A.6 Orchestral templates
    - A.6.1 Orchestra, choir and piano
  - A.7 Ancient notation templates
    - A.7.1 Transcription of mensural music
    - A.7.2 Gregorian transcription template
  - A.8 Other templates
    - A.8.1 Jazz combo
- Appendix B GNU Free Documentation License
- Appendix C Index