5.2.1 Properties of layout objects (LilyPond 学习手册)

#### 5.2.1 Properties of layout objects

Suppose you have a slur in a score which, to your mind, appears too thin and you’d like to draw it a little heavier. How do you go about doing this? You know from the statements earlier about the flexibility of LilyPond that such a thing should be possible, and you would probably guess that an `\override` command would be needed. But is there a heaviness property for a slur, and if there is, how might it be modified? This is where the Internals Reference manual comes in. It contains all the information you might need to construct this and all other `\override` commands.

Before we look at the Internals Reference a word of warning. This is a reference document, which means there is little or no explanation contained within it: its purpose is to present information precisely and concisely. This means it might look daunting at first sight. Don’t worry! The guidance and explanation presented here will enable you to extract the information from the Internals Reference for yourself with just a little practice.

Let’s use a concrete example with a simple fragment of real music:

>     {
>       \key es \major
>       \time 6/8
>       \relative {
>         r4 bes'8 bes[( g]) g |
>         g8[( es]) es d[( f]) as |
>         as8 g
>       }
>       \addlyrics {
>         The man who | feels love's sweet e -- | mo -- tion
>       }
>     }

Suppose now that we decide we would like the slurs to be a little heavier. Is this possible? The slur is certainly a layout object, so the question is, ‘Is there a property belonging to a slur which controls the heaviness?’ To answer this we must check the Internals Reference, or IR for short.

The IR for the version of LilyPond you are using may be found on the LilyPond website at https://lilypond.org. Go to the documentation page and click on the Internals Reference link. For learning purposes you should use the standard HTML version, not the ‘one big page’ or the PDF. For the next few paragraphs to make sense you will need to actually do this as you read.

Under the heading Top you will see five links. Select the link to the Backend, which is where information about layout objects is to be found. There, under the heading Backend, select the link to All layout objects. The page that appears lists all the layout objects used in your version of LilyPond, in alphabetic order. Select the link to `Slur`, and the properties of slurs are listed.

An alternative way of finding this page is from the Notation Reference. On one of the pages that deals with slurs you may find a link to the Internals Reference. This link will take you directly to this page, but if you have an idea about the name of the layout object to be tweaked, it is easier to go straight to the IR and search there.

This `Slur` page in the IR tells us first that `Slur` objects are created by the `Slur_engraver`. Then it lists the standard settings. Browse through them looking for a property that might control the heaviness of slurs, and you should find

    thickness (number)
        1.2
        [...] For slurs and ties, this is the distance between the two
        arcs of the curve's outline at its thickest point, [...]  This
        property is expressed as a multiple of the current staff-line
        thickness [...]

This looks a good bet to change the heaviness. It tells us that the value of `thickness` is a simple number, that the default value is 1.2, and that this value depends on the thickness of staff lines – which means more or less that smaller staves have thinner slurs.

As we said earlier, there are few to no explanations in the IR, but we already have enough information to try changing the slur thickness. We see that the name of the layout object is `Slur`, that the name of the property to change is `thickness` and that the new value should be a number somewhat larger than 1.2 if we are to make slurs thicker.

We can now construct the `\override` command by simply substituting the values we have found for the names, omitting the context. Let’s use a very large value for the thickness at first, so we can be sure the command is working. We get:

    \override Slur.thickness = 5.0

The final question is, ‘Where should this command be placed?’ While you are unsure and learning, the best answer is, ‘Within the music, before the first slur and close to it.’ Let’s do that:

>     {
>       \key es \major
>       \time 6/8
>       \relative {
>         % Increase thickness of all following slurs from 1.2 to 5.0
>         \override Slur.thickness = 5.0
>         r4 bes'8 bes[( g]) g |
>         g8[( es]) es d[( f]) as |
>         as8 g
>       }
>       \addlyrics {
>         The man who | feels love's sweet e -- | mo -- tion
>       }
>     }

and we see that the slur is indeed heavier.

So this is the basic way of constructing `\override` commands. There are a few more complications that we shall meet in later sections, but you now know all the essentials required to make up your own – but you will still need some practice. This is provided in the examples that follow.

#### Finding the context

But first, what if we had needed to specify the context? What should it be? We could guess that slurs are in the `Voice` context, as they are clearly closely associated with individual lines of music, but can we be sure? To find out, go back to the top of the IR page describing the `Slur` grob, where it says ‘`Slur` objects are created by the following engraver(s): `Slur_engraver`.’ So slurs will be created in whichever context the `Slur_engraver` is in. Follow the link to the `Slur_engraver` page. At the very bottom it tells us that `Slur_engraver` is part of ten voice contexts, including the standard voice context, `Voice`, so our guess was correct. And because `Voice` is one of the lowest-level contexts, which is implied unambiguously by the fact that we are entering notes, we can omit it in this location.

#### Overriding once only

As you can see, all the slurs are thicker in the final example above. But what if we wanted just the first slur to be thicker? This is achieved with the `\once` command. Placed immediately before the `\override` command it causes it to change only the slur which begins on the immediately following note. If the immediately following note does not begin a slur the command has no effect at all – it is not remembered until a slur is encountered, it is simply discarded. So the command with `\once` must be repositioned as follows:

>     {
>       \key es \major
>       \time 6/8
>       \relative {
>         r4 bes'8
>         % Increase thickness of immediately following slur only
>         \once \override Slur.thickness = 5.0
>         bes8[( g]) g |
>         g8[( es]) es d[( f]) as |
>         as8 g
>       }
>       \addlyrics {
>         The man who | feels love's sweet e -- | mo -- tion
>       }
>     }

Now only the first slur is made heavier.

The `\once` command can also be used before the `\set` command.

An alternative to `\once \override` is to use the `\tweak` command; you get the same result if you replace

    \once \override Slur.thickness = 5.0
    bes8[(

in the previous example with

    bes8[\tweak thickness 5.0 (

#### Reverting

Finally, what if we wanted just the first two slurs to be heavier? Well, we could use two commands, each preceded by `\once` placed immediately before each of the notes where the slurs begin:

>     {
>       \key es \major
>       \time 6/8
>       \relative {
>         r4 bes'8
>         % Increase thickness of immediately following slur only
>         \once \override Slur.thickness = 5.0
>         bes[( g]) g |
>         % Increase thickness of immediately following slur only
>         \once \override Slur.thickness = 5.0
>         g8[( es]) es d[( f]) as |
>         as8 g
>       }
>       \addlyrics {
>         The man who | feels love's sweet e -- | mo -- tion
>       }
>     }

or we could omit the `\once` command and use the `\revert` command to return the `thickness` property to its default value after the second slur:

>     {
>       \key es \major
>       \time 6/8
>       \relative {
>         r4 bes'8
>         % Increase thickness of all following slurs from 1.2 to 5.0
>         \override Slur.thickness = 5.0
>         bes[( g]) g |
>         g8[( es]) es
>         % Revert thickness of all following slurs to default of 1.2
>         \revert Slur.thickness
>         d8[( f]) as |
>         as8 g
>       }
>       \addlyrics {
>         The man who | feels love's sweet e -- | mo -- tion
>       }
>     }

The `\revert` command can be used to return any property changed with `\override` back to its default value. You may use whichever method best suits what you want to do.

That concludes our introduction to the IR, and the basic method of tweaking. Several examples follow in the later sections of this chapter, partly to introduce you to some of the additional features of the IR, and partly to give you more practice in extracting information from it. These examples will contain progressively fewer words of guidance and explanation.

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