Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
When revising a translation, copy the HEAD committish of the
- version that you are working on. See TRANSLATION for details.
+ version that you are working on. For details, see the Contributors'
+ Guide, node Updating translation committishes..
@end ignore
@c \version "2.12.0"
@cindex book
@cindex score
-Up to this point none of the examples you have seen has used a
+Up to this point none of the examples you have seen have used a
@code{\score@{@}} command. This is because LilyPond automatically
adds the extra commands which are needed when you give it simple
input. LilyPond treats input like this:
@cindex variables
-Another great shorthand is the ability to define variables. All
-the templates use this
+Another great shorthand is the ability to define variables (see
+@ref{Organizing pieces with variables}. All the templates use this
@example
melody = \relative c' @{
@ref{Music expressions explained}. In that section, we saw how to
build big music expressions from small pieces -- we started from
notes, then chords, etc. Now we're going to start from a big
-music expression and work our way down.
-
-@example
-\score @{
- @{ % this brace begins the overall compound music expression
- \new StaffGroup <<
- @var{...insert the whole score of a Wagner opera in here...}
- >>
- @} % this brace ends the overall compound music expression
- \layout @{ @}
-@}
-@end example
-
-A whole Wagner opera would easily double the length of this
-manual, so let's just add a singer and piano. We don't need a
+music expression and work our way down. For simplicity, we'll use
+just a singer and piano in our example. We don't need a
@code{StaffGroup} for this ensemble, which simply groups a number
-of staves together with a bracket at the left, so we shall remove
-it. We @emph{do} need a singer and a piano, though.
+of staves together with a bracket at the left, but we do need
+staves for a singer and a piano, though.
@example
\score @{
@}
@end example
+Here we have given names to the staves -- @qq{singer} and
+@qq{piano}. This is not essential here, but it is a useful habit
+to cultivate so that you can see at a glance what each stave is
+for.
+
Remember that we use @code{<< ... >>} instead of @code{@{ ... @}} to
-show simultaneous music. And we definitely want to show the vocal
-part and piano part at the same time, not one after the other! Note
-that the @code{<< ... >>} construct is not really necessary for the
-Singer staff, as it contains only one sequential music expression;
-however, using @code{<< ... >>} instead of braces is still necessary
-if the music in the Staff is made of two simultaneous expressions,
-e.g. two simultaneous Voices, or a Voice with lyrics. We'll add some
-real music later; for now let's just put in some dummy notes and
-lyrics.
+show simultaneous music. This causes the vocal part and piano part
+to appear one above the other in the score. The @code{<< ... >>}
+construct would not be necessary for the Singer staff in the example
+above if it were going to contain only one sequential music
+expression, but @code{<< ... >>} rather than braces is necessary if
+the music in the Staff is to contain two or more simultaneous
+expressions, e.g. two simultaneous Voices, or a Voice with lyrics.
+We're going to have a voice with lyrics, so angle brackets are
+required. We'll add some real music later; for now let's just put
+in some dummy notes and lyrics. If you've forgotten how to add lyrics
+you may wish to review @code{\addlyrics} in @ref{Setting simple songs}.
@lilypond[verbatim,quote,ragged-right]
\score {
notes, not necessarily vocal notes -- for example, a violin
generally plays one voice) and some lyrics. We also have a piano
staff: it contains an upper staff (right hand) and a lower staff
-(left hand).
+(left hand), although the lower staff has yet to be given a bass
+clef.
At this stage, we could start filling in notes. Inside the curly
braces next to @code{\new Voice = "vocal"}, we could start writing
But if we did that, the @code{\score} section would get pretty
long, and it would be harder to understand what was happening. So
let's use variables instead. These were introduced at the end
-of the previous section, remember? So, adding a few notes, we
-now have a piece of real music:
+of the previous section, remember? To ensure the contents of the
+@code{text} variable are interpreted as lyrics we preface them with
+@code{\lyricmode}. Like @code{\addlyrics}, this switches the input
+mode to lyrics. Without that, LilyPond would try to interpret the
+contents as notes, which would generate errors. (Several other
+input modes are available, see @ruser{Input modes}.)
+
+So, adding a few notes and a bass clef for the left hand, we now
+have a piece of real music:
@lilypond[verbatim,quote,ragged-right]
melody = \relative c'' { r4 d8\noBeam g, c4 r }
}
@end lilypond
-
-Be careful about the difference between notes, which are introduced
-with @code{\relative} or which are directly included in a music
-expression, and lyrics, which are introduced with
-@code{\lyricmode}. These are essential to tell LilyPond
-to interpret the following content as music and text
-respectively.
-
When writing (or reading) a @code{\score} section, just take it
slowly and carefully. Start with the outer level, then work on
each smaller level. It also really helps to be strict with
@cindex bracket types
@cindex brackets, enclosing vs. marking
-You have already met a number of different types of bracket in
-writing the input file to LilyPond. These obey different rules
-which can be confusing at first. Before we explain the rules
-let's first review the different types of bracket.
+You have already met a number of different types of bracket and
+bracket-like constructs in writing the input file to LilyPond.
+These obey different rules which can be confusing at first.
+Let's first review the different types of brackets and bracket-like
+constructs.
@c attempt to force this onto a new page
@need 50
opposite order to the opening brackets. This @strong{is} a
requirement for the three types of bracket described by the word
@q{Encloses} in the table above -- they must nest properly. However,
-the remaining brackets, described with the word @q{Marks} in the table
-above together with ties and tuplets, do @strong{not} have to nest
-properly with any of the brackets. In fact, these are not brackets in
+the remaining bracket-like constructs, described with the word
+@q{Marks} in the table above together with ties and tuplets, do
+@strong{not} have to nest properly with any of the brackets or
+bracket-like constructs. In fact, these are not brackets in
the sense that they enclose something -- they are simply markers to
indicate where something starts and ends.
{ g8\( a b[ c b\) a] }
@end lilypond
-In general, different kinds of brackets, and those implied by
-tuplets, ties and grace notes, may be mixed freely.
-This example shows a beam extending into a tuplet (line 1),
-a slur extending into a tuplet (line 2),
-a beam and a slur extending into a tuplet, a tie crossing
-two tuplets, and a phrasing slur extending out of a tuplet
-(lines 3 and 4).
+In general, different kinds of brackets, bracket-like constructs,
+and those implied by tuplets, ties and grace notes, may be mixed
+freely. This example shows a beam extending into a tuplet (line 1),
+a slur extending into a tuplet (line 2), a beam and a slur
+extending into a tuplet, a tie crossing two tuplets, and a
+phrasing slur extending out of a tuplet (lines 3 and 4).
@lilypond[quote,verbatim,fragment,ragged-right]
{
@cindex creating contexts
@cindex contexts, creating
-There can be only one top level context: the @code{Score} context.
-This is created with the @code{\score} command, or, in simple scores,
-it is created automatically.
+In an input file a score block, introduced with a @code{\score}
+command, contains a single music expression and an associated
+output definition (either a @code{\layout} or a @code{\midi} block).
+The @code{Score} context is usually left to be created automatically
+when the interpretation of that music expression starts.
For scores with only one voice and one staff, the @code{Voice} and
-@code{Staff} contexts may be left to be created automatically, but for
-more complex scores it is necessary to create them by hand. The
-simplest command that does this is @code{\new}. It is prepended to a
-music expression, for example
+@code{Staff} contexts may also be left to be created automatically,
+but for more complex scores it is necessary to create them by hand.
+The simplest command that does this is @code{\new}. It is prepended
+to a music expression, for example
@example
\new @var{type} @var{music-expression}
@code{Voice}). This command creates a new context, and starts
interpreting the @var{music-expression} within that context.
-Note that there is no @code{\new Score} command;
-the single top-level @code{Score} context is introduced
-with @code{\score}.
+(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}.)
You have seen many practical examples which created new
@code{Staff} and @code{Voice} contexts in earlier sections, but
@cindex contexts, naming
@cindex naming contexts
-The @code{\new} command may also give a identifying name to the
+The @code{\new} command may also give an identifying name to the
context to distinguish it from other contexts of the same type,
@example
Where the @emph{ContextName} is usually @code{Score},
@code{Staff} or @code{Voice}. It may be omitted,
-in which case @code{Voice} is assumed.
+in which case the current context (typically @code{Voice}) is assumed.
The names of context properties consist of words joined
together with no hyphens or underscores, all except the
@code{##t} and @code{##f}, with two hash signs. A text property
should be enclosed in double quotation signs, as above, although we
shall see later that text can actually be specified in a much more
-general way by using the very powerful @code{markup} command.
+general way by using the very powerful @code{\markup} command.
@subsubheading Setting context properties with @code{\with}
@funindex with
@cindex context properties, setting with \with
-Context properties may also be set at the time the context is
-created. Sometimes this is a clearer way of specifying a
+The default value of context properties may be set at the time the
+context is created. Sometimes this is a clearer way of setting a
property value if it is to remain fixed for the duration of
the context. When a context is created with a @code{\new}
-command it may be followed immediately by a
-@code{\with @{ .. @}} block in which the property values are
-set. For example, if we wish to suppress the printing of
-extra naturals for the duration of a staff we would write:
+command it may be followed immediately by a @code{\with @{ .. @}}
+block in which the default property values are set. For example,
+if we wish to suppress the printing of extra naturals for the
+duration of a staff we would write:
@example
\new Staff \with @{ extraNatural = ##f @}
>>
@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'' {
+ gis ges aes ais
+ }
+ }
+ \new Staff {
+ \relative c'' {
+ gis ges aes ais
+ }
+ }
+ >>
+}
+@end lilypond
+
Properties set in this way may still be changed dynamically using
-@code{\set} and returned to their default value with @code{\unset}.
+@code{\set} and returned to the default value set in the
+@code{\with} block with @code{\unset}.
@cindex fontSize, default and setting
-The @code{fontSize} property is treated differently. If this is
-set in a @code{\with} clause it effectively resets the default
-value of the font size. If it is later changed with @code{\set},
-this new default value may be restored with the
+So if the @code{fontSize} property is set in a @code{\with} clause
+it sets the default value of the font size. If it is later changed
+with @code{\set}, this new default value may be restored with the
@code{\unset fontSize} command.
@subsubheading Setting context properties with @code{\context}
Start off with the template that seems closest to what you want to end
up with. Let's say that you want to write something for soprano and
-cello. In this case, we would start with @q{Notes and lyrics} (for the
+cello. In this case, we would start with the @q{Notes and lyrics} template (for the
soprano part).
@example
@end lilypond
However, you can also use these variables (also known as
-variables, macros, or (user-defined) command) for tweaks:
+macros, or user-defined commands) for tweaks:
@c TODO Avoid padtext - not needed with skylining
@lilypond[quote,verbatim,ragged-right]
@end lilypond
Using variables is also a good way to reduce work if the
-LilyPond input syntax changes (see @ref{Updating old input files}). If
+LilyPond input syntax changes (see
+@rprogram{Updating files with convert-ly}). If
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,