@menu
* Contexts explained::
-* Creating contexts::
+* Creating and referencing contexts::
* Keeping contexts alive::
* Modifying context plug-ins::
* Changing context default settings::
@end ignore
-@node Creating contexts
-@subsection Creating contexts
-
-@c TODO more complete descriptions rather than learning style
-
-For scores with only one voice and one staff, contexts are
-created automatically. For more complex scores, it is necessary to
-create them by hand. There are three commands that do this.
-
-@itemize
-
-@item
-The easiest command is @code{\new}, and it also the quickest to type.
-It is prepended to a music expression, for example
+@node Creating and referencing contexts
+@subsection Creating and referencing contexts
@funindex \new
+@funindex \context
@cindex new contexts
-@cindex Context, creating
+@cindex referencing contexts
+@cindex Contexts, creating and referencing
+
+LilyPond will create lower-level contexts automatically if a music
+expression is encountered before a suitable context exists, but this
+is usually successful only for simple scores or music fragments like
+the ones in the documentation. For more complex scores it is
+advisable to specify all contexts explicitly with either the
+@code{\new} or @code{\context} command. The syntax of
+these two commands is very similar:
@example
-\new @var{type} @var{music expression}
+[\new | \context] @var{Context} [ = @var{name}] [@var{music-expression}]
@end example
@noindent
-where @var{type} is a context name (like @code{Staff} or
-@code{Voice}). This command creates a new context, and starts
-interpreting the @var{music expression} with that.
+where either @code{\new} or @code{\context} may be specified.
+@var{Context} is the type of context which is to be created,
+@var{name} is an optional name to be given to the particular context
+being created and @var{music-expression} is a single music expression
+that is to be interpreted by the engravers and performers in this
+context.
-A practical application of @code{\new} is a score with many
-staves. Each part that should be on its own staff, is preceded with
-@code{\new Staff}.
+The @code{\new} prefix without a name is commonly used to create
+scores with many staves:
-@lilypond[quote,verbatim,relative=2,ragged-right]
+@lilypond[quote,verbatim,relative=2]
<<
- \new Staff { c4 c }
- \new Staff { d4 d }
+ \new Staff {
+ % leave the Voice context to be created implicitly
+ c4 c
+ }
+ \new Staff {
+ d4 d
+ }
>>
@end lilypond
-The @code{\new} command may also give a name to the context,
+@noindent
+and to place several voices into one staff:
-@example
-\new @var{type} = @var{id} @var{music}
-@end example
-However, this user specified name is only used if there is no other
-context already earlier with the same name.
+@lilypond[quote,verbatim,relative=2]
+<<
+ \new Staff <<
+ \new Voice {
+ \voiceOne
+ c8 c c4 c c
+ }
+ \new Voice {
+ \voiceTwo
+ g4 g g g
+ }
+ >>
+>>
+@end lilypond
+@noindent
+@code{\new} should always be used to specify unnamed contexts.
-@funindex \context
+The difference between @code{\new} and @code{\context} is in the
+action taken:
+@itemize
@item
-Like @code{\new}, the @code{\context} command also directs a music
-expression to a context object, but gives the context an explicit name. The
-syntax is
+@code{\new} with or without a name will always create a fresh,
+distinct, context, even if one with the same name already exists:
-@example
-\context @var{type} = @var{id} @var{music}
-@end example
+@lilypond[quote,verbatim,relative=2]
+<<
+ \new Staff <<
+ \new Voice = "A" {
+ \voiceOne
+ c8 c c4 c c
+ }
+ \new Voice = "A" {
+ \voiceTwo
+ g4 g g g
+ }
+ >>
+>>
+@end lilypond
-This form will search for an existing context of type @var{type}
-called @var{id}. If that context does not exist yet, a new
-context with the specified name is created. This is useful if
-the context is referred to later on. For example, when
-setting lyrics the melody is in a named context
+@item
+@code{\context} with a name specified will create a distinct context
+only if a context of the same type with the same name in the same
+context hierarchy does not already exist. Otherwise it will be taken
+as a reference to that previously created context, and its music
+expression will be passed to that context for interpretation.
-@example
-\context Voice = "@b{tenor}" @var{music}
-@end example
+One application of named contexts is in separating the score layout
+from the musical content. Either of these two forms is valid:
-@noindent
-so the texts can be properly aligned to its notes,
+@lilypond[quote,verbatim]
+\score {
+ <<
+ % score layout
+ \new Staff <<
+ \new Voice = "one" {
+ \voiceOne
+ }
+ \new Voice = "two" {
+ \voiceTwo
+ }
+ >>
-@example
-\new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
-@end example
+ % musical content
+ \context Voice = "one" {
+ \relative c'' {
+ c4 c c c
+ }
+ }
+ \context Voice = "two" {
+ \relative c'' {
+ g8 g g4 g g
+ }
+ }
+ >>
+}
+@end lilypond
-@noindent
+@lilypond[quote,verbatim]
+\score {
+ <<
+ % score layout
+ \new Staff <<
+ \context Voice = "one" {
+ \voiceOne
+ }
+ \context Voice = "two" {
+ \voiceTwo
+ }
+ >>
-Another possible use of named contexts is funneling two different
-music expressions into one context. In the following example,
-articulations and notes are entered separately,
+ % musical content
+ \context Voice = "one" {
+ \relative c'' {
+ c4 c c c
+ }
+ }
+ \context Voice = "two" {
+ \relative c'' {
+ g8 g g4 g g
+ }
+ }
+ >>
+}
+@end lilypond
-@example
-music = @{ c4 c4 @}
-arts = @{ s4-. s4-> @}
-@end example
+@noindent
+Alternatively, variables may be employed to similar effect. See
+@rlearning{Organizing pieces with variables}.
-They are combined by sending both to the same @code{Voice} context,
+@item
+
+@code{\context} with no name will match the first of any previously
+created contexts of the same type in the same context heirarchy,
+even one that has been given a name, and its music expression will be
+passed to that context for interpretation. This form is rarely
+useful. However, @code{\context} with no name and no music expression
+is used to set the context in which a Scheme procedure specified with
+@code{\applyContext} is executed:
@example
-<<
- \new Staff \context Voice = "A" \music
- \context Voice = "A" \arts
->>
+\new Staff \relative c' @{
+ c1
+ \context Timing
+ \applyContext #(lambda (ctx)
+ (newline)
+ (display (ly:context-current-moment ctx)))
+ c1
+@}
@end example
-@lilypond[quote,ragged-right]
-music = { c4 c4 }
-arts = { s4-. s4-> }
-\relative c'' <<
- \new Staff \context Voice = "A" \music
- \context Voice = "A" \arts
->>
-@end lilypond
-With this mechanism, it is possible to define an Urtext (original
-edition), with the option to put several distinct articulations on the
-same notes.
+@end itemize
-@cindex creating contexts
+A context must be named if it is to be referenced later, for example
+when lyrics are associated with music:
-@item
-The third command for creating contexts is
@example
-\context @var{type} @var{music}
+\new Voice = "tenor" @var{music}
+...
+\new Lyrics \lyricsto "tenor" @var{lyrics}
@end example
-
@noindent
-This is similar to @code{\context} with @code{= @var{id}}, but matches
-any context of type @var{type}, regardless of its given name.
+For details of associating lyrics with music see
+@ref{Automatic syllable durations}.
-This variant is used with music expressions that can be interpreted at
-several levels. For example, the @code{\applyOutput} command (see
-@rextend{Running a function on all layout objects}). Without an explicit
-@code{\context}, it is usually applied to @code{Voice}
+The properties of all contexts of a particular type can be modified
+in a @code{\layout} block (with a different syntax), see
+@ref{Changing all contexts of the same type}. This construct also
+provides a means of keeping layout instructions separate from the
+musical content. If a single context is to be modified, a @code{\with}
+block must be used, see @ref{Changing just one specific context}.
-@example
-\applyOutput #'@var{context} #@var{function} % apply to Voice
-@end example
+@seealso
-To have it interpreted at the @code{Score} or @code{Staff} level use
-these forms
+Learning Manual:
+@rlearning{Organizing pieces with variables}.
-@example
-\applyOutput #'Score #@var{function}
-\applyOutput #'Staff #@var{function}
-@end example
+Notation Reference:
+@ref{Changing just one specific context},
+@ref{Automatic syllable durations}.
-@end itemize
@node Keeping contexts alive
@subsection Keeping contexts alive
to see the settings for each grob description. Grob descriptions
are modified with @code{\override}.
-@code{\override} is actually a shorthand;
-
-@example
-\override @var{context}.@var{GrobName} #'@var{property} = #@var{value}
-@end example
-
-@noindent
-is more or less equivalent to
+The syntax for the @code{\override} command is
-@c leave this long line -gp
@example
-\set @var{context}.@var{GrobName} =
- #(cons (cons '@var{property} @var{value})
- <previous value of @var{context}.@var{GrobName}>)
+\override [@var{context}.]@var{GrobName}.@var{property} = #@var{value}
@end example
-The value of @code{context}.@code{GrobName} (the alist) is used to initialize
-the properties of individual grobs. Grobs have
-properties, named in Scheme style, with
-@code{dashed-words}. The values of grob properties change
-during the formatting process: formatting basically amounts
-to computing properties using callback functions.
-
For example, we can increase the thickness of a note stem by
overriding the @code{thickness} property of the @code{Stem}
object:
}
@end lilypond
+Some tweakable options are called @q{subproperties} and reside inside
+properties. To tweak those, use commands in the form
+
+@example
+\override Stem.details.beamed-lengths = #'(4 4 3)
+@end example
+
+or to modify the ends of spanners, use a form like these
+
+@example
+\override TextSpanner.bound-details.left.text = #"left text"
+\override TextSpanner.bound-details.right.text = #"right text"
+@end example
+
@funindex \revert
@cindex reverting overrides
@cindex overrides, reverting
-The effects of @code{\override} can be undone by @code{\revert}:
+The effects of @code{\override} can be undone by @code{\revert}.
+
+The syntax for the @code{\revert} command is
+
+@example
+\revert [@var{context}.]@var{GrobName}.@var{property}
+@end example
+
+For example,
@lilypond[quote,verbatim,relative=2]
c4
@item a sensible value: here @code{3.0}.
@end itemize
-Some tweakable options are called @q{subproperties} and reside inside
-properties. To tweak those, use commands in the form
-
-@example
-\override Stem.details.beamed-lengths = #'(4 4 3)
-@end example
-
@cindex internal documentation
@cindex finding graphical objects
@cindex graphical object descriptions
syntax:
@example
-\tweak @var{layout-object} #'@var{grob-property} @var{value}
+\tweak [@var{layout-object}.]@var{grob-property} @var{value}
@end example
Specifying @var{layout-object} is optional.
-But the main use of the @code{\tweak} command is to modify just
+The main use of the @code{\tweak} command is to modify just
one of a number of notation elements which start at the same musical
moment, like the notes of a chord, or tuplet brackets which start
at the same time.
@code{NoteHead} layout objects rather than by music elements in the
input stream.
-Such indirectly created layout objects can be tweaked using the explicit
-form of the @code{\tweak} command:
+Such indirectly created layout objects can be tweaked using the form
+of the @code{\tweak} command in which the grob name is specified
+explicitly:
@lilypond[relative=2,verbatim,quote]
\tweak Stem.color #red
be determined automatically by LilyPond, but in some cases it may
be desirable to force a particular direction or placement.
-@strong{Articulation direction indicators}
+@menu
+* Articulation direction indicators::
+* The direction property::
+@end menu
+
+@node Articulation direction indicators
+@unnumberedsubsubsec Articulation direction indicators
By default some directions are always up or always down (e.g.
dynamics or fermata), while other things can alternate between
c2^( c)
@end lilypond
-@strong{The direction property}
+@node The direction property
+@unnumberedsubsubsec The direction property
The position or direction of many layout objects is controlled by the
@code{direction} property.
those that draw a straight line between the two objects, support in
addition the @code{line-spanner-interface}.
+@menu
+* Using the spanner-interface::
+* Using the line-spanner-interface::
+@end menu
+
+@node Using the spanner-interface
@unnumberedsubsubsec Using the @code{spanner-interface}
This interface provides two properties that apply to several spanners.
-@strong{@i{The @code{minimum-length} property}}
+@subsubsubheading The @code{minimum-length} property
The minimum length of the spanner is specified by the
@code{minimum-length} property. Increasing this usually has the
e8 e e e
@end lilypond
-@strong{@i{The @code{to-barline} property}}
+@subsubsubheading The @code{to-barline} property
The second useful property of the @code{spanner-interface} is
@code{to-barline}. By default this is true, causing hairpins and
or on other spanners for which terminating on the bar line would
not be meaningful.
+@node Using the line-spanner-interface
@unnumberedsubsubsec Using the @code{line-spanner-interface}
Objects which support the @code{line-spanner-interface} include
@item @code{Clef} @tab @code{Staff} @tab @code{begin-of-line-visible}
@item @code{Custos} @tab @code{Staff} @tab @code{end-of-line-visible}
@item @code{DoublePercentRepeat} @tab @code{Voice} @tab @code{begin-of-line-invisible}
-@c omit KeyCancellation until it can be explained -td
-@c @item @code{KeyCancellation} @tab ?? @tab @code{begin-of-line-invisible}
+@item @code{KeyCancellation} @tab @code{Staff} @tab @code{begin-of-line-invisible}
@item @code{KeySignature} @tab @code{Staff} @tab @code{begin-of-line-visible}
@c omit LeftEdge until it can be explained -td
@c @item @code{LeftEdge} @tab @code{Score} @tab @code{center-invisible}
f4 g a b
f4 g a b
% Remove bar line at the end of the current line
-\once \override Score.BarLine.break-visibility = #'#(#f #t #t)
+\once \override Score.BarLine.break-visibility = ##(#f #t #t)
\break
f4 g a b
f4 g a b
@node Special considerations
@unnumberedsubsubsec Special considerations
-@strong{@emph{Visibility following explicit changes}}
+@subsubsubheading Visibility following explicit changes
@cindex key signature, visibility following explicit change
@cindex explicitKeySignatureVisibility
f4 g a b
@end lilypond
-@strong{@emph{Visibility of cautionary accidentals}}
+@subsubsubheading Visibility of cancelling accidentals
-To remove the cautionary accidentals printed at an explicit key
+To remove the cancelling accidentals printed at an explicit key
change, set the Staff context property @code{printKeyCancellation}
to @code{#f}:
With these overrides only the accidentals before the notes remain
to indicate the change of key.
+Note that when changing the key to C@tie{}major or A@tie{}minor
+the cancelling accidentals would be the @emph{only} indication of
+the key change. In this case setting @code{printKeyCancellation} to
+@code{#f} has no effect:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\set Staff.printKeyCancellation = ##f
+\key c \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
+To suppress the cancelling accidentals even when the key is
+changed to C@tie{}major or A@tie{}minor, override
+the visibility of the @code{KeyCancellation} grob instead:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\override Staff.KeyCancellation.break-visibility = #all-invisible
+\key c \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
@c TODO Add visibility of cautionary accidentals before notes
-@strong{@emph{Automatic bars}}
+@subsubsubheading Automatic bars
@cindex automaticBars
@cindex bar lines, suppressing
@c TODO Add example
-@strong{@emph{Octavated clefs}}
+@subsubsubheading Octavated clefs
@cindex octavated clefs, visibility of
@cindex visibility of octavated clefs
@node Using the self-alignment-interface
@unnumberedsubsubsec Using the @code{self-alignment-interface}
-@emph{Self-aligning objects horizontally}
+@subsubsubheading Self-aligning objects horizontally
The horizontal alignment of an object which supports the
@code{self-alignment-interface} is controlled by the value of
^"aligned further to the right"
@end lilypond
-@emph{Self-aligning objects vertically}
+@subsubsubheading Self-aligning objects vertically
Objects may be aligned vertically in an analogous way to aligning
them horizontally if the @code{Y-offset} property is set to
@code{CENTER}, and @code{UP} may be substituted for @w{@code{-1}},
@code{0}, and @code{1}, respectively.
-@emph{Self-aligning objects in both directions}
+@subsubsubheading Self-aligning objects in both directions
By setting both @code{X-offset} and @code{Y-offset}, an object may
be aligned in both directions simultaneously.
projects / lilypond.git / blobdiff