@menu
* Interpretation contexts::
* The \override command::
+* Discussion of specific tweaks::
@end menu
entire score.
Within LilyPond, these rules and bits of information are grouped in
-@emph{Contexts}. Some examples of contexts are @context{Voice},
-@context{Staff}, and @context{Score}. They are hierarchical, for
-example: a @context{Staff} can contain many @context{Voice}s, and a
-@context{Score} can contain many @context{Staff} contexts.
+@emph{Contexts}. Some examples of contexts are @code{Voice},
+@code{Staff}, and @code{Score}. They are hierarchical, for
+example: a @code{Staff} can contain many @code{Voice}s, and a
+@code{Score} can contain many @code{Staff} contexts.
@quotation
-@image{context-example,5cm,,}
+@sourceimage{context-example,5cm,,}
@end quotation
Each context has the responsibility for enforcing some notation rules,
creating some notation objects and maintaining the associated
-properties. For example, the @context{Voice} context may introduce an
-accidental and then the @context{Staff} context maintains the rule to
+properties. For example, the @code{Voice} context may introduce an
+accidental and then the @code{Staff} context maintains the rule to
show or suppress the accidental for the remainder of the measure. The
-synchronization of bar lines is handled at @context{Score} context.
+synchronization of bar lines is handled at @code{Score} context.
However, in some music we may not want the bar lines to be
synchronized -- consider a polymetric score in 4/4 and 3/4 time. In
-such cases, we must modify the default settings of the @context{Score}
-and @context{Staff} contexts.
+such cases, we must modify the default settings of the @code{Score}
+and @code{Staff} contexts.
For very simple scores, contexts are created implicitly, and you need
not be aware of them. For larger pieces, such as anything with more
arts = @{ s4-. s4-> @}
@end example
-They are combined by sending both to the same @context{Voice} context,
+They are combined by sending both to the same @code{Voice} context,
@example
<<
This variant is used with music expressions that can be interpreted at
several levels. For example, the @code{\applyOutput} command (see
@ref{Running a function on all layout objects}). Without an explicit
-@code{\context}, it is usually applied to @context{Voice}
+@code{\context}, it is usually applied to @code{Voice}
@example
\applyOutput #'@var{context} #@var{function} % apply to Voice
@end example
-To have it interpreted at the @context{Score} or @context{Staff} level use
+To have it interpreted at the @code{Score} or @code{Staff} level use
these forms
@example
this case, it is @code{#t}, the boolean True value.
If the @var{context} argument is left out, then the current bottom-most
-context (typically @context{ChordNames}, @context{Voice}, or
-@context{Lyrics}) is used. In this example,
+context (typically @code{ChordNames}, @code{Voice}, or
+@code{Lyrics}) is used. In this example,
@lilypond[quote,verbatim,relative=2,fragment]
c8 c c c
@end lilypond
Contexts are hierarchical, so if a bigger context was specified, for
-example @context{Staff}, then the change would also apply to all
-@context{Voice}s in the current stave. The change is applied
+example @code{Staff}, then the change would also apply to all
+@code{Voice}s in the current stave. The change is applied
@q{on-the-fly}, during the music, so that the setting only affects the
second group of eighth notes.
For a full a description of each plug-in, see
@ifhtml
-@internalsref{Engravers}.
+@internalsref{Engravers and Performers}.
@end ifhtml
@ifnothtml
Internals Reference @expansion{} Translation @expansion{} Engravers.
signatures are normally synchronized across the score. This is done
by the @code{Timing_translator} and @code{Default_bar_line_engraver}.
This plug-in keeps an administration of time signature, location
-within the measure, etc. By moving thes engraver from @code{Score} to
+within the measure, etc. By moving these engraver from @code{Score} to
@code{Staff} context, we can have a score where each staff has its own
time signature.
@noindent
makes stems thicker (the default is 1.3, with staff line thickness as a
-unit). Since the command specifies @context{Staff} as context, it only
+unit). Since the command specifies @code{Staff} as context, it only
applies to the current staff. Other staves will keep their normal
appearance. Here we see the command in action:
@end lilypond
The @code{\override} command changes the definition of the @code{Stem}
-within the current @context{Staff}. After the command is interpreted
+within the current @code{Staff}. After the command is interpreted
all stems are thickened.
Analogous to @code{\set}, the @var{context} argument may be left out,
-causing the default context @context{Voice} to be used. Adding
+causing the default context @code{Voice} to be used. Adding
@code{\once} applies the change during one timestep only.
@lilypond[quote,fragment,verbatim,relative=2]
@internalsref{All layout objects}.
-@refbugs
+@knownissues
The back-end is not very strict in type-checking object properties.
Cyclic references in Scheme values for properties can cause hangs
-@refbugs
+@knownissues
It is not possible to collect context changes in a variable and apply
them to a @code{\context} definition by referring to that variable.
@node Defining new contexts
@subsection Defining new contexts
-Specific contexts, like @context{Staff} and @code{Voice}, are made of
+Specific contexts, like @code{Staff} and @code{Voice}, are made of
simple building blocks. It is possible to create new types of
contexts with different combinations of engraver plug-ins.
The next example shows how to build a different type of
-@context{Voice} context from scratch. It will be similar to
-@code{Voice}, but only prints centered slash noteheads. It can be used
+@code{Voice} context from scratch. It will be similar to
+@code{Voice}, but only prints centered slash note heads. It can be used
to indicate improvisation in jazz pieces,
@lilypond[quote,ragged-right]
\name ImproVoice
@end example
-Since it is similar to the @context{Voice}, we want commands that work
-on (existing) @context{Voice}s to remain working. This is achieved by
-giving the new context an alias @context{Voice},
+Since it is similar to the @code{Voice}, we want commands that work
+on (existing) @code{Voice}s to remain working. This is achieved by
+giving the new context an alias @code{Voice},
@example
\alias Voice
@end example
@funindex \accepts
-Contexts form hierarchies. We want to hang the @context{ImproVoice}
-under @context{Staff}, just like normal @code{Voice}s. Therefore, we
+Contexts form hierarchies. We want to hang the @code{ImproVoice}
+under @code{Staff}, just like normal @code{Voice}s. Therefore, we
modify the @code{Staff} definition with the @code{\accepts}
command,
@node Aligning contexts
@subsection Aligning contexts
-New contexts may be aligned above or below exisiting contexts. This
+New contexts may be aligned above or below existing contexts. This
could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and
in ossia,
+FIXME: this section doesn't work in pdf. (?)
+
@cindex ossia
@findex alignAboveContext
@findex alignBelowContext
To construct this tweak we must determine these bits of information:
@itemize
-@item the context: here @context{Voice}.
+@item the context: here @code{Voice}.
@item the layout object: here @code{Stem}.
@item the layout property: here @code{thickness}.
@item a sensible value: here @code{3.0}.
For many properties, regardless of the data type of the property, setting the
property to false ( @code{##f} ) will result in turning it off, causing
-Lilypond to ignore that property entirely. This is particularly useful for
+LilyPond to ignore that property entirely. This is particularly useful for
turning off grob properties which may otherwise be causing problems.
We demonstrate how to glean this information from the notation manual
@item
Horizontally, the center of the symbol should be aligned to the
-center of the notehead.
+center of the note head.
@item
Vertically, the symbol is placed next to the note and the staff.
@end quotation
By increasing the value of @code{padding}, we can move the
-fingering away from the notehead. The following command inserts
+fingering away from the note head. The following command inserts
3 staff spaces of white
between the note and the fingering:
@example
@end lilypond
-In this case, the context for this tweak is @context{Voice}. This
+In this case, the context for this tweak is @code{Voice}. This
fact can also be deduced from the program reference, for the page for
the @internalsref{Fingering_engraver} plug-in says
@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{_}.
+@code{^} and @code{_}.
Using Scheme, this problem can be circumvented. The route to the
result is given in @ref{Adding articulation to notes (example)},
@noindent
Here, the @code{tweaks} properties of the flageolet object
-@samp{m} (created with @code{make-music}) are extracted with
+@code{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.
+@code{let} block is the return value, @code{m} itself.
@node \set versus \override
Contexts can have properties, which are usually named in
@code{studlyCaps}. They mostly control the translation from
-music to notatino, eg. @code{localKeySignature} (for determining
+music to notation, eg. @code{localKeySignature} (for determining
whether to print accidentals), @code{measurePosition} (for
-determining when to print a barline). Context properties can
+determining when to print a bar line). Context properties can
change value over time while interpreting a piece of music;
@code{measurePosition} is an obvious example of
this. Context properties are modified with @code{\set}.
\set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
@end example
-The value of @code{context} (the alist) is used to initalize
+The value of @code{context} (the alist) is used to initialize
the properties of individual grobs. Grobs also have
properties, named in Scheme style, with
@code{dashed-words}. The values of grob properties change
expected within @code{\context} blocks.
@end itemize
+
+
+
+
+
+
+@node Discussion of specific tweaks
+@section Discussion of specific tweaks
+
+@menu
+* Line styles::
+* Controlling visibility of objects::
+@end menu
+
+@node Line styles
+@subsection Line styles
+
+@c TODO: split the following explanations between expressive marks and
+@c text-related stuff. Perhaps create a new subsection named
+@c "Spanner limits", "Spanner boundaries"? -vv
+
+Some performance indications, e.g., @i{rallentando} and
+@i{accelerando} and @i{trills} are written as text and are
+extended over many measures with lines, sometimes dotted or wavy.
+
+These all use the same routines as the glissando for drawing the
+texts and the lines, and tuning their behavior is therefore also
+done in the same way. It is done with a spanner, and the routine
+responsible for drawing the spanners is
+@code{ly:line-interface::print}. This routine determines the
+exact location of the two @i{span points} and draws a line in
+between, in the style requested.
+
+Here is an example of the different line styles available, and how
+to tune them.
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+d2 \glissando d'2
+\once \override Glissando #'style = #'dashed-line
+d,2 \glissando d'2
+\override Glissando #'style = #'dotted-line
+d,2 \glissando d'2
+\override Glissando #'style = #'zigzag
+d,2 \glissando d'2
+\override Glissando #'style = #'trill
+d,2 \glissando d'2
+@end lilypond
+
+The information that determines the end-points is computed
+on-the-fly for every graphic object, but it is possible to
+override these.
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+e2 \glissando f
+\once \override Glissando #'bound-details #'right #'Y = #-2
+e2 \glissando f
+@end lilypond
+
+The @code{Glissando} object, like any other using the
+@code{ly:line-interface::print} routine, carries a nested
+association list. In the above statement, the value for @code{Y}
+is set to @code{-2} for the association list corresponding to the
+right end point. Of course, it is also possible to adjust the
+left side with @code{left} instead of @code{right}.
+
+If @code{Y} is not set, the value is computed from the vertical
+position of right attachment point of the spanner.
+
+In case of a line break, the values for the span-points are
+extended with contents of the @code{left-broken} and
+@code{right-broken} sublists, for example
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+\override Glissando #'breakable = ##T
+\override Glissando #'bound-details #'right-broken #'Y = #-3
+c1 \glissando \break
+f1
+@end lilypond
+
+The following properties can be used for the
+
+@table @code
+@item Y
+This sets the Y-coordinate of the end point, in staff space. By
+default, it is the center of the bound object, so for a glissando
+it points to the vertical center of the note head.
+
+For horizontal spanners, such as text spanner and trill spanners,
+it is hardcoded to 0.
+
+@item attach-dir
+This determines where the line starts and ends in X-direction,
+relative to the bound object. So, a value of @code{-1} (or
+@code{LEFT}) makes the line start/end at the left side of the note
+head it is attached to.
+
+@item X
+This is the absolute coordinate of the end point. It is usually
+computed on the fly, and there is little use in overriding it.
+
+@item stencil
+Line spanners may have symbols at the beginning or end, which is
+contained in this sub-property. This is for internal use, it is
+recommended to use @code{text}.
+
+@item text
+This is a markup that is evaluated to yield stencil. It is used
+to put @i{cresc.} and @i{tr} on horizontal spanners.
+
+@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
+\override TextSpanner #'bound-details #'left #'text
+ = \markup { \small \bold Slower }
+c2\startTextSpan b c a\stopTextSpan
+@end lilypond
+
+@item stencil-align-dir-y
+@item stencil-offset
+Without setting this, the stencil is simply put there at the
+end-point, as defined by the @code{X} and @code{Y} sub properties.
+Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
+will move the symbol at the edge relative to the end point of the
+line
+
+@lilypond[relative=1,fragment,verbatim]
+\override TextSpanner #'bound-details
+ #'left #'stencil-align-dir-y = #DOWN
+\override TextSpanner #'bound-details
+ #'right #'stencil-align-dir-y = #UP
+
+\override TextSpanner #'bound-details
+ #'left #'text = #"gggg"
+\override TextSpanner #'bound-details
+ #'right #'text = #"hhhh"
+c4^\startTextSpan c c c \stopTextSpan
+@end lilypond
+
+@item arrow
+Setting this sub property to @code{#t} produce an arrowhead at the
+end of the line.
+
+@item padding
+This sub property controls the space between the specified
+end-point of the line and the actual end. Without padding, a
+glissando would start and end in the center of each note head.
+
+@end table
+
+FIXME: should this be in NR 3?
+
+The music function \endSpanners terminates spanners and hairpins
+after exactly one note.
+
+@lilypond[verbatim,quote,ragged-right,relative=2,fragment]
+\endSpanners
+c2 \startTextSpan c2
+c2 \< c2
+@end lilypond
+
+When using \endSpanners it is not necessary to close
+\startTextSpan with \stopTextSpan, nor is it necessary to close
+hairpins with \!.
+
+
+
+@seealso
+
+Internals Reference: @internalsref{TextSpanner},
+@internalsref{Glissando}, @internalsref{VoiceFollower},
+@internalsref{TrillSpanner},
+@internalsref{line-spanner-interface}.
+
+
+
+@node Controlling visibility of objects
+@subsection Controlling visibility of objects
+
+stuff about #'break-visibility
+
projects / lilypond.git / blobdiff