version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.61"
+@c \version "2.12.0"
@node Changing defaults
@chapter Changing defaults
@menu
* Contexts explained::
* Creating contexts::
+* Keeping contexts alive::
* Modifying context plug-ins::
* Changing context default settings::
* Defining new contexts::
* Aligning contexts::
@end menu
-@seealso
+@seealso
Learning Manual:
@rlearning{Contexts and engravers}.
@c TODO Describe propagation of property values -td
-Contexts are arranged heirarchically:
+Contexts are arranged hierarchically:
@menu
* Score - the master of all contexts::
Groups staves while adding a bracket on the left side, grouping
the staves together. The bar lines of the contained staves are
-connected vertically. StaffGroup only consists of a collection
+connected vertically. @code{StaffGroup} only consists of a collection
of staves, with a bracket in front and spanning bar lines.
@strong{@emph{ChoirStaff}}
-Identical to StaffGroup except that the bar lines of the contained
-staves are not connected vertically.
+Identical to @code{StaffGroup} except that the bar lines of the
+contained staves are not connected vertically.
@strong{@emph{GrandStaff}}
-A group of staves, with a brace on the left side, grouping
-the staves together. The bar lines of the contained staves are
+A group of staves, with a brace on the left side, grouping the
+staves together. The bar lines of the contained staves are
connected vertically.
@strong{@emph{PianoStaff}}
-@c TODO No longer correct? Check. -td
-Just like GrandStaff but with a forced distance between the
-staves, so cross staff beaming and slurring can be used.
-
-@ignore
-@strong{@emph{InnerStaffGroup}}
-
-TODO -td
-
-@strong{@emph{InnerChoirStaff}}
-
-TODO -td
-
-@end ignore
+Just like @code{GrandStaff}, but with support for instrument names
+to the left of each system.
@node Intermediate-level contexts - staves
@unnumberedsubsubsec Intermediate-level contexts - staves
@strong{@emph{Staff}}
-Handles clefs, bar lines, keys, accidentals. It can contain
-Voice contexts.
+Handles clefs, bar lines, keys, accidentals. It can contain
+@code{Voice} contexts.
@strong{@emph{RhythmicStaff}}
-Like Staff but for printing rhythms. Pitches are ignored;
+Like @code{Staff} but for printing rhythms. Pitches are ignored;
the notes are printed on one line.
@strong{@emph{TabStaff}}
-Context for generating tablature. By default lays the music
+Context for generating tablature. By default lays the music
expression out as a guitar tablature, printed on six lines.
@strong{@emph{DrumStaff}}
-Handles typesetting for percussion. Can contain DrumVoice
+Handles typesetting for percussion. Can contain @code{DrumVoice}
@strong{@emph{VaticanaStaff}}
-Same as Staff, except that it is designed for typesetting
+Same as @code{Staff}, except that it is designed for typesetting
a piece in gregorian style.
@strong{@emph{MensuralStaff}}
-Same as Staff, except that it is designed for typesetting
+Same as @code{Staff}, except that it is designed for typesetting
a piece in mensural style.
@node Bottom-level contexts - voices
@strong{@emph{Voice}}
-Corresponds to a voice on a staff. This context handles the
+Corresponds to a voice on a staff. This context handles the
conversion of dynamic signs, stems, beams, super- and sub-scripts,
slurs, ties, and rests. You have to instantiate this explicitly
if you require multiple voices on the same staff.
@strong{@emph{VaticanaVoice}}
-Same as Voice, except that it is designed for typesetting a piece
-in gregorian style.
+Same as @code{Voice}, except that it is designed for typesetting
+a piece in gregorian style.
@strong{@emph{MensuralVoice}}
-Same as Voice, with modifications for typesetting a piece in
+Same as @code{Voice}, with modifications for typesetting a piece in
mensural style.
@strong{@emph{Lyrics}}
-Corresponds to a voice with lyrics. Handles the printing of a
+Corresponds to a voice with lyrics. Handles the printing of a
single line of lyrics.
@strong{@emph{DrumVoice}}
@strong{@emph{FiguredBass}}
-The context in which BassFigure objects are created from
+The context in which @code{BassFigure} objects are created from
input entered in @code{\figuremode} mode.
@strong{@emph{TabVoice}}
-The voice context used within a TabStaff context. Usually left to
-be created implicitly.
+The voice context used within a @code{TabStaff} context. Usually
+left to be created implicitly.
@strong{@emph{ChordNames}}
@end itemize
+@node Keeping contexts alive
+@subsection Keeping contexts alive
+
+@cindex contexts, keeping alive
+@cindex contexts, lifetime
+
+Contexts are usually terminated at the first musical moment in
+which they have nothing to do. So @code{Voice} contexts die as
+soon as they contain no events; @code{Staff} contexts die as soon
+as all the @code{Voice} contexts within them contain no events; etc.
+This can cause difficulties if earlier contexts which have died
+have to be referenced, for example, when changing staves with
+@code{\change} commands, associating lyrics with a voice with
+@code{\lyricsto} commands, or when adding further musical events to
+an earlier context.
+
+There is an exception to this general rule: just one of the
+@code{Voice} contexts in a @code{Staff} context or in a
+@code{<<...>>} construct will always persist to the end of the
+enclosing @code{Staff} context or @code{<<...>>} construct, even
+though there may be periods when it has nothing to do. The context
+to persist in this way will be the first one encountered in the
+first enclosed @code{@{...@}} construct, ignoring any in enclosed
+@code{<<...>>} constructs.
+
+Any context can be kept alive by ensuring it has something to do at
+every musical moment. @code{Staff} contexts are kept alive by
+ensuring one of their voices is kept alive. One way of doing this
+is to add spacer rests to a voice in parallel with the real music.
+These need to be added to every @code{Voice} context which needs to
+be kept alive. If several voices are to be used sporadically it is
+safest to keep them all alive rather than attempting to rely on the
+exceptions mentioned above.
+
+In the following example, both voice A and voice B are kept alive
+in this way for the duration of the piece:
+
+@lilypond[quote,verbatim]
+musicA = \relative c'' { d4 d d d }
+musicB = \relative c'' { g4 g g g }
+keepVoicesAlive = {
+ <<
+ \new Voice = "A" { s1*5 } % Keep Voice "A" alive for 5 bars
+ \new Voice = "B" { s1*5 } % Keep Voice "B" alive for 5 bars
+ >>
+}
+
+music = {
+ \context Voice = "A" {
+ \voiceOneStyle
+ \musicA
+ }
+ \context Voice = "B" {
+ \voiceTwoStyle
+ \musicB
+ }
+ \context Voice = "A" { \musicA }
+ \context Voice = "B" { \musicB }
+ \context Voice = "A" { \musicA }
+}
+
+\score {
+ \new Staff <<
+ \keepVoicesAlive
+ \music
+ >>
+}
+@end lilypond
+
+@cindex lyrics, aligning with sporadic melody
+
+The following example shows how a sporadic melody line with lyrics
+might be written using this approach. In a real situation the
+melody and accompaniment would consist of several different
+sections, of course.
+
+@lilypond[quote,verbatim]
+melody = \relative c'' { a4 a a a }
+accompaniment = \relative c' { d4 d d d }
+words = \lyricmode { These words fol -- low the mel -- o -- dy }
+\score {
+ <<
+ \new Staff = "music" {
+ <<
+ \new Voice = "melody" {
+ \voiceOne
+ s1*4 % Keep Voice "melody" alive for 4 bars
+ }
+ {
+ \new Voice = "accompaniment" {
+ \voiceTwo
+ \accompaniment
+ }
+ <<
+ \context Voice = "melody" { \melody }
+ \context Voice = "accompaniment" { \accompaniment }
+ >>
+ \context Voice = "accompaniment" { \accompaniment }
+ <<
+ \context Voice = "melody" { \melody }
+ \context Voice = "accompaniment" { \accompaniment }
+ >>
+ }
+ >>
+ }
+ \new Lyrics \with { alignAboveContext = #"music" }
+ \lyricsto "melody" { \words }
+ >>
+}
+@end lilypond
+
+An alternative way, which may be better in many circumstances, is
+to keep the melody line alive by simply including spacer notes to
+line it up correctly with the accompaniment:
+
+@lilypond[quote,verbatim]
+melody = \relative c'' {
+ s1 % skip a bar
+ a4 a a a
+ s1 % skip a bar
+ a4 a a a
+}
+accompaniment = \relative c' {
+ d4 d d d
+ d4 d d d
+ d4 d d d
+ d4 d d d
+}
+words = \lyricmode { These words fol -- low the mel -- o -- dy }
+
+\score {
+ <<
+ \new Staff = "music" {
+ <<
+ \new Voice = "melody" {
+ \voiceOne
+ \melody
+ }
+ \new Voice = "accompaniment" {
+ \voiceTwo
+ \accompaniment
+ }
+ >>
+ }
+ \new Lyrics \with { alignAboveContext = #"music" }
+ \lyricsto "melody" { \words }
+ >>
+}
+@end lilypond
+
@node Modifying context plug-ins
@subsection Modifying context plug-ins
\name ImproVoice
\type "Engraver_group"
\consists "Note_heads_engraver"
+ \consists "Rhythmic_column_engraver"
\consists "Text_engraver"
\consists Pitch_squash_engraver
squashedPosition = #0
\relative c' \new Staff = "main" {
c4 c c c
<<
- \new Staff \with {alignAboveContext=main} \ossia
+ \new Staff \with { alignAboveContext = #"main" } \ossia
{ d8 f d f d f d f }
>>
}
such as
@example
-\override Stem #'details #'beamed-lengths = #'(4 4 3)
+\override Stem #'(details beamed-lengths) = #'(4 4 3)
@end example
@seealso
-
Internals: @rinternals{OverrideProperty}, @rinternals{RevertProperty},
@rinternals{PropertySet}, @rinternals{Backend}, and
@rinternals{All layout objects}.
properties. To tweak those, use commands in the form
@example
-\override Stem #'details #'beamed-lengths = #'(4 4 3)
+\override Stem #'(details beamed-lengths) = #'(4 4 3)
@end example
@cindex internal documentation
to apply after the input file has been converted to a music stream.
This is often not the case, as many additional elements are inserted
into the music stream implicitly. For example, when a note which is
-not part of a chord is processed, Lilypond implicitly inserts a
+not part of a chord is processed, LilyPond implicitly inserts a
@code{ChordEvent} event before the note, so separating the tweak
from the note. However, if chord symbols are placed round the
tweak and the note, the @code{\tweak} command comes after the
these items.
Notably the @code{\tweak} command cannot be used to modify stems,
-beams or accidentals, since these are generated later by note heads,
-rather than by music elements in the input stream. Nor can a
-@code{\tweak} command be used to modify clefs or time signatures,
-since these become separated from any preceding @code{\tweak}
-command in the input stream by the automatic insertion of extra
-elements required to specify the context.
+beams or accidentals directly, since these are generated later by
+note heads, rather than by music elements in the input stream.
+Nor can a @code{\tweak} command be used to modify clefs or time
+signatures, since these become separated from any preceding
+@code{\tweak} command in the input stream by the automatic
+insertion of extra elements required to specify the context.
But the @code{\tweak} command can be used as an alternative to
the @code{\override} command to modify those notational elements
see @ref{Displaying music expressions}. This may be helpful in
determining what may be modified by a @code{\tweak} command.
-@seealso
+@seealso
Learning Manual:
@rlearning{Tweaking methods}.
Notation Reference:
@ref{Displaying music expressions}.
+
@knownissues
@cindex tweaks in a variable
@item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
@end itemize
+These indications affect only the next note.
+
+@lilypond[verbatim,quote,relative=2]
+c2( c)
+c2_( c)
+c2( c)
+c2^( c)
+@end lilypond
+
@strong{The direction property}
The position or direction of many layout objects is controlled
TrillPitchGroup - not tried
@end ignore
+These indications affect all notes until they are cancelled.
+
+@lilypond[verbatim,quote,relative=2]
+c2( c)
+\slurDown
+c2( c)
+c2( c)
+\slurNeutral
+c2( c)
+@end lilypond
+
@node Distances and measurements
@code{staff-space}. For an explanation and an example of its use,
see @rlearning{Length and thickness of objects}.
-@seealso
+@seealso
Learning Manual:
@rlearning{Length and thickness of objects}.
@lilypond[relative=2,quote,verbatim]
e2 \glissando b
-\once \override Glissando #'bound-details #'left #'Y = #3
-\once \override Glissando #'bound-details #'right #'Y = #-2
+\once \override Glissando #'(bound-details left Y) = #3
+\once \override Glissando #'(bound-details right Y) = #-2
e2 \glissando b
@end lilypond
@lilypond[relative=2,ragged-right,verbatim,fragment]
\override Glissando #'breakable = ##t
-\override Glissando #'bound-details #'right-broken #'Y = #-3
+\override Glissando #'(bound-details right-broken Y) = #-3
c1 \glissando \break
f1
@end lilypond
to put @i{cresc.}, @i{tr} and other text on horizontal spanners.
@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
-\override TextSpanner #'bound-details #'left #'text
+\override TextSpanner #'(bound-details left text)
= \markup { \small \bold Slower }
c2\startTextSpan b c a\stopTextSpan
@end lilypond
relative to the end point of the line:
@lilypond[relative=1,fragment,verbatim]
-\override TextSpanner #'bound-details
- #'left #'stencil-align-dir-y = #-2
-\override TextSpanner #'bound-details
- #'right #'stencil-align-dir-y = #UP
-
-\override TextSpanner #'bound-details
- #'left #'text = #"ggg"
-\override TextSpanner #'bound-details
- #'right #'text = #"hhh"
+\override TextSpanner
+ #'(bound-details left stencil-align-dir-y) = #-2
+\override TextSpanner
+ #'(bound-details right stencil-align-dir-y) = #UP
+
+\override TextSpanner
+ #'(bound-details left text) = #"ggg"
+\override TextSpanner
+ #'(bound-details right text) = #"hhh"
c4^\startTextSpan c c c \stopTextSpan
@end lilypond
hairpins with @code{\!}.
-
@seealso
-
Internals Reference: @rinternals{TextSpanner},
@rinternals{Glissando}, @rinternals{VoiceFollower},
@rinternals{TrillSpanner},
considerations.
@menu
-* Removing the stencil::
-* Making objects transparent::
-* Painting objects white::
-* Using break-visibility::
-* Special considerations::
+* Removing the stencil::
+* Making objects transparent::
+* Painting objects white::
+* Using break-visibility::
+* Special considerations::
@end menu
@c FIXME Complete
@lilypond[relative=2,ragged-right,verbatim,fragment]
e2 \glissando f
-\once \override Glissando #'bound-details #'right #'Y = #-2
+\once \override Glissando #'(bound-details right Y) = #-2
e2 \glissando f
@end lilypond
* Modifying shapes::
@end menu
-@seealso
+@seealso
Learning Manual:
@rlearning{Tweaking output},
@rlearning{Other sources of information}.
Internals Reference:
@rinternals{All layout objects}.
+
@node Aligning objects
@subsection Aligning objects
* Setting @code{X-offset} and @code{Y-offset} directly::
* Using the @code{side-position-interface}::
* Using the @code{self-alignment-interface}::
-* Using the @code{break-aligned-interface}::
+* Using the @code{break-alignable-interface}::
@end menu
@node Setting @code{X-offset} and @code{Y-offset} directly
@c TODO The align-interface, BassFigureAlignment and VerticalAlignment
-@node Using the @code{break-aligned-interface}
-@unnumberedsubsubsec Using the @code{break-aligned-interface}
+@node Using the @code{break-alignable-interface}
+@unnumberedsubsubsec Using the @code{break-alignable-interface}
+
+@cindex align to objects
+@cindex break-align-symbols
-Rehearsal marks may be aligned with notation objects other
-than bar lines. These objects include @code{ambitus},
+Rehearsal marks and bar numbers may be aligned with notation
+objects other than bar lines. These objects include @code{ambitus},
@code{breathing-sign}, @code{clef}, @code{custos}, @code{staff-bar},
@code{left-edge}, @code{key-cancellation}, @code{key-signature}, and
@code{time-signature}.
-By default, rehearsal marks will be horizontally centered above the
-object:
+By default, rehearsal marks and bar numbers will be horizontally
+centered above the object:
@lilypond[verbatim,quote,relative=1]
e1
e2.
@end lilypond
+A list of possible target alignment objects may be specified. If
+some of the objects are invisible at that point due to the setting
+of @code{break-visibility} or the explicit visibility settings for
+keys and clefs, the rehearsal mark or bar number is aligned to the
+first object in the list which is visible. If no objects in the
+list are visible the object is aligned to the bar line. If the bar
+line is invisible the object is aligned to the place where the bar
+line would be.
+
+@lilypond[verbatim,quote,relative=1]
+e1
+% the RehearsalMark will be centered above the Key Signature
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\key a \major
+\clef treble
+\mark "↓"
+e
+% the RehearsalMark will be centered above the Clef
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\key a \minor
+\clef bass
+\mark "↓"
+e,
+@end lilypond
+
The alignment of the rehearsal mark relative to the notation object
can be changed, as shown in the following example. In a score with
multiple staves, this setting should be done for all the staves.
@end lilypond
-
@node Vertical grouping of grobs
@subsection Vertical grouping of grobs
@c TODO Add inserting Postscript or ref to later
-@seealso
+@seealso
Notation Reference:
@ref{Graphic notation inside markup},
@ref{Formatting text},
@node Modifying ties and slurs
@unnumberedsubsubsec Modifying ties and slurs
+@cindex slurs, modifying
+@cindex ties, modifying
+@cindex Bézier curves
+@cindex Bézier control points
+
Ties, slurs and phrasing slurs are drawn as third-order Bézier
curves. If the shape of the tie or slur which is calculated
automatically is not optimum, the shape may be modified manually by
curve's control points.
For the example above the following override gives a satisfactory
-tie:
+tie. Note the placement -- it has to be immediately before the note
+to which the start of the tie (or slur) is attached.
@lilypond[verbatim,quote,relative=1]
<<
- \once \override Tie
- #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
- { e1 ~ e1 }
+ {
+ \once \override Tie
+ #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
+ e1 ~ e1
+ }
\\
{ r4 <g c,> <g c,> <g c,>4 }
>>
projects / lilypond.git / blobdiff