version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.51"
+@c \version "2.11.61"
@node Fundamental concepts
@chapter Fundamental concepts
@example
\version @w{"@version{}"}
+\header @{ @}
\score @{
@var{...compound music expression...} % all the music goes here!
- \header @{ @}
\layout @{ @}
\midi @{ @}
@}
example serves as a useful starting place.
@funindex \book
+@funindex book
@funindex \score
+@funindex score
@cindex book
@cindex score
was wrapped up inside the commands shown above.
@cindex implicit contexts
+@cindex contexts, implicit
@strong{A word of warning!} Many of the examples in the LilyPond
documentation will omit the @code{\new Staff} and @code{\new Voice}
@end example
@funindex \header
+@funindex header
@funindex \layout
+@funindex layout
@funindex \midi
+@funindex midi
@cindex header
@cindex layout
@cindex midi
@noindent
-Note that these three commands -- @code{\header}, @code{\layout}
-and @code{\midi} -- are special: unlike all other commands which
-begin with a backward slash (@code{\}) they are @emph{not} music
-expressions and are not part of any music expression.
-So they may be placed inside a @code{\score} block
-or outside it. In fact, these commands are commonly placed
-outside the @code{\score} block -- for example, @code{\header}
-is often placed above the @code{\score} command because headers
-naturally appear at the top of a score. That's just another
-shorthand that LilyPond accepts.
+Note that these three commands -- @code{\header}, @code{\layout} and
+@code{\midi} -- are special: unlike many other commands which begin
+with a backward slash (@code{\}) they are @emph{not} music expressions
+and are not part of any music expression. So they may be placed
+inside a @code{\score} block or outside it. In fact, these commands
+are commonly placed outside the @code{\score} block -- for example,
+@code{\header} is often placed above the @code{\score} command, as the
+example at the beginning of this section shows.
Two more commands you have not previously seen are
@code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
shown they will cause LilyPond to produce a printed output and a
MIDI output respectively. They are described fully in the
-Notation Reference -- @ruser{Score layout} and
+Notation Reference -- @ruser{Score layout}, and
@ruser{Creating MIDI files}.
@cindex scores, multiple
+@cindex book block, implicit
+@cindex implicit book block
+@funindex \book
+@funindex book
You may code multiple @code{\score} blocks. Each will be
treated as a separate score, but they will be all combined into
In summary:
Every @code{\book} block creates a separate output file (e.g., a
-pdf file). If you haven't explicitly added one, LilyPond wraps
+PDF file). If you haven't explicitly added one, LilyPond wraps
your entire input code in a @code{\book} block implicitly.
Every @code{\score} block is a separate chunk of music within a
@code{\book} block.
+@cindex layout block, effect of location
+
Every @code{\layout} block affects the @code{\score} or
@code{\book} block in which it appears -- i.e., a @code{\layout}
block inside a @code{\score} block affects only that @code{\score}
(and thus in a @code{\book} block, either explicitly or
implicitly) will affect every @code{\score} in that @code{\book}.
-Every @code{\context} block will affect the named context (e.g.,
-@code{\StaffGroup}) throughout the block (@code{\score} or
-@code{\book}) in which it appears.
-
For details see @ruser{Multiple scores in a book}.
@cindex variables
@subsection Score is a (single) compound musical expression
@funindex \score
+@funindex score
@cindex score
-@cindex Compound music expression
-@cindex Music expression, compound
+@cindex contents of a score block
+@cindex score block, contents of
+@cindex compound music expression
+@cindex music expression, compound
We saw the general organization of LilyPond input files in the
-previous section, @ref{How LilyPond input files work}. But we seemed to
-skip over the most important part: how do we figure out what to
-write after @code{\score}?
+previous section, @ref{Introduction to the LilyPond file structure}.
+But we seemed to skip over the most important part: how do we figure
+out what to write after @code{\score}?
We didn't skip over it at all. The big mystery is simply that
there @emph{is} no mystery. This line explains it all:
@noindent
To understand what is meant by a music expression and a compound
-music expression you may find it useful to review
+music expression, you may find it useful to review the tutorial,
@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
<<
\new Staff = "singer" <<
>>
- \new PianoStaff = piano <<
+ \new PianoStaff = "piano" <<
>>
>>
\layout @{ @}
@}
@end example
-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! However, the
-@code{<< ... >>} construct is not really necessary for the Singer
-staff, as it contains only one music expression, but Staves often
-do require simultaneous Voices within them, so using
-@code{<< ... >>}
-rather than braces is a good habit to adopt. We'll add some real
-music later; for now let's just put in some dummy notes and lyrics.
+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.
@lilypond[verbatim,quote,ragged-right]
\score {
(left hand).
At this stage, we could start filling in notes. Inside the curly
-braces next to @code{\new Voice = vocal}, we could start writing
+braces next to @code{\new Voice = "vocal"}, we could start writing
@example
\relative c'' @{
Be careful about the difference between notes, which are introduced
-with @code{\relative}, and lyrics, which are introduced with
+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 layer, then work on
-each smaller layer. It also really helps to be strict with
-indentation -- make sure that each item on the same layer starts
+slowly and carefully. Start with the outer level, then work on
+each smaller level. It also really helps to be strict with
+indentation -- make sure that each item on the same level starts
on the same horizontal position in your text editor.
+@seealso
+
+Notation Reference: @ruser{Structure of a score}.
@node Nesting music expressions
@subsection Nesting music expressions
@cindex staves, temporary
+@cindex temporary staves
@cindex ossias
-It is not essential to declare all staves at the beginning;
-they may be introduced temporarily at any point. This is
-particularly useful for creating ossia sections
-(see @rglos{ossia}). Here is a simple example showing how
-to introduce a new staff temporarily for the duration of
-three notes:
+It is not essential to declare all staves at the beginning; they may
+be introduced temporarily at any point. This is particularly useful
+for creating ossia sections -- see @rglos{ossia}. Here is a simple
+example showing how to introduce a new staff temporarily for the
+duration of three notes:
@lilypond[verbatim,quote,ragged-right]
\new Staff {
as follows:
@lilypond[verbatim,quote,ragged-right]
-\new Staff ="main" {
+\new Staff = "main" {
\relative g' {
r4 g8 g c4 c8 d |
e4 r8
placed above the staff called @qq{main} instead of the default
position which is below.
+@seealso
+
Ossia are often written without clef and without
time signature and are usually in a smaller font.
These require further commands which
-have not yet been introduced. See @ref{Size of objects}
+have not yet been introduced. See @ref{Size of objects},
+and @ruser{Ossia staves}.
+
@node On the un-nestedness of brackets and ties
@subsection On the un-nestedness of brackets and ties
@cindex brackets, nesting
+@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
@item @code{< .. >}
@tab Encloses the notes of a chord
@item @code{<< .. >>}
- @tab Encloses concurrent or simultaneous sections
+ @tab Encloses simultaneous music expressions
@item @code{( .. )}
@tab Marks the start and end of a slur
@item @code{\( .. \)}
- @tab Marks the start and end of a phrase mark
+ @tab Marks the start and end of a phrasing slur
@item @code{[ .. ]}
@tab Marks the start and end of a manual beam
@end multitable
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
@cindex polyphony
@cindex layers
@cindex multiple voices
+@cindex voices, multiple
@cindex Voice context
@cindex context, Voice
@cindex simultaneous music
+@cindex music, simultaneous
@cindex concurrent music
+@cindex music, concurrent
+@cindex voices vs. chords
+@cindex chords vs. voices
The lowest, most fundamental or innermost layers in a LilyPond
score are called @q{Voice contexts} or just @q{Voices} for short.
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
different durations: the quarter-note D and the eighth-note
F-sharp. How are these to be coded? They cannot be written as
a chord because all the notes in a chord must have the same
-duration. And they cannot be written as two separate notes
+duration. And they cannot be written as two sequential notes
as they need to start at the same time. This is when two
voices are required.
@end lilypond
+@cindex voices, naming
+@cindex voices crossing brackets
+@cindex slurs crossing brackets
+@cindex ties crossing brackest
+
This example has just two voices, but the same construct may be
used to encode three or more voices by adding more back-slash
separators.
See @ref{Visibility and color of objects} and
@ref{Using variables for tweaks}.
+@cindex polyphony and relative note entry
+@cindex relative note entry and polyphony
+
Polyphony does not change the relationship of notes within a
@code{\relative @{ @}} block. Each note is still calculated
relative to the note immediately preceding it, or to the first
@code{noteB} is relative to @code{noteA} @*
@code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
@code{noteD} is relative to @code{noteB}, not @code{noteA} or
-@code{noteC}. @*
-@code{noteE} is relative to @code{noteD}, not @code{noteA}
+@code{noteC}; @*
+@code{noteE} is relative to @code{noteD}, not @code{noteA}.
An alternative way, which may be clearer if the notes in the
voices are widely separated, is to place a @code{\relative}
\relative c' @{ noteE ... @}
@end example
-Let us finally analyze the voices in a more complex piece of
-music. Here are
-the notes from the first two bars of the second of Chopin's
-Deux Nocturnes, Op 32. This example will be used at later
-stages in this and the next chapter to illustrate several
-techniques for producing notation, so please ignore for now
-anything in the underlying code which looks mysterious and
-concentrate just on the music and the voices -- the
-complications will all be explained in later sections.
+Let us finally analyze the voices in a more complex piece of music.
+Here are the notes from the first two bars of the second of Chopin's
+Deux Nocturnes, Op 32. This example will be used at later stages in
+this and the next chapter to illustrate several techniques for
+producing notation, so please ignore for now anything in the
+underlying code which looks mysterious and concentrate just on the
+music and the voices -- the complications will all be explained in
+later sections.
@c The following should appear as music without code
@lilypond[quote,ragged-right]
}
@end lilypond
-The direction of the stems is often used to indicate the
-continuity of two simultaneous melodic lines. Here the
-stems of the highest notes are all pointing up and the
-stems of the lower notes are all pointing down.
-This is the first indication that more than one voice
-is required.
+The direction of the stems is often used to indicate the continuity of
+two simultaneous melodic lines. Here the stems of the highest notes
+are all pointing up and the stems of the lower notes are all pointing
+down. This is the first indication that more than one voice is
+required.
But the real need for multiple voices arises when notes
which start at the same time have different durations.
@end lilypond
@cindex stem down
+@cindex voices and stem directions
+@cindex stem directions and voices
@cindex stem up
The stem directions are automatically assigned with the
@end lilypond
@noindent
-We see that this fixes the stem direction, but exposes a
-problem sometimes encountered with multiple voices -- the
-stems of the notes in one voice can collide with the note heads
-in other voices. In laying out the notes, LilyPond allows the
-notes or chords from two voices to occupy the same vertical
-note column provided the stems are in opposite directions, but
-the notes from the third and fourth voices are displaced to 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 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 force-hshift property in @ref{Fixing overlapping
-notation} )
+We see that this fixes the stem direction, but exposes a problem
+sometimes encountered with multiple voices -- the stems of the notes
+in one voice can collide with the note heads in other voices. In
+laying out the notes, LilyPond allows the notes or chords from two
+voices to occupy the same vertical note column provided the stems are
+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
+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}.
+
+@seealso
+
+Notation Reference: @ruser{Multiple voices}.
+
@node Explicitly instantiating voices
@subsection Explicitly instantiating voices
@funindex \voiceOne
+@funindex voiceOne
@funindex \voiceTwo
+@funindex voiceTwo
@funindex \voiceThree
+@funindex voiceThree
@funindex \voiceFour
+@funindex voiceFour
@funindex \oneVoice
+@funindex oneVoice
@funindex \new Voice
-@cindex Voice contexts, creating
+@cindex voice contexts, creating
Voice contexts can also be created manually
inside a @code{<< >>} block to create polyphonic music, using
>>
@end lilypond
+@cindex voices, reverting to single
+@cindex reverting to a single voice
+
The @code{\voiceXXX} commands set the direction of stems, slurs,
ties, articulations, text annotations, augmentation dots of dotted
notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
@cindex nesting music expressions
@cindex nesting simultaneous constructs
-
+@cindex nesting voices
@cindex voices, temporary
@cindex voices, nesting
@subsubheading Note columns
@cindex note column
+@cindex note collisions
+@cindex collisions, notes
@cindex shift commands
@funindex \shiftOff
+@funindex shiftOff
@funindex \shiftOn
+@funindex shiftOn
@funindex \shiftOnn
+@funindex shiftOnn
@funindex \shiftOnnn
+@funindex shiftOnnn
Closely spaced notes in a chord, or notes occurring at the same
time in different voices, are arranged in two, occasionally more,
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
+When a shift is applied, voices one and three are shifted to
the right and voices two and four to the left.
@code{\shiftOnn} and @code{\shiftOnnn} define further shift
have no shift or the same shift specified, the error message
@qq{Too many clashing note columns} will be produced.
+@seealso
+
+Notation Reference: @ruser{Multiple voices}.
+
+
@node Voices and vocals
@subsection Voices and vocals
@funindex \new Lyrics
@funindex \lyricsto
+@funindex lyricsto
+@funindex Lyrics
@cindex Lyrics context, creating
@cindex lyrics, linking to voice
@cindex lyrics and beaming
@cindex beaming and lyrics
@funindex \autoBeamOff
+@funindex autoBeamOff
The automatic beaming which LilyPond uses by default works well
for instrumental music, but not so well for music with lyrics,
@code{\autoBeamOff} to turn off the automatic beaming.
@funindex \new ChoirStaff
+@funindex ChoirStaff
@funindex \lyricmode
+@funindex lyricmode
@cindex vocal score structure
+@cindex choir staff
Let us reuse the earlier example from Judas Maccabæus to
illustrate this more flexible technique. We first recast
}
@end lilypond
-This is the basic structure of all vocal scores. More staves may
-be added as required, more voices may be added to the staves,
-more verses may be added to the lyrics,
-and the variables containing the music can easily be placed
-in separate files should they become too long.
+This is the basic structure of all vocal scores. More staves may be
+added as required, more voices may be added to the staves, more verses
+may be added to the lyrics, and the variables containing the music can
+easily be placed in separate files should they become too long.
@cindex hymn structure
+@cindex SATB structure
+@cindex vocal scores with multiple verses
+@cindex multiple vocal verses
+@cindex verses, multiple vocal
-Here is a example of the first line of a hymn with four
+Here is an example of the first line of a hymn with four
verses, set for SATB. In this case the words for all four
parts are the same. Note how we use variables to separate the
music notation and words from the staff structure. See too
@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,
}
@end lilypond
+@seealso
+
+Notation Reference: @ruser{Vocal music}.
+
+
@node Contexts and engravers
@section Contexts and engravers
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
+
+Notation Reference: @ruser{Contexts explained}.
+
+
@node Creating contexts
@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}
@end example
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.
-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 in @ref{Voices and vocals}.
+@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
+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
+
+Notation Reference: @ruser{Creating contexts}.
@node Engravers explained
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 applies 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 Staff Context, as different staves may require
+found in every @code{Staff} Context, as different staves may require
different clefs and keys.
The @code{Note_heads_engraver} and @code{Stem_engraver} live
@tab Engraves clefs
@item Completion_heads_engraver
@tab Splits notes which cross bar lines
-@item Dynamic_engraver
+@c The old Dynamic_engraver is deprecated. -jm
+@item New_dynamic_engraver
@tab Creates hairpins and dynamic texts
@item Forbid_line_break_engraver
@tab Prevents line breaks if a musical element is still active
We shall see later how the output of LilyPond can be changed
by modifying the action of Engravers.
+@seealso
+
+Internals reference: @rinternals{Engravers and Performers}.
+
@node Modifying context properties
@subsection Modifying context properties
@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
is specified, no error message is produced, but the expected
action will not take place. For example, the
-@code{instrumentName} clearly lives in the Staff context, since
+@code{instrumentName} clearly lives in the @code{Staff} context, since
it is the staff that is to be named.
In this example the first staff is labelled, but not the second,
because we omitted the context name.
>>
@end lilypond
-Remember the default context name is Voice, so the second
+Remember the default context name is @code{Voice}, so the second
@code{\set} command set the property @code{instrumentName} in the
-Voice context to @qq{Alto}, but as LilyPond does not look
+@code{Voice} context to @qq{Alto}, but as LilyPond does not look
for any such property in the @code{Voice} context, no
further action took place. This is not an error, and no error
message is logged in the log file.
-Similarly, if the property name is mis-spelt no error message
-is produced, and clearly the expected action cannot be performed.
-If fact, you can set any (fictitious) @q{property} using any
-name you like in any context that exists by using the
-@code{\set} command. But if the name is not
-known to LilyPond it will not cause any action to be taken.
-This is one of the reasons why it is highly recommended to
-use a context-sensitive editor with syntax highlighting for
-editing LilyPond input files, such as Vim, Jedit, ConTEXT or Emacs,
-since unknown property names will be highlighted differently.
+Similarly, if the property name is mis-spelt no error message is
+produced, and clearly the expected action cannot be performed. In
+fact, you can set any (fictitious) @q{property} using any name you
+like in any context that exists by using the @code{\set} command. But
+if the name is not known to LilyPond it will not cause any action to
+be taken. Some text editors with special support for LilyPond input
+files document property names with bullets when you hover them with
+the mouse, like JEdit with LilyPondTool, or highlight unknown property
+names differently, like ConTEXT. If you do not use an editor with
+such features, it is recommended to check the property name in the
+Internals Reference: see @rinternals{Tunable context properties}, or
+@rinternals{Contexts}.
The @code{instrumentName} property will take effect only
if it is set in the @code{Staff} context, but
a b
@end lilypond
-We have now seen how to set the values of several different
-types of property. Note that integers and numbers are always
-preceded by a hash sign, @code{#}, while a true or false value
-is specified by ##t and ##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.
+We have now seen how to set the values of several different types of
+property. Note that integers and numbers are always preceded by a
+hash sign, @code{#}, while a true or false value is specified by
+@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.
+@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}
+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.
+@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
+@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
+throughout the @code{\score} or @code{\book} block in which the
+@code{\layout} block appears. Here is a example to show the format:
+
+@lilypond[verbatim,quote]
+\score {
+ \new Staff {
+ \relative c'' {
+ cis4 e d ces
+ }
+ }
+ \layout {
+ \context {
+ \Staff
+ extraNatural = ##t
+ }
+ }
+}
+@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
+@code{\set} commands embedded in music statements.
+
+@seealso
+
+Notation Reference:
+@ruser{Changing context default settings}.
+@c FIXME
+@c uncomment when backslash-node-name issue is resolved -pm
+@c @ruser{The set command}.
+
+Internals Reference:
+@rinternals{Contexts},
+@rinternals{Tunable context properties}.
+
+
@node Adding and removing engravers
@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
output, like bar lines, staves, note heads, stems, etc. If an
-engraver is removed from a context it can no longer produce its
+engraver is removed from a context, it can no longer produce its
output. This is a crude way of modifying the output, but it
can sometimes be useful.
@code{\with} command placed immediately after the context creation
command, as in the previous section.
-As an
-illustration let's repeat an example from the previous
-section with the staff lines removed. Remember that the
-staff lines are produced by the Staff_symbol_engraver.
+As an illustration, let's repeat an example from the previous section
+with the staff lines removed. Remember that the staff lines are
+produced by the @code{Staff_symbol_engraver}.
@lilypond[quote,verbatim,ragged-right]
\new Staff \with {
Engravers can also be added to individual contexts.
The command to do this is
-@code{\consists @emph{Engraver_name}},
+@code{\consists @var{Engraver_name}},
-placed inside a @code{\with} block. Some vocal scores
-have an @rglos{ambitus} placed at the beginning of a
-staff to indicate the range of notes in that staff.
-The ambitus is produced by the @code{Ambitus_engraver},
-which is not normally included in any context. If
-we add it to the @code{Voice} context it calculates
-the range from that voice only:
+@noindent
+placed inside a @code{\with} block. Some vocal scores have an ambitus
+placed at the beginning of a staff to indicate the range of notes in
+that staff -- see @rglos{ambitus}. The ambitus is produced by the
+@code{Ambitus_engraver}, which is not normally included in any
+context. If we add it to the @code{Voice} context, it calculates the
+range from that voice only:
@lilypond[quote,verbatim,ragged-right]
\new Staff <<
@end lilypond
@noindent
-but if we add the Ambitus engraver to the
-@code{Staff} context it calculates the range from all
+but if we add the ambitus engraver to the
+@code{Staff} context, it calculates the range from all
the notes in all the voices on that staff:
@lilypond[quote,verbatim,ragged-right]
@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
engravers to every context of a specific type by placing the
commands in the appropriate context in a @code{\layout}
block. For example, if we wanted to show an ambitus for every
-staff in a four-staff score we could write
+staff in a four-staff score, we could write
@lilypond[quote,verbatim,ragged-right]
\score {
@code{\set} command in a @code{\context} block in the
same way.
+@seealso
+
+Notation Reference: @ruser{Modifying context plug-ins},
+@ruser{Changing context default settings}.
+
+
@node Extending the templates
@section Extending the templates
understand the fundamental concepts. But how can you
get the staves that you want? Well, you can find lots of
templates (see @ref{Templates}) which may give you a start.
-But what
-if you want something that isn't covered there? Read on.
-
-TODO Add links to templates after they have been moved to LSR
+But what if you want something that isn't covered there? Read on.
@menu
* Soprano and cello::
@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
underneath the soprano stuff. We also need to add @code{<<} and
@code{>>} around the music -- that tells LilyPond that there's
more than one thing (in this case, two @code{Staves}) happening
-at once. The @code{\score} looks like this now
+at once. The @code{\score} looks like this now:
@c Indentation in this example is deliberately poor
@example
}
@end lilypond
+@seealso
+
+The starting templates can be found in the @q{Templates} appendix,
+see @ref{Single staff}.
+
@node Four-part SATB vocal score
@subsection Four-part SATB vocal score
}
@end lilypond
-None of the templates provides this layout exactly. The
-nearest is @q{SATB vocal score and automatic piano reduction},
-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.
-
-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.
+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
+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.
+
+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:
@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
+After gaining some facility with writing LilyPond code, you
may find that it is easier to build a score from scratch
rather than modifying one of the templates. You can also
develop your own style this way to suit the sort of music you
We simply mirror the staff structure we want.
Organ music is usually written on three staves,
one for each manual and one for the pedals. The
-manual staves should be bracketed together so we
+manual staves should be bracketed together, so we
need to use a PianoStaff for them. The first
manual part needs two voices and the second manual
part just one.
>>
@end example
-It is not strictly necessary to use the simultaneous construct
+It is not necessary to use the simultaneous construct
@code{<< .. >>} for the manual two staff and the pedal organ staff,
-since they contain only one music expression, but it does no harm
+since they contain only one music expression, but it does no harm,
and always using angle brackets after @code{\new Staff} is a good
habit to cultivate in case there are multiple voices. The opposite
is true for Voices: these should habitually be followed by braces
@code{@{ .. @}} in case your music is coded in several variables
which need to run consecutively.
-Let's add this structure to the score block, and adjust the
-indenting. We also add the appropriate clefs, ensure the
-second voice stems point down with @code{\voiceTwo} and
-enter the time signature and key to each staff using our
-predefined variable, @code{\TimeKey}.
+Let's add this structure to the score block, and adjust the indenting.
+We also add the appropriate clefs, ensure stems, ties and slurs in
+each voice on the upper staff point to the right direction with
+@code{\voiceOne} and @code{\voiceTwo}, and enter the time signature
+and key to each staff using our predefined variable, @code{\TimeKey}.
@example
\score @{
\new Staff = "ManualOne" <<
\TimeKey % set time signature and key
\clef "treble"
- \new Voice @{ \ManualOneVoiceOneMusic @}
+ \new Voice @{ \voiceOne \ManualOneVoiceOneMusic @}
\new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
>> % end ManualOne Staff context
\new Staff = "ManualTwo" <<
\new Staff = "ManualOne" <<
\TimeKey % set time signature and key
\clef "treble"
- \new Voice { \ManualOneVoiceOneMusic }
+ \new Voice { \voiceOne \ManualOneVoiceOneMusic }
\new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
>> % end ManualOne Staff context
\new Staff = "ManualTwo" <<
@end lilypond
-
-
-
-
-
projects / lilypond.git / blobdiff