+++ /dev/null
-@c -*- coding: utf-8; mode: texinfo; -*-
-@c This file is part of lilypond-learning.tely
-@ignore
- Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
-
- When revising a translation, copy the HEAD committish of the
- version that you are working on. See TRANSLATION for details.
-@end ignore
-
-@c \version "2.12.0"
-
-@node Tweaking output
-@chapter Tweaking output
-
-This chapter discusses how to modify output. LilyPond is extremely
-configurable; virtually every fragment of output may be changed.
-
-
-@menu
-* Tweaking basics::
-* The Internals Reference manual::
-* Appearance of objects::
-* Placement of objects::
-* Collisions of objects::
-* Further tweaking::
-@end menu
-
-@node Tweaking basics
-@section Tweaking basics
-
-@menu
-* Introduction to tweaks::
-* Objects and interfaces::
-* Naming conventions of objects and properties::
-* Tweaking methods::
-@end menu
-
-@node Introduction to tweaks
-@subsection Introduction to tweaks
-
-@q{Tweaking} is a LilyPond term for the various methods available
-to the user for modifying the actions taken during interpretation
-of the input file and modifying the appearance of the printed
-output. Some tweaks are very easy to use; others are more
-complex. But taken together the methods available for tweaking
-permit almost any desired appearance of the printed music to be
-achieved.
-
-In this section we cover the basic concepts required to understand
-tweaking. Later we give a variety of ready-made commands which can
-simply be copied to obtain the same effect in your own scores, and
-at the same time we show how these commands may be constructed so
-that you may learn how to develop your own tweaks.
-
-Before starting on this Chapter you may wish to review the section
-@ref{Contexts and engravers}, as Contexts, Engravers, and the
-Properties contained within them are fundamental to understanding
-and constructing Tweaks.
-
-@node Objects and interfaces
-@subsection Objects and interfaces
-
-@cindex object
-@cindex grob
-@cindex spanner
-@cindex interface
-@cindex properties, object
-@cindex object properties
-@cindex layout object
-@cindex object, layout
-@cindex interface
-
-Tweaking involves modifying the internal operation and structures
-of the LilyPond program, so we must first introduce some terms
-which are used to describe those internal operations and
-structures.
-
-The term @q{Object} is a generic term used to refer to the
-multitude of internal structures built by LilyPond during the
-processing of an input file. So when a command like @code{\new
-Staff} is encountered a new object of type @code{Staff} is
-constructed. That @code{Staff} object then holds all the
-properties associated with that particular staff, for example, its
-name and its key signature, together with details of the engravers
-which have been assigned to operate within that staff's context.
-Similarly, there are objects to hold the properties of all other
-contexts, such as @code{Voice} objects, @code{Score} objects,
-@code{Lyrics} objects, as well as objects to represent all
-notational elements such as bar lines,
-note heads, ties, dynamics, etc. Every object has its own set of
-property values.
-
-Some types of object are given special names. Objects which represent
-items of notation on the printed output such as note heads, stems,
-slurs, ties, fingering, clefs, etc are called @q{Layout objects},
-often known as @q{Graphical Objects}, or @q{Grobs} for short. These
-are still objects in the generic sense above, and so they too all have
-properties associated with them, such as their position, size, color,
-etc.
-
-Some layout objects are still more specialized. Phrasing slurs,
-crescendo hairpins, ottava marks, and many other grobs are not
-localized in a single place -- they have a starting point, an
-ending point, and maybe other properties concerned with their
-shape. Objects with an extended shape like these are called
-@q{Spanners}.
-
-It remains to explain what @q{Interfaces} are. Many objects, even
-though they are quite different, share common features which need to
-be processed in the same way. For example, all grobs have a color, a
-size, a position, etc, and all these properties are processed in the
-same way during LilyPond's interpretation of the input file. To
-simplify these internal operations these common actions and properties
-are grouped together in an object called a @code{grob-interface}.
-There are many other groupings of common properties like this, each
-one given a name ending in @code{interface}. In total there are over
-100 such interfaces. We shall see later why this is of interest and
-use to the user.
-
-These, then, are the main terms relating to objects which we
-shall use in this chapter.
-
-@node Naming conventions of objects and properties
-@subsection Naming conventions of objects and properties
-
-@cindex naming conventions for objects
-@cindex naming conventions for properties
-@cindex objects, naming conventions
-@cindex properties, naming conventions
-
-We met some object naming conventions previously, in
-@ref{Contexts and engravers}. Here for reference is a list
-of the most common object and property types together with
-the conventions for naming them and a couple of examples of
-some real names. We have used @q{A} to stand for any capitalized
-alphabetic character and @q{aaa} to stand for any number of
-lower-case alphabetic characters. Other characters are used
-verbatim.
-
-@multitable @columnfractions .33 .33 .33
-@headitem Object/property type
- @tab Naming convention
- @tab Examples
-@item Contexts
- @tab Aaaa or AaaaAaaaAaaa
- @tab Staff, GrandStaff
-@item Layout Objects
- @tab Aaaa or AaaaAaaaAaaa
- @tab Slur, NoteHead
-@item Engravers
- @tab Aaaa_aaa_engraver
- @tab Clef_engraver, Note_heads_engraver
-@item Interfaces
- @tab aaa-aaa-interface
- @tab grob-interface, break-aligned-interface
-@item Context Properties
- @tab aaa or aaaAaaaAaaa
- @tab alignAboveContext, skipBars
-@item Layout Object Properties
- @tab aaa or aaa-aaa-aaa
- @tab direction, beam-thickness
-@end multitable
-
-As we shall see shortly, the properties of different types of
-object are modified by different commands, so it is useful to
-be able to recognize the type of object from the names of its
-properties.
-
-
-@node Tweaking methods
-@subsection Tweaking methods
-
-@cindex tweaking methods
-
-@strong{\override command}
-
-@cindex override command
-@cindex override syntax
-
-@funindex \override
-@funindex override
-
-We have already met the commands @code{\set} and @code{\with}, used to
-change the properties of @strong{contexts} and to remove and add
-@strong{engravers}, in @ref{Modifying context properties}, and
-@ref{Adding and removing engravers}. We now must meet some more
-important commands.
-
-The command to change the properties of @strong{layout objects} is
-@code{\override}. Because this command has to modify
-internal properties deep within LilyPond its syntax is not
-as simple as the commands you have met so far. It needs to
-know precisely which property of which object in which context
-has to be modified, and what its new value is to be. Let's see
-how this is done.
-
-The general syntax of this command is:
-
-@example
-\override @var{Context}.@var{LayoutObject} #'@var{layout-property} =
-#@var{value}
-@end example
-
-@noindent
-This will set the property with the name @var{layout-property} of the
-layout object with the name @var{LayoutObject}, which is a member of
-the @var{Context} context, to the value @var{value}.
-
-The @var{Context} can be omitted (and usually is) when the
-required context is unambiguously implied and is one of lowest
-level contexts, i.e., @code{Voice}, @code{ChordNames} or
-@code{Lyrics}, and we shall omit it in many of the following
-examples. We shall see later when it must be specified.
-
-Later sections deal comprehensively with properties and their
-values, but to illustrate the format and use of these commands
-we shall use just a few simple properties and values which are
-easily understood.
-
-For now, don't worry about the @code{#'}, which must precede the
-layout property, and the @code{#}, which must precede the value.
-These must always be present in exactly this form. This is the
-most common command used in tweaking, and most of the rest of
-this chapter will be directed to presenting examples of how it is
-used. Here is a simple example to change the color of the
-note head:
-
-@cindex color property, example
-@cindex NoteHead, example of overriding
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-c d
-\override NoteHead #'color = #red
-e f g
-\override NoteHead #'color = #green
-a b c
-@end lilypond
-
-@strong{\revert command}
-
-@cindex revert command
-
-@funindex \revert
-@funindex revert
-
-Once overridden, the property retains its new value until it is
-overridden again or a @code{\revert} command is encountered.
-The @code{\revert} command has the following syntax and causes
-the value of the property to revert to its original default
-value; note, not its previous value if several @code{\override}
-commands have been issued.
-
-@example
-\revert @var{Context}.@var{LayoutObject} #'@var{layout-property}
-@end example
-
-Again, just like @var{Context} in the @code{\override} command,
-@var{Context} is often not needed. It will be omitted
-in many of the following examples. Here we revert the color
-of the note head to the default value for the final two notes:
-
-@cindex color property, example
-@cindex NoteHead, example of overriding
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-c d
-\override NoteHead #'color = #red
-e f g
-\override NoteHead #'color = #green
-a
-\revert NoteHead #'color
-b c
-@end lilypond
-
-@strong{\once prefix}
-
-@funindex \once
-@funindex once
-
-Both the @code{\override} and the @code{\set} commands may be
-prefixed by @code{\once}. This causes the following
-@code{\override} or @code{\set} command to be effective only
-during the current musical moment before the property reverts
-back to its default value. Using the same example, we can
-change the color of a single note like this:
-
-@cindex color property, example
-@cindex NoteHead, example of overriding
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-c d
-\once \override NoteHead #'color = #red
-e f g
-\once \override NoteHead #'color = #green
-a b c
-@end lilypond
-
-@strong{\overrideProperty command}
-
-@cindex overrideProperty command
-
-@funindex \overrideProperty
-@funindex overrideProperty
-
-There is another form of the override command,
-@code{\overrideProperty}, which is occasionally required.
-We mention it here for completeness, but for details see
-@ruser{Difficult tweaks}.
-@c Maybe explain in a later iteration -td
-
-@strong{\tweak command}
-
-@cindex tweak command
-
-@funindex \tweak
-@funindex tweak
-
-The final tweaking command which is available is @code{\tweak}.
-This should be used to change the properties of objects which
-occur at the same musical moment, such as the notes within a
-chord. Using @code{\override} would affect all the notes
-within a chord, whereas @code{\tweak} affects just the following
-item in the input stream.
-
-Here's an example. Suppose we wish to change the size of the
-middle note head (the E) in a C major chord. Let's first see what
-@code{\once \override} would do:
-
-@cindex font-size property, example
-@cindex NoteHead, example of overriding
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
- <c e g>4
- \once \override NoteHead #'font-size = #-3
- <c e g>
- <c e g>
-@end lilypond
-
-We see the override affects @emph{all} the note heads in the chord.
-This is because all the notes of a chord occur at the same
-@emph{musical moment}, and the action of @code{\once} is to
-apply the override to all layout objects of the type specified
-which occur at the same musical moment as the @code{\override}
-command itself.
-
-The @code{\tweak} command operates in a different way. It acts
-on the immediately following item in the input stream. However,
-it is effective only on objects which are created directly from
-the input stream, essentially note heads and articulations;
-objects such as stems and accidentals are created later and
-cannot be tweaked in this way. Furthermore, when it is applied
-to note heads these @emph{must} be within a chord, i.e., within
-single angle brackets, so to tweak a single note the @code{\tweak}
-command must be placed inside single angle brackets with the
-note.
-
-So to return to our example, the size of the middle note of
-a chord would be changed in this way:
-
-@cindex font-size property, example
-@cindex @code{\tweak}, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
- <c e g>4
- <c \tweak #'font-size #-3 e g>4
-@end lilypond
-
-Note that the syntax of @code{\tweak} is different from that
-of the @code{\override} command. Neither the context nor the
-layout object should be specified; in fact, it would generate
-an error to do so. These are both implied by the following
-item in the input stream. Note also that an equals sign should
-not be present. So the general syntax of the
-@code{\tweak} command is simply
-
-@example
-\tweak #'@var{layout-property} #@var{value}
-@end example
-
-A @code{\tweak} command can also be used to modify just one in
-a series of articulations, as shown here:
-
-@cindex color property, example
-@cindex @code{\tweak}, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-a ^Black
- -\tweak #'color #red ^Red
- -\tweak #'color #green _Green
-@end lilypond
-
-@noindent
-Note that the @code{\tweak} command must be preceded by an
-articulation mark as if it were an articulation itself.
-
-@cindex tuplets, nested
-@cindex triplets, nested
-@cindex bracket, tuplet
-@cindex bracket, triplet
-@cindex tuplet bracket
-@cindex triplet bracket
-
-@funindex TupletBracket
-
-The @code{\tweak} command must also be used to change the
-appearance of one of a set of nested tuplets which begin at the
-same musical moment. In the following example, the long tuplet
-bracket and the first of the three short brackets begin at the
-same musical moment, so any @code{\override} command would apply
-to both of them. In the example, @code{\tweak} is used to
-distinguish between them. The first @code{\tweak} command
-specifies that the long tuplet bracket is to be placed above the
-notes and the second one specifies that the tuplet number is to be
-printed in red on the first short tuplet bracket.
-
-@cindex @code{\tweak}, example
-@cindex direction property, example
-@cindex color property, example
-
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
-\tweak #'direction #up
-\times 4/3 {
- \tweak #'color #red
- \times 2/3 { c8[ c8 c8] }
- \times 2/3 { c8[ c8 c8] }
- \times 2/3 { c8[ c8 c8] }
-}
-@end lilypond
-
-If nested tuplets do not begin at the same moment, their
-appearance may be modified in the usual way with
-@code{\override} commands:
-
-@cindex text property, example
-@cindex tuplet-number function, example
-@cindex transparent property, example
-@cindex TupletNumber, example of overriding
-
-@c NOTE Tuplet brackets collide if notes are high on staff
-@c See issue 509
-@lilypond[quote,ragged-right,verbatim,fragment,relative=1]
-\times 2/3 { c8[ c c]}
-\once \override TupletNumber
- #'text = #tuplet-number::calc-fraction-text
-\times 2/3 {
- c[ c]
- c[ c]
- \once \override TupletNumber #'transparent = ##t
- \times 2/3 { c8[ c c] }
-\times 2/3 { c8[ c c]}
-}
-@end lilypond
-
-
-@seealso
-Notation Reference:
-@ruser{The tweak command}.
-
-
-@node The Internals Reference manual
-@section The Internals Reference manual
-
-@cindex Internals Reference
-
-@menu
-* Properties of layout objects::
-* Properties found in interfaces::
-* Types of properties::
-@end menu
-
-@node Properties of layout objects
-@subsection Properties of layout objects
-
-@cindex properties of layout objects
-@cindex properties of grobs
-@cindex grobs, properties of
-@cindex layout objects, properties of
-@cindex Internals Reference manual
-
-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
-@code{\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 @code{\override} commands.
-
-Before we look at the Internals Reference a word of warning.
-This is a @strong{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.
-
-@cindex override example
-@cindex Internals Reference, example of using
-@cindex @code{\addlyrics} example
-
-Let's use a concrete example with a simple fragment of real
-music:
-
-@lilypond[quote,verbatim,relative=2]
-{
- \time 6/8
- {
- r4 b8 b[( g]) g |
- g[( e]) e d[( f]) a |
- a g
- }
- \addlyrics {
- The man who feels love's sweet e -- mo -- tion
- }
-}
-@end lilypond
-
-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, @q{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 @uref{http://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 @q{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 @strong{Top} you will see five links. Select
-the link to the @emph{Backend}, which is where information about
-layout objects is to be found. There, under the heading
-@strong{Backend}, select the link to @emph{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. Note
-these are @strong{not} in alphabetic order. Browse down them looking
-for a property that might control the heaviness of slurs, and you
-should find
-
-@example
-@code{thickness} (number)
- @code{1.2}
- Line thickness, generally measured in @code{line-thickness}
-@end example
-
-This looks a good bet to change the heaviness. It tells us that
-the value of @code{thickness} is a simple @emph{number},
-that the default value is 1.2, and that the units are
-in another property called @code{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 @code{Slur}, that the name of the property to change is
-@code{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 @code{\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:
-
-@example
-\override Slur #'thickness = #5.0
-@end example
-
-Don't forget the @code{#'} preceding the
-property name and a @code{#} preceding the new value!
-
-The final question is, @q{Where should this command be
-placed?} While you are unsure and learning, the best
-answer is, @q{Within the music, before the first slur and
-close to it.} Let's do that:
-
-@cindex Slur example of overriding
-@cindex thickness property, example
-
-@lilypond[quote,verbatim,relative=2]
-{
- \time 6/8
- {
- % Increase thickness of all following slurs from 1.2 to 5.0
- \override Slur #'thickness = #5.0
- r4 b8 b[( g]) g |
- g[( e]) e d[( f]) a |
- a g
- }
- \addlyrics {
- The man who feels love's sweet e -- mo -- tion
- }
-}
-@end lilypond
-
-@noindent
-and we see that the slur is indeed heavier.
-
-So this is the basic way of constructing @code{\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.
-
-@subheading Finding the context
-
-@cindex context, finding
-@cindex context, identifying correct
-
-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 @q{Slur objects are created by: Slur
-engraver}. So slurs will be created in whichever context
-the @code{Slur_engraver} is in. Follow the link to the
-@code{Slur_engraver} page. At the very bottom it tells
-us that @code{Slur_engraver} is part of five Voice contexts,
-including the standard voice context, @code{Voice}, so our
-guess was correct. And because @code{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.
-
-@subheading Overriding once only
-
-@cindex overriding once only
-@cindex once override
-
-@funindex \once
-@funindex once
-
-As you can see, @emph{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 @code{\once} command. Placed immediately before
-the @code{\override} command it causes it to change only the slur
-which begins on the @strong{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 @code{\once} must be
-repositioned as follows:
-
-@cindex Slur, example of overriding
-@cindex thickness property, example
-
-@lilypond[quote,verbatim,relative=2]
-{
- \time 6/8
- {
- r4 b8
- % Increase thickness of immediately following slur only
- \once \override Slur #'thickness = #5.0
- b[( g]) g |
- g[( e]) e d[( f]) a |
- a g
- }
- \addlyrics {
- The man who feels love's sweet e -- mo -- tion
- }
-}
-@end lilypond
-
-@noindent
-Now only the first slur is made heavier.
-
-The @code{\once} command can also be used before the @code{\set}
-command.
-
-@subheading Reverting
-
-@cindex revert
-@cindex default properties, reverting to
-
-@funindex \revert
-@funindex revert
-
-Finally, what if we wanted just the first two slurs to be
-heavier? Well, we could use two commands, each preceded by
-@code{\once} placed immediately before each of the notes where
-the slurs begin:
-
-@cindex Slur, example of overriding
-@cindex thickness property, example
-
-@lilypond[quote,verbatim,relative=2]
-{
- \time 6/8
- {
- r4 b8
- % Increase thickness of immediately following slur only
- \once \override Slur #'thickness = #5.0
- b[( g]) g |
- % Increase thickness of immediately following slur only
- \once \override Slur #'thickness = #5.0
- g[( e]) e d[( f]) a |
- a g
- }
- \addlyrics {
- The man who feels love's sweet e -- mo -- tion
- }
-}
-@end lilypond
-
-@noindent
-or we could omit the @code{\once} command and use the @code{\revert}
-command to return the @code{thickness} property to its default value
-after the second slur:
-
-@cindex Slur, example of overriding
-@cindex thickness property, example
-
-@lilypond[quote,verbatim,relative=2]
-{
- \time 6/8
- {
- r4 b8
- % Increase thickness of all following slurs from 1.2 to 5.0
- \override Slur #'thickness = #5.0
- b[( g]) g |
- g[( e])
- % Revert thickness of all following slurs to default of 1.2
- \revert Slur #'thickness
- e d[( f]) a |
- a g
- }
- \addlyrics {
- The man who feels love's sweet e -- mo -- tion
- }
-}
-@end lilypond
-
-@noindent
-The @code{\revert} command can be used to return any property
-changed with @code{\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.
-
-
-@node Properties found in interfaces
-@subsection Properties found in interfaces
-
-@cindex interface
-@cindex interface properties
-@cindex properties in interfaces
-
-Suppose now that we wish to print the lyrics in italics. What form of
-@code{\override} command do we need to do this? We first look in the
-IR page listing @q{All layout objects}, as before, and look for an
-object that might control lyrics. We find @code{LyricText}, which
-looks right. Clicking on this shows the settable properties for lyric
-text. These include the @code{font-series} and @code{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 @strong{Interface}, the
-@code{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 @code{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 @code{font-shape(symbol)}, where @code{symbol} can be
-set to @code{upright}, @code{italics} or @code{caps}.
-
-You will notice that @code{font-series} and @code{font-size} are also
-listed there. This immediately raises the question: Why are the
-common font properties @code{font-series} and @code{font-size} listed
-under @code{LyricText} as well as under the interface
-@code{font-interface} but @code{font-shape} is not? The answer is
-that @code{font-series} and @code{font-size} are changed from their
-global default values when a @code{LyricText} object is created, but
-@code{font-shape} is not. The entries in @code{LyricText} then tell
-you the values for those two properties which apply to
-@code{LyricText}. Other objects which support @code{font-interface}
-will set these properties differently when they are created.
-
-Let's see if we can now construct the @code{\override} command
-to change the lyrics to italics. The object is @code{LyricText},
-the property is @code{font-shape} and the value is
-@code{italic}. As before, we'll omit the context.
-
-As an aside, although it is an important one, note that because the
-values of @code{font-shape} are symbols they must be introduced with a
-single apostrophe, @code{'}. That is why apostrophes are needed
-before @code{thickness} in the earlier example and @code{font-shape}.
-These are both symbols too. Symbols are then read internally by
-LilyPond. Some of them are the names of properties, like
-@code{thickness} or @code{font-shape}, others are used as values that
-can be given to properties, like @code{italic}. Note the distinction
-from arbitrary text strings, which would appear as @code{"a text
-string"}; for more details about symbols and strings, see @ref{Scheme
-tutorial}.
-
-Ok, so the @code{\override} command we need to print the lyrics
-in italics should be
-
-@example
-\override LyricText #'font-shape = #'italic
-@end example
-
-@noindent
-and this should be placed just in front of and close to the
-lyrics which it should affect, like this:
-
-@cindex font-shape property, example
-@cindex italic, example
-@cindex LyricText, example of overriding
-@cindex @code{\addlyrics}, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
- \time 6/8
- {
- r4 b8 b[( g]) g |
- g[( e]) e d[( f]) a |
- a g
- }
- \addlyrics {
- \override LyricText #'font-shape = #'italic
- The man who feels love's sweet e -- mo -- tion
- }
-}
-@end lilypond
-
-@noindent
-and the lyrics are all printed in italics.
-
-@subheading Specifying the context in lyric mode
-
-@cindex context, specifying in lyric mode
-@cindex lyric mode, specifying context
-
-In the case of lyrics, if you try specifying the context in the
-format given earlier the command will fail. A syllable
-entered in lyricmode is terminated by either a space,
-a newline or a digit. All other characters are included
-as part of the syllable. For this reason a space or newline
-must appear before the terminating @code{@}} to prevent it being
-included as part of the final syllable. Similarly,
-spaces must be inserted before and after the
-period or dot, @q{.}, separating the context name from the
-object name, as otherwise the two names are run together and
-the interpreter cannot recognize them. So the command should be:
-
-@example
-\override Lyrics . LyricText #'font-shape = #'italic
-@end example
-
-@warning{In lyrics always leave whitespace between the final
-syllable and the terminating brace.}
-
-@warning{In overrides in lyrics always place spaces around
-the dot between the context name and the object name.}
-
-
-@seealso
-Learning Manual: @ref{Scheme tutorial}.
-
-
-@node Types of properties
-@subsection Types of properties
-
-@cindex property types
-
-So far we have seen two types of property: @code{number} and
-@code{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, @code{#}, of course,
-to the front of these values when they are entered in the
-@code{\override} command.
-
-@multitable @columnfractions .2 .45 .35
-@headitem Property type
- @tab Rules
- @tab Examples
-@item Boolean
- @tab Either True or False, represented by #t or #f
- @tab @code{#t}, @code{#f}
-@item Dimension (in staff space)
- @tab A positive decimal number (in units of staff space)
- @tab @code{2.5}, @code{0.34}
-@item Direction
- @tab A valid direction constant or its numerical equivalent (decimal
-values between -1 and 1 are allowed)
- @tab @code{LEFT}, @code{CENTER}, @code{UP},
- @code{1}, @code{-1}
-@item Integer
- @tab A positive whole number
- @tab @code{3}, @code{1}
-@item List
- @tab A set of values separated by spaces, enclosed in parentheses
-and preceded by an apostrophe
- @tab @code{'(left-edge staff-bar)}, @code{'(1)},
- @code{'(1.0 0.25 0.5)}
-@item Markup
- @tab Any valid markup
- @tab @code{\markup @{ \italic "cresc." @}}
-@item Moment
- @tab A fraction of a whole note constructed with the
-make-moment function
- @tab @code{(ly:make-moment 1 4)},
- @code{(ly:make-moment 3 8)}
-@item Number
- @tab Any positive or negative decimal value
- @tab @code{3.5}, @code{-2.45}
-@item Pair (of numbers)
- @tab Two numbers separated by a @q{space . space} and enclosed
-in brackets preceded by an apostrophe
- @tab @code{'(2 . 3.5)}, @code{'(0.1 . -3.2)}
-@item Symbol
- @tab Any of the set of permitted symbols for that property,
-preceded by an apostrophe
- @tab @code{'italic}, @code{'inside}
-@item Unknown
- @tab A procedure, or @code{#f} to cause no action
- @tab @code{bend::print}, @code{ly:text-interface::print},
- @code{#f}
-@item Vector
- @tab A list of three items enclosed in parentheses and preceded
-by apostrophe-hash, @code{'#}.
- @tab @code{'#(#t #t #f)}
-@end multitable
-
-
-@seealso
-Learning Manual: @ref{Scheme tutorial}.
-
-
-@node Appearance of objects
-@section Appearance of objects
-
-Let us now put what we have learned into practice with a few
-examples which show how tweaks may be used to change the
-appearance of the printed music.
-
-@menu
-* Visibility and color of objects::
-* Size of objects::
-* Length and thickness of objects::
-@end menu
-
-@node Visibility and color of objects
-@subsection Visibility and color of objects
-
-In the educational use of music we might wish to print a score
-with certain elements omitted as an exercise for the student,
-who is required to supply them. As a simple example,
-let us suppose the exercise is to supply the missing bar lines
-in a piece of music. But the bar lines are normally inserted
-automatically. How do we prevent them printing?
-
-Before we tackle this, let us remember that object properties are
-grouped in what are called @emph{interfaces} -- see @ref{Properties
-found in interfaces}. This is simply to group together those
-properties that may be used together to tweak a graphical object -- if
-one of them is allowed for an object, so are the others. Some objects
-then use the properties in some interfaces, others use them from other
-interfaces. The interfaces which contain the properties used by a
-particular grob are listed in the IR at the bottom of the page
-describing that grob, and those properties may be viewed by looking at
-those interfaces.
-
-We explained how to find information about grobs in @ref{Properties of
-layout objects}. Using the same approach, we go to the IR to find the
-layout object which prints bar lines. Going via @emph{Backend} and
-@emph{All layout objects} we find there is a layout object called
-@code{BarLine}. Its properties include two that control its
-visibility: @code{break-visibility} and @code{stencil}. Barline also
-supports a number of interfaces, including the @code{grob-interface},
-where we find the @code{transparent} and the @code{color} properties.
-All of these can affect the visibility of bar lines (and, of course,
-by extension, many other layout objects too.) Let's consider each of
-these in turn.
-
-@subheading stencil
-
-@cindex stencil property
-
-This property controls the appearance of the bar lines by specifying
-the symbol (glyph) which should be printed. In common
-with many other properties, it can be set to print nothing by
-setting its value to @code{#f}. Let's try it, as before, omitting
-the implied Context, @code{Voice}:
-
-@cindex BarLine, example of overriding
-@cindex stencil property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
- \time 12/16
- \override BarLine #'stencil = ##f
- c4 b8 c d16 c d8 |
- g, a16 b8 c d4 e16 |
- e8
-}
-@end lilypond
-
-The bar lines are still printed. What is wrong? Go back to the IR
-and look again at the page giving the properties of BarLine. At the
-top of the page it says @qq{Barline objects are created by:
-Bar_engraver}. Go to the @code{Bar_engraver} page. At the bottom it
-gives a list of Contexts in which the bar engraver operates. All of
-them are of the type @code{Staff}, so the reason the @code{\override}
-command failed to work as expected is because @code{Barline} is not in
-the default @code{Voice} context. If the context is specified
-wrongly, the command simply does not work. No error message is
-produced, and nothing is logged in the log file. Let's try correcting
-it by adding the correct context:
-
-@cindex BarLine, example of overriding
-@cindex stencil property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
- \time 12/16
- \override Staff.BarLine #'stencil = ##f
- c4 b8 c d16 c d8 |
- g, a16 b8 c d4 e16 |
- e8
-}
-@end lilypond
-
-Now the bar lines have vanished.
-
-@subheading break-visibility
-
-@cindex break-visibility property
-
-We see from the @code{BarLine} properties in the IR that the
-@code{break-visibility} property requires a vector of three booleans.
-These control respectively whether bar lines are printed at the end of
-a line, in the middle of lines, and at the beginning of lines. For
-our example we want all bar lines to be suppressed, so the value we
-need is @code{'#(#f #f #f)}. Let's try that, remembering to include
-the @code{Staff} context. Note also that in writing this value we
-have @code{#'#} before the opening bracket. The @code{'#} is required
-as part of the value to introduce a vector, and the first @code{#} is
-required, as always, to precede the value itself in the
-@code{\override} command.
-
-@cindex BarLine, example of overriding
-@cindex break-visibility property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
- \time 12/16
- \override Staff.BarLine #'break-visibility = #'#(#f #f #f)
- c4 b8 c d16 c d8 |
- g, a16 b8 c d4 e16 |
- e8
-}
-@end lilypond
-
-And we see this too removes all the bar lines.
-
-@subheading transparent
-
-@cindex transparent property
-@cindex transparency
-
-We see from the properties specified in the @code{grob-interface} page
-in the IR that the @code{transparent} property is a boolean. This
-should be set to @code{#t} to make the grob transparent. In this next
-example let us make the time signature invisible rather than the bar
-lines. To do this we need to find the grob name for the time
-signature. Back to the @q{All layout objects} page in the IR to find
-the properties of the @code{TimeSignature} layout object. This is
-produced by the @code{Time_signature_engraver} which you can check
-also lives in the @code{Staff} context and also supports the
-@code{grob-interface}. So the command to make the time signature
-transparent is:
-
-@cindex TimeSignature, example of overriding
-@cindex transparent property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
- \time 12/16
- \override Staff.TimeSignature #'transparent = ##t
- c4 b8 c d16 c d8 |
- g, a16 b8 c d4 e16 |
- e8
-}
-@end lilypond
-
-@noindent
-The time signature is gone, but this command leaves a gap where
-the time signature should be. Maybe this is what is wanted for
-an exercise for the student to fill it in, but in other
-circumstances a gap might be undesirable. To remove it, the
-stencil for the time signature should be set to @code{#f}
-instead:
-
-@cindex TimeSignature, example of overriding
-@cindex stencil property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
- \time 12/16
- \override Staff.TimeSignature #'stencil = ##f
- c4 b8 c d16 c d8 |
- g, a16 b8 c d4 e16 |
- e8
-}
-@end lilypond
-
-@noindent
-and the difference is obvious: setting the stencil to @code{#f}
-removes the object entirely; making the object @code{transparent}
-leaves it where it is, but makes it invisible.
-
-@subheading color
-
-@cindex color property
-
-Finally let us try making the bar lines invisible by coloring
-them white. (There is a difficulty with this in that the
-white bar line may or may not blank out the staff lines where
-they cross. You may see in some of the examples below that this
-happens unpredictably. The details of why this is so and how to
-control it are covered in @ruser{Painting objects white}. But at
-the moment we are learning about color, so please just accept this
-limitation for now.)
-
-The @code{grob-interface} specifies that the
-color property value is a list, but there is no
-explanation of what that list should be. The list it
-requires is actually a list of values in internal units,
-but, to avoid having to know what these are, several ways
-are provided to specify colors. The first way is to use one
-of the @q{normal} colors listed in the first table in
-@ruser{List of colors}. To set the bar lines to white
-we write:
-
-@cindex BarLine, example of overriding
-@cindex color property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
- \time 12/16
- \override Staff.BarLine #'color = #white
- c4 b8 c d16 c d8 |
- g, a16 b8 c d4 e16 |
- e8
-}
-@end lilypond
-
-@noindent
-and again, we see the bar lines are not visible. Note that
-@emph{white} is not preceded by an apostrophe -- it is not
-a symbol, but a @emph{function}. When called, it provides
-the list of internal values required to set the color to
-white. The other colors in the normal list are functions
-too. To convince yourself this is working you might like
-to change the color to one of the other functions in the
-list.
-
-@cindex color, X11
-@cindex X11 colors
-
-@funindex x11-color
-
-The second way of changing the color is to use the list of
-X11 color names in the second list in @ruser{List of colors}.
-However, these must be preceded by another function, which
-converts X11 color names into the list of internal values,
-@code{x11-color}, like this:
-
-@cindex BarLine, example of overriding
-@cindex color property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
- \time 12/16
- \override Staff.BarLine #'color = #(x11-color 'white)
- c4 b8 c d16 c d8 |
- g, a16 b8 c d4 e16 |
- e8
-}
-@end lilypond
-
-@noindent
-Note that in this case the function @code{x11-color} takes
-a symbol as an argument, so the symbol must be preceded by
-an apostrophe and the two enclosed in brackets.
-
-@cindex rgb colors
-@cindex color, rgb
-
-@funindex rgb-color
-
-There is yet a third function, one which converts RGB values into
-internal colors -- the @code{rgb-color} function. This takes
-three arguments giving the intensities of the red, green and
-blue colors. These take values in the range 0 to 1. So to
-set the color to red the value should be @code{(rgb-color 1 0 0)}
-and to white it should be @code{(rgb-color 1 1 1)}:
-
-@cindex BarLine, example of overriding
-@cindex color property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
- \time 12/16
- \override Staff.BarLine #'color = #(rgb-color 1 1 1)
- c4 b8 c d16 c d8 |
- g, a16 b8 c d4 e16 |
- e8
-}
-@end lilypond
-
-Finally, there is also a grey scale available as part of the
-X11 set of colors. These range from black, @code{'grey0'},
-to white, @code{'grey100}, in steps of 1. Let's illustrate
-this by setting all the layout objects in our example to
-various shades of grey:
-
-@cindex StaffSymbol, example of overriding
-@cindex TimeSignature, example of overriding
-@cindex Clef, example of overriding
-@cindex NoteHead, example of overriding
-@cindex Stem, example of overriding
-@cindex BarLine, example of overriding
-@cindex color property, example
-@cindex x11-color, example of using
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
- \time 12/16
- \override Staff.StaffSymbol #'color = #(x11-color 'grey30)
- \override Staff.TimeSignature #'color = #(x11-color 'grey60)
- \override Staff.Clef #'color = #(x11-color 'grey60)
- \override Voice.NoteHead #'color = #(x11-color 'grey85)
- \override Voice.Stem #'color = #(x11-color 'grey85)
- \override Staff.BarLine #'color = #(x11-color 'grey10)
- c4 b8 c d16 c d8 |
- g, a16 b8 c d4 e16 |
- e8
-}
-@end lilypond
-
-@noindent
-Note the contexts associated with each of the layout objects.
-It is important to get these right, or the commands will not
-work! Remember, the context is the one in which the appropriate
-engraver is placed. The default context for engravers can be
-found by starting from the layout object, going from there to
-the engraver which produces it, and on the engraver page in the
-IR it tells you in which context the engraver will normally be
-found.
-
-
-@node Size of objects
-@subsection Size of objects
-
-@cindex changing size of objects
-@cindex size of objects
-@cindex objects, size of
-@cindex objects, changing size of
-
-Let us begin by looking again at the earlier example
-see @ref{Nesting music expressions}) which showed
-how to introduce a new temporary staff, as in an @rglos{ossia}.
-
-@cindex alignAboveContext property, example
-@cindex @code{\with}, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\new Staff ="main" {
- \relative g' {
- r4 g8 g c4 c8 d |
- e4 r8
- <<
- { f c c }
- \new Staff \with {
- alignAboveContext = #"main" }
- { f8 f c }
- >>
- r4 |
- }
- }
-@end lilypond
-
-Ossia are normally written without clef and time signature, and
-are usually printed slightly smaller than the main staff. We
-already know now how to remove the clef and time signature --
-we simply set the stencil of each to @code{#f}, as follows:
-
-@cindex alignAboveContext property, example
-@cindex @code{\with}, example
-@cindex stencil property, example
-@cindex Clef, example of overriding
-@cindex TimeSignature, example of overriding
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\new Staff ="main" {
- \relative g' {
- r4 g8 g c4 c8 d |
- e4 r8
- <<
- { f c c }
- \new Staff \with {
- alignAboveContext = #"main"
- }
- {
- \override Staff.Clef #'stencil = ##f
- \override Staff.TimeSignature #'stencil = ##f
- { f8 f c }
- }
- >>
- r4 |
- }
-}
-@end lilypond
-
-@noindent
-where the extra pair of braces after the @code{\with} clause are
-required to ensure the enclosed overrides and music are applied
-to the ossia staff.
-
-But what is the difference between modifying the staff context by
-using @code{\with} and modifying the stencils of the clef and the
-time signature with \override? The main difference is that
-changes made in a @code{\with} clause are made at the time the
-context is created, and remain in force as the @strong{default}
-values for the duration of that context, whereas
-@code{\set} or @code{\override} commands embedded in the
-music are dynamic -- they make changes synchronized with
-a particular point in the music. If changes are unset or
-reverted using @code{\unset} or @code{\revert} they return to
-their default values, which will be the ones set in the
-@code{\with} clause, or if none have been set there, the normal
-default values.
-
-Some context properties can be modified only in @code{\with} clauses.
-These are those properties which cannot sensibly be changed after the
-context has been created. @code{alignAboveContext} and its partner,
-@code{alignBelowContext}, are two such properties -- once the staff
-has been created its alignment is decided and it would make no sense
-to try to change it later.
-
-The default values of layout object properties can also be set
-in @code{\with} clauses. Simply use the normal @code{\override}
-command leaving out the context name, since this is unambiguously
-defined as the context which the @code{\with} clause is modifying.
-If fact, an error will be generated if a context is specified
-in this location.
-
-So we could replace the example above with
-
-@cindex alignAboveContext property, example
-@cindex @code{\with}, example
-@cindex Clef, example of overriding
-@cindex TimeSignature, example of overriding
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\new Staff ="main" {
- \relative g' {
- r4 g8 g c4 c8 d |
- e4 r8
- <<
- { f c c }
- \new Staff \with {
- alignAboveContext = #"main"
- % Don't print clefs in this staff
- \override Clef #'stencil = ##f
- % Don't print time signatures in this staff
- \override TimeSignature #'stencil = ##f
- }
- { f8 f c }
- >>
- r4 |
- }
-}
-@end lilypond
-
-Finally we come to changing the size of layout objects.
-
-Some layout objects are created as glyphs selected from a typeface
-font. These include note heads, accidentals, markup, clefs, time
-signatures, dynamics and lyrics. Their size is changed by modifying
-the @code{font-size} property, as we shall shortly see. Other layout
-objects such as slurs and ties -- in general, spanner objects -- are
-drawn individually, so there is no @code{font-size} associated with
-them. These objects generally derive their size from the objects to
-which they are attached, so usually there is no need to change their
-size manually. Still other properties such as the length of stems and
-bar lines, thickness of beams and other lines, and the separation of
-staff lines all need to be modified in special ways.
-
-Returning to the ossia example, let us first change the font-size.
-We can do this in two ways. We can either change the size of the
-fonts of each object type, like @code{NoteHead}s with commands
-like
-
-@example
-\override NoteHead #'font-size = #-2
-@end example
-
-or we can change the size of all fonts by setting a special
-property, @code{fontSize}, using @code{\set}, or by including
-it in a @code{\with} clause (but without the @code{\set}).
-
-@example
-\set fontSize = #-2
-@end example
-
-Both of these statements would cause the font size to be reduced
-by 2 steps from its previous value, where each
-step reduces or increases the size by approximately 12%.
-
-Let's try it in our ossia example:
-
-@cindex alignAboveContext property, example
-@cindex @code{\with}, example
-@cindex Clef, example of overriding
-@cindex TimeSignature, example of overriding
-@cindex fontSize property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\new Staff ="main" {
- \relative g' {
- r4 g8 g c4 c8 d |
- e4 r8
- <<
- { f c c }
- \new Staff \with {
- alignAboveContext = #"main"
- \override Clef #'stencil = ##f
- \override TimeSignature #'stencil = ##f
- % Reduce all font sizes by ~24%
- fontSize = #-2
- }
- { f8 f c }
- >>
- r4 |
- }
-}
-@end lilypond
-
-This is still not quite right. The note heads and flags are
-smaller, but the stems are too long in proportion and the
-staff lines are spaced too widely apart. These need to be
-scaled down in proportion to the font reduction. The next
-sub-section discusses how this is done.
-
-@node Length and thickness of objects
-@subsection Length and thickness of objects
-
-@cindex distances
-@cindex thickness
-@cindex length
-@cindex magstep
-@cindex size, changing
-@cindex stem length, changing
-@cindex staff line spacing, changing
-
-Distances and lengths in LilyPond are generally measured in
-staff-spaces, the distance between adjacent lines in the staff,
-(or occasionally half staff spaces) while most @code{thickness}
-properties are measured in units of an internal property called
-@code{line-thickness.} For example, by default, the lines of
-hairpins are given a thickness of 1 unit of @code{line-thickness},
-while the @code{thickness} of a note stem is 1.3. Note, though,
-that some thickness properties are different; for example, the
-thickness of beams is measured in staff-spaces.
-
-So how are lengths to be scaled in proportion to the font size?
-This can be done with the help of a special function called
-@code{magstep} provided for exactly this purpose. It takes
-one argument, the change in font size (#-2 in the example above)
-and returns a scaling factor suitable for reducing other
-objects in proportion. It is used like this:
-
-@cindex alignAboveContext property, example
-@cindex @code{\with}, example
-@cindex Clef, example of overriding
-@cindex TimeSignature, example of overriding
-@cindex fontSize property, example
-@cindex StaffSymbol, example of overriding
-@cindex magstep function, example of using
-@cindex staff-space property, example
-@cindex stencil property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\new Staff ="main" {
- \relative g' {
- r4 g8 g c4 c8 d |
- e4 r8
- <<
- { f c c }
- \new Staff \with {
- alignAboveContext = #"main"
- \override Clef #'stencil = ##f
- \override TimeSignature #'stencil = ##f
- fontSize = #-2
- % Reduce stem length and line spacing to match
- \override StaffSymbol #'staff-space = #(magstep -2)
- }
- { f8 f c }
- >>
- r4 |
- }
-}
-@end lilypond
-
-@noindent
-Since the length of stems and many other length-related properties are
-always calculated relative to the value of the @code{staff-space}
-property these are automatically scaled down in length too. Note that
-this affects only the vertical scale of the ossia -- the horizontal
-scale is determined by the layout of the main music in order to remain
-synchronized with it, so it is not affected by any of these changes in
-size. Of course, if the scale of all the main music were changed in
-this way then the horizontal spacing would be affected. This is
-discussed later in the layout section.
-
-This, then, completes the creation of an ossia. The sizes and
-lengths of all other objects may be modified in analogous ways.
-
-For small changes in scale, as in the example above, the
-thickness of the various drawn lines such as bar lines,
-beams, hairpins, slurs, etc does not usually require global
-adjustment. If the thickness of any particular layout object
-needs to be adjusted this can be best achieved by overriding its
-@code{thickness} property. An example of changing the thickness
-of slurs was shown above in @ref{Properties of layout objects}.
-The thickness of all drawn objects (i.e., those not produced
-from a font) may be changed in the same way.
-
-
-@node Placement of objects
-@section Placement of objects
-
-@menu
-* Automatic behavior::
-* Within-staff objects::
-* Outside-staff objects::
-@end menu
-
-
-@node Automatic behavior
-@subsection Automatic behavior
-
-@cindex within-staff objects
-@cindex outside-staff objects
-@cindex objects, within-staff
-@cindex objects, outside-staff
-
-There are some objects in musical notation that belong to
-the staff and there are other objects that should be
-placed outside the staff. These are called within-staff
-objects and outside-staff objects respectively.
-
-Within-staff objects are those that are located on the staff
--- note heads, stems, accidentals, etc. The positions of
-these are usually fixed by the music itself -- they are
-vertically positioned on specific lines of the staff or are
-tied to other objects that are so positioned. Collisions of
-note heads, stems and accidentals in closely set chords are
-normally avoided automatically. There are commands and
-overrides which can modify this automatic behavior, as we
-shall shortly see.
-
-Objects belonging outside the staff include things such as
-rehearsal marks, text and dynamic markings. LilyPond's rule for
-the vertical placement of outside-staff objects is to place them
-as close to the staff as possible but not so close that they
-collide with any other object. LilyPond uses the
-@code{outside-staff-priority} property to determine the order in
-which the objects should be placed, as follows.
-
-First, LilyPond places all the within-staff objects.
-Then it sorts the outside-staff objects according to their
-@code{outside-staff-priority}. The outside-staff objects are
-taken one by one, beginning with the object with the lowest
-@code{outside-staff-priority}, and placed so that they do not
-collide with any objects that have already been placed. That is,
-if two outside-staff grobs are competing for the same space, the
-one with the lower @code{outside-staff-priority} will be placed
-closer to the staff. If two objects have the same
-@code{outside-staff-priority} the one encountered first will be
-placed closer to the staff.
-
-In the following example all the markup texts have the same
-priority (since it is not explicitly set). Note that @q{Text3}
-is automatically positioned close to the staff again, nestling
-under @q{Text2}.
-
-@cindex markup example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-c2^"Text1"
-c^"Text2"
-c^"Text3"
-c^"Text4"
-@end lilypond
-
-Staves are also positioned, by default, as closely together as
-possible (subject to a minimum separation). If notes project
-a long way towards an adjacent staff they will force the
-staves further apart only if an overlap of the notation
-would otherwise occur. The following example demonstrates
-this @q{nestling} of the notes on adjacent staves:
-
-@lilypond[quote,ragged-right,verbatim]
-<<
- \new Staff {
- \relative c' { c a, }
- }
- \new Staff {
- \relative c'''' { c a, }
- }
->>
-@end lilypond
-
-
-@node Within-staff objects
-@subsection Within-staff objects
-
-We have already seen how the commands @code{\voiceXXX} affect
-the direction of slurs, ties, fingering and
-everything else which depends on the direction of the stems.
-These commands are essential when writing polyphonic music to
-permit interweaving melodic lines to be distinguished.
-But occasionally it may be necessary to override this automatic
-behavior. This can be done for whole sections of music or even
-for an individual note. The property which controls this
-behavior is the @code{direction} property of each layout object.
-We first explain what this does, and then introduce a number of
-ready-made commands which avoid your having to code explicit
-overrides for the more common modifications.
-
-Some layout objects like slurs and ties curve, bend or point
-either up or down; others like stems and flags also move to
-right or left when they point up or down. This is controlled
-automatically when @code{direction} is set.
-
-@cindex down
-@cindex up
-@cindex center
-@cindex neutral
-
-The following example shows in bar 1 the default behavior of stems,
-with those on high notes pointing down and those on low notes pointing
-up, followed by four notes with all stems forced down, four notes with
-all stems forced up, and finally four notes reverted back to the
-default behavior.
-
-@cindex Stem, example of overriding
-@cindex direction property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-a4 g c a
-\override Stem #'direction = #DOWN
-a g c a
-\override Stem #'direction = #UP
-a g c a
-\revert Stem #'direction
-a g c a
-@end lilypond
-
-Here we use the constants @code{DOWN} and @code{UP}.
-These have the values @code{-1} and @code{+1} respectively, and
-these numerical values may be used instead. The value @code{0}
-may also be used in some cases. It is simply treated as meaning
-@code{UP} for stems, but for some objects it means @q{center}.
-There is a constant, @code{CENTER} which has the value @code{0}.
-
-However, these explicit overrides are not usually used, as there are
-simpler equivalent predefined commands available. Here is a table of
-the commonest. The meaning of each is stated where it is not obvious.
-
-@multitable @columnfractions .2 .2 .25 .35
-@headitem Down/Left
- @tab Up/Right
- @tab Revert
- @tab Effect
-@item @code{\arpeggioArrowDown}
- @tab @code{\arpeggioArrowUp}
- @tab @code{\arpeggioNormal}
- @tab Arrow is at bottom, at top, or no arrow
-@item @code{\dotsDown}
- @tab @code{\dotsUp}
- @tab @code{\dotsNeutral}
- @tab Direction of movement to avoid staff lines
-@item @code{\dynamicDown}
- @tab @code{\dynamicUp}
- @tab @code{\dynamicNeutral}
- @tab
-@item @code{\phrasingSlurDown}
- @tab @code{\phrasingSlurUp}
- @tab @code{\phrasingSlurNeutral}
- @tab Note: distinct from slur commands
-@item @code{\slurDown}
- @tab @code{\slurUp}
- @tab @code{\slurNeutral}
- @tab
-@item @code{\stemDown}
- @tab @code{\stemUp}
- @tab @code{\stemNeutral}
- @tab
-@item @code{\textSpannerDown}
- @tab @code{\textSpannerUp}
- @tab @code{\textSpannerNeutral}
- @tab Text entered as spanner is below/above staff
-@item @code{\tieDown}
- @tab @code{\tieUp}
- @tab @code{\tieNeutral}
- @tab
-@item @code{\tupletDown}
- @tab @code{\tupletUp}
- @tab @code{\tupletNeutral}
- @tab Tuplets are below/above notes
-@end multitable
-
-Note that these predefined commands may @strong{not} be
-preceded by @code{\once}. If you wish to limit the
-effect to a single note you must either use the equivalent
-@code{\once \override} command or use the predefined command
-followed after the affected note by the corresponding
-@code{\xxxNeutral} command.
-
-@subheading Fingering
-
-@cindex fingering, placement
-@cindex fingering, chords
-
-The placement of fingering on single notes can also be controlled
-by the @code{direction} property, but changing @code{direction}
-has no effect on chords. As we shall see, there are special
-commands which allow the fingering of individual notes
-of chords to be controlled, with the fingering being placed
-above, below, to the left or to the right of each note.
-
-First, here's the effect of @code{direction} on the fingering
-attached to single notes. The first bar shows the default
-behaviour, and the following two bars shows the effect of
-specifying @code{DOWN} and @code{UP}:
-
-@cindex Fingering, example of overriding
-@cindex direction property, example
-
-@lilypond[quote,verbatim,relative=2]
-c-5 a-3 f-1 c'-5
-\override Fingering #'direction = #DOWN
-c-5 a-3 f-1 c'-5
-\override Fingering #'direction = #UP
-c-5 a-3 f-1 c'-5
-@end lilypond
-
-However, overriding the @code{direction} property is not the
-easiest way of manually setting the fingering above or below
-the notes; using @code{_} or @code{^} instead of @code{-} before
-the fingering number is usually preferable. Here is the previous
-example using this method:
-
-@cindex fingering example
-
-@lilypond[quote,verbatim,relative=2]
-c-5 a-3 f-1 c'-5
-c_5 a_3 f_1 c'_5
-c^5 a^3 f^1 c'^5
-@end lilypond
-
-The @code{direction} property is ignored for chords, but the
-directional prefixes, @code{_} and @code{^} do work. By default,
-the fingering is automatically placed both above and below the
-notes of a chord, as shown:
-
-@cindex fingering example
-
-@lilypond[quote,verbatim,relative=2]
-<c-5 g-3>
-<c-5 g-3 e-2>
-<c-5 g-3 e-2 c-1>
-@end lilypond
-
-@noindent
-but this may be overriden to manually force all or any of the
-individual fingering numbers above or below:
-
-@cindex fingering example
-
-@lilypond[quote,verbatim,relative=2]
-<c-5 g-3 e-2 c-1>
-<c^5 g_3 e_2 c_1>
-<c^5 g^3 e^2 c_1>
-@end lilypond
-
-Even greater control over the placement of fingering of the
-individual notes in a chord is possible by using the
-@code{\set fingeringOrientations} command. The format of this
-command is:
-
-@example
-@code{\set fingeringOrientations = #'([up] [left/right] [down])}
-@end example
-
-@noindent
-@code{\set} is used because @code{fingeringOrientations} is a
-property of the @code{Voice} context, created and used by the
-@code{New_fingering_engraver}.
-
-The property may be set to a list of one to three values.
-It controls whether fingerings may be placed above (if
-@code{up} appears in the list), below (if @code{down} appears),
-to the left (if @code{left} appears, or to the right
-(if @code{right} appears). Conversely, if a location is not
-listed, no fingering is placed there. LilyPond takes these
-constraints and works out the best placement for the fingering
-of the notes of the following chords. Note that @code{left} and
-@code{right} are mutually exclusive -- fingering may be placed
-only on one side or the other, not both.
-
-@warning{To control the placement of the fingering of a single
-note using this command it is necessary to write it as a single
-note chord by placing angle brackets round it.}
-
-Here are a few examples:
-
-@cindex fingering example
-@cindex @code{\set}, example of using
-@cindex fingeringOrientations property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-\set fingeringOrientations = #'(left)
-<f-2>
-< c-1 e-2 g-3 b-5 > 4
-\set fingeringOrientations = #'(left)
-<f-2>
-< c-1 e-2 g-3 b-5 > 4
-\set fingeringOrientations = #'(up left down)
-<f-2>
-< c-1 e-2 g-3 b-5 > 4
-\set fingeringOrientations = #'(up left)
-<f-2>
-< c-1 e-2 g-3 b-5 > 4
-\set fingeringOrientations = #'(right)
-<f-2>
-< c-1 e-2 g-3 b-5 > 4
-@end lilypond
-
-@noindent
-If the fingering seems a little crowded the @code{font-size}
-could be reduced. The default value can be seen from the
-@code{Fingering} object in the IR to be @code{-5}, so let's
-try @code{-7}:
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-\override Fingering #'font-size = #-7
-\set fingeringOrientations = #'(left)
-<f-2>
-< c-1 e-2 g-3 b-5 > 4
-\set fingeringOrientations = #'(left)
-<f-2>
-< c-1 e-2 g-3 b-5 > 4
-\set fingeringOrientations = #'(up left down)
-<f-2>
-< c-1 e-2 g-3 b-5 > 4
-\set fingeringOrientations = #'(up left)
-<f-2>
-< c-1 e-2 g-3 b-5 > 4
-\set fingeringOrientations = #'(right)
-<f-2>
-< c-1 e-2 g-3 b-5 > 4
-@end lilypond
-
-@node Outside-staff objects
-@subsection Outside-staff objects
-
-Outside-staff objects are automatically placed to avoid collisions.
-Objects with the lower value of the @code{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 @code{outside-staff-priority} is defined in the
-@code{grob-interface} and so is a property of all layout objects.
-By default it is set to @code{#f} for all within-staff objects,
-and to a numerical value appropriate to each outside-staff object
-when the object is created. The following table shows
-the default numerical values for some of the commonest
-outside-staff objects which are, by default, placed in the
-@code{Staff} or @code{Voice} contexts.
-
-@multitable @columnfractions .3 .3 .3
-@headitem Layout Object
- @tab Priority
- @tab Controls position of:
-@item @code{MultiMeasureRestText}
- @tab @code{450}
- @tab Text over full-bar rests
-@item @code{TextScript}
- @tab @code{450}
- @tab Markup text
-@item @code{OttavaBracket}
- @tab @code{400}
- @tab Ottava brackets
-@item @code{TextSpanner}
- @tab @code{350}
- @tab Text spanners
-@item @code{DynamicLineSpanner}
- @tab @code{250}
- @tab All dynamic markings
-@item @code{VoltaBracketSpanner}
- @tab @code{100}
- @tab Volta brackets
-@item @code{TrillSpanner}
- @tab @code{50}
- @tab Spanning trills
-@end multitable
-
-Here is an example showing the default placement of some of
-these.
-
-@cindex text spanner
-@cindex ottava bracket
-
-@funindex \startTextSpan
-@funindex startTextSpan
-@funindex \stopTextSpan
-@funindex stopTextSpan
-
-@cindex TextSpanner, example of overriding
-@cindex bound-details property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-% Set details for later Text Spanner
-\override TextSpanner #'(bound-details left text)
- = \markup { \small \bold Slower }
-% Place dynamics above staff
-\dynamicUp
-% Start Ottava Bracket
-\ottava #1
-c' \startTextSpan
-% Add Dynamic Text
-c\pp
-% Add Dynamic Line Spanner
-c\<
-% Add Text Script
-c^Text
-c c
-% Add Dynamic Text
-c\ff c \stopTextSpan
-% Stop Ottava Bracket
-\ottava #0
-c, c c c
-@end lilypond
-
-This example also shows how to create Text Spanners --
-text with extender lines above a section of music. The
-spanner extends from the @code{\startTextSpan} command to
-the @code{\stopTextSpan} command, and the format of the
-text is defined by the @code{\override TextSpanner} command.
-For more details see @ruser{Text spanners}.
-
-It also shows how ottava brackets are created.
-
-@cindex tweaking bar number placement
-@cindex bar numbers, tweaking placement
-@cindex tweaking metronome mark placement
-@cindex metronome mark, tweaking placement
-@cindex tweaking rehearsal mark placement
-@cindex rehearsal marks, tweaking placement
-
-Note that bar numbers, metronome marks and rehearsal marks are not
-shown. By default these are created in the @code{Score} context and
-their @code{outside-staff-priority} is ignored relative to the layout
-objects which are created in the @code{Staff} context. If you wish to
-place bar numbers, metronome marks or rehearsal marks in accordance
-with the value of their @code{outside-staff-priority} the
-@code{Bar_number_engraver}, @code{Metronome_mark_engraver} or
-@code{Mark_engraver} respectively should be removed from the
-@code{Score} context and placed in the top @code{Staff} context. If
-this is done, these marks will be given the following default
-@code{outside-staff-priority} values:
-
-@multitable @columnfractions .3 .3
-@headitem Layout Object @tab Priority
-@item @code{RehearsalMark} @tab @code{1500}
-@item @code{MetronomeMark} @tab @code{1000}
-@item @code{BarNumber} @tab @code{ 100}
-@end multitable
-
-If the default values of @code{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 @code{OttavaBracket} in the IR or in the
-tables above, and reduce it to a value lower than that of a
-@code{TextSpanner}, remembering that @code{OttavaBracket} is created
-in the @code{Staff} context:
-
-@cindex TextSpanner, example of overriding
-@cindex bound-details property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-% 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' \startTextSpan
-% Add Dynamic Text
-c\pp
-% Add Dynamic Line Spanner
-c\<
-% Add Text Script
-c^Text
-c c
-% Add Dynamic Text
-c\ff c \stopTextSpan
-% Stop Ottava Bracket
-\ottava #0
-c, c c c
-@end lilypond
-
-@cindex slurs and outside-staff-priority
-@cindex slurs and articulations
-@cindex articulations and slurs
-
-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 @code{avoid-slur} property of the
-articulation can be set to @code{'inside} to bring the articulation
-inside the slur, but the @code{avoid-slur} property is effective
-only if the @code{outside-staff-priority} is also set to @code{#f}.
-Alternatively, the @code{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:
-
-@lilypond[quote,verbatim,relative=2]
-c4( c^\markup\tiny\sharp d4.) c8
-c4(
-\once \override TextScript #'avoid-slur = #'inside
-\once \override TextScript #'outside-staff-priority = ##f
-c^\markup\tiny\sharp d4.) c8
-\once \override Slur #'outside-staff-priority = #500
-c4( c^\markup\tiny\sharp d4.) c8
-@end lilypond
-
-Changing the @code{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 @qq{Text3} to be placed above @qq{Text4} in the example
-under Automatic behavior, above (see @ref{Automatic behavior}).
-All we need to do is to look up the priority of @code{TextScript}
-in the IR or in the tables above, and increase the priority of
-@qq{Text3} to a higher value:
-
-@cindex TextScript, example of overriding
-@cindex outside-staff-priority property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-c2^"Text1"
-c^"Text2"
-\once \override TextScript #'outside-staff-priority = #500
-c^"Text3"
-c^"Text4"
-@end lilypond
-
-This certainly lifts @qq{Text3} above @qq{Text4} but it also lifts it
-above @qq{Text2}, and @qq{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 @code{textLengthOn}
-command.
-
-@subheading \textLengthOn
-
-@cindex notes, spreading out with text
-
-@funindex \textLengthOn
-@funindex textLengthOn
-@funindex \textLengthOff
-@funindex textLengthOff
-
-By default, text produced by markup takes up no horizontal space
-as far as laying out the music is concerned. The @code{\textLengthOn}
-command reverses this behavior, causing the notes to be spaced
-out as far as is necessary to accommodate the text:
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\textLengthOn % Cause notes to space out to accommodate text
-c2^"Text1"
-c^"Text2"
-c^"Text3"
-c^"Text4"
-@end lilypond
-
-The command to revert to the default behavior is
-@code{\textLengthOff}. Remember @code{\once} only works with
-@code{\override}, @code{\set}, @code{\revert} or @code{unset},
-so cannot be used with @code{\textLengthOn}.
-
-@cindex markup text, allowing collisions
-
-Markup text will also avoid notes which project above the staff.
-If this is not desired, the automatic displacement upwards may
-be turned off by setting the priority to @code{#f}. Here's an
-example to show how markup text interacts with such notes.
-
-@cindex TextScript, example of overriding
-@cindex outside-staff-priority property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-% This markup is short enough to fit without collision
-c2^"Tex"
-c''2
-R1
-% This is too long to fit, so it is displaced upwards
-c,,2^"Text"
-c''2
-R1
-% Turn off collision avoidance
-\once \override TextScript #'outside-staff-priority = ##f
-c,,2^"Long Text "
-c''2
-R1
-% Turn off collision avoidance
-\once \override TextScript #'outside-staff-priority = ##f
-\textLengthOn % and turn on textLengthOn
-c,,2^"Long Text " % Spaces at end are honored
-c''2
-@end lilypond
-
-
-@subheading Dynamics
-
-@cindex tweaking dynamics placement
-@cindex dynamics, tweaking placement
-
-Dynamic markings will normally be positioned beneath the
-staff, but may be positioned above with the @code{dynamicUp}
-command. They will be positioned vertically relative to the
-note to which they are attached, and will float below (or above)
-all within-staff objects such as phrasing slurs and bar numbers.
-This can give quite acceptable results, as this example
-shows:
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-\clef "bass"
-\key aes \major
-\time 9/8
-\dynamicUp
-bes4.~\f\< \( bes4 bes8 des4\ff\> c16 bes\! |
-ees,2.~\)\mf ees4 r8 |
-@end lilypond
-
-However, if the notes and attached dynamics are close
-together the automatic placement will avoid collisions
-by displacing later dynamic markings further away, but this may
-not be the optimum placement, as this rather artificial example
-shows:
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\dynamicUp
-a4\f b\mf c\mp b\p
-@end lilypond
-
-@noindent
-Should a similar situation arise in @q{real} music, it may be
-preferable to space out the notes a little further, so the dynamic
-markings can all fit at the same vertical distance from the staff. We
-were able to do this for markup text by using the @code{\textLengthOn}
-command, but there is no equivalent command for dynamic marks. So we
-shall have to work out how to do this using @code{\override} commands.
-
-@subheading Grob sizing
-
-@cindex grob sizing
-@cindex sizing grobs
-
-First we must learn how grobs are sized. All grobs have a
-reference point defined within them which is used to position
-them relative to their parent object. This point in the grob
-is then positioned at a horizontal distance, @code{X-offset},
-and at a vertical distance, @code{Y-offset}, from its parent.
-The horizontal extent of the object is given by a pair of
-numbers, @code{X-extent}, which say where the left and right
-edges are relative to the reference point. The vertical extent
-is similarly defined by a pair of numbers, @code{Y-extent}.
-These are properties of all grobs which support the
-@code{grob-interface}.
-
-@cindex @code{extra-spacing-width}
-
-By default, outside-staff objects are given a width of zero so
-that they may overlap in the horizontal direction. This is done
-by the trick of adding infinity to the leftmost extent and
-minus infinity to the rightmost extent by setting the
-@code{extra-spacing-width} to @code{'(+inf.0 . -inf.0)}. So
-to ensure they do not overlap in the horizontal direction we
-must override this value of @code{extra-spacing-width} to
-@code{'(0 . 0)} so the true width shines through. This is
-the command to do this for dynamic text:
-
-@example
-\override DynamicText #'extra-spacing-width = #'(0 . 0)
-@end example
-
-@noindent
-Let's see if this works in our previous example:
-
-@cindex DynamicText, example of overriding
-@cindex extra-spacing-width property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\dynamicUp
-\override DynamicText #'extra-spacing-width = #'(0 . 0)
-a4\f b\mf c\mp b\p
-@end lilypond
-
-@noindent
-Well, it has certainly stopped the dynamic marks being
-displaced, but two problems remain. The marks should be
-spaced a little further apart and it would be better
-if they were all the same distance from the staff.
-We can solve the first problem easily. Instead of making
-the @code{extra-spacing-width} zero we could add a little
-more to it. The units are the space between two staff
-lines, so moving the left edge half a unit to the left and the
-right edge half a unit to the right should do it:
-
-@cindex DynamicText, example of overriding
-@cindex extra-spacing-width property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\dynamicUp
-% Extend width by 1 staff space
-\override DynamicText #'extra-spacing-width = #'(-0.5 . 0.5)
-a4\f b\mf c\mp b\p
-@end lilypond
-
-@noindent
-This looks better, but maybe we would prefer the dynamic marks
-to be aligned along the same baseline rather than going up and
-down with the notes. The property to do this is
-@code{staff-padding} which is covered in the following section.
-
-
-@node Collisions of objects
-@section Collisions of objects
-
-@menu
-* Moving objects::
-* Fixing overlapping notation::
-* Real music example::
-@end menu
-
-@node Moving objects
-@subsection Moving objects
-
-@cindex moving overlapping objects
-@cindex moving colliding objects
-@cindex moving colliding grobs
-@cindex objects, moving colliding
-@cindex grobs, moving colliding
-
-This may come as a surprise, but LilyPond is not perfect. Some
-notation elements can overlap. This is unfortunate, but in fact
-rather rare. Usually the need to move objects is for clarity or
-aesthetic reasons -- they would look better with a little more
-or a little less space around them.
-
-There are three main approaches to resolving overlapping
-notation. They should be considered in the following order:
-
-@enumerate
-@item
-The @strong{direction} of one of the overlapping objects may
-be changed using the predefined commands listed above for
-within-staff objects (see @ref{Within-staff objects}).
-Stems, slurs, beams, ties, dynamics, text and tuplets may be
-repositioned easily in this way. The limitation is that you
-have a choice of only two positions, and neither may be
-suitable.
-
-@item
-The @strong{object properties}, which LilyPond uses when positioning
-layout objects, may be modified using @code{\override}. The
-advantages of making changes to this type of property are (a) that
-some other objects will be moved automatically if necessary to make
-room and (b) the single override can apply to all instances of the
-same type of object. Such properties include:
-
-@itemize
-
-@item
-@code{direction}
-
-This has already been covered in some detail -- see
-@ref{Within-staff objects}.
-
-@item
-@code{padding}, @code{left-padding},
-@code{right-padding}, @code{staff-padding}
-
-@cindex padding
-@cindex left-padding property
-@cindex padding property
-@cindex right-padding property
-@cindex staff-padding property
-
-As an object is being positioned the value of its @code{padding}
-property specifies the gap that must be left between itself and the
-nearest edge of the object against which it is being positioned. Note
-that it is the @code{padding} value of the object @strong{being
-placed} that is used; the @code{padding} value of the object which is
-already placed is ignored. Gaps specified by @code{padding} can be
-applied to all objects which support the
-@code{side-position-interface}.
-
-Instead of @code{padding}, the placement of groups of accidentals
-is controlled by @code{left-padding} and @code{right-padding}.
-These properties are to be found in the @code{AccidentalPlacement}
-object which, note, lives in the @strong{staff} context. In the
-type-setting process the note heads are type-set first and then
-the accidentals, if any, are added to the left of the note heads
-using the @code{right-padding} property to determine the separation
-from the note heads. So only the @code{right-padding} property of the
-@code{AccidentalPlacement} object has any effect on the placement
-of the accidentals.
-
-The @code{staff-padding} property is closely related to the
-@code{padding} property: @code{padding} controls the minimum amount of
-space between any object which supports the
-@code{side-position-interface} and the nearest other object (generally
-the note or the staff lines); @code{staff-padding} applies only to
-those objects which are always set outside the staff -- it controls
-the minimum amount of space that should be inserted between that
-object and the staff. Note that @code{staff-padding} has no effect on
-objects which are positioned relative to the note rather than the
-staff, even though it may be overridden without error for such objects
--- it is simply ignored.
-
-To discover which padding property is required for the object you wish
-to reposition, you need to return to the IR and look up the object's
-properties. Be aware that the padding properties might not be located
-in the obvious object, so look in objects that appear to be related.
-
-All padding values are measured in staff spaces. For most
-objects, this value is set by default to be around 1.0 or less
-(it varies with each object). It may be overridden if a larger
-(or smaller) gap is required.
-
-@item
-@code{self-alignment-X}
-
-@cindex self-alignment-X property
-
-This property can be used to align the object to the left, to
-the right, or to center it with respect to the parent object's
-reference point. It may be used with all objects which support
-the @code{self-alignment-interface}. In general these are objects
-that contain text. The values are @code{LEFT}, @code{RIGHT}
-or @code{CENTER}. Alternatively, a numerical value between
-@code{-1} and @code{+1} may be specified, where @code{-1} is
-left-aligned, @code{+1} is right-aligned, and numbers in between
-move the text progressively from left-aligned to right-aligned.
-Numerical values greater than @code{1} may be specified to move
-the text even further to the left, or less than @code{-1} to
-move the text even further to the right. A change of @code{1}
-in the value corresponds to a movement of half the text's length.
-
-@item
-@code{extra-spacing-width}
-
-@cindex extra-spacing-width property
-
-This property is available for all objects which support the
-@code{item-interface}. It takes two numbers, the first is added
-to the leftmost extent and the second is added to the rightmost
-extent. Negative numbers move the edge to the left, positive to
-the right, so to widen an object the first number must be negative,
-the second positive. Note that not all objects honor both
-numbers. For example, the @code{Accidental} object only takes
-notice of the first (left edge) number.
-
-@item
-@code{staff-position}
-
-@cindex staff-position property
-
-@code{staff-position} is a property of the
-@code{staff-symbol-referencer-interface}, which is supported by
-objects which are positioned relative to the staff. It specifies
-the vertical position of the object relative to the center line
-of the staff in half staff-spaces. It is useful in resolving
-collisions between layout objects like multi-measure rests, ties
-and notes in different voices.
-
-@item
-@code{force-hshift}
-
-@cindex force-hshift property
-
-Closely spaced notes in a chord, or notes occurring at the same
-time in different voices, are arranged in two, occasionally more,
-columns to prevent the note heads overlapping. These are called
-note columns, and an object called @code{NoteColumn} is created
-to lay out the notes in that column.
-
-The @code{force-hshift} property is a property of a @code{NoteColumn}
-(actually of the @code{note-column-interface}). Changing it permits a
-note column to be moved in units appropriate to a note column,
-viz. the note head width of the first voice note. It should be used
-in complex situations where the normal @code{\shiftOn} commands (see
-@ref{Explicitly instantiating voices}) do not resolve the note
-conflict. It is preferable to the @code{extra-offset} property for
-this purpose as there is no need to work out the distance in
-staff-spaces, and moving the notes into or out of a @code{NoteColumn}
-affects other actions such as merging note heads.
-
-@end itemize
-
-@item
-Finally, when all else fails, objects may be manually repositioned
-relative to the staff center line vertically, or by displacing them by
-any distance to a new position. The disadvantages are that the
-correct values for the repositioning have to be worked out, often by
-trial and error, for every object individually, and, because the
-movement is done after LilyPond has placed all other objects, the user
-is responsible for avoiding any collisions that might ensue. But the
-main difficulty with this approach is that the repositioning values
-may need to be reworked if the music is later modified. The
-properties that can be used for this type of manual repositioning are:
-
-@table @code
-@item extra-offset
-
-@cindex extra-offset property
-
-This property applies to any layout object supporting the
-@code{grob-interface}. It takes a pair of numbers which specify the
-extra displacement in the horizontal and vertical directions.
-Negative numbers move the object to the left or down. The units are
-staff-spaces. The extra displacement is made after the typesetting of
-objects is finished, so an object may be repositioned anywhere without
-affecting anything else.
-
-@item positions
-
-@cindex positions property
-
-This is most useful for manually adjusting the slope and height
-of beams, slurs, and tuplets. It takes a pair of numbers
-giving the position of the left and right ends of the beam, slur,
-etc. relative to the center line of the staff. Units are
-staff-spaces. Note, though, that slurs and phrasing slurs cannot
-be repositioned by arbitrarily large amounts. LilyPond first
-generates a list of possible positions for the slur and by default
-finds the slur that @qq{looks best}. If the @code{positions}
-property has been overridden the slur that is closest to the
-requested positions is selected from the list.
-@end table
-
-@end enumerate
-
-A particular object may not have all of these properties.
-It is necessary to go to the IR to look up which properties
-are available for the object in question.
-
-Here is a list of the objects which are most likely to be
-involved in collisions, together with the name of the object which
-should be looked up in the IR in order to discover which properties
-should be used to move them.
-
-@multitable @columnfractions .5 .5
-@headitem Object type @tab Object name
-@item Articulations @tab @code{Script}
-@item Beams @tab @code{Beam}
-@item Dynamics (vertically) @tab @code{DynamicLineSpanner}
-@item Dynamics (horizontally) @tab @code{DynamicText}
-@item Fingerings @tab @code{Fingering}
-@item Rehearsal / Text marks @tab @code{RehearsalMark}
-@item Slurs @tab @code{Slur}
-@item Text e.g. @code{^"text"} @tab @code{TextScript}
-@item Ties @tab @code{Tie}
-@item Tuplets @tab @code{TupletBracket}
-@end multitable
-
-
-@node Fixing overlapping notation
-@subsection Fixing overlapping notation
-
-Let's now see how the properties in the previous section can
-help to resolve overlapping notation.
-
-@subheading padding property
-
-@cindex padding
-@cindex fixing overlapping notation
-@cindex overlapping notation
-
-The @code{padding} property can be set to increase
-(or decrease) the distance between symbols that are printed
-above or below notes.
-
-@cindex Script, example of overriding
-@cindex padding property, example
-
-@lilypond[quote,fragment,relative=1,verbatim]
-c2\fermata
-\override Script #'padding = #3
-b2\fermata
-@end lilypond
-
-@cindex MetronomeMark, example of overriding
-@cindex padding property, example
-
-@lilypond[quote,fragment,relative=1,verbatim]
-% This will not work, see below:
-\override MetronomeMark #'padding = #3
-\tempo 4=120
-c1
-% This works:
-\override Score.MetronomeMark #'padding = #3
-\tempo 4=80
-d1
-@end lilypond
-
-Note in the second example how important it is to figure out what
-context handles a certain object. Since the @code{MetronomeMark}
-object is handled in the @code{Score} context, property changes in the
-@code{Voice} context will not be noticed. For more details, see
-@ruser{Modifying properties}.
-
-If the @code{padding} property of an object is increased when that
-object is in a stack of objects being positioned according to
-their @code{outside-staff-priority}, then that object and all
-objects outside it are moved.
-
-
-@subheading left-padding and right-padding
-
-@cindex left-padding property
-@cindex right-padding property
-
-The @code{right-padding} property affects the spacing between the
-accidental and the note to which it applies. It is not often
-required, but the following example shows one situation where it
-is needed. Suppose we wish to show a chord containing both
-a B-natural and a B-flat. To avoid ambiguity we would like to
-precede the notes with both a natural and a flat sign. Here
-are a few attempts to do this:
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-<b bes>
-<b! bes>
-<b? bes>
-@end lilypond
-
-None work, with the second two showing bad collisions between
-the two signs.
-
-One way of achieving this is to override the accidental stencil
-with a markup containing the natural and flat symbols in the
-order we would like, like this:
-
-@cindex Accidental, example of overriding
-@cindex text property, example
-@cindex stencil property, example
-@cindex AccidentalPlacement, example of overriding
-@cindex right-padding property, example
-
-@lilypond[quote,ragged-right,verbatim]
-naturalplusflat = \markup { \natural \flat }
-\relative c'' {
- \once \override Accidental
- #'stencil = #ly:text-interface::print
- \once \override Accidental #'text = #naturalplusflat
- \once \override Score.AccidentalPlacement #'right-padding = #1.5
- <b bes>
-}
-@end lilypond
-
-@noindent
-This necessarily uses an override for the accidental stencil which
-will not be covered until later. The stencil type must be a
-procedure, here changed to print the contents of the @code{text}
-property of @code{Accidental}, which itself is set to be a natural
-sign followed by a flat sign. These are then moved further away
-from the note head by overriding @code{right-padding}.
-
-@noindent
-
-@subheading staff-padding property
-
-@cindex aligning objects on a baseline
-@cindex objects, aligning on a baseline
-
-@code{staff-padding} can be used to align objects such as dynamics
-along a baseline at a fixed height above the staff, rather than at a
-height dependent on the position of the note to which they are
-attached. It is not a property of @code{DynamicText} but of
-@code{DynamicLineSpanner}. This is because the baseline should apply
-equally to @strong{all} dynamics, including those created as extended
-spanners. So this is the way to align the dynamic marks in the
-example taken from the previous section:
-
-@cindex DynamicText, example of overriding
-@cindex extra-spacing-width property, example
-@cindex DynamicLineSpanner, example of overriding
-@cindex staff-padding property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\dynamicUp
-% Extend width by 1 unit
-\override DynamicText #'extra-spacing-width = #'(-0.5 . 0.5)
-% Align dynamics to a base line 2 units above staff
-\override DynamicLineSpanner #'staff-padding = #2
-a4\f b\mf c\mp b\p
-@end lilypond
-
-
-@subheading self-alignment-X property
-
-The following example shows how this can resolve the collision
-of a string fingering object with a note's stem by aligning the
-right edge with the reference point of the parent note:
-
-@cindex StringNumber, example of overriding
-@cindex self-alignment-X property, example
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=3]
-\voiceOne
-< a \2 >
-\once \override StringNumber #'self-alignment-X = #RIGHT
-< a \2 >
-@end lilypond
-
-@subheading staff-position property
-
-@cindex object collision within a staff
-
-Multimeasure rests in one voice can collide with notes in another.
-Since these rests are typeset centered between the bar lines, it
-would require significant effort for LilyPond to figure out which
-other notes might collide with it, since all the current collision
-handling between notes and between notes and rests is done only
-for notes and rests that occur at the same time. Here's an
-example of a collision of this type:
-
-@lilypond[quote,verbatim,fragment,ragged-right, relative=1]
-<< {c c c c} \\ {R1} >>
-@end lilypond
-
-The best solution here is to move the multimeasure rest down, since
-the rest is in voice two. The default in @code{\voiceTwo} (i.e. in
-the second voice of a @code{<<@{...@} \\ @{...@}>>} construct) is that
-@code{staff-position} is set to -4 for MultiMeasureRest, so we need to
-move it, say, four half-staff spaces down to @code{-8}.
-
-@cindex MultiMeasureRest, example of overriding
-@cindex staff-position property, example
-
-@lilypond[quote,verbatim,fragment,ragged-right, relative=1]
-<<
- {c c c c}
-\\
- \override MultiMeasureRest #'staff-position = #-8
- {R1}
->>
-@end lilypond
-
-This is better than using, for example, @code{extra-offset},
-because the ledger line above the rest is inserted automatically.
-
-@subheading extra-offset property
-
-@cindex positioning objects
-@cindex positioning grobs
-@cindex objects, positioning
-@cindex grobs, positioning
-
-The @code{extra-offset} property provides complete control over the
-positioning of an object both horizontally and vertically.
-
-In the following example, the second fingering is moved a little to
-the left, and 1.8 staff space downwards:
-
-@cindex Fingering, example of overriding
-@cindex extra-offset property, example
-
-@lilypond[quote,fragment,relative=1,verbatim]
-\stemUp
-f-5
-\once \override Fingering
- #'extra-offset = #'(-0.3 . -1.8)
-f-5
-@end lilypond
-
-
-@subheading positions property
-
-@cindex controlling tuplets, slurs, phrasing slurs, and beams manually
-@cindex manually controlling tuplets, slurs, phrasing slurs, and beams
-@cindex tuplet beams, controlling manually
-@cindex slurs, controlling manually
-@cindex phrasing slurs, controlling manually
-@cindex beams, controlling manually
-
-The @code{positions} property allows the position and slope of
-tuplets, slurs, phrasing slurs and beams to be controlled manually.
-Here's an example which has an ugly phrasing slur due to its trying to
-avoid the slur on the acciaccatura.
-
-@lilypond[quote,verbatim,fragment,ragged-right,relative=1]
-r4 \acciaccatura e8\( d8 c ~c d c d\)
-@end lilypond
-
-@noindent
-We could simply move the phrasing slur above the notes, and this
-would be the preferred solution:
-
-@lilypond[quote,verbatim,fragment,ragged-right,relative=1]
-r4
-\phrasingSlurUp
-\acciaccatura e8\( d8 c ~c d c d\)
-@end lilypond
-
-@noindent
-But if there were some reason why this could not be done the
-other alternative would be to move the left end of the phrasing
-slur down a little using the @code{positions} property. This
-also resolves the rather nasty shape.
-
-@cindex PhrasingSlur, example of overriding
-@cindex positions property, example
-
-@lilypond[quote,verbatim,fragment,ragged-right,relative=1]
-r4
-\once \override PhrasingSlur #'positions = #'(-4 . -3)
-\acciaccatura
-e8\( d8 c ~c d c d\)
-@end lilypond
-
-Here's a further example taken from the opening of the left-hand
-staff of Chopin's Prelude Op 28 No. 2. We see that the beam
-collides with the upper notes:
-
-@lilypond[quote,verbatim,fragment,ragged-right]
-{
-\clef "bass"
-<< {b,8 ais, b, g,} \\ {e, g e, g} >>
-<< {b,8 ais, b, g,} \\ {e, g e, g} >>
-}
-@end lilypond
-
-@noindent
-This can be resolved by manually moving both ends of the beam
-up from their position at 2 staff-spaces above the center line to,
-say, 3:
-
-@cindex Beam, example of overriding
-@cindex positions property, example
-
-@lilypond[quote,verbatim,fragment,ragged-right]
-{
- \clef "bass"
- <<
- \override Beam #'positions = #'(3 . 3)
- {b,8 ais, b, g,}
- \\
- {e, g e, g}
- >>
- << {b,8 ais, b, g,} \\ {e, g e, g} >>
-}
-@end lilypond
-
-@noindent
-Note that the override continues to apply in the first voice of
-the second block of quavers, but not to any of the beams in the
-second voice.
-
-@subheading force-hshift property
-
-@c FIXME: formatting stuff (ie not important right now IMO)
-@c @a nchor Chopin finally corrected TODOgp
-
-We can now see how to apply the final corrections to the Chopin
-example introduced at the end of @ref{I'm hearing Voices}, which
-was left looking like this:
-
-@lilypond[quote,verbatim,fragment,ragged-right]
-\new Staff \relative c'' {
- \key aes \major
- <<
- { c2 aes4. bes8 } \\
- { aes2 f4 fes } \\
- { \voiceFour
- <ees c>2
- des2
- }
- >> |
- <c ees aes c>1 |
-}
-@end lilypond
-
-@noindent
-The lower two notes of the first chord (i.e, those in the third voice)
-should not be shifted away from the note column of the higher two
-notes. To correct this we set @code{force-hshift}, which is a
-property of @code{NoteColumn}, of these notes to zero. The lower note
-of the second chord is best placed just to the right of the higher
-notes. We achieve this by setting @code{force-hshift} of this note to
-0.5, ie half a note head's width to the right of the note column of
-the higher notes.
-
-Here's the final result:
-
-@cindex NoteColumn, example of overriding
-@cindex force-hshift property, example
-
-@lilypond[quote,verbatim,fragment,ragged-right]
-\new Staff \relative c'' {
- \key aes \major
- <<
- { c2 aes4. bes8 } \\
- { aes2 f4 fes } \\
- { \voiceFour
- \once \override NoteColumn #'force-hshift = #0 <ees c>2
- \once \override NoteColumn #'force-hshift = #0.5 des2
- }
- >> |
- <c ees aes c>1 |
-}
-@end lilypond
-
-
-@node Real music example
-@subsection Real music example
-
-We end this section on Tweaks by showing the steps to be taken to
-deal with a tricky example which needs several tweaks to produce
-the desired output. The example has been deliberately chosen to
-illustrate the use of the Notation Reference to resolve unusual
-problems with notation. It is not representative of more usual
-engraving process, so please do not let these difficulties put
-you off! Fortunately, difficulties like these are not very common!
-
-The example is from Chopin's Première Ballade, Op. 23, bars 6 to
-9, the transition from the opening Lento to Moderato.
-Here, first, is what we want the output to look like, but to avoid
-over-complicating the example too much we have left out the
-dynamics, fingering and pedalling.
-
-@c The following should appear as music without code
-@c This example should not be indexed
-@lilypond[quote,ragged-right]
-rhMusic = \relative c'' {
- r2
- c4.\( g8 |
- \once \override Tie #'staff-position = #3.5
- bes1~ |
- \bar "||"
- \time 6/4
- \mergeDifferentlyHeadedOn
- \mergeDifferentlyDottedOn
- bes2.^\markup {\bold "Moderato"} r8
- <<
- {c,8[ d fis bes a] | }
- \\
- % Reposition the c2 to the right of the merged note
- {c,8~ \once \override NoteColumn #'force-hshift = #1.0
- % Move the c2 out of the main note column so the merge will work
- \shiftOnn c2}
- \\
- % Stem on the d2 must be down to permit merging
- {s8 \stemDown \once \override Stem #'transparent = ##t d2}
- \\
- {s4 fis4.}
- >>
- \mergeDifferentlyHeadedOff
- \mergeDifferentlyDottedOff
- g2.\)
-}
-
-lhMusic = \relative c' {
- r2 <c g ees>2( |
- <d g, d>1)\arpeggio |
- r2. d,,4 r4 r |
- r4
-}
-
-\score {
- \new PianoStaff <<
- \new Staff = "RH" <<
- \key g \minor
- \rhMusic
- >>
- \new Staff = "LH" <<
- \key g \minor
- \clef "bass"
- \lhMusic
- >>
- >>
-}
-@end lilypond
-
-We note first that the right hand part in the third bar
-requires four voices. These are the five beamed eighth notes,
-the tied C, the half-note D which is merged with the eighth note
-D, and the dotted quarter note F-sharp, which is also merged with
-the eighth note at the same pitch. Everything else is in a single
-voice, so the easiest way is to introduce these four voices
-temporarily at the time they are needed. If you have forgotten
-how to do this, look at @ref{I'm hearing Voices}. Let us begin
-by entering the notes as two variables and setting up the staff
-structure in a score block, and see what LilyPond produces by
-default:
-
-@lilypond[quote,verbatim,ragged-right]
-rhMusic = \relative c'' {
- r2 c4. g8 |
- bes1~ |
- \time 6/4
- bes2. r8
- % Start polyphonic section of four voices
- <<
- {c,8 d fis bes a | }
- \\
- {c,8~ c2 | }
- \\
- {s8 d2 | }
- \\
- {s4 fis4. | }
- >>
- g2.
-}
-
-lhMusic = \relative c' {
- r2 <c g ees>2 |
- <d g, d>1 |
- r2. d,,4 r4 r |
- r4
-}
-
-\score {
- \new PianoStaff <<
- \new Staff = "RH" <<
- \key g \minor
- \rhMusic
- >>
- \new Staff = "LH" <<
- \key g \minor
- \clef "bass"
- \lhMusic
- >>
- >>
-}
-@end lilypond
-
-All the notes are right, but the appearance is far from satisfactory.
-The tie clashes with the change in time signature, the beaming in the
-third bar is wrong, the notes are not merged together, and several
-notation elements are missing. Let's first deal with the easier
-things. We can correct the beaming by inserting a beam manually, and
-we can easily add the left hand slur and the right hand phrasing slur,
-since these were all covered in the Tutorial. Doing this gives:
-
-@lilypond[quote,verbatim,ragged-right]
-rhMusic = \relative c'' {
- r2 c4.\( g8 |
- bes1~ |
- \time 6/4
- bes2. r8
- % Start polyphonic section of four voices
- <<
- {c,8[ d fis bes a] | }
- \\
- {c,8~ c2 | }
- \\
- {s8 d2 | }
- \\
- {s4 fis4. | }
- >>
- g2.\)
-}
-
-lhMusic = \relative c' {
- r2 <c g ees>2( |
- <d g, d>1) |
- r2. d,,4 r4 r |
- r4
-}
-
-\score {
- \new PianoStaff <<
- \new Staff = "RH" <<
- \key g \minor
- \rhMusic
- >>
- \new Staff = "LH" <<
- \key g \minor
- \clef "bass"
- \lhMusic
- >>
- >>
-}
-@end lilypond
-
-The first bar is now correct. The second bar contains an arpeggio and
-is terminated by a double bar line. How do we do these, as they have
-not been mentioned in this Learning Manual? This is where we need to
-turn to the Notation Reference. Looking up @q{arpeggio} and @q{bar
-line} in the index quickly shows us that an arpeggio is produced by
-appending @code{\arpeggio} to a chord, and a double bar line is
-produced by the @code{\bar "||"} command. That's easily done. We
-next need to correct the collision of the tie with the time signature.
-This is best done by moving the tie upwards. Moving objects was
-covered earlier in @ref{Moving objects}, which says that objects
-positioned relative to the staff can be moved by overriding their
-@code{staff-position} property, which is specified in half staff
-spaces relative to the center line of the staff. So the following
-override placed just before the first tied note would move the tie up
-to 3.5 half staff spaces above the center line:
-
-@code{\once \override Tie #'staff-position = #3.5}
-
-This completes bar two, giving:
-
-@lilypond[quote,verbatim,ragged-right]
-rhMusic = \relative c'' {
- r2 c4.\( g8 |
- \once \override Tie #'staff-position = #3.5
- bes1~ |
- \bar "||"
- \time 6/4
- bes2. r8
- % Start polyphonic section of four voices
- <<
- {c,8[ d fis bes a] | }
- \\
- {c,8~ c2 | }
- \\
- {s8 d2 | }
- \\
- {s4 fis4. | }
- >>
- g2.\)
-}
-
-lhMusic = \relative c' {
- r2 <c g ees>2( |
- <d g, d>1)\arpeggio |
- r2. d,,4 r4 r |
- r4
-}
-
-\score {
- \new PianoStaff <<
- \new Staff = "RH" <<
- \key g \minor
- \rhMusic
- >>
- \new Staff = "LH" <<
- \key g \minor
- \clef "bass"
- \lhMusic
- >>
- >>
-}
-@end lilypond
-
-On to bar three and the start of the Moderato section. The tutorial
-showed how to add embolded text with the @code{\markup} command, so
-adding @q{Moderato} in bold is easy. But how do we merge notes in
-different voices together? This is where we need to turn to the
-Notation Reference for help. A search for @qq{merge} in the Notation
-Reference index quickly leads us to the commands for merging
-differently headed and differently dotted notes in @ruser{Collision
-resolution}. In our example we need to merge both types of note for
-the duration of the polyphonic section in bar 3, so using the
-information we find in the Notation Reference we add
-
-@example
-\mergeDifferentlyHeadedOn
-\mergeDifferentlyDottedOn
-@end example
-
-@noindent
-to the start of that section and
-
-@example
-\mergeDifferentlyHeadedOff
-\mergeDifferentlyDottedOff
-@end example
-
-@noindent
-to the end, giving:
-
-@lilypond[quote,verbatim,ragged-right]
-rhMusic = \relative c'' {
- r2 c4.\( g8 |
- \once \override Tie #'staff-position = #3.5
- bes1~ |
- \bar "||"
- \time 6/4
- bes2.^\markup {\bold "Moderato"} r8
- \mergeDifferentlyHeadedOn
- \mergeDifferentlyDottedOn
- % Start polyphonic section of four voices
- <<
- {c,8[ d fis bes a] | }
- \\
- {c,8~ c2 | }
- \\
- {s8 d2 | }
- \\
- {s4 fis4. | }
- >>
- \mergeDifferentlyHeadedOff
- \mergeDifferentlyDottedOff
- g2.\)
-}
-
-lhMusic = \relative c' {
- r2 <c g ees>2( |
- <d g, d>1)\arpeggio |
- r2. d,,4 r4 r |
- r4
-}
-
-\score {
- \new PianoStaff <<
- \new Staff = "RH" <<
- \key g \minor
- \rhMusic
- >>
- \new Staff = "LH" <<
- \key g \minor
- \clef "bass"
- \lhMusic
- >>
- >>
-}
-@end lilypond
-
-These overrides have merged the two F-sharp notes, but not the two
-on D. Why not? The answer is there in the same section in the
-Notation Reference -- notes being merged must have stems in
-opposite directions and two notes cannot be merged successfully if
-there is a third note in the same note column. Here the two D's
-both have upward stems and there is a third note -- the C. We know
-how to change the stem direction using @code{\stemDown}, and
-the Notation Reference also says how to move the C -- apply a shift
-using one of the @code{\shift} commands. But which one?
-The C is in voice two which has shift off, and the two D's are in
-voices one and three, which have shift off and shift on,
-respectively. So we have to shift the C a further level still
-using @code{\shiftOnn} to avoid it interfering with the two D's.
-Applying these changes gives:
-
-@cindex Tie, example of overriding
-@cindex staff-position property, example
-
-@lilypond[quote,verbatim,ragged-right]
-rhMusic = \relative c'' {
- r2 c4.\( g8 |
- \once \override Tie #'staff-position = #3.5
- bes1~ |
- \bar "||"
- \time 6/4
- bes2.^\markup {\bold "Moderato"} r8
- \mergeDifferentlyHeadedOn
- \mergeDifferentlyDottedOn
- % Start polyphonic section of four voices
- <<
- {c,8[ d fis bes a] | }
- \\
- % Move the c2 out of the main note column so the merge will work
- {c,8~ \shiftOnn c2 | }
- \\
- % Stem on the d2 must be down to permit merging
- {s8 \stemDown d2 | }
- \\
- {s4 fis4. | }
- >>
- \mergeDifferentlyHeadedOff
- \mergeDifferentlyDottedOff
- g2.\)
-}
-
-lhMusic = \relative c' {
- r2 <c g ees>2( |
- <d g, d>1)\arpeggio |
- r2. d,,4 r4 r |
- r4
-}
-
-\score {
- \new PianoStaff <<
- \new Staff = "RH" <<
- \key g \minor
- \rhMusic
- >>
- \new Staff = "LH" <<
- \key g \minor
- \clef "bass"
- \lhMusic
- >>
- >>
-}
-@end lilypond
-
-Nearly there. Only two problems remain: The downward stem on the
-merged D should not be there, and the C would be better positioned
-to the right of the D's. We know how to do both of these from the
-earlier tweaks: we make the stem transparent, and move the C with
-the @code{force-hshift} property. Here's the final result:
-
-@cindex NoteColumn, example of overriding
-@cindex force-hshift property, example
-@cindex Stem, example of overriding
-@cindex transparent property, example
-
-@lilypond[quote,verbatim,ragged-right]
-rhMusic = \relative c'' {
- r2
- c4.\( g8 |
- \once \override Tie #'staff-position = #3.5
- bes1~ |
- \bar "||"
- \time 6/4
- bes2.^\markup {\bold "Moderato"} r8
- \mergeDifferentlyHeadedOn
- \mergeDifferentlyDottedOn
- <<
- {c,8[ d fis bes a] | }
- \\
- % Reposition the c2 to the right of the merged note
- {c,8~ \once \override NoteColumn #'force-hshift = #1.0
- % Move the c2 out of the main note column so the merge will work
- \shiftOnn c2}
- \\
- % Stem on the d2 must be down to permit merging
- {s8 \stemDown \once \override Stem #'transparent = ##t d2}
- \\
- {s4 fis4.}
- >>
- \mergeDifferentlyHeadedOff
- \mergeDifferentlyDottedOff
- g2.\)
-}
-
-lhMusic = \relative c' {
- r2 <c g ees>2( |
- <d g, d>1)\arpeggio |
- r2. d,,4 r4 r |
- r4
-}
-
-\score {
- \new PianoStaff <<
- \new Staff = "RH" <<
- \key g \minor
- \rhMusic
- >>
- \new Staff = "LH" <<
- \key g \minor
- \clef "bass"
- \lhMusic
- >>
- >>
-}
-@end lilypond
-
-
-@node Further tweaking
-@section Further tweaking
-
-@menu
-* Other uses for tweaks::
-* Using variables for tweaks::
-* Other sources of information::
-* Avoiding tweaks with slower processing::
-* Advanced tweaks with Scheme::
-@end menu
-
-@node Other uses for tweaks
-@subsection Other uses for tweaks
-
-@cindex transparent property, use of
-@cindex objects, making invisible
-@cindex removing objects
-@cindex objects, removing
-@cindex hiding objects
-@cindex objects, hiding
-@cindex invisible objects
-@cindex objects, invisible
-@cindex tying notes across voices
-
-@subheading Tying notes across voices
-
-The following example demonstrates how to connect notes in
-different voices using ties. Normally, only two notes in the
-same voice can be connected with ties. By using two voices,
-with the tied notes in one of them
-
-@lilypond[quote,fragment,relative=2]
-<< { b8~ b8\noBeam }
-\\ { b[ g8] }
->>
-@end lilypond
-
-@noindent
-and blanking the first up-stem in that voice, the tie appears to
-cross voices:
-
-@cindex Stem, example of overriding
-@cindex transparent property, example
-
-@lilypond[quote,fragment,relative=2,verbatim]
-<<
- {
- \once \override Stem #'transparent = ##t
- b8~ b8\noBeam
- }
-\\
- { b[ g8] }
->>
-@end lilypond
-
-To make sure that the just-blanked stem doesn't squeeze the tie
-too much, we can lengthen the stem by setting the
-@code{length} to @code{8},
-
-@lilypond[quote,fragment,relative=2,verbatim]
-<<
- {
- \once \override Stem #'transparent = ##t
- \once \override Stem #'length = #8
- b8~ b8\noBeam
- }
-\\
- { b[ g8] }
->>
-@end lilypond
-
-@subheading Simulating a fermata in MIDI
-
-@cindex stencil property, use of
-@cindex fermata, implementing in MIDI
-
-For outside-staff objects it is usually better to override the
-object's @code{stencil} property rather than its @code{transparent}
-property when you wish to remove it from the printed output.
-Setting the @code{stencil} property of an object to @code{#f} will
-remove that object entirely from the printed output. This means it
-has no effect on the placement of other objects placed relative to
-it.
-
-For example, if we wished to change the metronome setting in order
-to simulate a fermata in the MIDI output we would not want the
-metronome markings to appear in the printed output, and we would
-not want it to influence the spacing between the two systems or
-the positions of adjacent annotations on the staff. So setting
-its @code{stencil} property to @code{#f} would be the best way.
-We show here the effect of the two methods:
-
-@cindex MetronomeMark, example of overriding
-@cindex transparent property, example
-
-@lilypond[quote,verbatim,ragged-right]
-\score {
- \relative c'' {
- % Visible tempo marking
- \tempo 4=120
- a4 a a
- \once \override Score.MetronomeMark #'transparent = ##t
- % Invisible tempo marking to lengthen fermata in MIDI
- \tempo 4=80
- a\fermata
- % New tempo for next section
- \tempo 4=100
- a a a a
- }
- \layout { }
- \midi { }
-}
-@end lilypond
-
-@cindex MetronomeMark, example of overriding
-@cindex stencil property, example
-
-@lilypond[quote,verbatim,ragged-right]
-\score {
- \relative c'' {
- % Visible tempo marking
- \tempo 4=120
- a4 a a
- \once \override Score.MetronomeMark #'stencil = ##f
- % Invisible tempo marking to lengthen fermata in MIDI
- \tempo 4=80
- a\fermata
- % New tempo for next section
- \tempo 4=100
- a a a a
- }
- \layout { }
- \midi { }
-}
-@end lilypond
-
-@noindent
-Both methods remove the metronome mark which lengthens the fermata
-from the printed output, and both affect the MIDI timing as
-required, but the transparent metronome mark in the first line
-forces the following tempo indication too high while the
-second (with the stencil removed) does not.
-
-@node Using variables for tweaks
-@subsection Using variables for tweaks
-
-@cindex variables, using for tweaks
-@cindex using variables for tweaks
-@cindex tweaks, using variables for
-
-Override commands are often long and tedious to type, and they
-have to be absolutely correct. If the same overrides are to be
-used many times it may be worth defining variables to hold them.
-
-Suppose we wish to emphasize certain words in lyrics by printing
-them in bold italics. The @code{\italic} and @code{\bold}
-commands only work within lyrics if they are embedded, together with
-the word or words to be modified, within a @code{\markup} block,
-which makes them tedious to enter. The need to embed the words
-themselves prevents their use in simple variables. As an
-alternative can we use @code{\override} and @code{\revert} commands?
-
-@example
-@code{\override Lyrics . LyricText #'font-shape = #'italic}
-@code{\override Lyrics . LyricText #'font-series = #'bold}
-
-@code{\revert Lyrics . LyricText #'font-shape}
-@code{\revert Lyrics . LyricText #'font-series}
-@end example
-
-These would also be extremely tedious to enter if there were many
-words requiring emphasis. But we @emph{can} define these as two
-variables and use those to bracket the words to be emphasized.
-Another advantage of using variables for these overrides is that
-the spaces around the dot are not necessary, since they are not
-being interpreted in @code{\lyricmode} directly. Here's an example
-of this, although in practice we would choose shorter names
-for the variables to make them quicker to type:
-
-@cindex LyricText, example of overriding
-@cindex font-shape property, example
-@cindex font-series property, example
-
-@lilypond[quote,verbatim]
-emphasize = {
- \override Lyrics.LyricText #'font-shape = #'italic
- \override Lyrics.LyricText #'font-series = #'bold
-}
-normal = {
- \revert Lyrics.LyricText #'font-shape
- \revert Lyrics.LyricText #'font-series
-}
-
-global = { \time 4/4 \partial 4 \key c \major}
-SopranoMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
-AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
-TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
-BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
-VerseOne = \lyrics { E -- | ter -- nal \emphasize Fa -- ther, \normal | strong to save, }
-VerseTwo = \lyricmode { O | \emphasize Christ, \normal whose voice the | wa -- ters heard, }
-VerseThree = \lyricmode { O | \emphasize Ho -- ly Spi -- rit, \normal | who didst brood }
-VerseFour = \lyricmode { O | \emphasize Tri -- ni -- ty \normal of | love and pow'r }
-
-\score {
- \new ChoirStaff <<
- \new Staff <<
- \clef "treble"
- \new Voice = "Soprano" { \voiceOne \global \SopranoMusic }
- \new Voice = "Alto" { \voiceTwo \AltoMusic }
- \new Lyrics \lyricsto "Soprano" { \VerseOne }
- \new Lyrics \lyricsto "Soprano" { \VerseTwo }
- \new Lyrics \lyricsto "Soprano" { \VerseThree }
- \new Lyrics \lyricsto "Soprano" { \VerseFour }
- >>
- \new Staff <<
- \clef "bass"
- \new Voice = "Tenor" { \voiceOne \TenorMusic }
- \new Voice = "Bass" { \voiceTwo \BassMusic }
- >>
- >>
-}
-@end lilypond
-
-
-
-@node Other sources of information
-@subsection Other sources of information
-
-The Internals Reference documentation contains a lot of information
-about LilyPond, but even more information can be gathered by
-looking at the internal LilyPond files. To explore these, you must
-first find the directory appropriate to your system. The location
-of this directory depends (a) on whether you obtained LilyPond
-by downloading a precompiled binary from lilypond.org
-or whether you installed it from a package manager (i.e.
-distributed with Linux, or installed under fink or cygwin) or
-compiled it from source, and (b) on which operating system it is
-being used:
-
-@strong{Downloaded from lilypond.org}
-
-@itemize @bullet
-@item Linux
-
-Navigate to
-@file{@var{INSTALLDIR}/lilypond/usr/share/lilypond/current/}
-
-@item MacOS X
-
-Navigate to
-@file{@var{INSTALLDIR}/LilyPond.app/Contents/Resources/share/lilypond/current/}
-by either @code{cd}-ing into this directory from the
-Terminal, or control-clicking on the LilyPond application and
-selecting @q{Show Package Contents}.
-
-@item Windows
-
-Using Windows Explorer, navigate to
-@file{@var{INSTALLDIR}/LilyPond/usr/share/lilypond/current/}
-
-@end itemize
-
-@strong{Installed from a package manager or compiled from source}
-
-Navigate to
-@file{@var{PREFIX}/share/lilypond/@var{X.Y.Z}/}, where
-@var{PREFIX} is set by your package manager or @code{configure}
-script, and @var{X.Y.Z} is the LilyPond version number.
-
-@smallspace
-
-Within this directory the two interesting subdirectories are
-
-@itemize
-@item @file{ly/} - contains files in LilyPond format
-@item @file{scm/} - contains files in Scheme format
-@end itemize
-
-Let's begin by looking at some files in @file{ly/}.
-Open @file{ly/property-init.ly} in a text editor. The one
-you normally use for @code{.ly} files will be fine. This file
-contains the definitions of all the standard LilyPond predefined
-commands, such as @code{\stemUp} and @code{\slurDotted}. You will
-see that these are nothing more than definitions of variables
-containing one or a group of @code{\override} commands. For
-example, @code{/tieDotted} is defined to be:
-
-@example
-tieDotted = @{
- \override Tie #'dash-period = #0.75
- \override Tie #'dash-fraction = #0.1
-@}
-@end example
-
-If you do not like the default values these predefined commands can
-be redefined easily, just like any other variable, at the
-head of your input file.
-
-The following are the most useful files to be found in
-@file{ly/}:
-
-@multitable @columnfractions .4 .6
-@headitem Filename
- @tab Contents
-@item @file{ly/engraver-init.ly}
- @tab Definitions of engraver Contexts
-@item @file{ly/paper-defaults-init.ly}
- @tab Specifications of paper-related defaults
-@item @file{ly/performer-init.ly}
- @tab Definitions of performer Contexts
-@item @file{ly/property-init.ly}
- @tab Definitions of all common predefined commands
-@item @file{ly/spanner-init.ly}
- @tab Definitions of spanner-related predefined commands
-@end multitable
-
-Other settings (such as the definitions of markup commands) are
-stored as @code{.scm} (Scheme) files. The Scheme programming
-language is used to provide a programmable interface into
-LilyPond internal operation. Further explanation of these files
-is currently outside the scope of this manual, as a knowledge of
-the Scheme language is required. Users should be warned that
-a substantial amount of technical knowledge or time is required
-to understand Scheme and these files (see @ref{Scheme tutorial}).
-
-If you have this knowledge, the Scheme files which may be of
-interest are:
-
-@multitable @columnfractions .4 .6
-@headitem Filename
- @tab Contents
-@item @file{scm/auto-beam.scm}
- @tab Sub-beaming defaults
-@item @file{scm/define-grobs.scm}
- @tab Default settings for grob properties
-@item @file{scm/define-markup-commands.scm}
- @tab Specify all markup commands
-@item @file{scm/midi.scm}
- @tab Default settings for MIDI output
-@item @file{scm/output-lib.scm}
- @tab Settings that affect appearance of frets, colors,
- accidentals, bar lines, etc
-@item @file{scm/parser-clef.scm}
- @tab Definitions of supported clefs
-@item @file{scm/script.scm}
- @tab Default settings for articulations
-@end multitable
-
-
-
-@node Avoiding tweaks with slower processing
-@subsection Avoiding tweaks with slower processing
-
-LilyPond can perform extra checks while it processes input files. These
-checks will take extra time to perform, but fewer manual tweaks
-may be required to obtain an acceptable result. If a text script
-or part of the lyrics extends over the margins these checks will
-compress that line of the score just enough to fit within the
-margins.
-
-To be effective under all circumstances these checks must be enabled
-by placing the overrides in a Score @code{\with} block, rather than
-in-line in music, as follows:
-
-@example
-\new Score \with @{
- % Makes sure text scripts and lyrics are within the paper margins
- \override PaperColumn #'keep-inside-line = ##t
- \override NonMusicalPaperColumn #'keep-inside-line = ##t
-@} @{
- ..
-@}
-@end example
-
-@node Advanced tweaks with Scheme
-@subsection Advanced tweaks with Scheme
-
-Although many things are possible with the @code{\override} and
-@code{\tweak} commands, an even more powerful way of modifying
-the action of LilyPond is available through a programmable
-interface to the LilyPond internal operation. Code written in
-the Scheme programming language can be incorporated directly in
-the internal operation of LilyPond. Of course, at least a basic
-knowledge of programming in Scheme is required to do this, and an
-introduction is provided in the @ref{Scheme tutorial}.
-
-As an illustration of one of the many possibilities, instead of
-setting a property to a constant it can be set to a Scheme
-procedure which is then called whenever that property is accessed
-by LilyPond. The property can then be set dynamically to a value
-determined by the procedure at the time it is called. In this
-example we color the note head in accordance with its position on
-the staff.
-
-@cindex x11-color function, example of using
-@cindex NoteHead, example of overriding
-@cindex color property, setting to Scheme procedure
-
-@lilypond[quote,verbatim,ragged-right]
-#(define (color-notehead grob)
- "Color the notehead according to its position on the staff."
- (let ((mod-position (modulo (ly:grob-property grob 'staff-position) 7)))
- (case mod-position
- ;; Return rainbow colors
- ((1) (x11-color 'red )) ; for C
- ((2) (x11-color 'orange )) ; for D
- ((3) (x11-color 'yellow )) ; for E
- ((4) (x11-color 'green )) ; for F
- ((5) (x11-color 'blue )) ; for G
- ((6) (x11-color 'purple )) ; for A
- ((0) (x11-color 'violet )) ; for B
- )
- )
-)
-
-\relative c' {
- % Arrange to obtain color from color-notehead procedure
- \override NoteHead #'color = #color-notehead
- c2 c' |
- b4 g8 a b4 c |
- c,2 a' |
- g1 |
-}
-\addlyrics {
- Some -- where o -- ver the Rain -- bow, way up high,
-}
-@end lilypond
-
-Further examples showing the use of these programmable interfaces
-can be found in @ref{Tweaking with Scheme}.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
projects / lilypond.git / blobdiff