Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.13.39"
@node Fundamental concepts
@chapter Fundamental concepts
treated as a separate score, but they will be all combined into
a single output file. A @code{\book} command is not necessary
-- one will be implicitly created. However, if you would like
-separate output files from one @code{.ly} file then the
+separate output files from one @file{.ly} file then the
@code{\book} command should be used to separate the different
sections: each @code{\book} block will produce a
separate output file.
When LilyPond looks at this file, it takes the value of
@code{melody} (everything after the equals sign) and inserts it
whenever it sees @code{\melody}. There's nothing special about
-the names -- it could be @code{melody}, @code{global},
-@code{keyTime}, @code{pianorighthand}, or @code{foofoobarbaz}.
-For more details, see @ref{Saving typing with variables and
-functions}. Remember that you can use almost any name you like as
-long as it contains just alphabetic characters and is distinct
-from LilyPond command names. The exact limitations on variable
-names are detailed in @ruser{File structure}.
+the name -- it could be @code{melody}, @code{global},
+@code{keyTime}, @code{pianorighthand}, or something else.
+Remember that you can use almost any name you like as long as it
+contains just alphabetic characters and is distinct from LilyPond
+command names. For more details, see @ref{Saving typing with
+variables and functions}. The exact limitations on variable names
+are detailed in @ruser{File structure}.
@seealso
@end lilypond
It is not necessary to use a separate @code{<< \\ >>} construct
-for each bar. For music with few notes in each bar this layout
+for each bar. For music with few notes in each bar this layout
can help the legibility of the code, but if there are many
notes in each bar it may be better to split out each voice
separately, like this:
@cindex voices, naming
@cindex voices crossing brackets
@cindex slurs crossing brackets
-@cindex ties crossing brackest
+@cindex ties crossing brackets
This example has just two voices, but the same construct may be
used to encode three or more voices by adding more back-slash
voices downward ones. The stems for voices 1 and 2 are right,
but the stems in voice 3 should go down in this particular piece
of music. We can correct this by skipping voice three
-and placing the music in voice four. This is done by simply
+and placing the music in voice four. This is done by simply
adding another pair of @code{\\}.
@lilypond[quote,verbatim,fragment,ragged-right]
in opposite directions, but the notes from the third and fourth voices
are displaced, if necessary, to avoid the note heads colliding. This
usually works well, but in this example the notes of the lowest voice
-are clearly not well placed by default. LilyPond provides several ways
+are clearly not well placed by default. LilyPond provides several ways
to adjust the horizontal placing of notes. We are not quite ready yet
to see how to correct this, so we shall leave this problem until a
-later section --- see the @code{force-hshift} property in @ref{Fixing
-overlapping notation}.
+later section --- see the @code{force-hshift} property in
+@ref{Fixing overlapping notation}.
@seealso
The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
@code{\shiftOff} commands specify the degree to which notes and
chords of the voice should be shifted if a collision
-would otherwise occur. By default, the outer voices (normally
+would otherwise occur. By default, the outer voices (normally
voices one and two) have @code{\shiftOff} specified, while the
inner voices (three and four) have @code{\shiftOn} specified.
When a shift is applied, voices one and three are shifted to
}
@end lilypond
-@cindex verse and refrain
-
-We end with an example to show how we might code a solo verse which
-continues into a two-part refrain in two staves. The positioning
-of the sequential and simultaneous sections to achieve this within
-a single score is quite tricky, so follow the explanation carefully!
-
-Let's start with a score block containing a @code{ChoirStaff}, as
-we would like the brace to appear at the start of the chorus.
-Normally you would need angle brackets after @code{\new ChoirStaff}
-to bring in all the staves in parallel, but here we want to
-defer the parallelism during the solo so we use braces, although
-angle brackets here wouldn't hurt. Inside the @code{ChoirStaff} we
-want first the staff which will contain the verse. This must
-contain notes and lyrics in parallel, so here we need angle
-brackets around the @code{\new Voice} and @code{\new Lyrics} to
-start them at the same time:
-
-@lilypond[quote,verbatim,ragged-right]
-versenotes = \relative c'' {
- \clef "treble"
- \key g \major
- \time 3/4
- g4 g g | b4 b b |
-}
-
-versewords = \lyricmode {
- One two three | four five six |
-}
-
-\score {
- \new ChoirStaff {
- \new Staff <<
- \new Voice = "verse" {
- \versenotes \break
- }
- \new Lyrics \lyricsto verse {
- \versewords
- }
- >>
- }
-}
-@end lilypond
-
-That gives the verse line.
-
-Now we want to continue with refrainA on the same staff while a
-second staff is introduced in parallel with it for refrainB, so
-this is a parallel section which must be positioned immediately
-following the @code{\break} in the verse Voice. Yes, @emph{within}
-the verse Voice! Here's that parallel section. More staves
-could be introduced here in the same way.
-
-@example
-<<
- \refrainnotesA
- \new Lyrics \lyricsto verse @{
- \refrainwordsA
- @}
- \new Staff <<
- \new Voice = "refrainB" @{
- \refrainnotesB
- @}
- \new Lyrics \lyricsto "refrainB" @{
- \refrainwordsB
- @}
- >>
->>
-@end example
-
-Here's the final result with two staves in the chorus showing
-how the parallel section is positioned within the verse Voice:
-
-@lilypond[quote,verbatim, ragged-right]
-versenotes = \relative c'' {
- \clef "treble"
- \key g \major
- \time 3/4
- g4 g g | b4 b b |
-}
-versewords = \lyricmode {
- One two three | four five six |
-}
-refrainnotesA = \relative c'' {
- \clef "treble"
- \key g \major
- \time 2/4
- c4 c | g4 g | \bar "|."
-}
-refrainwordsA = \lyricmode {
- la la | la la |
-}
-refrainnotesB = \relative c {
- \clef "bass"
- \key g \major
- \time 2/4
- c4 e | d4 d |
-}
-refrainwordsB = \lyricmode {
- dum dum | dum dum |
-}
-
-\score {
- \new ChoirStaff {
- \new Staff <<
- \new Voice = "verse" {
- \versenotes \break
- <<
- \refrainnotesA
- \new Lyrics \lyricsto "verse" {
- \refrainwordsA
- }
- \new Staff <<
- \new Voice = "refrainB" {
- \refrainnotesB
- }
- \new Lyrics \lyricsto "refrainB" {
- \refrainwordsB
- }
- >>
- >>
- }
- \new Lyrics \lyricsto "verse" {
- \versewords
- }
- >>
- }
-}
-@end lilypond
-
-@cindex book, example of using
-@funindex \book
-@funindex book
-
-However, although this is an interesting and useful exercise to
-help you to understand how sequential and simultaneous blocks work,
-in practice one would perhaps choose to code this as two
-@code{\score} blocks within an implicit @code{\book} block, as
-follows:
-
-@lilypond[quote,verbatim,ragged-right]
-versenotes = \relative c'' {
- \clef "treble"
- \key g \major
- \time 3/4
- g4 g g | b4 b b |
-}
-
-versewords = \lyricmode {
- One two three | four five six |
-}
-
-refrainnotesA = \relative c'' {
- \clef "treble"
- \key g \major
- \time 2/4
- c4 c | g4 g | \bar "|."
-}
-
-refrainwordsA = \lyricmode {
- la la | la la |
-}
-
-refrainnotesB = \relative c {
- \clef "bass"
- \key g \major
- \time 2/4
- c4 e | d4 d |
-}
-
-refrainwordsB = \lyricmode {
- dum dum | dum dum |
-}
-
-\score {
- \new Staff <<
- \new Voice = "verse" {
- \versenotes
- }
- \new Lyrics \lyricsto "verse" {
- \versewords
- }
- >>
-}
-
-\score {
- \new ChoirStaff <<
- \new Staff <<
- \new Voice = "refrainA" {
- \refrainnotesA
- }
- \new Lyrics \lyricsto "refrainA" {
- \refrainwordsA
- }
- >>
- \new Staff <<
- \new Voice = "refrainB" {
- \refrainnotesB
- }
- \new Lyrics \lyricsto "refrainB" {
- \refrainwordsB
- }
- >>
- >>
-}
-@end lilypond
-
@seealso
Notation Reference: @ruser{Vocal music}.
@code{Voice}). This command creates a new context, and starts
interpreting the @var{music-expression} within that context.
-(Note that a @code{\new Score} command is not normally required,
-as the essential top-level @code{Score} context is created
-automatically when the music expression within the @code{\score}
-block is interpreted. The only reason for creating a @code{Score}
-context explicitly using @code{\new Score} is to introduce a
-@code{\with} block in which one or more score-wide default values
-of context properties may be specified. Information on using
-@code{\with} blocks can be found under the heading
-@qq{Setting context properties with @code{\\with} } in
-@ref{Modifying context properties}.)
+@warning{@bs{}@code{new Score} should not be used as the essential
+top-level @code{Score} context is created automatically when the music
+expression within the @bs{}@code{score} block is interpreted. Score-wide
+default values of context properties can be changed within the
+@bs{}@code{layout} block. See @ref{Modifying context properties}}
You have seen many practical examples which created new
@code{Staff} and @code{Voice} contexts in earlier sections, but
>>
@end lilypond
-Or, if the property override is to be applied to all staves
-within the score, it may be appended to an explicit
-@code{\new Score} command, like this:
-
-@lilypond[quote,verbatim,ragged-right]
-\score {
- \new Score \with { extraNatural = ##f } <<
- \new Staff {
- \relative c'' {
- gis4 ges aes ais
- }
- }
- \new Staff {
- \relative c'' {
- gis4 ges aes ais
- }
- }
- >>
-}
-@end lilypond
-
Properties set in this way may still be changed dynamically using
@code{\set} and returned to the default value set in the
@code{\with} block with @code{\unset}.
}
@end lilypond
+If the property override is to be applied to all staves
+within the score:
+
+@lilypond[quote,verbatim]
+\score {
+ <<
+ \new Staff {
+ \relative c'' {
+ gis4 ges aes ais
+ }
+ }
+ \new Staff {
+ \relative c'' {
+ gis4 ges aes ais
+ }
+ }
+ >>
+ \layout {
+ \context {
+ \Score extraNatural = ##f
+ }
+ }
+}
+@end lilypond
+
@noindent
Context properties set in this way may be overridden for particular
instances of contexts by statements in a @code{\with} block, and by
@end lilypond
None of the templates provides this layout exactly. The nearest is
-@q{SATB vocal score and automatic piano reduction} -- see @ref{Vocal
-ensembles} -- but we need to change the layout and add a piano
+@q{SATB vocal score and automatic piano reduction} -- see
+@ref{Vocal ensembles} -- but we need to change the layout and add a piano
accompaniment which is not derived automatically from the vocal parts.
The variables holding the music and words for the vocal parts are
fine, but we shall need to add variables for the piano reduction.
@} % end Score context
@end example
+@cindex stretchability of staves
+@cindex staves, stretchability
+
+The above layout of the organ staves is almost perfect; however,
+there is a slight defect which is not visible by looking at just a
+single system: The distance of the pedal staff to the left hand staff
+should behave approximately the same as the right hand staff to the
+left hand staff. In particular, the stretchability of staves in a
+@code{PianoStaff} context is limited (so that the distance between
+the staves for the left and right hand can't become too large), and
+the pedal staff should behave similarly.
+
+@cindex sub-properties
+@cindex properties, sub-properties
+@cindex graphical objects
+@cindex objects, graphical
+@cindex grobs
+
+Stretchability of staves can be controlled with the
+@code{staff-staff-spacing} property of the
+@code{VerticalAxisGroup} @q{graphical object} (commonly called
+@q{grob}s within the lilypond documentation) -- don't worry about
+the details right now; this is fully explained later. For the
+curious, have a look at @ruser{Overview of modifying properties}.
+In this case, we want to modify the @code{stretchability}
+sub-property only. Again, for the curious, you can find the
+default values for the staff-staff-spacing property
+in file @file{scm/define-grobs.scm} by looking up the definition
+of the @code{VerticalAxisGroup} grob. The value for
+@code{stretchability} is taken from the definition of the
+@code{PianoStaff} context (in file @file{ly/engraver-init.ly})
+so that the values are identical.
+
+@example
+\score @{
+ << % PianoStaff and Pedal Staff must be simultaneous
+ \new PianoStaff <<
+ \new Staff = "ManualOne" <<
+ \keyTime % set key and time signature
+ \clef "treble"
+ \new Voice @{
+ \voiceOne
+ \ManualOneVoiceOneMusic
+ @}
+ \new Voice @{
+ \voiceTwo
+ \ManualOneVoiceTwoMusic
+ @}
+ >> % end ManualOne Staff context
+ \new Staff = "ManualTwo" \with @{
+ \override VerticalAxisGroup
+ #'staff-staff-spacing #'stretchability = 5
+ @} <<
+ \keyTime
+ \clef "bass"
+ \new Voice @{
+ \ManualTwoMusic
+ @}
+ >> % end ManualTwo Staff context
+ >> % end PianoStaff context
+ \new Staff = "PedalOrgan" <<
+ \keyTime
+ \clef "bass"
+ \new Voice @{
+ \PedalOrganMusic
+ @}
+ >> % end PedalOrgan Staff
+ >>
+@} % end Score context
+@end example
That completes the structure. Any three-staff organ music
will have a similar structure, although the number of voices
may vary. All that remains now
\ManualOneVoiceTwoMusic
}
>> % end ManualOne Staff context
- \new Staff = "ManualTwo" <<
+ \new Staff = "ManualTwo" \with {
+ \override VerticalAxisGroup
+ #'staff-staff-spacing #'stretchability = 5
+ } <<
\keyTime
\clef "bass"
\new Voice {
} % end Score context
@end lilypond
+@seealso
+Music Glossary:
+@rglos{system}.
@node Saving typing with variables and functions
@subsection Saving typing with variables and functions
you have a single definition (such as @code{\dolce}) for all your
input files (see @ref{Style sheets}), then if the syntax changes, you
only need to update your single @code{\dolce} definition,
-instead of making changes throughout every @code{.ly} file.
+instead of making changes throughout every @file{.ly} file.
@node Scores and parts