@subsection Contexts explained
When music is printed, a lot of notational elements must be added to the
-input. For example, compare the input and output of the following example:
+output. For example, compare the input and output of the following example:
@lilypond[quote,verbatim,relative=2,fragment]
cis4 cis2. g4
all stems are thickened.
Analogous to @code{\set}, the @var{context} argument may be left out,
-causing it to default to @context{Voice}, and adding @code{\once} applies
-the change during one timestep only
+causing the default context @context{Voice} to be used. Adding
+@code{\once} applies the change during one timestep only.
@lilypond[quote,fragment,verbatim,relative=2]
c4
@}
@end example
-Here @code{\Staff} takes the existing definition for context @context{Staff} from the
-identifier @code{\Staff}.
+The @code{\Staff} command brings in the existing definition of the
+staff context so that it can be modified.
The statements
@example
@}
@end example
-In the following discussion, the example input shown should go on the
-@dots{} in the previous fragment.
+In the following discussion, the example input shown should go in place
+of the @dots{} in the previous fragment.
-First the context's name is defined. Instead of @context{Voice} it
-will be called @context{ImproVoice},
+First it is necessary to define a name for the new context:
@example
\name ImproVoice
\alias Voice
@end example
-The context will print notes, and instructive texts
+The context will print notes and instructive texts, so we need to add
+the engravers which provide this functionality,
@example
\consists Note_heads_engraver
\consists Text_engraver
@end example
-but only on the center line,
+but we only need this on the center line,
@example
\consists Pitch_squash_engraver
@node The \override command
-@section The \override command
+@section The @code{\override} command
In the previous section, we have already touched on a command that
changes layout details: the @code{\override} command. In this section,
-we will look in more detail at how to use the command in practice.
+we will look in more detail at how to use the command in practice. The
+general syntax of this command is:
+@example
+\override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value}
+@end example
+
+This will set the @var{layout_property} of the specified @var{layout_object},
+which is a member of the @var{context}, to the @var{value}.
@menu
* Constructing a tweak::
* Layout interfaces::
* Determining the grob property::
* Objects connected to the input::
-* \set vs. \override::
+* Using Scheme code instead of \tweak::
+* \set versus \override::
* Difficult tweaks::
@end menu
@end example
@noindent
-This means that we must determine these bits of information:
+To construct this tweak we must determine these bits of information:
@itemize
@item the context: here @context{Voice}.
manual.
@end ignore
+@ifnothtml
+The programmer's reference is available as an HTML document. It is
+highly recommended that you read it in HTML form, either online or
+by downloading the HTML documentation. This section will be much more
+difficult to understand if you are using the
+PDF manual.
+@end ifnothtml
+
Follow the link to @internalsref{Fingering}. At the top of the
page, you will see
@internalsref{New_fingering_engraver}.
@end quotation
-By clicking around in the program reference, we can follow the
-flow of information within the program, following links like this:
+By following related links inside the program reference, we can follow the
+flow of information within the program:
@itemize @bullet
@end quotation
@noindent
-which means that the number will be kept at a distance of at least 0.6
+which means that the number will be kept at a distance of at least 0.5
of the note head.
@funindex \tweak
In some cases, it is possible to take a short-cut for tuning graphical
-objects. For objects that result directly from a piece of the input,
+objects. For objects that result directly from a piece of the input,
you can use the @code{\tweak} function, for example
@lilypond[relative=2,fragment,verbatim,ragged-right]
>4-\tweak #'padding #10 -.
@end lilypond
-As you can see, properties are set directly in the objects directly,
+As you can see, properties are set in the objects directly,
without mentioning the grob name or context where this should be
applied.
an @internalsref{event} from the input, for example
@itemize @bullet
-@item note heads, caused by chord-pitch (i.e., notes inside a chord).
-@item articulation signs, caused by articulation instructions.
+@item note heads, caused by chord-pitch (i.e., notes inside a chord)
+@item articulation signs, caused by articulation instructions
@end itemize
It notably does not work for stems and accidentals (these are caused
@end example
@noindent
-will not change color. See @ref{Displaying music expressions} for
+does not change color. See @ref{Displaying music expressions} for
details.
-@node \set vs. \override
-@subsection \set vs. \override
+@node Using Scheme code instead of \tweak
+@subsection Using Scheme code instead of @code{\tweak}
+
+The main disadvantage of @code{\tweak} is its syntactical
+inflexibility. For example, the following produces a syntax error.
+
+@example
+F = \tweak #'font-size #-3 -\flageolet
+
+\relative c'' @{
+ c4^\F c4_\F
+@}
+@end example
+
+@noindent
+With other words, @code{\tweak} doesn't behave like an articulation
+regarding the syntax; in particular, it can't be attached with
+@samp{^} and @samp{_}.
+
+Using Scheme, this problem can be circumvented. The route to the
+result is given in @ref{Adding articulation to notes (example)},
+especially how to use @code{\displayMusic} as a helping guide.
+
+@example
+F = #(let ((m (make-music 'ArticulationEvent
+ 'articulation-type "flageolet")))
+ (set! (ly:music-property m 'tweaks)
+ (acons 'font-size -3
+ (ly:music-property m 'tweaks)))
+ m)
+
+\relative c'' @{
+ c4^\F c4_\F
+@}
+@end example
+
+@noindent
+Here, the @code{tweaks} properties of the flageolet object
+@samp{m} (created with @code{make-music}) are extracted with
+@code{ly:music-property}, a new key-value pair to change the
+font size is prepended to the property list with the
+@code{acons} Scheme function, and the result is finally
+written back with @code{set!}. The last element of the
+@code{let} block is the return value, @samp{m} itself.
+
+
+@node \set versus \override
+@subsection @code{\set} vs. @code{\override}
We have seen two methods of changing properties: @code{\set} and
@code{\override}. There are actually two different kinds of
projects / lilypond.git / blobdiff