4.2 The Internals Reference manual

4.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 look in 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
     Line thickness, generally measured in 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 the units are in another property called line-thickness.

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

Don’t forget the # preceding the new value!

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 which 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, where it says ‘Slur objects are created by: 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 seven 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.

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.

4.2.2 Properties found in interfaces

Suppose now that we wish to print the lyrics in italics. What form of \override command do we need to do this? We first look in the IR page listing ‘All layout objects’, as before, and look for an object that might control lyrics. We find LyricText, which looks right. Clicking on this shows the settable properties for lyric text. These include the font-series and font-size, but nothing that might give an italic shape. This is because the shape property is one that is common to all font objects, so, rather than including it in every layout object, it is grouped together with other similar common properties and placed in an Interface, the font-interface.

So now we need to learn how to find the properties of interfaces, and to discover what objects use these interface properties.

Look again at the IR page which describes LyricText. At the bottom of the page is a list of clickable interfaces which LyricText supports. The list has several items, including font-interface. Clicking on this brings up the properties associated with this interface, which are also properties of all the objects which support it, including LyricText.

Now we see all the user-settable properties which control fonts, including font-shape(symbol), where symbol can be set to upright, italics or caps.

You will notice that font-series and font-size are also listed there. This immediately raises the question: Why are the common font properties font-series and font-size listed under LyricText as well as under the interface font-interface but font-shape is not? The answer is that font-series and font-size are changed from their global default values when a LyricText object is created, but font-shape is not. The entries in LyricText then tell you the values for those two properties which apply to LyricText. Other objects which support font-interface will set these properties differently when they are created.

Let’s see if we can now construct the \override command to change the lyrics to italics. The object is LyricText, the property is font-shape and the value is italic. As before, we’ll omit the context.

As an aside, although it is an important one, note that some properties take values that are symbols, like italic, and must be preceded by an apostrophe, '. Symbols are then read internally by LilyPond. Note the distinction from arbitrary text strings, which would appear as "a text string"; for more details about symbols and strings, see (extending)Scheme tutorial section ‘Scheme tutorial’ in Extending.

So we see that the \override command needed to print the lyrics in italics is:

\override LyricText.font-shape = #'italic

This should be placed just in front of the lyrics we wish to affect, like so:

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

and the lyrics are all printed in italics.

See also

Extending: (extending)Scheme tutorial section ‘Scheme tutorial’ in Extending.

4.2.3 Types of properties

So far we have seen two types of property: number and symbol. To be valid, the value given to a property must be of the correct type and obey the rules for that type. The type of property is always shown in brackets after the property name in the IR. Here is a list of the types you may need, together with the rules for that type, and some examples. You must always add a hash symbol, #, of course, to the front of these values when they are entered in the \override command, even if the value itself already starts with #. We only give examples for constants here: if you want to compute a value using Scheme, see (extending)Calculations in Scheme section ‘Calculations in Scheme’ in Extending.

See also

Extending: (extending)Scheme tutorial section ‘Scheme tutorial’ in Extending.

This document was generated by gub on July 13, 2020 using texi2html 1.82.

Más nyelvek: català, česky, deutsch, español, français, italiano, 日本語, nederlands.
Az automatikus nyelvválasztásról.