version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.38"
+@c \version "2.11.61"
@node Tweaking output
@chapter Tweaking output
@node Objects and interfaces
@subsection Objects and interfaces
-@cindex objects
-@cindex grobs
-@cindex spanners
-@cindex 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
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 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
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.
+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 A to stand for any capitalized
-alphabetic character and aaa to stand for any number 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 Example
+ @tab Examples
@item Contexts
@tab Aaaa or AaaaAaaaAaaa
@tab Staff, GrandStaff
@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.
+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
The general syntax of this command is:
@example
-\override @emph{context}.@emph{layout_object}
- #'@emph{layout_property} = #@emph{value}
+\override @var{Context}.@var{LayoutObject} #'@var{layout-property} =
+#@var{value}
@end example
@noindent
-This will set the property with the name @emph{layout_property}
-of the layout object with the name
-@emph{layout_object}, which is a member of the @emph{context}
-context, to the value @emph{value}.
+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 @emph{context} can be omitted (and usually is) when the
+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
@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.
commands have been issued.
@example
-\revert @emph{context}.@emph{layout_object} #'@emph{layout_property}
+\revert @var{Context}.@var{LayoutObject} #'@var{layout-property}
@end example
-Again, just like @emph{context} in the @code{\override} command,
-@emph{context} is often not needed. It will be omitted
+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:
@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
@strong{\overrideProperty command}
@cindex overrideProperty command
+
@funindex \overrideProperty
+@funindex overrideProperty
There is another form of the override command,
@code{\overrideProperty}, which is occasionally required.
@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
item in the input stream.
Here's an example. Suppose we wish to change the size of the
-middle note (the E) in a C major chord. Let's first see what
+middle note head (the E) in a C major chord. Let's first see what
@code{\once \override} would do:
@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
<c e g>
@end lilypond
-We see the override affects @emph{all} the notes in the chord.
+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
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
+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
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. So the general syntax of the
-@code{\tweak} command is simply:
+@code{\tweak} command is simply
@example
-\tweak #'@emph{layout_property} = #@emph{value}
+\tweak #'@var{layout-property} = #@var{value}
@end example
A @code{\tweak} command can also be used to modify just one in
-\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 bracket, tuplet
@cindex tuplet bracket
@cindex triplet bracket
+
@funindex TupletBracket
The @code{\tweak} command must also be used to change the
}
@end lilypond
-You can find more details of the @code{\tweak} command in
-@ruser{Objects connected to the input}.
-
-If nested tuplets do not begin at the same moment their
+If nested tuplets do not begin at the same moment, their
appearance may be modified in the usual way with
@code{\override} commands:
}
@end lilypond
+@seealso
+
+Notation Reference:
+@ruser{The tweak command}.
+
@node The Internals Reference manual
@section The Internals Reference manual
@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.
Let's use a concrete example with a simple fragment of real
music:
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,verbatim,relative=2]
{
\time 6/8
{
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,
+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.
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 often it is easier to go
-straight to the IR and search there.)
+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
+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)
answer is, @q{Within the music, before the first slur and
close to it.} Let's do that:
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,verbatim,relative=2]
{
\time 6/8
{
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
@cindex overriding once only
@cindex once override
-@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
+@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:
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,verbatim,relative=2]
{
\time 6/8
{
@subheading Reverting
@cindex revert
-@cindex default properties, reverting
+@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:
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,verbatim,relative=2]
{
\time 6/8
{
@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
+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:
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,verbatim,relative=2]
{
\time 6/8
{
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
+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 (in the html versions
-of the IR) interfaces which LyricText supports. The list has
-seven 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.
+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.
+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 special names which are known internally to
-LilyPond. Some of them are the names of properties,
-like @code{thickness} or @code{font-shape}, others are in
-effect special 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"}.
+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
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
@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
+@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
@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
- @tab @code{#LEFT}, @code{#CENTER}, @code{#UP},
+ @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 bracketed set of items separated by spaces,
-preceded by an apostrophe
+ @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
preceded by an apostrophe
@tab @code{'italic}, @code{'inside}
@item Unknown
- @tab A procedure or @code{#f} (to cause no action)
+ @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 brackets and preceded
-by a hash sign, @code{#}.
- @tab @code{#(#t #t #f)}
+ @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
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 are commonly required
-together -- if one of them is required for an object, so are
-the others. Some objects then need the properties in some
-interfaces, others need them from other interfaces. The
-interfaces which contain the properties required 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.
+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
}
@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:
+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:
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
{
@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 two hash signs before the opening bracket.
-One is required as part of the value to introduce a vector,
-and one is required, as always, to precede the value itself in
-the @code{\override} command.
+@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.
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
{
\time 12/16
- \override Staff.BarLine #'break-visibility = ##(#f #f #f)
+ \override Staff.BarLine #'break-visibility = #'#(#f #f #f)
c4 b8 c d16 c d8 |
g, a16 b8 c d4 e16 |
e8
And we see this too removes all the bar lines.
@subheading transparent
-@cindex transparent property
-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
+@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:
@end lilypond
@noindent
-The time signature is gone, but this command leaves a gap where
+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
+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:
leaves it where it is, but makes it invisible.
@subheading color
+
@cindex color property
-Finally we could make the bar lines invisible by coloring
-them white. The @code{grob-interface} specifies that the
+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,
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
+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
@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
+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)}:
@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}.
@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.
+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}
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.
+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
@node Length and thickness of objects
@subsection Length and thickness of objects
-@cindex Distances
-@cindex Thickness
-@cindex Length
+@cindex distances
+@cindex thickness
+@cindex length
@cindex magstep
@cindex size, changing
@cindex stem length, changing
@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
+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
@menu
* Automatic behavior::
* Within-staff objects::
-* Outside 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
right or left when they point up or down. This is controlled
automatically when @code{direction} is set.
-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 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.
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
a4 g c a
@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.
+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{\arpeggioDown}
- @tab @code{\arpeggioUp}
- @tab @code{\arpeggioNeutral}
+@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}
@code{\xxxNeutral} command.
@subheading Fingering
+
@cindex fingering, placement
+@cindex fingering, chords
The placement of fingering is also affected by the value
of its @code{direction} property, but there are special
c-5 a-3 f-1 c'-5
@end lilypond
-This is how to control fingering on single notes, but the
-@code{direction}
-property is ignored for chords. Instead, by default, the
-fingering is automatically placed both above and below the
-notes of a chord, as shown:
+This is how to control fingering on single notes, but the
+@code{direction} property is ignored for chords. Instead, by default,
+the fingering is automatically placed both above and below the notes
+of a chord, as shown:
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
<c-5 g-3>
<f-2>
< c-1 e-2 g-3 b-5 > 4
@end lilypond
-
+@c START HERE
@node Outside staff objects
@subsection Outside staff objects
% Place dynamics above staff
\dynamicUp
% Start Ottava Bracket
-#(set-octavation 1)
+\ottava #1
c' \startTextSpan
% Add Dynamic Text
c\pp
% Add Dynamic Text
c\ff c \stopTextSpan
% Stop Ottava Bracket
-#(set-octavation 0)
+\ottava #0
c, c c c
@end lilypond
%Place following Ottava Bracket below Text Spanners
\once \override Staff.OttavaBracket #'outside-staff-priority = #340
% Start Ottava Bracket
-#(set-octavation 1)
+\ottava #1
c' \startTextSpan
% Add Dynamic Text
c\pp
% Add Dynamic Text
c\ff c \stopTextSpan
% Stop Ottava Bracket
-#(set-octavation 0)
+\ottava #0
c, c c c
@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
+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
bes1~ |
\bar "||"
\time 6/4
- \override Staff.NoteCollision #'merge-differently-headed = ##t
- \override Staff.NoteCollision #'merge-differently-dotted = ##t
+ \mergeDifferentlyHeadedOn
+ \mergeDifferentlyDottedOn
bes2.^\markup {\bold "Moderato"} r8
<<
{c,8[ d fis bes a] | }
\\
{s4 fis4.}
>>
- \revert Staff.NoteCollision #'merge-differently-headed
- \revert Staff.NoteCollision #'merge-differently-dotted
+ \mergeDifferentlyHeadedOff
+ \mergeDifferentlyDottedOff
g2.\)
}
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.
+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
+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:
@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? The
-index in the Notation Reference does not mention merging,
-but a search of the text for @q{merge} quickly leads us to
-the overrides for merging differently headed and differently
+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
-in the Notation Reference we add
+we find in the Notation Reference we add
@example
-\override Staff.NoteCollision #'merge-differently-headed = ##t
-\override Staff.NoteCollision #'merge-differently-dotted = ##t
+\mergeDifferentlyHeadedOn
+\mergeDifferentlyDottedOn
@end example
@noindent
to the start of that section and
@example
-\revert Staff.NoteCollision #'merge-differently-headed
-\revert Staff.NoteCollision #'merge-differently-dotted
+\mergeDifferentlyHeadedOff
+\mergeDifferentlyDottedOff
@end example
@noindent
\bar "||"
\time 6/4
bes2.^\markup {\bold "Moderato"} r8
- \override Staff.NoteCollision #'merge-differently-headed = ##t
- \override Staff.NoteCollision #'merge-differently-dotted = ##t
+ \mergeDifferentlyHeadedOn
+ \mergeDifferentlyDottedOn
% Start polyphonic section of four voices
<<
{c,8[ d fis bes a] | }
\\
{s4 fis4. | }
>>
- \revert Staff.NoteCollision #'merge-differently-headed
- \revert Staff.NoteCollision #'merge-differently-dotted
+ \mergeDifferentlyHeadedOff
+ \mergeDifferentlyDottedOff
g2.\)
}
}
@end lilypond
-These overrides have merged the two F-sharp notes, but not the two
+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
+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
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.
+using @code{\shiftOnn} to avoid it interfering with the two D's.
Applying these changes gives:
@lilypond[quote,verbatim,ragged-right]
\bar "||"
\time 6/4
bes2.^\markup {\bold "Moderato"} r8
- \override Staff.NoteCollision #'merge-differently-headed = ##t
- \override Staff.NoteCollision #'merge-differently-dotted = ##t
+ \mergeDifferentlyHeadedOn
+ \mergeDifferentlyDottedOn
% Start polyphonic section of four voices
<<
{c,8[ d fis bes a] | }
\\
{s4 fis4. | }
>>
- \revert Staff.NoteCollision #'merge-differently-headed
- \revert Staff.NoteCollision #'merge-differently-dotted
+ \mergeDifferentlyHeadedOff
+ \mergeDifferentlyDottedOff
g2.\)
}
\bar "||"
\time 6/4
bes2.^\markup {\bold "Moderato"} r8
- \override Staff.NoteCollision #'merge-differently-headed = ##t
- \override Staff.NoteCollision #'merge-differently-dotted = ##t
+ \mergeDifferentlyHeadedOn
+ \mergeDifferentlyDottedOn
<<
{c,8[ d fis bes a] | }
\\
\\
{s4 fis4.}
>>
- \revert Staff.NoteCollision #'merge-differently-headed
- \revert Staff.NoteCollision #'merge-differently-dotted
+ \mergeDifferentlyHeadedOff
+ \mergeDifferentlyDottedOff
g2.\)
}
@section Further tweaking
@menu
-* Other uses for tweaks::
-* Using variables for tweaks::
-* Other sources of information::
-* Avoiding tweaks with slower processing::
+* Other uses for tweaks::
+* Using variables for tweaks::
+* Other sources of information::
+* Avoiding tweaks with slower processing::
* Advanced tweaks with Scheme::
@end menu
>>
@end lilypond
-@subheading Simulating a fermata
+@subheading Simulating a fermata in MIDI
@cindex stencil property, use of
@cindex fermata, implementing in MIDI
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 spacing of the notes on the staff. So setting its
-@code{stencil} property to @code{#f} would be the best way.
+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:
@lilypond[quote,verbatim,ragged-right]
\tempo 4=120
a4 a a
\once \override Score.MetronomeMark #'transparent = ##t
- % Invisible tempo marking to lengthen fermata note in MIDI
+ % Invisible tempo marking to lengthen fermata in MIDI
\tempo 4=80
a\fermata
- \once \override Score.MetronomeMark #'stencil = ##f
- % Invisible tempo marking to restore tempo in MIDI
+ % New tempo for next section
+ \tempo 4=100
+ a a a a
+ }
+ \layout { }
+ \midi { }
+}
+@end lilypond
+
+@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 { }
@end lilypond
@noindent
-Both methods remove the metronome mark from the printed output,
-and both affect the MIDI timing as required, but the first
-(transparent) metronome mark still influences the note spacing
-while the second (with no stencil) does not.
+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
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 do not work within lyrics so we must instead use the
-following @code{\override} and @code{\revert} commands:
+commands only work within lyrics if they are also embedded in
+@code{\markup}, which makes them tedious to enter, so as an
+alternative can we instead use the @code{\override} and
+@code{\revert} commands?
@example
@code{\override Lyrics . LyricText #'font-shape = #'italic}
@code{\revert Lyrics . LyricText #'font-series}
@end example
-These would be extremely tedious to enter if there were many words
-requiring emphasis. So instead we define these as two variables,
-and use them as follows:
+These would also be extremely tedious to enter if there were many
+words requiring emphasis. So instead we define these as two
+variables, and use them as follows, although normally we would
+perhaps choose shorter names for the variables to make them
+quicker to type:
@lilypond[quote,verbatim]
-emph = {
+emphasize = {
\override Lyrics . LyricText #'font-shape = #'italic
\override Lyrics . LyricText #'font-series = #'bold
}
-norm = {
+normal = {
\revert Lyrics . LyricText #'font-shape
\revert Lyrics . LyricText #'font-series
}
global = { \time 4/4 \partial 4 \key c \major}
-SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
+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 \emph Fa -- ther, \norm | strong to save, }
-VerseTwo = \lyricmode { O | \emph Christ, \norm whose voice the | wa -- ters heard, }
-VerseThree = \lyricmode { O | \emph Ho -- ly Spi -- rit, \norm | who didst brood }
-VerseFour = \lyricmode { O | \emph Tri -- ni -- ty \norm of | love and pow'r }
+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 = "Sop" { \voiceOne \global \SopMusic }
+ \new Voice = "Soprano" { \voiceOne \global \SopranoMusic }
\new Voice = "Alto" { \voiceTwo \AltoMusic }
- \new Lyrics \lyricsto "Sop" { \VerseOne }
- \new Lyrics \lyricsto "Sop" { \VerseTwo }
- \new Lyrics \lyricsto "Sop" { \VerseThree }
- \new Lyrics \lyricsto "Sop" { \VerseFour }
+ \new Lyrics \lyricsto "Soprano" { \VerseOne }
+ \new Lyrics \lyricsto "Soprano" { \VerseTwo }
+ \new Lyrics \lyricsto "Soprano" { \VerseThree }
+ \new Lyrics \lyricsto "Soprano" { \VerseFour }
>>
\new Staff <<
\clef "bass"
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, first
-find the directory appropriate to your system, as follows:
+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{Download from lilypond.org: Linux}
+@strong{Downloaded from lilypond.org}
+
+@itemize @bullet
+@item Linux
Navigate to
@file{@var{INSTALLDIR}/lilypond/usr/share/lilypond/current/}
-@strong{Download from lilypond.org: MacOS X}
+@item MacOS X
Navigate to
@file{@var{INSTALLDIR}/LilyPond.app/Contents/Resources/share/lilypond/current/}
Terminal, or control-clicking on the LilyPond application and
selecting @q{Show Package Contents}.
-@strong{Download from lilypond.org: Windows}
+@item Windows
Using Windows Explorer, navigate to
@file{@var{INSTALLDIR}/LilyPond/usr/share/lilypond/current/}
-@strong{Installed from a package manager or from source: all}
+@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
projects / lilypond.git / blobdiff