version that you are working on. See TRANSLATION for details.
@end ignore
+@c \version "2.12.0"
+
@node Fundamental concepts
@chapter Fundamental concepts
examples this works well, but for more complex examples, especially
when additional commands are used, the implicit creation of contexts
can give surprising results, maybe creating extra unwanted staves.
-The way to create contexts explicitly is explained in
+The way to create contexts explicitly is explained in
@ref{Contexts and engravers}.
@warning{When entering more than a few lines of music it is
@example
@{
- \new GrandStaff <<
+ \new StaffGroup <<
@var{...insert the whole score of a Wagner opera in here...}
>>
@}
@ruser{File structure}.
-
@seealso
-
For a complete definition of the input format, see
@ruser{File structure}.
+
@node Score is a (single) compound musical expression
@subsection Score is a (single) compound musical expression
@example
\score @{
@{ % this brace begins the overall compound music expression
- \new GrandStaff <<
+ \new StaffGroup <<
@var{...insert the whole score of a Wagner opera in here...}
>>
@} % this brace ends the overall compound music expression
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
-@code{GrandStaff} for this ensemble, which simply groups a number
-of staves together with a brace at the left, so we shall remove
+@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.
@example
indentation -- make sure that each item on the same level starts
on the same horizontal position in your text editor.
-@seealso
+@seealso
Notation Reference: @ruser{Structure of a score}.
+
@node Nesting music expressions
@subsection Nesting music expressions
<<
{ f c c }
\new Staff \with {
- alignAboveContext = "main" }
+ alignAboveContext = #"main" }
{ f8 f c }
>>
r4 |
placed above the staff called @qq{main} instead of the default
position which is below.
-@seealso
+@seealso
Ossia are often written without clef and without
time signature and are usually in a smaller font.
These require further commands which
tuplets written as @code{\times x/y @{..@}}, and grace notes
written as @code{\grace@{..@}}.
-Outside LilyPond, the conventional use of brackets requires
-the different types to be properly nested, like this,
-@code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
-encountered in exactly the 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 sense that they enclose something -- they are simply
-markers to indicate where something starts and ends.
+Outside LilyPond, the conventional use of brackets requires the
+different types to be properly nested, like this, @code{<< [ @{ ( .. )
+@} ] >>}, with the closing brackets being encountered in exactly the
+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 sense that they enclose something -- they are simply markers to
+indicate where something starts and ends.
So, for example, a phrasing slur can start before a manually
inserted beam and end before the end of the beam -- not very
Voices are sometimes called @q{layers} in other notation
packages.
-In fact, a Voice layer or context is the only one which can
-contain music. If a Voice context is not explicitly declared
-one is created automatically, as we saw at the beginning of
-this chapter. Some instruments such as an
-Oboe can play only one note at a time. Music written for
-such instruments is monophonic and requires just a single
-voice. Instruments which can play more than one note at a
-time like the piano will often require multiple voices to
-encode the different concurrent notes and rhythms they are
-capable of playing.
+In fact, a Voice layer or context is the only one which can contain
+music. If a Voice context is not explicitly declared one is created
+automatically, as we saw at the beginning of this chapter. Some
+instruments such as an Oboe can play only one note at a time. Music
+written for such instruments is monophonic and requires just a single
+voice. Instruments which can play more than one note at a time like
+the piano will often require multiple voices to encode the different
+concurrent notes and rhythms they are capable of playing.
A single voice can contain many notes in a chord, of course,
so when exactly are multiple voices needed? Look first at
Voice one is set to red diamonds, voice two to blue triangles,
voice three to green crossed circles, and voice four (not used
here) to magenta crosses; @code{\voiceNeutralStyle} (also not
-used here) reverts the style back to the default.
+used here) reverts the style back to the default.
We shall see later how commands like these may be created by the
user.
See @ref{Visibility and color of objects} and
later section --- see the @code{force-hshift} property in @ref{Fixing
overlapping notation}.
-@seealso
+@seealso
Notation Reference: @ruser{Multiple voices}.
have no shift or the same shift specified, the error message
@qq{Too many clashing note columns} will be produced.
-@seealso
+@seealso
Notation Reference: @ruser{Multiple voices}.
One two three four five six
}
\score {
- \new Choirstaff {
+ \new ChoirStaff {
\new Staff <<
\new Voice = "verse" {
\versenotes \break
}
@end lilypond
-@seealso
+@seealso
Notation Reference: @ruser{Vocal music}.
to a single staff, while a bar line must be synchronized across
the entire score.
-Within LilyPond, these rules and bits of information are grouped
-in @emph{Contexts}. We have already met the
-@code{Voice} context.
-Others are the @code{Staff} and @code{Score} contexts.
-Contexts are hierarchical to reflect the hierarchical nature of
-a musical score.
-For example: a @code{Staff} context can contain many
-@code{Voice} contexts, and a @code{Score} context can
-contain many @code{Staff} contexts.
+Within LilyPond, these rules and bits of information are grouped in
+@emph{Contexts}. We have already met the @code{Voice} context.
+Others are the @code{Staff} and @code{Score} contexts. Contexts are
+hierarchical to reflect the hierarchical nature of a musical score.
+For example: a @code{Staff} context can contain many @code{Voice}
+contexts, and a @code{Score} context can contain many @code{Staff}
+contexts.
@quotation
@sourceimage{context-example,5cm,,}
preceding word with no hyphen or underscore, e.g.,
@code{GregorianTranscriptionStaff}.
-@seealso
+@seealso
Notation Reference: @ruser{Contexts explained}.
@subsection Creating contexts
@funindex \new
+@funindex new
@cindex new contexts
@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.
+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.
-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
+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
@example
\new @var{type} @var{music-expression}
Note the distinction between the name of the context type,
@code{Staff}, @code{Voice}, etc, and the identifying name of a
-particular instance of that type, which can be any sequence of letters
-invented by the user. Digits and spaces can also be used in the
+particular instance of that type, which can be any sequence of letters
+invented by the user. Digits and spaces can also be used in the
identifying name, but then it has to be placed in quotes,
i.e. @code{\new Staff = "MyStaff 1" @var{music-expression}}.
The identifying name is used to
refer back to that particular instance of a context. We saw this in
use in the section on lyrics, see @ref{Voices and vocals}.
-@seealso
+@seealso
Notation Reference: @ruser{Creating contexts}.
more than a few, and for simple scores you do not need to know
about any.
-Engravers live and operate in Contexts.
-Engravers such as the @code{Metronome_mark_engraver}, whose
-action and output apply to the score as a whole, operate in
-the highest level context -- the @code{Score} context.
+Engravers live and operate in Contexts. Engravers such as the
+@code{Metronome_mark_engraver}, whose action and output apply to the
+score as a whole, operate in the highest level context -- the
+@code{Score} context.
The @code{Clef_engraver} and @code{Key_engraver} are to be
found in every @code{Staff} Context, as different staves may require
We shall see later how the output of LilyPond can be changed
by modifying the action of Engravers.
-@seealso
+@seealso
Internals reference: @rinternals{Engravers and Performers}.
@cindex context properties, modifying
@cindex modifying context properties
@funindex \set
+@funindex set
@funindex \unset
+@funindex unset
Contexts are responsible for holding the values of a number of
context @emph{properties}. Many of them can be changed to
in the @code{\set} statement. So when a Boolean is being
entered you need to code two hash signs, e.g., @code{##t}.
+@cindex properties operating in contexts
+@cindex setting properties within contexts
+
Before we can set any of these properties we need to know
in which context they operate. Sometimes this is obvious,
but occasionally it can be tricky. If the wrong context
@unnumberedsubsubsec Setting context properties with @code{\with}
@funindex \with
+@funindex with
@cindex context properties, setting with \with
Context properties may also be set at the time the context is
Properties set in this way may still be changed dynamically using
@code{\set} and returned to their default value 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},
@unnumberedsubsubsec Setting context properties with @code{\context}
+@cindex context properties, setting with \context
+@funindex \context
+@funindex context
+
The values of context properties may be set in @emph{all} contexts
of a particular type, such as all @code{Staff} contexts, with a single
command. The context type is identified by using its
type name, like @code{Staff}, prefixed by a back-slash: @code{\Staff}.
-The statement which sets the property value is the same as that in a
+The statement which sets the property value is the same as that in a
@code{\with} block, introduced above. It is placed in a
@code{\context} block within a @code{\layout} block. Each
@code{\context} block will affect all contexts of the type specified
instances of contexts by statements in a @code{\with} block, and by
@code{\set} commands embedded in music statements.
-@seealso
+@seealso
Notation Reference:
@ruser{Changing context default settings}.
@c FIXME
@subsection Adding and removing engravers
@cindex engravers, adding
+@cindex adding engravers
@cindex engravers, removing
+@cindex removing engravers
@funindex \consists
+@funindex consists
@funindex \remove
+@funindex remove
We have seen that contexts each contain several engravers, each
of which is responsible for producing a particular part of the
@subsubheading Changing all contexts of the same type
@funindex \layout
+@funindex layout
The examples above show how to remove or add engravers to
individual contexts. It is also possible to remove or add
@code{\set} command in a @code{\context} block in the
same way.
-@seealso
+@seealso
Notation Reference: @ruser{Modifying context plug-ins},
@ruser{Changing context default settings}.
@subsection Soprano and cello
@cindex template, modifying
+@cindex modifying templates
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
}
@end lilypond
-@seealso
+@seealso
The starting templates can be found in the @q{Templates} appendix,
see @ref{Single staff}.
<< % combine ChoirStaff and PianoStaff in parallel
\new ChoirStaff <<
\new Staff = "sopranos" <<
- \set Staff.instrumentName = "Soprano"
+ \set Staff.instrumentName = #"Soprano"
\new Voice = "sopranos" { \global \sopranoMusic }
>>
\new Lyrics \lyricsto "sopranos" { \sopranoWords }
\new Staff = "altos" <<
- \set Staff.instrumentName = "Alto"
+ \set Staff.instrumentName = #"Alto"
\new Voice = "altos" { \global \altoMusic }
>>
\new Lyrics \lyricsto "altos" { \altoWords }
\new Staff = "tenors" <<
- \set Staff.instrumentName = "Tenor"
+ \set Staff.instrumentName = #"Tenor"
\new Voice = "tenors" { \global \tenorMusic }
>>
\new Lyrics \lyricsto "tenors" { \tenorWords }
\new Staff = "basses" <<
- \set Staff.instrumentName = "Bass"
+ \set Staff.instrumentName = #"Bass"
\new Voice = "basses" { \global \bassMusic }
>>
\new Lyrics \lyricsto "basses" { \bassWords }
>> % end ChoirStaff
\new PianoStaff <<
- \set PianoStaff.instrumentName = "Piano"
+ \set PianoStaff.instrumentName = #"Piano"
\new Staff = "upper" \upper
\new Staff = "lower" \lower
>>
The variables holding the music and words for the vocal parts are
fine, but we shall need to add variables for the piano reduction.
-The order in which the contexts appear in the ChoirStaff of
-the template do not correspond with the order in the vocal
-score shown above. We need to rearrange them so there are
-four staves with the words written directly underneath the
-notes for each part.
-All the voices should be @code{\voiceOne}, which is
-the default, so the @code{\voiceXXX} commands should be removed.
-We also need to specify the tenor clef for the tenors.
-The way in which lyrics are specified in the template has not yet
-been encountered so we need to use the method with which we are
-familiar. We should also add the names of each staff.
+The order in which the contexts appear in the ChoirStaff of the
+template do not correspond with the order in the vocal score shown
+above. We need to rearrange them so there are four staves with the
+words written directly underneath the notes for each part. All the
+voices should be @code{\voiceOne}, which is the default, so the
+@code{\voiceXXX} commands should be removed. We also need to specify
+the tenor clef for the tenors. The way in which lyrics are specified
+in the template has not yet been encountered so we need to use the
+method with which we are familiar. We should also add the names of
+each staff.
Doing this gives for our ChoirStaff:
@example
\new ChoirStaff <<
\new Staff = "sopranos" <<
- \set Staff.instrumentName = "Soprano"
+ \set Staff.instrumentName = #"Soprano"
\new Voice = "sopranos" @{ \global \sopranoMusic @}
>>
\new Lyrics \lyricsto "sopranos" @{ \sopranoWords @}
\new Staff = "altos" <<
- \set Staff.instrumentName = "Alto"
+ \set Staff.instrumentName = #"Alto"
\new Voice = "altos" @{ \global \altoMusic @}
>>
\new Lyrics \lyricsto "altos" @{ \altoWords @}
\new Staff = "tenors" <<
- \set Staff.instrumentName = "Tenor"
+ \set Staff.instrumentName = #"Tenor"
\new Voice = "tenors" @{ \global \tenorMusic @}
>>
\new Lyrics \lyricsto "tenors" @{ \tenorWords @}
\new Staff = "basses" <<
- \set Staff.instrumentName = "Bass"
+ \set Staff.instrumentName = #"Bass"
\new Voice = "basses" @{ \global \bassMusic @}
>>
\new Lyrics \lyricsto "basses" @{ \bassWords @}
@example
\new PianoStaff <<
- \set PianoStaff.instrumentName = "Piano "
+ \set PianoStaff.instrumentName = #"Piano "
\new Staff = "upper" \upper
\new Staff = "lower" \lower
>>
>> % end ChoirStaff
\new PianoStaff <<
- \set PianoStaff.instrumentName = "Piano"
+ \set PianoStaff.instrumentName = #"Piano"
\new Staff = "upper" \upper
\new Staff = "lower" \lower
>>
<< % combine ChoirStaff and PianoStaff in parallel
\new ChoirStaff <<
\new Staff = "sopranos" <<
- \set Staff.instrumentName = "Soprano"
+ \set Staff.instrumentName = #"Soprano"
\new Voice = "sopranos" { \global \sopranoMusic }
>>
\new Lyrics \lyricsto "sopranos" { \sopranoWords }
\new Staff = "altos" <<
- \set Staff.instrumentName = "Alto"
+ \set Staff.instrumentName = #"Alto"
\new Voice = "altos" { \global \altoMusic }
>>
\new Lyrics \lyricsto "altos" { \altoWords }
\new Staff = "tenors" <<
- \set Staff.instrumentName = "Tenor"
+ \set Staff.instrumentName = #"Tenor"
\new Voice = "tenors" { \global \tenorMusic }
>>
\new Lyrics \lyricsto "tenors" { \tenorWords }
\new Staff = "basses" <<
- \set Staff.instrumentName = "Bass"
+ \set Staff.instrumentName = #"Bass"
\new Voice = "basses" { \global \bassMusic }
>>
\new Lyrics \lyricsto "basses" { \bassWords }
>> % end ChoirStaff
\new PianoStaff <<
- \set PianoStaff.instrumentName = "Piano "
+ \set PianoStaff.instrumentName = #"Piano "
\new Staff = "upper" \upper
\new Staff = "lower" \lower
>>
@subsection Building a score from scratch
@cindex template, writing your own
+@cindex example of writing a score
+@cindex writing a score, example
+@cindex score, example of writing
After gaining some facility with writing LilyPond code, you
may find that it is easier to build a score from scratch
projects / lilypond.git / blobdiff