@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
@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}
* Soprano and cello::
* Four-part SATB vocal score::
* Building a score from scratch::
+* Saving typing with variables and functions::
+* Scores and parts::
@end menu
@node Soprano and cello
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
+@node Saving typing with variables and functions
+@subsection Saving typing with variables and functions
+
+@cindex variables
+@cindex variables
+
+By this point, you've seen this kind of thing:
+
+@lilypond[quote,verbatim,ragged-right]
+hornNotes = \relative c'' { c4 b dis c }
+\score {
+ {
+ \hornNotes
+ }
+}
+@end lilypond
+
+You may even realize that this could be useful in minimalist music:
+
+@lilypond[quote,verbatim,ragged-right]
+fragmentA = \relative c'' { a4 a8. b16 }
+fragmentB = \relative c'' { a8. gis16 ees4 }
+violin = \new Staff { \fragmentA \fragmentA \fragmentB \fragmentA }
+\score {
+ {
+ \violin
+ }
+}
+@end lilypond
+
+However, you can also use these variables (also known as
+macros, or user-defined commands) for tweaks:
+
+@c TODO Avoid padtext - not needed with skylining
+@lilypond[quote,verbatim,ragged-right]
+dolce = \markup{ \italic \bold dolce }
+padText = { \once \override TextScript #'padding = #5.0 }
+fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
+violin = \relative c'' {
+ \repeat volta 2 {
+ c4._\dolce b8 a8 g a b |
+ \padText
+ c4.^"hi there!" d8 e' f g d |
+ c,4.\fthenp b8 c4 c-. |
+ }
+}
+\score {
+ {
+ \violin
+ }
+\layout{ragged-right=##t}
+}
+@end lilypond
+
+These variables are obviously useful for saving
+typing. But they're worth considering even if you
+only use them once -- they reduce complexity. Let's
+look at the previous example without any
+variables. It's a lot harder to read, especially
+the last line.
+
+@example
+violin = \relative c'' @{
+ \repeat volta 2 @{
+ c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
+ \once \override TextScript #'padding = #5.0
+ c4.^"hi there!" d8 e' f g d |
+ c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
+ \hspace #0.1 \dynamic p @} b8 c4 c-. |
+ @}
+@}
+@end example
+
+@c TODO Replace the following with a better example -td
+@c Skylining handles this correctly without padText
+
+So far we've seen static substitution -- when LilyPond
+sees @code{\padText}, it replaces it with the stuff that
+we've defined it to be (ie the stuff to the right of
+@code{padtext=}).
+
+LilyPond can handle non-static substitution, too (you
+can think of these as functions).
+
+@lilypond[quote,verbatim,ragged-right]
+padText =
+#(define-music-function (parser location padding) (number?)
+ #{
+ \once \override TextScript #'padding = #$padding
+ #})
+
+\relative c''' {
+ c4^"piu mosso" b a b
+ \padText #1.8
+ c4^"piu mosso" d e f
+ \padText #2.6
+ c4^"piu mosso" fis a g
+}
+@end lilypond
+
+Using variables is also a good way to reduce work if the
+LilyPond input syntax changes (see @rprogram{Updating old input files}). 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,
+instead of making changes throughout every @code{.ly} file.
+
+
+@node Scores and parts
+@subsection Scores and parts
+
+In orchestral music, all notes are printed twice. Once in a part for
+the musicians, and once in a full score for the conductor. Variables can
+be used to avoid double work. The music is entered once, and stored in
+a variable. The contents of that variable is then used to generate
+both the part and the full score.
+
+It is convenient to define the notes in a special file. For example,
+suppose that the file @file{horn-music.ly} contains the following part
+of a horn/@/bassoon duo
+
+@example
+hornNotes = \relative c @{
+ \time 2/4
+ r4 f8 a cis4 f e d
+@}
+@end example
+
+@noindent
+Then, an individual part is made by putting the following in a file
+
+@example
+\include "horn-music.ly"
+\header @{
+ instrument = "Horn in F"
+@}
+
+@{
+ \transpose f c' \hornNotes
+@}
+@end example
+
+The line
+
+@example
+\include "horn-music.ly"
+@end example
+
+@noindent
+substitutes the contents of @file{horn-music.ly} at this position in
+the file, so @code{hornNotes} is defined afterwards. The command
+@code{\transpose f@tie{}c'} indicates that the argument, being
+@code{\hornNotes}, should be transposed by a fifth upwards. Sounding
+@code{f} is denoted by notated @code{c'}, which corresponds with the
+tuning of a normal French Horn in@tie{}F. The transposition can be seen
+in the following output
+
+@lilypond[quote,ragged-right]
+\transpose f c' \relative c {
+ \time 2/4
+ r4 f8 a cis4 f e d
+}
+@end lilypond
+
+In ensemble pieces, one of the voices often does not play for many
+measures. This is denoted by a special rest, the multi-measure
+rest. It is entered with a capital @code{R} followed by a duration
+(@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
+etc.). By multiplying the
+duration, longer rests can be constructed. For example, this rest
+takes 3@tie{}measures in 2/4 time
+
+@example
+R2*3
+@end example
+
+When printing the part, multi-rests
+must be condensed. This is done by setting a run-time variable
+
+@example
+\set Score.skipBars = ##t
+@end example
+
+@noindent
+This command sets the property @code{skipBars} in the
+@code{Score} context to true (@code{##t}). Prepending the rest and
+this option to the music above, leads to the following result
+
+@lilypond[quote,ragged-right]
+\transpose f c' \relative c {
+ \time 2/4
+ \set Score.skipBars = ##t
+ R2*3
+ r4 f8 a cis4 f e d
+}
+@end lilypond
+
+
+The score is made by combining all of the music together. Assuming
+that the other voice is in @code{bassoonNotes} in the file
+@file{bassoon-music.ly}, a score is made with
+
+@example
+\include "bassoon-music.ly"
+\include "horn-music.ly"
+
+<<
+ \new Staff \hornNotes
+ \new Staff \bassoonNotes
+>>
+@end example
+
+@noindent
+leading to
+
+@lilypond[quote,ragged-right]
+\relative c <<
+ \new Staff {
+ \time 2/4 R2*3
+ r4 f8 a cis4 f e d
+ }
+ \new Staff {
+ \clef bass
+ r4 d,8 f | gis4 c | b bes |
+ a8 e f4 | g d | gis f
+ }
+>>
+@end lilypond
+
+
+
projects / lilypond.git / blobdiff