version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.51"
+@c \version "2.11.61"
@node Tweaking output
@chapter Tweaking output
@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
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
+@ref{Modifying context properties}, and @ref{Adding
and removing engravers}. We now must meet some more important
commands.
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}
+This will set the property with the name @var{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}.
+@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
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:
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.
}
@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
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
{
@code{\once} must be
repositioned as follows:
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,verbatim,relative=2]
{
\time 6/8
{
@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
{
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
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
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
@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
@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 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.
+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,
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)}.
+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.
+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
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.
+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
@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:
@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.
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)}:
@subheading Fingering
@cindex fingering, placement
-The placement of fingering is also affected by the value
-of its @code{direction} property, but there are special
+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 fingering,
-the first bar shows the default, then the effect of specifying
-@code{DOWN} and @code{UP}:
+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}:
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@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
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
+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:
+
+@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:
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@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
-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
+@noindent
+but this may be overriden to manually force all or any of the
+individual fingering numbers above or below:
+
+@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])}
@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
+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
+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.
-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.
-
+@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:
@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
\set fingeringOrientations = #'(right)
<f-2>
< c-1 e-2 g-3 b-5 > 4
-@end lilypond
+@end lilypond
@noindent
If the fingering seems a little crowded the @code{font-size}
% 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
>>
@end lilypond
-@subheading Simulating a fermata
+@subheading Simulating a fermata in MIDI
@cindex stencil property, use of
@cindex fermata, implementing in MIDI
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]
emphasize = {
\clef "treble"
\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"
projects / lilypond.git / blobdiff