From: Graham Percival Date: Tue, 1 Mar 2005 07:18:52 +0000 (+0000) Subject: Swappage and organization. X-Git-Tag: release/2.5.14~53 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=c14c7001a03a9db69e5c38c0871b0ef8a71af374;p=lilypond.git Swappage and organization. --- diff --git a/Documentation/user/basic-notation.itely b/Documentation/user/basic-notation.itely index 2cab325c68..6076976abd 100644 --- a/Documentation/user/basic-notation.itely +++ b/Documentation/user/basic-notation.itely @@ -14,10 +14,10 @@ This chapter explains how to use all basic notation features. * Note entry:: * Easier music entry:: * Staff notation:: +* More than notes:: +* Expressive marks:: * Polyphony:: -* Beaming:: * Repeats:: -* Expressive marks:: @end menu @@ -32,18 +32,15 @@ related constructs, such as stems, tuplets and ties. @menu * Notes:: * Pitches:: -* Chromatic alterations:: +* Cautionary accidentals:: * Micro tones:: * Chords:: * Rests:: * Skips:: * Durations:: * Augmentation dots:: -* Scaling durations:: -* Stems:: -* Ties:: * Tuplets:: -* Transpose:: +* Scaling durations:: @end menu @@ -53,8 +50,8 @@ related constructs, such as stems, tuplets and ties. A note is printed by specifying its pitch and then its duration, -@lilypond[quote,verbatim,raggedright] -{ cis'4 d'8 e'16 c'16 } +@lilypond[quote,verbatim,raggedright,fragment] +cis'4 d'8 e'16 c'16 @end lilypond @@ -78,6 +75,18 @@ letters span the octave above that C a,4 b, c d e f g a b c' d' e' \clef treble f' g' a' b' c'' @end lilypond +@cindex @code{'} +@cindex @code{,} + +The optional octave specification takes the form of a series of +single quote (`@code{'}') characters or a series of comma +(`@code{,}') characters. Each @code{'} raises the pitch by one +octave; each @code{,} lowers the pitch by an octave + +@lilypond[quote,raggedright,fragment,verbatim] +c' c'' es' g' as' gisis' ais' +@end lilypond + @cindex note names, Dutch A sharp is formed by adding @code{-is} to the end of a pitch name and @@ -126,32 +135,6 @@ catalan.ly do re mi fa sol la sib si -d/-s -b espanol.ly do re mi fa sol la sib si -s -b @end example -@cindex @code{'} -@cindex @code{,} - - - -The optional octave specification takes the form of a series of -single quote (`@code{'}') characters or a series of comma -(`@code{,}') characters. Each @code{'} raises the pitch by one -octave; each @code{,} lowers the pitch by an octave - -@lilypond[quote,raggedright,fragment,verbatim] -c' c'' es' g' as' gisis' ais' -@end lilypond - - -@ignore -@c FIXME: we need this info (hide/unhide) somewhere in the manual, but this ain't the place. -gp -@c wait; this is already in advanced notation. -@refcommands -Notes can be hidden and unhidden with the following commands - -@cindex @code{\hideNotes} -@code{\hideNotes}, -@cindex @code{\unHideNotes} -@code{\unHideNotes}. -@end ignore @seealso @@ -159,8 +142,8 @@ Program reference: @internalsref{NoteEvent}, and @internalsref{NoteHead}. -@node Chromatic alterations -@subsection Chromatic alterations +@node Cautionary accidentals +@subsection Cautionary accidentals Normally accidentals are printed automatically, but you may also print them manually. A reminder accidental @@ -170,6 +153,7 @@ can be forced by adding an exclamation mark @code{!} after the pitch. A cautionary accidental @cindex cautionary accidental @cindex parenthesized accidental +@cindex @code{!} (i.e., an accidental within parentheses) can be obtained by adding the question mark `@code{?}' after the pitch. @@ -382,126 +366,6 @@ direction manually Program reference: @internalsref{Dots}, and @internalsref{DotColumn}. -@node Scaling durations -@subsection Scaling durations - -You can alter the length of duration by a fraction @var{N/M} -appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This -will not affect the appearance of the notes or rests produced. - -In the following example, the first three notes take up exactly two -beats, but no triplet bracket is printed. -@lilypond[quote,raggedright,fragment,relative=2,verbatim] -\time 2/4 -a4*2/3 gis4*2/3 a4*2/3 -a4 a4 a4*2 -b16*4 c4 -@end lilypond - - -@seealso - -This manual: @ref{Tuplets} - - -@c TODO: I'm not certain that Stems belong here in the manual. -gp -@node Stems -@subsection Stems - -Whenever a note is found, a @internalsref{Stem} object is created -automatically. For whole notes and rests, they are also created but -made invisible. - -@refcommands - -@cindex @code{\stemUp} -@code{\stemUp}, -@cindex @code{\stemDown} -@code{\stemDown}, -@cindex @code{\stemNeutral} -@code{\stemNeutral}. - - -@node Ties -@subsection Ties - -@cindex Tie -@cindex ties -@cindex @code{~} - -A tie connects two adjacent note heads of the same pitch. The tie in -effect extends the length of a note. Ties should not be confused with -slurs, which indicate articulation, or phrasing slurs, which indicate -musical phrasing. A tie is entered using the tilde symbol `@code{~}' - -@lilypond[quote,raggedright,fragment,verbatim] -e' ~ e' ~ -@end lilypond - -When a tie is applied to a chord, all note heads whose pitches match -are connected. When no note heads match, no ties will be created. - -A tie is just a way of extending a note duration, similar to the -augmentation dot. The following example shows two ways of notating -exactly the same concept -@c -@lilypond[quote,fragment,raggedright] -\time 3/4 c'2. c'2 ~ c'4 -@end lilypond - -@noindent -Ties are used either when the note crosses a bar line, or when dots -cannot be used to denote the rhythm. When using ties, larger note -values should be aligned to subdivisions of the measure, eg. - -@lilypond[fragment,quote,raggedright] -\relative { - r8 c8 ~ c2 r4 | r8^"not" c2 ~ c8 r4 -} -@end lilypond - -If you need to tie a lot of notes over bars, it may be easier to use -automatic note splitting (see @ref{Automatic note splitting}). This -mechanism automatically splits long notes, and ties them across bar -lines. - -Ties are sometimes used to write out arpeggios. In this case, two tied -notes need not be consecutive. This can be achieved by setting the -@code{tieWaitForNote} property to true. For example, - -@lilypond[fragment,verbatim,relative=1,raggedright] -\set tieWaitForNote = ##t -\grace { c16[~ e~ g]~ } 4 -@end lilypond - - -@refcommands - - -@cindex @code{\tieUp} -@code{\tieUp}, -@cindex @code{\tieDown} -@code{\tieDown}, -@cindex @code{\tieNeutral} -@code{\tieNeutral}, -@cindex @code{\tieDotted} -@code{\tieDotted}, -@cindex @code{\tieSolid} -@code{\tieSolid}. - -@seealso - -In this manual: @ref{Automatic note splitting}. - -Program reference: @internalsref{TieEvent}, @internalsref{Tie}. - -@refbugs - - -Switching staves when a tie is active will not produce a slanted tie. - -Formatting of ties is a difficult subject. The results are often not -optimal. @node Tuplets @subsection Tuplets @@ -546,11 +410,9 @@ denominator, but if it is set to the Scheme function @code{fraction-tuplet-formatter}, @var{num}:@var{den} will be printed instead. - @cindex @code{tupletNumberFormatFunction} @cindex tuplet formatting - @refcommands @cindex @code{\tupletUp} @@ -577,83 +439,26 @@ tuplet brackets should be moved manually, which is demonstrated in @inputfileref{input/@/regression,tuplet@/-nest@/.ly}. -@node Transpose -@subsection Transpose -@cindex Transpose -@cindex transposition of pitches -@cindex @code{\transpose} - -A music expression can be transposed with @code{\transpose}. The -syntax is -@example -\transpose @var{from} @var{to} @var{musicexpr} -@end example - -This means that @var{musicexpr} is transposed by the interval between -the pitches @var{from} and @var{to}: any note with pitch @code{from} -is changed to @code{to}. - - -For example, consider a piece written in the key of D-major. If -this piece is a little too low for its performer, it can be -transposed up to E-major with -@example -\transpose d e @dots{} -@end example - -Consider a part written for violin (a C instrument). If -this part is to be played on the A clarinet, the following -transposition will produce the appropriate part - -@example -\transpose a c @dots{} -@end example +@node Scaling durations +@subsection Scaling durations -@code{\transpose} distinguishes between enharmonic pitches: both -@code{\transpose c cis} or @code{\transpose c des} will transpose up -half a tone. The first version will print sharps and the second -version will print flats +You can alter the length of duration by a fraction @var{N/M} +appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This +will not affect the appearance of the notes or rests produced. -@lilypond[quote,raggedright,verbatim] -mus = { \key d \major cis d fis g } -\context Staff { - \clef "F" \mus - \clef "G" - \transpose c g' \mus - \transpose c f' \mus -} +In the following example, the first three notes take up exactly two +beats, but no triplet bracket is printed. +@lilypond[quote,raggedright,fragment,relative=2,verbatim] +\time 2/4 +a4*2/3 gis4*2/3 a4*2/3 +a4 a4 a4*2 +b16*4 c4 @end lilypond -@code{\transpose} may also be used to input written notes for a -transposing instrument. Pitches are normally entered into LilyPond -in C (or ``concert pitch''), but they may be entered in another -key. For example, when entering music for a B-flat trumpet which -begins on concert D, one would write - -@example -\transpose c bes @{ e4 @dots{} @} -@end example - -To print this music in B-flat again (ie producing a trumpet part, -instead of a concert pitch conductor's score) you would wrap the -existing music with another @code{transpose} - -@example -\transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @} -@end example - @seealso -Program reference: @internalsref{TransposedMusic}, and -@internalsref{UntransposableMusic}. - -@refbugs - -If you want to use both @code{\transpose} and @code{\relative}, -you must put @code{\transpose} outside of @code{\relative}, since -@code{\relative} will have no effect music that appears inside a -@code{\transpose}. +This manual: @ref{Tuplets} @node Easier music entry @@ -920,6 +725,8 @@ Examples: @inputfileref{input/@/regression,completion@/-heads@/.ly}. Program reference: @internalsref{Completion_heads_engraver}. + + @node Staff notation @section Staff notation @@ -932,17 +739,14 @@ such as key signatures, clefs and time signatures. * Staff symbol:: * Key signature:: * Clef:: -* Ottava brackets:: * Time signature:: * Partial measures:: * Unmetered music:: * Bar lines:: -* Time administration:: -* Controlling formatting of prefatory matter:: * System start delimiters:: -* Aligning to cadenzas:: @end menu + @node Staff symbol @subsection Staff symbol @@ -1138,54 +942,6 @@ Program reference: @internalsref{Clef}. -@node Ottava brackets -@subsection Ottava brackets - -`Ottava' brackets introduce an extra transposition of an octave for -the staff. They are created by invoking the function -@code{set-octavation} - -@cindex ottava -@cindex 15ma -@cindex octavation - -@lilypond[quote,raggedright,verbatim,fragment] -\relative c''' { - a2 b - #(set-octavation 1) - a b - #(set-octavation 0) - a b -} -@end lilypond - -The @code{set-octavation} function also takes -1 (for 8va bassa) and 2 -(for 15ma) as arguments. Internally the function sets the properties -@code{ottavation} (e.g., to @code{"8va"}) and -@code{centralCPosition}. For overriding the text of the bracket, set -@code{ottavation} after invoking @code{set-octavation}, i.e., - -@lilypond[quote,raggedright,verbatim] -{ - #(set-octavation 1) - \set Staff.ottavation = #"8" - c''' -} -@end lilypond - -@seealso - -Program reference: @internalsref{OttavaBracket}. - -Examples: @inputfileref{input/@/regression,ottava@/.ly}, -@inputfileref{input/@/regression,ottava@/-broken@/.ly}. - -@refbugs - -@code{set-octavation} will get confused when clef changes happen -during an octavation bracket. - - @node Time signature @@ -1418,93 +1174,12 @@ Program reference: @internalsref{BarLine} (created at Examples: @inputfileref{input/@/test,bar@/-lines@/.ly}, -@node Time administration -@subsection Time administration - -Time is administered by the @internalsref{Time_signature_engraver}, -which usually lives in the @internalsref{Score} context. -The bookkeeping deals with the following variables - -@table @code -@item currentBarNumber -The measure number. - -@item measureLength -The length of the measures in the current time signature. For a 4/4 -time this is@tie{}1, and for 6/8 it is 3/4. - -@item measurePosition -The point within the measure where we currently are. This quantity -is reset to@tie{}0 whenever it exceeds @code{measureLength}. When that -happens, @code{currentBarNumber} is incremented. - -@item timing -If set to true, the above variables are updated for every time -step. When set to false, the engraver stays in the current measure -indefinitely. -@end table - -Timing can be changed by setting any of these variables explicitly. -In the next example, the 4/4 time signature is printed, but -@code{measureLength} is set to 5/4. After a while, the measure is -shortened by 1/8, by setting @code{measurePosition} to 7/8 at 2/4 -in the measure, so the next bar line will fall at 2/4 + 3/8. The -3/8 arises because 5/4 normally has 10/8, but we have manually -set the measure position to be 7/8 and 10/8 - 7/8 = 3/8. - -@lilypond[quote,raggedright,verbatim,relative,fragment] -\set Score.measureLength = #(ly:make-moment 5 4) -c1 c4 -c1 c4 -c4 c4 -\set Score.measurePosition = #(ly:make-moment 7 8) -b8 b b -c4 c1 -@end lilypond - - -@node Controlling formatting of prefatory matter -@subsection Controlling formatting of prefatory matter - -@c This section will be moved to somewhere else soon. -gp -This example demonstrates how to place prefatory matter -(such as the clef and key signature) at the end of a line. - -@lilypond[quote,verbatim] -\transpose c c' { - \override Staff.Clef - #'break-visibility = #end-of-line-visible - \override Staff.KeySignature - #'break-visibility = #end-of-line-visible - \set Staff.explicitClefVisibility = #end-of-line-visible - \set Staff.explicitKeySignatureVisibility = #end-of-line-visible - - % We want the time sig to take space, otherwise there is not - % enough white at the start of the line. - - \override Staff.TimeSignature #'transparent = ##t - \set Score.defaultBarType = #"empty" - - c1 d e f g a b c - \key d \major - \break - - % see above. - \time 4/4 - - d e fis g a b cis d - \key g \major - \break - \time 4/4 -} -@end lilypond - @node System start delimiters @subsection System start delimiters -Polyphonic scores consist of many staves. These staves can be -constructed in three different ways +Many scores consist of more than one staff. These staves can be +joined in three different ways @itemize @bullet @item The group is started with a brace at the left, and bar lines are connected. This is done with the @internalsref{GrandStaff} context. @@ -1558,373 +1233,134 @@ The bar lines at the start of each system are in every context, and that type is determined by the property @code{systemStartDelimiter}. -@node Aligning to cadenzas -@subsection Aligning to cadenzas +@node More than notes +@section More than notes +@c silly title; should change. -In an orchestral context, cadenzas present a special problem: -when constructing a score that includes a cadenza, all other -instruments should skip just as many notes as the length of the -cadenza, otherwise they will start too soon or too late. +This section deals with notation that affects more than one note. -A solution to this problem are the functions @code{mmrest-of-length} -and @code{skip-of-length}. These Scheme functions take a piece of music -as argument, and generate a @code{\skip} or multi-rest, exactly as -long as the piece. The use of @code{mmrest-of-length} is demonstrated -in the following example. +@menu +* Ties:: +* Automatic beams:: +* Manual beams:: +* Grace notes:: +* Fingering instructions:: +@end menu -@lilypond[verbatim,raggedright,quote] -cadenza = \relative c' { - c4 d8 << { e f g } \\ { d4. } >> - g4 f2 g4 g -} +@node Ties +@subsection Ties -\new GrandStaff << - \new Staff { \cadenza c'4 } - \new Staff { - #(ly:export (mmrest-of-length cadenza)) - c'4 - } ->> -@end lilypond +@cindex Tie +@cindex ties +@cindex @code{~} +A tie connects two adjacent note heads of the same pitch. The tie in +effect extends the length of a note. Ties should not be confused with +slurs, which indicate articulation, or phrasing slurs, which indicate +musical phrasing. A tie is entered using the tilde symbol `@code{~}' +@lilypond[quote,raggedright,fragment,verbatim] +e' ~ e' ~ +@end lilypond +When a tie is applied to a chord, all note heads whose pitches match +are connected. When no note heads match, no ties will be created. -@node Polyphony -@section Polyphony - -Polyphony in music refers to having more than one voice occuring in -a piece of music. Polyphony in LilyPond refers to having more than -one voice on the same staff. - -@menu -* Basic polyphony:: -* Explicitly instantiating voices:: -* Collision Resolution:: -@end menu - -@node Basic polyphony -@subsection Basic polyphony -@cindex polyphony - -The easiest way to enter fragments with more than one voice on a staff -is to enter each voice as a sequence (with @code{@{...@}}), and combine -them simultaneously, separating the voices with @code{\\} +A tie is just a way of extending a note duration, similar to the +augmentation dot. The following example shows two ways of notating +exactly the same concept +@c +@lilypond[quote,fragment,raggedright] +\time 3/4 c'2. c'2 ~ c'4 +@end lilypond -@cindex @code{\\} +@noindent +Ties are used either when the note crosses a bar line, or when dots +cannot be used to denote the rhythm. When using ties, larger note +values should be aligned to subdivisions of the measure, eg. -@lilypond[quote,verbatim,fragment] -\new Staff \relative c' { - c16 d e f - << { g4 f e | d2 e2 } \\ - { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\ - { s2. | s4 b4 c2 } - >> +@lilypond[fragment,quote,raggedright] +\relative { + r8 c8 ~ c2 r4 | r8^"not" c2 ~ c8 r4 } @end lilypond -The separator causes @internalsref{Voice} contexts@footnote{Polyphonic -voices are sometimes called ``layers'' in other notation packages} -@cindex layers -to be instantiated. They bear the names @code{"1"}, @code{"2"}, etc. In -each of these contexts, vertical direction of slurs, stems, etc., is set -appropriately. +If you need to tie a lot of notes over bars, it may be easier to use +automatic note splitting (see @ref{Automatic note splitting}). This +mechanism automatically splits long notes, and ties them across bar +lines. -These voices are all seperate from the voice that contains the notes just -outside the @code{<< \\ >>} construct. This should be noted when making -changes at the voice level. This also means that slurs and ties cannot go -into or out of a @code{<< \\ >>} construct. -Conversely, parallel voices from separate @code{<< \\ >>} constructs on the -same staff are the the same voice. -Here is the same example, with different noteheads for each voice. -Note that the change to the note-head style in the main voice does not affect -the inside of the @code{<< \\ >>} constructs. Also, the change to the second -voice in the first @code{<< \\ >>} construct is effective in the second -@code{<< \\ >>}, and the voice is tied accross the two constructs. +Ties are sometimes used to write out arpeggios. In this case, two tied +notes need not be consecutive. This can be achieved by setting the +@code{tieWaitForNote} property to true. For example, -@lilypond[quote,verbatim,fragment] -\new Staff \relative c' { - \override NoteHead #'style = #'cross - c16 d e f - << - { g4 f e } \\ - { \override NoteHead #'style = #'triangle - r8 e4 d c8 ~ - } - >> | - << - { d2 e2 } \\ - { c8 b16 a b8 g ~ g2 } \\ - { \override NoteHead #'style = #'slash s4 b4 c2 } - >> -} +@lilypond[fragment,verbatim,relative=1,raggedright] +\set tieWaitForNote = ##t +\grace { c16[~ e~ g]~ } 4 @end lilypond -@node Explicitly instantiating voices -@subsection Explicitly instantiating voices -@internalsref{Voice} contexts can also also be instantiated manually -inside a @code{<< >>} block to create polyphonic music, using -@code{\voiceOne}, up to @code{\voiceFour} to assign stem directions -and a horizontal shift for each part. +@refcommands -Specifically, -@example -<< \upper \\ \lower >> -@end example -@noindent -is equivalent to +@cindex @code{\tieUp} +@code{\tieUp}, +@cindex @code{\tieDown} +@code{\tieDown}, +@cindex @code{\tieNeutral} +@code{\tieNeutral}, +@cindex @code{\tieDotted} +@code{\tieDotted}, +@cindex @code{\tieSolid} +@code{\tieSolid}. -@example -<< - \context Voice = "1" @{ \voiceOne \upper @} - \context Voice = "2" @{ \voiceTwo \lower @} ->> -@end example +@seealso -@cindex @code{\voiceOne} -@cindex @code{\voiceFour} +In this manual: @ref{Automatic note splitting}. -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} make -these objects point upwards, while @code{\voiceTwo} and @code{\voiceFour} -make them point downwards. -The command @code{\oneVoice} will revert back to the normal setting. -@cindex @code{\oneVoice} +Program reference: @internalsref{TieEvent}, @internalsref{Tie}. -An expression that appears directly inside a @code{<< >>} belongs to -the main voice. This is useful when extra voices appear while the main -voice is playing. Here is a more correct rendition of the example from -the previous section. The crossed noteheads demonstrate that the main -melody is now in a single voice context. +@refbugs -@lilypond[quote,raggedright,verbatim] -\new Staff \relative c' { - \override NoteHead #'style = #'cross - c16 d e f - \voiceOne - << - { g4 f e | d2 e2} - \context Voice="1" { \voiceTwo - r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 - \oneVoice - } - \new Voice { \voiceThree - s2. | s4 b4 c2 - \oneVoice - } - >> - \oneVoice -} -@end lilypond -The correct definition of the voices allows the melody to be slurred. -@lilypond[quote,raggedright,verbatim] -\new Staff \relative c' { - c16^( d e f - \voiceOne - << - { g4 f e | d2 e2) } - \context Voice="1" { \voiceTwo - r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 - \oneVoice - } - \new Voice { \voiceThree - s2. s4 b4 c2 - \oneVoice - } - >> - \oneVoice -} -@end lilypond +Switching staves when a tie is active will not produce a slanted tie. -Avoiding the @code{\\} seperator also allows nesting polyphony -constructs, which in some case might be a more natural way to typeset -the music. +Formatting of ties is a difficult subject. The results are often not +optimal. -@lilypond[quote,raggedright,verbatim] -\new Staff \relative c' { - c16^( d e f - \voiceOne - << - { g4 f e | d2 e2) } - \context Voice="1" { \voiceTwo - r8 e4 d c8 ~ | - << - {c8 b16 a b8 g ~ g2} - \new Voice { \voiceThree - s4 b4 c2 - \oneVoice - } - >> - \oneVoice - } - >> - \oneVoice -} -@end lilypond -@node Collision Resolution -@subsection Collision Resolution +@node Automatic beams +@subsection Automatic beams -Normally, note heads with a different number of dots are not merged, but -when the object property @code{merge-differently-dotted} is set in -the @internalsref{NoteCollision} object, they are merged -@lilypond[quote,verbatim,fragment,raggedright,relative=2] -\context Voice << { - g8 g8 - \override Staff.NoteCollision - #'merge-differently-dotted = ##t - g8 g8 -} \\ { g8.[ f16] g8.[ f16] } >> -@end lilypond +LilyPond inserts beams automatically -Similarly, you can merge half note heads with eighth notes, by setting -@code{merge-differently-headed} -@lilypond[quote,raggedright,fragment,relative=2,verbatim] -\context Voice << { - c8 c4. - \override Staff.NoteCollision - #'merge-differently-headed = ##t -c8 c4. } \\ { c2 c2 } >> +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +\time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8 @end lilypond -LilyPond also vertically shifts rests that are opposite of a stem, -for example - -@lilypond[quote,raggedright,fragment,verbatim] -\context Voice << c''4 \\ r4 >> -@end lilypond +When these automatic decisions are not good enough, beaming can be +entered explicitly. It is also possible to define beaming patterns +that differ from the defaults. +Individual notes may be marked with @code{\noBeam}, to prevent them +from being beamed -@refcommands +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +\time 2/4 c8 c\noBeam c c +@end lilypond +@seealso -@cindex @code{\oneVoice} -@code{\oneVoice}, -@cindex @code{\voiceOne} -@code{\voiceOne}, -@cindex @code{\voiceTwo} -@code{\voiceTwo}, -@cindex @code{\voiceThree} -@code{\voiceThree}, -@cindex @code{\voiceFour} -@code{\voiceFour}. +Program reference: @internalsref{Beam}. - -@cindex @code{\shiftOn} -@code{\shiftOn}, -@cindex @code{\shiftOnn} -@code{\shiftOnn}, -@cindex @code{\shiftOnnn} -@code{\shiftOnnn}, -@cindex @code{\shiftOff} -@code{\shiftOff}: these commands specify in what chords of the current -voice should be shifted. The outer voices (normally: voice one and -two) have @code{\shiftOff}, while the inner voices (three and four) -have @code{\shiftOn}. @code{\shiftOnn} and @code{\shiftOnnn} define -further shift levels. - - -When LilyPond cannot cope, the @code{force-hshift} -property of the @internalsref{NoteColumn} object and pitched rests can -be used to override typesetting decisions. - -@lilypond[quote,verbatim,raggedright] -\relative << -{ - - -} \\ { - - \once \override NoteColumn #'force-hshift = #1.7 - -} >> -@end lilypond - - - -@seealso - -Program reference: the objects responsible for resolving collisions are -@internalsref{NoteCollision} and @internalsref{RestCollision}. - -Examples: -@inputfileref{input/@/regression,collision@/-dots@/.ly}, -@inputfileref{input/@/regression,collision@/-head-chords@/.ly}, -@inputfileref{input/@/regression,collision@/-heads@/.ly}, -@inputfileref{input/@/regression,collision@/-mesh@/.ly}, and -@inputfileref{input/@/regression,collisions@/.ly}. - - -@refbugs - - -When using @code{merge-differently-headed} with an upstem eighth or a -shorter note, and a downstem half note, the eighth note gets the wrong -offset. - -There is no support for clusters where the same note occurs with -different accidentals in the same chord. In this case, it is -recommended to use enharmonic transcription, or to use special cluster -notation (see @ref{Clusters}). - -@node Beaming -@section Beaming - -@c todo: split this up; noBeaming and manual beams stay in basic; -@c seting automatic beam behavior and beam formatting goes into -@c advanced. -gp - -Beams are used to group short notes into chunks that are aligned with -the metrum. LilyPond normally inserts beams automatically, but if you -wish you may control them manually or change how beams are automatically -grouped. - -@cindex Automatic beams -@menu -* Automatic beams:: -* Manual beams:: -* Setting automatic beam behavior:: -* Beam formatting:: -@end menu - -@node Automatic beams -@subsection Automatic beams - -LilyPond inserts beams automatically - -@lilypond[quote,raggedright,fragment,verbatim,relative=2] -\time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8 -@end lilypond - -When these automatic decisions are not good enough, beaming can be -entered explicitly. It is also possible to define beaming patterns -that differ from the defaults. - -Individual notes may be marked with @code{\noBeam}, to prevent them -from being beamed - -@lilypond[quote,raggedright,fragment,verbatim,relative=2] -\time 2/4 c8 c\noBeam c c -@end lilypond - - -@seealso - -Program reference: @internalsref{Beam}. - - -@node Manual beams -@subsection Manual beams -@cindex beams, manual -@cindex @code{]} -@cindex @code{[} +@node Manual beams +@subsection Manual beams +@cindex beams, manual +@cindex @code{]} +@cindex @code{[} In some cases it may be necessary to override the automatic beaming algorithm. For example, the autobeamer will not put beams over rests @@ -2004,525 +1440,304 @@ texts and accidentals. @c FIXME. -@node Setting automatic beam behavior -@subsection Setting automatic beam behavior - -@cindex @code{autoBeamSettings} -@cindex @code{(end * * * *)} -@cindex @code{(begin * * * *)} -@cindex automatic beams, tuning -@cindex tuning automatic beaming - -@c [TODO: use \applycontext] +@node Grace notes +@subsection Grace notes -In normal time signatures, automatic beams can start on any note but can -only end in a few positions within the measure: beams can end on a beat, -or at durations specified by the properties in -@code{autoBeamSettings}. The defaults for @code{autoBeamSettings} -are defined in @file{scm/@/auto@/-beam@/.scm}. +@cindex @code{\grace} +@cindex ornaments +@cindex grace notes -The value of @code{autoBeamSettings} is changed with three functions, -@example -#(override-auto-beam-setting - '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b} - [@var{context}]) -#(score-override-auto-beam-setting - '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b}) -#(revert-auto-beam-setting '(@var{be} @var{p} @var{q} @var{n} @var{m}) - [@var{context}]) -@end example -Here, @var{be} is the symbol @code{begin} or @code{end}, and -@var{context} is an optional context (default: @code{'Voice}). It -determines whether the rule applies to begin or end-points. The -quantity @var{p}/@var{q} refers to the length of the beamed notes (and -`@code{* *}' designates notes of any length), @var{n}/@var{M} refers -to a time signature (wildcards `@code{* *}' may be entered to -designate all time signatures), @var{a}/@var{b} is a duration. By -default, this command changes settings for the current voice. It is -also possible to adjust settings at higher contexts, by adding a -@var{context} argument. @code{score-override-auto-beam-setting} is -equal to @code{override-auto-beam-setting} with the argument -@var{context} set to @code{'Score}. - -For example, if automatic beams should end on every quarter note, use -the following -@example -#(override-auto-beam-setting '(end * * * *) 1 4 'Staff) -@end example -Since the duration of a quarter note is 1/4 of a whole note, it is -entered as @code{(ly:make-moment 1 4)}. +Grace notes are ornaments that are written out. The most common ones +are acciaccatura, which should be played as very short. It is denoted +by a slurred small note with a slashed stem. The appoggiatura is a +grace note that takes a fixed fraction of the main note, and is +denoted as a slurred note in small print without a slash. They +are entered with the commands @code{\acciaccatura} and +@code{\appoggiatura}, as demonstrated in the following example -The same syntax can be used to specify beam starting points. In this -example, automatic beams can only end on a dotted quarter note -@example -#(override-auto-beam-setting '(end * * * *) 3 8) -@end example -In 4/4 time signature, this means that automatic beams could end only on -3/8 and on the fourth beat of the measure (after 3/4, that is 2 times -3/8, has passed within the measure). - -Rules can also be restricted to specific time signatures. A rule that -should only be applied in @var{N}/@var{M} time signature is formed by -replacing the second asterisks by @var{N} and @var{M}. For example, a -rule for 6/8 time exclusively looks like -@example -#(override-auto-beam-setting '(begin * * 6 8) @dots{}) -@end example -If a rule should be to applied only to certain types of beams, use the -first pair of asterisks. Beams are classified according to the -shortest note they contain. For a beam ending rule that only applies -to beams with 32nd notes (and no shorter notes), use @code{(end 1 32 * -*)}. +@cindex appoggiatura +@cindex acciaccatura -@cindex automatic beam generation -@cindex autobeam -@cindex @code{autoBeaming} -@cindex lyrics +@lilypond[quote,raggedright,relative=2,verbatim,fragment] +b4 \acciaccatura d8 c4 \appoggiatura e8 d4 +\acciaccatura { g16[ f] } e4 +@end lilypond -If beams are used to indicate melismata in songs, then automatic -beaming should be switched off. This is done by setting -@code{autoBeaming} to @code{#f}. +Both are special forms of the @code{\grace} command. By prefixing this +keyword to a music expression, a new one is formed, which will be +printed in a smaller font and takes up no logical time in a measure. -@refcommands +@lilypond[quote,raggedright,relative=2,verbatim,fragment] +c4 \grace c16 c4 +\grace { c16[ d16] } c2 c4 +@end lilypond -@cindex @code{\autoBeamOff} -@code{\autoBeamOff}, -@cindex @code{\autoBeamOn} -@code{\autoBeamOn}. +@noindent +Unlike @code{\acciaccatura} and @code{\appoggiatura}, the +@code{\grace} command does not start a slur. +Internally, timing for grace notes is done using a second, `grace' +timing. Every point in time consists of two rational numbers: one +denotes the logical time, one denotes the grace timing. The above +example is shown here with timing tuples -@refbugs +@lilypond[quote,raggedright] +<< + \relative c''{ + c4 \grace c16 c4 \grace { + c16[ d16] } c2 c4 + } + \new Lyrics \lyricmode { + \override LyricText #'font-family = #'typewriter -If a score ends while an automatic beam has not been ended and is -still accepting notes, this last beam will not be typeset at all. The -same holds polyphonic voices, entered with @code{<< @dots{} \\ @dots{} ->>}. If a polyphonic voice ends while an automatic beam is still -accepting notes, it is not typeset. + \markup { (0,0) } 4 + \grace { \markup { + ( \fraction 1 4 , \fraction -1 16 ) } 16 } + \markup { (\fraction 1 4 , 0 ) } 4 + \grace { + \markup { (\fraction 2 4 , \fraction "-1" 8 ) } 16 + \markup { (\fraction 2 4 , \fraction "-1" 16 ) } 16 + } + \markup { ( \fraction 2 4 , 0 ) } + } +>> +@end lilypond -The rules for ending a beam depend on the shortest note in a beam. -So, while it is possible to have different ending rules for eight -beams and sixteenth beams, a beam that contains both eight and -sixteenth notes will use the rules for the sixteenth beam. -In the example below, the autobeamer makes eighth beams and sixteenth -end at three eighths. The third beam can only be corrected by -specifying manual beaming. +The placement of grace notes is synchronized between different staves. +In the following example, there are two sixteenth grace notes for +every eighth grace note -@lilypond[quote,raggedright,fragment,relative=1] -#(override-auto-beam-setting '(end * * * *) 3 8) -% rather show case where it goes wrong -%\time 12/8 c'8 c c c16 c c c c c c[ c c c] c8[ c] c4 -\time 12/8 c'8 c c c16 c c c c c c c c c c8 c c4 +@lilypond[quote,raggedright,relative=2,verbatim,fragment] +<< \new Staff { e4 \grace { c16[ d e f] } e4 } + \new Staff { c4 \grace { g8[ b] } c4 } >> @end lilypond -It is not possible to specify beaming parameters that act differently in -different parts of a measure. This means that it is not possible to use -automatic beaming in irregular meters such as @code{5/8}. -@node Beam formatting -@subsection Beam formatting -When a beam falls in the middle of the staff, the beams point normally -down. However, this behaviour can be altered with the -@code{neutral-direction} property. - +If you want to end a note with a grace, use the @code{\afterGrace} +command. It takes two arguments: the main note, and the grace notes +following the main note. -@lilypond[quote,raggedright,relative=2,fragment,verbatim] -{ - b8[ b] - \override Beam #'neutral-direction = #-1 - b[ b] - \override Beam #'neutral-direction = #1 - b[ b] -} +@lilypond[raggedright, verbatim,relative=2,fragment] +c1 \afterGrace d1 { c16[ d] } c4 @end lilypond +This will put the grace notes after a ``space'' lasting 3/4 of the +length of the main note. The fraction 3/4 can be changed by setting +@code{afterGraceFraction}, ie. -@node Repeats -@section Repeats - -Repetition is a central concept in music, and multiple notations exist -for repetitions. - -@menu -* Repeat types:: -* Repeat syntax:: -* Repeats and MIDI:: -* Manual repeat commands:: -* Tremolo repeats:: -* Tremolo subdivisions:: -* Measure repeats:: -@end menu +@example +afterGraceFraction = #(cons 7 8) +@end example -@node Repeat types -@subsection Repeat types +@noindent +will put the grace note at 7/8 of the main note. -@cindex repeats -@cindex @code{\repeat} -The following types of repetition are supported +The same effect can be achieved manually by doing -@table @code -@item unfold -Repeated music is fully written (played) out. This is useful when -entering repetitious music. This is the only kind of repeat that -is included in MIDI output. -@item volta -Repeats are not written out, but alternative endings (volte) are -printed, left to right with brackets. This is the standard notation -for repeats with alternatives. These are not played in MIDI output by default. +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +\context Voice { + << { d1^\trill_( } + { s2 \grace { c16[ d] } } >> + c4) +} +@end lilypond -@ignore -@item fold -Alternative endings are written stacked. This has limited use but may be -used to typeset two lines of lyrics in songs with repeats, see -@inputfileref{input,star-spangled-banner@/.ly}. -@end ignore +@noindent +By adjusting the duration of the skip note (here it is a half-note), +the space between the main-note and the grace is adjusted. -@c tremolo, beamed -@item tremolo -Make tremolo beams. These are not played in MIDI output by default. -@item percent -Make beat or measure repeats. These look like percent signs. These -are not played in MIDI output by default. Percent repeats must be -declared within a Voice context. -@end table -@node Repeat syntax -@subsection Repeat syntax +A @code{\grace} section will introduce special typesetting settings, +for example, to produce smaller type, and set directions. Hence, when +introducing layout tweaks, they should be inside the grace section, +for example, +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +\new Voice { + \acciaccatura { + \stemDown + f16-> + \stemNeutral + } + g4 +} +@end lilypond +@noindent +The overrides should also be reverted inside the grace section. -LilyPond has one syntactic construct for specifying different types of -repeats. The syntax is - -@example -\repeat @var{variant} @var{repeatcount} @var{repeatbody} -@end example +The layout of grace sections can be changed throughout the music using +the function @code{add-grace-property}. The following example +undefines the Stem direction for this grace, so stems do not always +point up. -If you have alternative endings, you may add -@cindex @code{\alternative} @example -\alternative @{ @var{alternative1} - @var{alternative2} - @var{alternative3} @dots{} @} +\new Staff @{ + #(add-grace-property 'Voice 'Stem 'direction '()) + @dots{} +@} @end example -where each @var{alternative} is a music expression. If you do not -give enough alternatives for all of the repeats, the first alternative -is assumed to be played more than once. -Standard repeats are used like this -@lilypond[quote,raggedright,fragment,verbatim,relative=2] -c1 -\repeat volta 2 { c4 d e f } -\repeat volta 2 { f e d c } -@end lilypond +@noindent +Another option is to change the variables @code{startGraceMusic}, +@code{stopGraceMusic}, @code{startAcciaccaturaMusic}, +@code{stopAcciaccaturaMusic}, @code{startAppoggiaturaMusic}, +@code{stopAppoggiaturaMusic}. More information is in the file +@file{ly/@/grace@/-init@/.ly}. -With alternative endings -@lilypond[quote,raggedright,fragment,verbatim,relative=2] -c1 -\repeat volta 2 {c4 d e f} -\alternative { {d2 d} {f f,} } -@end lilypond +@seealso -@lilypond[quote,raggedright,fragment,verbatim,relative=2] -\context Staff { - \partial 4 - \repeat volta 4 { e | c2 d2 | e2 f2 | } - \alternative { { g4 g g } { a | a a a a | b2. } } -} -@end lilypond +Program reference: @internalsref{GraceMusic}. -It is possible to shorten volta brackets -by setting @code{voltaSpannerDuration}. In the next example, the -bracket only lasts one measure, which is a duration of 3/4. +@refbugs +A score that starts with a @code{\grace} section needs an explicit +@code{\context Voice} declaration, otherwise the main note and the grace +note end up on different staves. +Grace note synchronization can also lead to surprises. Staff notation, +such as key signatures, bar lines, etc., are also synchronized. Take +care when you mix staves with grace notes and staves without, for example, -@lilypond[verbatim,raggedright,quote] -\relative c''{ - \time 3/4 - c c c - \set Staff.voltaSpannerDuration = #(ly:make-moment 3 4) - \repeat "volta" 5 { d d d } - \alternative { { e e e f f f } - { g g g } } -} +@lilypond[quote,raggedright,relative=2,verbatim,fragment] +<< \new Staff { e4 \bar "|:" \grace c16 d4 } + \new Staff { c4 \bar "|:" d4 } >> @end lilypond +@noindent +This can be remedied by inserting grace skips, for the above example -@seealso - -Examples: - -Brackets for the repeat are normally only printed over the topmost -staff. This can be adjusted by setting the @code{voltaOnThisStaff} -property; see @inputfileref{input/@/regression,volta@/-multi@/-staff@/.ly}. +@example +\new Staff @{ c4 \bar "|:" \grace s16 d4 @} +@end example -@c not necessary -@c @inputfileref{input/@/regression,volta@/-chord@/-names@/.ly}. +Grace sections should only be used within sequential music +expressions. Nesting or juxtaposing grace sections is not supported, +and might produce crashes or other errors. -@refbugs +@node Fingering instructions +@subsection Fingering instructions -A nested repeat like +@cindex fingering +Fingering instructions can be entered using @example -\repeat @dots{} -\repeat @dots{} -\alternative +@var{note}-@var{digit} @end example +For finger changes, use markup texts -@noindent -is ambiguous, since it is is not clear to which @code{\repeat} the -@code{\alternative} belongs. This ambiguity is resolved by always -having the @code{\alternative} belong to the inner @code{\repeat}. -For clarity, it is advisable to use braces in such situations. -@cindex ambiguity +@lilypond[quote,verbatim,raggedright,fragment,relative=1] +c4-1 c-2 c-3 c-4 +c^\markup { \finger "2-3" } +@end lilypond + +@cindex finger change +@cindex scripts +@cindex superscript +@cindex subscript +You can use the thumb-script to indicate that a note should be +played with the thumb (e.g., in cello music) +@lilypond[quote,verbatim,raggedright,fragment,relative=2] +8 +@end lilypond +Fingerings for chords can also be added to individual notes +of the chord by adding them after the pitches +@lilypond[quote,verbatim,raggedright,fragment,relative=2] +< c-1 e-2 g-3 b-5 >4 +@end lilypond -Timing information is not remembered at the start of an alternative, -so after a repeat timing information must be reset by hand, for -example by setting @code{Score.measurePosition} or entering -@code{\partial}. Similarly, slurs or ties are also not repeated. +@noindent +In this case, setting @code{fingeringOrientations} will put fingerings next +to note heads +@lilypond[quote,verbatim,raggedright,fragment,relative=1] +\set fingeringOrientations = #'(left down) + 4 +\set fingeringOrientations = #'(up right down) + 4 +@end lilypond +Using this feature, it is also possible to put fingering instructions +very close to note heads in monophonic music, +@lilypond[verbatim,raggedright,quote,fragment] +\set fingeringOrientations = #'(right) +4 +@end lilypond -@node Repeats and MIDI -@subsection Repeats and MIDI -@cindex expanding repeats +@seealso -With a little bit of tweaking, all types of repeats can be present -in the MIDI output. This is achieved by applying the -@code{\unfoldrepeats} music function. This functions changes all -repeats to unfold repeats. +Program reference: @internalsref{FingerEvent}, and @internalsref{Fingering}. -@lilypond[quote,verbatim,fragment,linewidth=8.0\cm] -\unfoldrepeats { - \repeat tremolo 8 {c'32 e' } - \repeat percent 2 { c''8 d'' } - \repeat volta 2 {c'4 d' e' f'} - \alternative { - { g' a' a' g' } - {f' e' d' c' } - } -} -\bar "|." -@end lilypond +Examples: @inputfileref{input/@/regression,finger@/-chords@/.ly}. -When creating a score file using @code{\unfoldrepeats} for midi, then -it is necessary to make two @code{\score} blocks. One for MIDI (with -unfolded repeats) and one for notation (with volta, tremolo, and -percent repeats). For example, -@example -\score @{ - @var{..music..} - \layout @{ .. @} -@} -\score @{ - \unfoldrepeats @var{..music..} - \midi @{ .. @} -@} -@end example -@node Manual repeat commands -@subsection Manual repeat commands -@cindex @code{repeatCommands} +@node Expressive marks +@section Expressive marks -The property @code{repeatCommands} can be used to control the layout of -repeats. Its value is a Scheme list of repeat commands. +Expressive marks help musicians to bring more to the music than simple +notes and rhythms. -@table @asis -@item @code{start-repeat} -Print a @code{|:} bar line. +@menu +* Slurs:: +* Phrasing slurs:: +* Articulations:: +* Dynamics:: +* Breath marks:: +* Running trills:: +* Glissando:: +* Arpeggio:: +@end menu -@item @code{end-repeat} -Print a @code{:|} bar line. -@item @code{(volta @var{text})} -Print a volta bracket saying @var{text}: The text can be specified as -a text string or as a markup text, see @ref{Text markup}. Do not -forget to change the font, as the default number font does not contain -alphabetic characters; +@node Slurs +@subsection Slurs +@cindex Slurs -@item @code{(volta #f)} -Stop a running volta bracket. -@end table +A slur indicates that notes are to be played bound or @emph{legato}. -@lilypond[quote,raggedright,verbatim,fragment,relative=2] -c4 - \set Score.repeatCommands = #'((volta "93") end-repeat) -c4 c4 - \set Score.repeatCommands = #'((volta #f)) -c4 c4 +They are entered using parentheses +@lilypond[quote,raggedright,relative=2,fragment,verbatim] +f( g a) a8 b( a4 g2 f4) +2( 2) @end lilypond +The direction of a slur can be set with the +generic commands +@example +\override Slur #'direction = #UP +\slurUp % shortcut for the previous line +@end example -@seealso +@noindent +However, there is a convenient shorthand for forcing slur +directions. By adding @code{_} or @code{^} before the opening +parentheses, the direction is also set. For example, -Program reference: @internalsref{VoltaBracket}, @internalsref{RepeatedMusic}, -@internalsref{VoltaRepeatedMusic}, -@internalsref{UnfoldedRepeatedMusic}, and -@internalsref{FoldedRepeatedMusic}. +@lilypond[relative=2,raggedright,quote,verbatim,fragment] +c4_( c) c^( c) +@end lilypond -@node Tremolo repeats -@subsection Tremolo repeats -@cindex tremolo beams +Some composers write two slurs when they want legato chords. This can +be achieved in LilyPond by setting @code{doubleSlurs}, -To place tremolo marks between notes, use @code{\repeat} with tremolo -style -@lilypond[quote,verbatim,raggedright] -\new Voice \relative c' { - \repeat "tremolo" 8 { c16 d16 } - \repeat "tremolo" 4 { c16 d16 } - \repeat "tremolo" 2 { c16 d16 } -} -@end lilypond - -Tremolo marks can also be put on a single note. In this case, the -note should not be surrounded by braces. -@lilypond[quote,verbatim,raggedright] -\repeat "tremolo" 4 c'16 -@end lilypond - -Similar output is obtained using the tremolo subdivision, described in -@ref{Tremolo subdivisions}. - -@seealso - -In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}. - -Program reference: tremolo beams are @internalsref{Beam} objects. Single stem -tremolos are @internalsref{StemTremolo} objects. The music expression is -@internalsref{TremoloEvent}. - -Example files: @inputfileref{input/@/regression,chord@/-tremolo@/.ly}, -@inputfileref{input/@/regression,stem@/-tremolo@/.ly}. - -@node Tremolo subdivisions -@subsection Tremolo subdivisions -@cindex tremolo marks -@cindex @code{tremoloFlags} - -Tremolo marks can be printed on a single note by adding -`@code{:}[@var{number}]' after the note. The number indicates the -duration of the subdivision, and it must be at least 8. A -@var{length} value of 8 gives one line across the note stem. If the -length is omitted, the last value (stored in @code{tremoloFlags}) is -used - -@lilypond[quote,raggedright,verbatim,fragment] -c'2:8 c':32 | c': c': | -@end lilypond - -@c [TODO: stok is te kort bij 32en] -@c somebody want to translate that into English? -@c `Stem is too short for 32nds' (wl) - -@refbugs - -Tremolos entered in this way do not carry over into the MIDI output. - -@seealso - -In this manual: @ref{Tremolo repeats}. - -Elsewhere: @internalsref{StemTremolo}, @internalsref{TremoloEvent}. - -@node Measure repeats -@subsection Measure repeats - -@cindex percent repeats -@cindex measure repeats - -In the @code{percent} style, a note pattern can be repeated. It is -printed once, and then the pattern is replaced with a special sign. -Patterns of one and two measures are replaced by percent-like signs, -patterns that divide the measure length are replaced by slashes. -Percent repeats must be declared within a @code{Voice} context. - -@lilypond[quote,verbatim,raggedright] -\new Voice \relative c' { - \repeat "percent" 4 { c4 } - \repeat "percent" 2 { c2 es2 f4 fis4 g4 c4 } -} -@end lilypond - -@seealso - -Program reference: @internalsref{RepeatSlash}, @internalsref{PercentRepeat}, -@internalsref{PercentRepeatedMusic}, and -@internalsref{DoublePercentRepeat}. - - -@node Expressive marks -@section Expressive marks - - -@c todo: should change ordering -@c where to put text spanners, metronome marks, -@c fingering? - -Expressive marks help musicians to bring more to the music than simple -notes and rhythms. - -@menu -* Slurs:: -* Phrasing slurs:: -* Breath marks:: -* Running trills:: -* Fingering instructions:: -* Grace notes:: -* Glissando:: -* Dynamics:: -@end menu - - -@node Slurs -@subsection Slurs -@cindex Slurs - -A slur indicates that notes are to be played bound or @emph{legato}. - -They are entered using parentheses -@lilypond[quote,raggedright,relative=2,fragment,verbatim] -f( g a) a8 b( a4 g2 f4) -2( 2) -@end lilypond - -The direction of a slur can be set with the -generic commands - -@example -\override Slur #'direction = #UP -\slurUp % shortcut for the previous line -@end example - -@noindent -However, there is a convenient shorthand for forcing slur -directions. By adding @code{_} or @code{^} before the opening -parentheses, the direction is also set. For example, - -@lilypond[relative=2,raggedright,quote,verbatim,fragment] -c4_( c) c^( c) -@end lilypond - -Some composers write two slurs when they want legato chords. This can -be achieved in LilyPond by setting @code{doubleSlurs}, - -@lilypond[verbatim,raggedright,relative,fragment,quote] -\set doubleSlurs = ##t -4 ( ) +@lilypond[verbatim,raggedright,relative,fragment,quote] +\set doubleSlurs = ##t +4 ( ) @end lilypond @@ -2588,442 +1803,993 @@ Program reference: see also @internalsref{PhrasingSlur}, and Putting phrasing slurs over rests leads to spurious warnings. -@node Breath marks -@subsection Breath marks -Breath marks are entered using @code{\breathe} +@node Articulations +@subsection Articulations +@cindex Articulations +@cindex articulations +@cindex scripts +@cindex ornaments -@lilypond[quote,raggedright,fragment,relative=1,verbatim] -c'4 \breathe d4 +A variety of symbols can appear above and below notes to indicate +different characteristics of the performance. They are added to a note +by adding a dash and the character signifying the +articulation. They are demonstrated here + +@lilypondfile[quote,raggedright]{script-abbreviations.ly} + +The meanings of these shorthands can be changed. See +@file{ly/@/script@/-init@/.ly} for examples. + + +The script is automatically placed, but the direction can be forced as +well. Like other pieces of LilyPond code, @code{_} will place them +below the staff, and @code{^} will place them above. + + +@lilypond[quote,raggedright,fragment,verbatim] +c''4^^ c''4_^ @end lilypond -The glyph of the breath mark can be tuned by overriding the -@code{text} property of the @code{BreathingSign} layout object with -any markup text. For example, -@lilypond[quote,raggedright,fragment,verbatim,relative=1] -c'4 -\override BreathingSign #'text - = #(make-musicglyph-markup "scripts.rvarcomma") -\breathe -d4 +Other symbols can be added using the syntax +@var{note}@code{\}@var{name}. Again, they +can be forced up or down using @code{^} and @code{_}, +e.g., + +@lilypond[quote,raggedright,verbatim,fragment,relative=2] +c\fermata c^\fermata c_\fermata @end lilypond -@seealso -Program reference: @internalsref{BreathingSign}, -@internalsref{BreathingSignEvent}. -Examples: @inputfileref{input/@/regression,breathing@/-sign@/.ly}. +@cindex accent +@cindex marcato +@cindex staccatissimo +@cindex espressivo +@cindex fermata +@cindex stopped +@cindex staccato +@cindex portato +@cindex tenuto +@cindex upbow +@cindex downbow +@cindex foot marks +@cindex organ pedal marks +@cindex turn +@cindex open +@cindex flageolet +@cindex reverseturn +@cindex trill +@cindex prall +@cindex mordent +@cindex prallprall +@cindex prallmordent +@cindex prall, up +@cindex prall, down +@cindex mordent +@cindex thumb marking +@cindex segno +@cindex coda +@cindex varcoda +Here is a chart showing all scripts available, -@node Running trills -@subsection Running trills +@lilypondfile[raggedright,quote]{script-chart.ly} -Long running trills are made with @code{\startTrillSpan} and -@code{\stopTrillSpan}, +The vertical ordering of scripts is controlled with the +@code{script-priority} property. The lower this number, the closer it +will be put to the note. In this example, the +@internalsref{TextScript} (the sharp symbol) first has the lowest +priority, so it is put lowest in the first example. In the second, the +prall trill (the @internalsref{Script}) has the lowest, so it is on the +inside. When two objects have the same priority, the order in which +they are entered decides which one comes first. -@lilypond[verbatim,raggedright,relative=2,quote,fragment] -\new Voice { - << { c1 \startTrillSpan } - { s2. \grace { d16[\stopTrillSpan e] } } >> - c4 } + +@lilypond[verbatim,relative=3,raggedright,fragment,quote] +\once \override TextScript #'script-priority = #-100 +a4^\prall^\markup { \sharp } + +\once \override Script #'script-priority = #-100 +a4^\prall^\markup { \sharp } @end lilypond -@refcommands -@code{\startTrillSpan}, -@cindex @code{\startTrillSpan} -@code{\stopTrillSpan}. -@cindex @code{\stopTrillSpan} + @seealso -Program reference: @internalsref{TrillSpanner}, -@internalsref{TrillSpanEvent}. +Program reference: @internalsref{ScriptEvent}, and @internalsref{Script}. -@node Fingering instructions -@subsection Fingering instructions +@refbugs -@cindex fingering +These signs appear in the printed output but have no effect on the +MIDI rendering of the music. -Fingering instructions can be entered using -@example -@var{note}-@var{digit} -@end example -For finger changes, use markup texts -@lilypond[quote,verbatim,raggedright,fragment,relative=1] -c4-1 c-2 c-3 c-4 -c^\markup { \finger "2-3" } -@end lilypond +@node Dynamics +@subsection Dynamics +@cindex Dynamics -@cindex finger change -@cindex scripts -@cindex superscript -@cindex subscript -You can use the thumb-script to indicate that a note should be -played with the thumb (e.g., in cello music) + +@cindex @code{\ppp} +@cindex @code{\pp} +@cindex @code{\p} +@cindex @code{\mp} +@cindex @code{\mf} +@cindex @code{\f} +@cindex @code{\ff} +@cindex @code{\fff} +@cindex @code{\ffff} +@cindex @code{\fp} +@cindex @code{\sf} +@cindex @code{\sff} +@cindex @code{\sp} +@cindex @code{\spp} +@cindex @code{\sfz} +@cindex @code{\rfz} + + +Absolute dynamic marks are specified using a command after a note +@code{c4\ff}. The available dynamic marks are @code{\ppp}, +@code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff}, +@code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff}, +@code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz} + @lilypond[quote,verbatim,raggedright,fragment,relative=2] -8 +c\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff +c2\fp c\sf c\sff c\sp c\spp c\sfz c\rfz @end lilypond -Fingerings for chords can also be added to individual notes -of the chord by adding them after the pitches -@lilypond[quote,verbatim,raggedright,fragment,relative=2] -< c-1 e-2 g-3 b-5 >4 +@cindex @code{\<} +@cindex @code{\>} +@cindex @code{\"!} + + + +A crescendo mark is started with @code{\<} and terminated with +@code{\!}. A decrescendo is started with @code{\>} and also terminated +with @code{\!}. Because these marks are bound to notes, you must +use spacer notes if multiple marks are needed during one note + +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +c\< c\! d\> e\! +<< f1 { s4 s4\< s4\! \> s4\! } >> @end lilypond +This may give rise to very short hairpins. Use @code{minimum-length} +in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for +example -@noindent -In this case, setting @code{fingeringOrientations} will put fingerings next -to note heads +@example +\override Staff.Hairpin #'minimum-length = #5 +@end example + +You can also use a text saying @emph{cresc.} instead of hairpins. Here +is an example how to do it + +@lilypond[quote,raggedright,fragment,relative=2,verbatim] +\setTextCresc +c\< d e f\! +\setHairpinCresc +e\> d c b\! +\setTextDecresc +c\> d e f\! +\setTextDim +e\> d c b\! +@end lilypond + +@cindex crescendo +@cindex decrescendo + +You can also supply your own texts +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +\set crescendoText = \markup { \italic "cresc. poco" } +\set crescendoSpanner = #'dashed-line +a'2\< a a a\!\mf +@end lilypond + +@cindex diminuendo + +To create new dynamic marks or text that should be aligned +with dynamics, see @ref{New dynamic marks}. + + +@refcommands + +@cindex @code{\dynamicUp} +@code{\dynamicUp}, +@cindex @code{\dynamicDown} +@code{\dynamicDown}, +@cindex @code{\dynamicNeutral} +@code{\dynamicNeutral}. + +@cindex direction, of dynamics + +@seealso + +Program reference: @internalsref{CrescendoEvent}, +@internalsref{DecrescendoEvent}, and +@internalsref{AbsoluteDynamicEvent}. + +Dynamics are @internalsref{DynamicText} and @internalsref{Hairpin} +objects. Vertical positioning of these symbols is handled by the +@internalsref{DynamicLineSpanner} object. + +@node Breath marks +@subsection Breath marks + +Breath marks are entered using @code{\breathe} + + +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +c'4 \breathe d4 +@end lilypond + +The glyph of the breath mark can be tuned by overriding the +@code{text} property of the @code{BreathingSign} layout object with +any markup text. For example, +@lilypond[quote,raggedright,fragment,verbatim,relative=1] +c'4 +\override BreathingSign #'text + = #(make-musicglyph-markup "scripts.rvarcomma") +\breathe +d4 +@end lilypond + +@seealso + +Program reference: @internalsref{BreathingSign}, +@internalsref{BreathingSignEvent}. + +Examples: @inputfileref{input/@/regression,breathing@/-sign@/.ly}. + + +@node Running trills +@subsection Running trills + +Long running trills are made with @code{\startTrillSpan} and +@code{\stopTrillSpan}, + + +@lilypond[verbatim,raggedright,relative=2,quote,fragment] +\new Voice { + << { c1 \startTrillSpan } + { s2. \grace { d16[\stopTrillSpan e] } } >> + c4 } +@end lilypond + +@refcommands + +@code{\startTrillSpan}, +@cindex @code{\startTrillSpan} +@code{\stopTrillSpan}. +@cindex @code{\stopTrillSpan} + +@seealso + +Program reference: @internalsref{TrillSpanner}, +@internalsref{TrillSpanEvent}. + + + + +@node Glissando +@subsection Glissando +@cindex Glissando + +@cindex @code{\glissando} + +A glissando is a smooth change in pitch. It is denoted by a line or a +wavy line between two notes. It is requested by attaching +@code{\glissando} to a note + +@lilypond[quote,raggedright,fragment,relative=2,verbatim] +c\glissando c' +@end lilypond + +@seealso + +Program reference: @internalsref{Glissando}, and @internalsref{GlissandoEvent}. + +Example files: @file{input/@/regression/@/glissando@/.ly}. + + + +@refbugs + +Printing text over the line (such as @emph{gliss.}) is not supported. + + +@node Arpeggio +@subsection Arpeggio +@cindex Arpeggio + +@cindex broken chord +@cindex @code{\arpeggio} + +You can specify an arpeggio sign (also known as broken chord) on a +chord by attaching an @code{\arpeggio} to a chord + + +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +\arpeggio +@end lilypond + +When an arpeggio crosses staves, you attach an arpeggio to the chords +in both staves, and set +@internalsref{PianoStaff}.@code{connectArpeggios} + +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +\context PianoStaff << + \set PianoStaff.connectArpeggios = ##t + \new Staff { \arpeggio } + \new Staff { \clef bass \arpeggio } +>> +@end lilypond + +The direction of the arpeggio is sometimes denoted by adding an +arrowhead to the wiggly line + +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +\context Voice { + \arpeggioUp + \arpeggio + \arpeggioDown + \arpeggio +} +@end lilypond + +A square bracket on the left indicates that the player should not +arpeggiate the chord + +@c todo: ugh, lousy typography. Look for real example. --hwn + +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +\arpeggioBracket +\arpeggio +@end lilypond + +@refcommands + +@cindex @code{\arpeggio} +@code{\arpeggio}, +@cindex @code{\arpeggioUp} +@code{\arpeggioUp}, +@cindex @code{\arpeggioDown} +@code{\arpeggioDown}, +@cindex @code{\arpeggioNeutral} +@code{\arpeggioNeutral}, +@cindex @code{\arpeggioBracket} +@code{\arpeggioBracket}. + +@seealso + +Notation manual: @ref{Ties}, for writing out arpeggios. + +Program reference: @internalsref{ArpeggioEvent}, +@internalsref{Arpeggio}. + + + +@refbugs + +It is not possible to mix connected arpeggios and unconnected +arpeggios in one @internalsref{PianoStaff} at the same point in time. + + + +@node Polyphony +@section Polyphony + +Polyphony in music refers to having more than one voice occuring in +a piece of music. Polyphony in LilyPond refers to having more than +one voice on the same staff. + +@menu +* Basic polyphony:: +* Explicitly instantiating voices:: +* Collision Resolution:: +@end menu + +@node Basic polyphony +@subsection Basic polyphony +@cindex polyphony + +The easiest way to enter fragments with more than one voice on a staff +is to enter each voice as a sequence (with @code{@{...@}}), and combine +them simultaneously, separating the voices with @code{\\} + +@cindex @code{\\} + +@lilypond[quote,verbatim,fragment] +\new Staff \relative c' { + c16 d e f + << { g4 f e | d2 e2 } \\ + { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\ + { s2. | s4 b4 c2 } + >> +} +@end lilypond + +The separator causes @internalsref{Voice} contexts@footnote{Polyphonic +voices are sometimes called ``layers'' in other notation packages} +@cindex layers +to be instantiated. They bear the names @code{"1"}, @code{"2"}, etc. In +each of these contexts, vertical direction of slurs, stems, etc., is set +appropriately. + +These voices are all seperate from the voice that contains the notes just +outside the @code{<< \\ >>} construct. This should be noted when making +changes at the voice level. This also means that slurs and ties cannot go +into or out of a @code{<< \\ >>} construct. +Conversely, parallel voices from separate @code{<< \\ >>} constructs on the +same staff are the the same voice. +Here is the same example, with different noteheads for each voice. +Note that the change to the note-head style in the main voice does not affect +the inside of the @code{<< \\ >>} constructs. Also, the change to the second +voice in the first @code{<< \\ >>} construct is effective in the second +@code{<< \\ >>}, and the voice is tied accross the two constructs. + +@lilypond[quote,verbatim,fragment] +\new Staff \relative c' { + \override NoteHead #'style = #'cross + c16 d e f + << + { g4 f e } \\ + { \override NoteHead #'style = #'triangle + r8 e4 d c8 ~ + } + >> | + << + { d2 e2 } \\ + { c8 b16 a b8 g ~ g2 } \\ + { \override NoteHead #'style = #'slash s4 b4 c2 } + >> +} +@end lilypond + +@node Explicitly instantiating voices +@subsection Explicitly instantiating voices + +@internalsref{Voice} contexts can also also be instantiated manually +inside a @code{<< >>} block to create polyphonic music, using +@code{\voiceOne}, up to @code{\voiceFour} to assign stem directions +and a horizontal shift for each part. + +Specifically, +@example +<< \upper \\ \lower >> +@end example + +@noindent +is equivalent to + +@example +<< + \context Voice = "1" @{ \voiceOne \upper @} + \context Voice = "2" @{ \voiceTwo \lower @} +>> +@end example + +@cindex @code{\voiceOne} +@cindex @code{\voiceFour} + +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} make +these objects point upwards, while @code{\voiceTwo} and @code{\voiceFour} +make them point downwards. +The command @code{\oneVoice} will revert back to the normal setting. +@cindex @code{\oneVoice} + +An expression that appears directly inside a @code{<< >>} belongs to +the main voice. This is useful when extra voices appear while the main +voice is playing. Here is a more correct rendition of the example from +the previous section. The crossed noteheads demonstrate that the main +melody is now in a single voice context. + +@lilypond[quote,raggedright,verbatim] +\new Staff \relative c' { + \override NoteHead #'style = #'cross + c16 d e f + \voiceOne + << + { g4 f e | d2 e2} + \context Voice="1" { \voiceTwo + r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 + \oneVoice + } + \new Voice { \voiceThree + s2. | s4 b4 c2 + \oneVoice + } + >> + \oneVoice +} +@end lilypond + +The correct definition of the voices allows the melody to be slurred. +@lilypond[quote,raggedright,verbatim] +\new Staff \relative c' { + c16^( d e f + \voiceOne + << + { g4 f e | d2 e2) } + \context Voice="1" { \voiceTwo + r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 + \oneVoice + } + \new Voice { \voiceThree + s2. s4 b4 c2 + \oneVoice + } + >> + \oneVoice +} +@end lilypond + +Avoiding the @code{\\} seperator also allows nesting polyphony +constructs, which in some case might be a more natural way to typeset +the music. + +@lilypond[quote,raggedright,verbatim] +\new Staff \relative c' { + c16^( d e f + \voiceOne + << + { g4 f e | d2 e2) } + \context Voice="1" { \voiceTwo + r8 e4 d c8 ~ | + << + {c8 b16 a b8 g ~ g2} + \new Voice { \voiceThree + s4 b4 c2 + \oneVoice + } + >> + \oneVoice + } + >> + \oneVoice +} +@end lilypond + +@node Collision Resolution +@subsection Collision Resolution + +Normally, note heads with a different number of dots are not merged, but +when the object property @code{merge-differently-dotted} is set in +the @internalsref{NoteCollision} object, they are merged +@lilypond[quote,verbatim,fragment,raggedright,relative=2] +\context Voice << { + g8 g8 + \override Staff.NoteCollision + #'merge-differently-dotted = ##t + g8 g8 +} \\ { g8.[ f16] g8.[ f16] } >> +@end lilypond + +Similarly, you can merge half note heads with eighth notes, by setting +@code{merge-differently-headed} +@lilypond[quote,raggedright,fragment,relative=2,verbatim] +\context Voice << { + c8 c4. + \override Staff.NoteCollision + #'merge-differently-headed = ##t +c8 c4. } \\ { c2 c2 } >> +@end lilypond + +LilyPond also vertically shifts rests that are opposite of a stem, +for example + +@lilypond[quote,raggedright,fragment,verbatim] +\context Voice << c''4 \\ r4 >> +@end lilypond + + +@refcommands + + + +@cindex @code{\oneVoice} +@code{\oneVoice}, +@cindex @code{\voiceOne} +@code{\voiceOne}, +@cindex @code{\voiceTwo} +@code{\voiceTwo}, +@cindex @code{\voiceThree} +@code{\voiceThree}, +@cindex @code{\voiceFour} +@code{\voiceFour}. + + + +@cindex @code{\shiftOn} +@code{\shiftOn}, +@cindex @code{\shiftOnn} +@code{\shiftOnn}, +@cindex @code{\shiftOnnn} +@code{\shiftOnnn}, +@cindex @code{\shiftOff} +@code{\shiftOff}: these commands specify in what chords of the current +voice should be shifted. The outer voices (normally: voice one and +two) have @code{\shiftOff}, while the inner voices (three and four) +have @code{\shiftOn}. @code{\shiftOnn} and @code{\shiftOnnn} define +further shift levels. -@lilypond[quote,verbatim,raggedright,fragment,relative=1] -\set fingeringOrientations = #'(left down) - 4 -\set fingeringOrientations = #'(up right down) - 4 -@end lilypond -Using this feature, it is also possible to put fingering instructions -very close to note heads in monophonic music, +When LilyPond cannot cope, the @code{force-hshift} +property of the @internalsref{NoteColumn} object and pitched rests can +be used to override typesetting decisions. -@lilypond[verbatim,raggedright,quote,fragment] -\set fingeringOrientations = #'(right) -4 +@lilypond[quote,verbatim,raggedright] +\relative << +{ + + +} \\ { + + \once \override NoteColumn #'force-hshift = #1.7 + +} >> @end lilypond -@seealso - -Program reference: @internalsref{FingerEvent}, and @internalsref{Fingering}. - -Examples: @inputfileref{input/@/regression,finger@/-chords@/.ly}. +@seealso +Program reference: the objects responsible for resolving collisions are +@internalsref{NoteCollision} and @internalsref{RestCollision}. +Examples: +@inputfileref{input/@/regression,collision@/-dots@/.ly}, +@inputfileref{input/@/regression,collision@/-head-chords@/.ly}, +@inputfileref{input/@/regression,collision@/-heads@/.ly}, +@inputfileref{input/@/regression,collision@/-mesh@/.ly}, and +@inputfileref{input/@/regression,collisions@/.ly}. -@node Grace notes -@subsection Grace notes +@refbugs -@c should have blurb about accaciatura / appogiatura -@cindex @code{\grace} -@cindex ornaments -@cindex grace notes +When using @code{merge-differently-headed} with an upstem eighth or a +shorter note, and a downstem half note, the eighth note gets the wrong +offset. -Grace notes are ornaments that are written out. The most common ones -are acciaccatura, which should be played as very short. It is denoted -by a slurred small note with a slashed stem. The appoggiatura is a -grace note that takes a fixed fraction of the main note, and is -denoted as a slurred note in small print without a slash. They -are entered with the commands @code{\acciaccatura} and -@code{\appoggiatura}, as demonstrated in the following example +There is no support for clusters where the same note occurs with +different accidentals in the same chord. In this case, it is +recommended to use enharmonic transcription, or to use special cluster +notation (see @ref{Clusters}). -@cindex appoggiatura -@cindex acciaccatura -@lilypond[quote,raggedright,relative=2,verbatim,fragment] -b4 \acciaccatura d8 c4 \appoggiatura e8 d4 -\acciaccatura { g16[ f] } e4 -@end lilypond +@node Repeats +@section Repeats -Both are special forms of the @code{\grace} command. By prefixing this -keyword to a music expression, a new one is formed, which will be -printed in a smaller font and takes up no logical time in a measure. +Repetition is a central concept in music, and multiple notations exist +for repetitions. -@lilypond[quote,raggedright,relative=2,verbatim,fragment] -c4 \grace c16 c4 -\grace { c16[ d16] } c2 c4 -@end lilypond +@menu +* Repeat types:: +* Repeat syntax:: +* Repeats and MIDI:: +* Manual repeat commands:: +* Tremolo repeats:: +* Tremolo subdivisions:: +* Measure repeats:: +@end menu -@noindent -Unlike @code{\acciaccatura} and @code{\appoggiatura}, the -@code{\grace} command does not start a slur. +@node Repeat types +@subsection Repeat types -Internally, timing for grace notes is done using a second, `grace' -timing. Every point in time consists of two rational numbers: one -denotes the logical time, one denotes the grace timing. The above -example is shown here with timing tuples +@cindex repeats +@cindex @code{\repeat} -@lilypond[quote,raggedright] -<< - \relative c''{ - c4 \grace c16 c4 \grace { - c16[ d16] } c2 c4 - } - \new Lyrics \lyricmode { - \override LyricText #'font-family = #'typewriter +The following types of repetition are supported - \markup { (0,0) } 4 - \grace { \markup { - ( \fraction 1 4 , \fraction -1 16 ) } 16 } - \markup { (\fraction 1 4 , 0 ) } 4 - \grace { - \markup { (\fraction 2 4 , \fraction "-1" 8 ) } 16 - \markup { (\fraction 2 4 , \fraction "-1" 16 ) } 16 - } - \markup { ( \fraction 2 4 , 0 ) } - } ->> -@end lilypond +@table @code +@item unfold +Repeated music is fully written (played) out. This is useful when +entering repetitious music. This is the only kind of repeat that +is included in MIDI output. +@item volta +Repeats are not written out, but alternative endings (volte) are +printed, left to right with brackets. This is the standard notation +for repeats with alternatives. These are not played in MIDI output by default. -The placement of grace notes is synchronized between different staves. -In the following example, there are two sixteenth grace notes for -every eighth grace note +@ignore +@item fold +Alternative endings are written stacked. This has limited use but may be +used to typeset two lines of lyrics in songs with repeats, see +@inputfileref{input,star-spangled-banner@/.ly}. +@end ignore -@lilypond[quote,raggedright,relative=2,verbatim,fragment] -<< \new Staff { e4 \grace { c16[ d e f] } e4 } - \new Staff { c4 \grace { g8[ b] } c4 } >> -@end lilypond +@c tremolo, beamed +@item tremolo +Make tremolo beams. These are not played in MIDI output by default. +@item percent +Make beat or measure repeats. These look like percent signs. These +are not played in MIDI output by default. Percent repeats must be +declared within a Voice context. +@end table -If you want to end a note with a grace, use the @code{\afterGrace} -command. It takes two arguments: the main note, and the grace notes -following the main note. +@node Repeat syntax +@subsection Repeat syntax -@lilypond[raggedright, verbatim,relative=2,fragment] -c1 \afterGrace d1 { c16[ d] } c4 -@end lilypond -This will put the grace notes after a ``space'' lasting 3/4 of the -length of the main note. The fraction 3/4 can be changed by setting -@code{afterGraceFraction}, ie. +LilyPond has one syntactic construct for specifying different types of +repeats. The syntax is @example -afterGraceFraction = #(cons 7 8) +\repeat @var{variant} @var{repeatcount} @var{repeatbody} @end example -@noindent -will put the grace note at 7/8 of the main note. +If you have alternative endings, you may add +@cindex @code{\alternative} +@example +\alternative @{ @var{alternative1} + @var{alternative2} + @var{alternative3} @dots{} @} +@end example +where each @var{alternative} is a music expression. If you do not +give enough alternatives for all of the repeats, the first alternative +is assumed to be played more than once. +Standard repeats are used like this +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +c1 +\repeat volta 2 { c4 d e f } +\repeat volta 2 { f e d c } +@end lilypond -The same effect can be achieved manually by doing +With alternative endings +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +c1 +\repeat volta 2 {c4 d e f} +\alternative { {d2 d} {f f,} } +@end lilypond @lilypond[quote,raggedright,fragment,verbatim,relative=2] -\context Voice { - << { d1^\trill_( } - { s2 \grace { c16[ d] } } >> - c4) +\context Staff { + \partial 4 + \repeat volta 4 { e | c2 d2 | e2 f2 | } + \alternative { { g4 g g } { a | a a a a | b2. } } } @end lilypond -@noindent -By adjusting the duration of the skip note (here it is a half-note), -the space between the main-note and the grace is adjusted. - +It is possible to shorten volta brackets +by setting @code{voltaSpannerDuration}. In the next example, the +bracket only lasts one measure, which is a duration of 3/4. -A @code{\grace} section will introduce special typesetting settings, -for example, to produce smaller type, and set directions. Hence, when -introducing layout tweaks, they should be inside the grace section, -for example, -@lilypond[quote,raggedright,fragment,verbatim,relative=2] -\new Voice { - \acciaccatura { - \stemDown - f16-> - \stemNeutral - } - g4 +@lilypond[verbatim,raggedright,quote] +\relative c''{ + \time 3/4 + c c c + \set Staff.voltaSpannerDuration = #(ly:make-moment 3 4) + \repeat "volta" 5 { d d d } + \alternative { { e e e f f f } + { g g g } } } @end lilypond -@noindent -The overrides should also be reverted inside the grace section. -The layout of grace sections can be changed throughout the music using -the function @code{add-grace-property}. The following example -undefines the Stem direction for this grace, so stems do not always -point up. +@seealso + +Examples: + +Brackets for the repeat are normally only printed over the topmost +staff. This can be adjusted by setting the @code{voltaOnThisStaff} +property; see @inputfileref{input/@/regression,volta@/-multi@/-staff@/.ly}. + +@c not necessary +@c @inputfileref{input/@/regression,volta@/-chord@/-names@/.ly}. + + +@refbugs + +A nested repeat like @example -\new Staff @{ - #(add-grace-property 'Voice 'Stem 'direction '()) - @dots{} -@} +\repeat @dots{} +\repeat @dots{} +\alternative @end example -@noindent -Another option is to change the variables @code{startGraceMusic}, -@code{stopGraceMusic}, @code{startAcciaccaturaMusic}, -@code{stopAcciaccaturaMusic}, @code{startAppoggiaturaMusic}, -@code{stopAppoggiaturaMusic}. More information is in the file -@file{ly/@/grace@/-init@/.ly}. +@noindent +is ambiguous, since it is is not clear to which @code{\repeat} the +@code{\alternative} belongs. This ambiguity is resolved by always +having the @code{\alternative} belong to the inner @code{\repeat}. +For clarity, it is advisable to use braces in such situations. +@cindex ambiguity + -@seealso +Timing information is not remembered at the start of an alternative, +so after a repeat timing information must be reset by hand, for +example by setting @code{Score.measurePosition} or entering +@code{\partial}. Similarly, slurs or ties are also not repeated. -Program reference: @internalsref{GraceMusic}. -@refbugs -A score that starts with a @code{\grace} section needs an explicit -@code{\context Voice} declaration, otherwise the main note and the grace -note end up on different staves. -Grace note synchronization can also lead to surprises. Staff notation, -such as key signatures, bar lines, etc., are also synchronized. Take -care when you mix staves with grace notes and staves without, for example, +@node Repeats and MIDI +@subsection Repeats and MIDI -@lilypond[quote,raggedright,relative=2,verbatim,fragment] -<< \new Staff { e4 \bar "|:" \grace c16 d4 } - \new Staff { c4 \bar "|:" d4 } >> +@cindex expanding repeats + +With a little bit of tweaking, all types of repeats can be present +in the MIDI output. This is achieved by applying the +@code{\unfoldrepeats} music function. This functions changes all +repeats to unfold repeats. + +@lilypond[quote,verbatim,fragment,linewidth=8.0\cm] +\unfoldrepeats { + \repeat tremolo 8 {c'32 e' } + \repeat percent 2 { c''8 d'' } + \repeat volta 2 {c'4 d' e' f'} + \alternative { + { g' a' a' g' } + {f' e' d' c' } + } +} +\bar "|." @end lilypond -@noindent -This can be remedied by inserting grace skips, for the above example +When creating a score file using @code{\unfoldrepeats} for midi, then +it is necessary to make two @code{\score} blocks. One for MIDI (with +unfolded repeats) and one for notation (with volta, tremolo, and +percent repeats). For example, @example -\new Staff @{ c4 \bar "|:" \grace s16 d4 @} +\score @{ + @var{..music..} + \layout @{ .. @} +@} +\score @{ + \unfoldrepeats @var{..music..} + \midi @{ .. @} +@} @end example -Grace sections should only be used within sequential music -expressions. Nesting or juxtaposing grace sections is not supported, -and might produce crashes or other errors. - - -@node Glissando -@subsection Glissando -@cindex Glissando - -@cindex @code{\glissando} +@node Manual repeat commands +@subsection Manual repeat commands -A glissando is a smooth change in pitch. It is denoted by a line or a -wavy line between two notes. It is requested by attaching -@code{\glissando} to a note +@cindex @code{repeatCommands} -@lilypond[quote,raggedright,fragment,relative=2,verbatim] -c\glissando c' -@end lilypond +The property @code{repeatCommands} can be used to control the layout of +repeats. Its value is a Scheme list of repeat commands. -@seealso +@table @asis +@item @code{start-repeat} +Print a @code{|:} bar line. -Program reference: @internalsref{Glissando}, and @internalsref{GlissandoEvent}. +@item @code{end-repeat} +Print a @code{:|} bar line. -Example files: @file{input/@/regression/@/glissando@/.ly}. +@item @code{(volta @var{text})} +Print a volta bracket saying @var{text}: The text can be specified as +a text string or as a markup text, see @ref{Text markup}. Do not +forget to change the font, as the default number font does not contain +alphabetic characters; +@item @code{(volta #f)} +Stop a running volta bracket. +@end table +@lilypond[quote,raggedright,verbatim,fragment,relative=2] +c4 + \set Score.repeatCommands = #'((volta "93") end-repeat) +c4 c4 + \set Score.repeatCommands = #'((volta #f)) +c4 c4 +@end lilypond -@refbugs -Printing text over the line (such as @emph{gliss.}) is not supported. +@seealso -@node Dynamics -@subsection Dynamics -@cindex Dynamics +Program reference: @internalsref{VoltaBracket}, @internalsref{RepeatedMusic}, +@internalsref{VoltaRepeatedMusic}, +@internalsref{UnfoldedRepeatedMusic}, and +@internalsref{FoldedRepeatedMusic}. +@node Tremolo repeats +@subsection Tremolo repeats +@cindex tremolo beams +To place tremolo marks between notes, use @code{\repeat} with tremolo +style +@lilypond[quote,verbatim,raggedright] +\new Voice \relative c' { + \repeat "tremolo" 8 { c16 d16 } + \repeat "tremolo" 4 { c16 d16 } + \repeat "tremolo" 2 { c16 d16 } +} +@end lilypond -@cindex @code{\ppp} -@cindex @code{\pp} -@cindex @code{\p} -@cindex @code{\mp} -@cindex @code{\mf} -@cindex @code{\f} -@cindex @code{\ff} -@cindex @code{\fff} -@cindex @code{\ffff} -@cindex @code{\fp} -@cindex @code{\sf} -@cindex @code{\sff} -@cindex @code{\sp} -@cindex @code{\spp} -@cindex @code{\sfz} -@cindex @code{\rfz} +Tremolo marks can also be put on a single note. In this case, the +note should not be surrounded by braces. +@lilypond[quote,verbatim,raggedright] +\repeat "tremolo" 4 c'16 +@end lilypond +Similar output is obtained using the tremolo subdivision, described in +@ref{Tremolo subdivisions}. -Absolute dynamic marks are specified using a command after a note -@code{c4\ff}. The available dynamic marks are @code{\ppp}, -@code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff}, -@code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff}, -@code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz} +@seealso -@lilypond[quote,verbatim,raggedright,fragment,relative=2] -c\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff -c2\fp c\sf c\sff c\sp c\spp c\sfz c\rfz -@end lilypond +In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}. -@cindex @code{\<} -@cindex @code{\>} -@cindex @code{\"!} +Program reference: tremolo beams are @internalsref{Beam} objects. Single stem +tremolos are @internalsref{StemTremolo} objects. The music expression is +@internalsref{TremoloEvent}. +Example files: @inputfileref{input/@/regression,chord@/-tremolo@/.ly}, +@inputfileref{input/@/regression,stem@/-tremolo@/.ly}. +@node Tremolo subdivisions +@subsection Tremolo subdivisions +@cindex tremolo marks +@cindex @code{tremoloFlags} -A crescendo mark is started with @code{\<} and terminated with -@code{\!}. A decrescendo is started with @code{\>} and also terminated -with @code{\!}. Because these marks are bound to notes, you must -use spacer notes if multiple marks are needed during one note +Tremolo marks can be printed on a single note by adding +`@code{:}[@var{number}]' after the note. The number indicates the +duration of the subdivision, and it must be at least 8. A +@var{length} value of 8 gives one line across the note stem. If the +length is omitted, the last value (stored in @code{tremoloFlags}) is +used -@lilypond[quote,raggedright,fragment,verbatim,relative=2] -c\< c\! d\> e\! -<< f1 { s4 s4\< s4\! \> s4\! } >> +@lilypond[quote,raggedright,verbatim,fragment] +c'2:8 c':32 | c': c': | @end lilypond -This may give rise to very short hairpins. Use @code{minimum-length} -in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for -example - -@example -\override Staff.Hairpin #'minimum-length = #5 -@end example -You can also use a text saying @emph{cresc.} instead of hairpins. Here -is an example how to do it +@c [TODO: stok is te kort bij 32en] +@c somebody want to translate that into English? +@c `Stem is too short for 32nds' (wl) -@lilypond[quote,raggedright,fragment,relative=2,verbatim] -\setTextCresc -c\< d e f\! -\setHairpinCresc -e\> d c b\! -\setTextDecresc -c\> d e f\! -\setTextDim -e\> d c b\! -@end lilypond +@refbugs -@cindex crescendo -@cindex decrescendo +Tremolos entered in this way do not carry over into the MIDI output. -You can also supply your own texts -@lilypond[quote,raggedright,fragment,relative=1,verbatim] -\set crescendoText = \markup { \italic "cresc. poco" } -\set crescendoSpanner = #'dashed-line -a'2\< a a a\!\mf -@end lilypond +@seealso -@cindex diminuendo +In this manual: @ref{Tremolo repeats}. -To create new dynamic marks or text that should be aligned -with dynamics, see @ref{New dynamic marks}. +Elsewhere: @internalsref{StemTremolo}, @internalsref{TremoloEvent}. +@node Measure repeats +@subsection Measure repeats -@refcommands +@cindex percent repeats +@cindex measure repeats -@cindex @code{\dynamicUp} -@code{\dynamicUp}, -@cindex @code{\dynamicDown} -@code{\dynamicDown}, -@cindex @code{\dynamicNeutral} -@code{\dynamicNeutral}. +In the @code{percent} style, a note pattern can be repeated. It is +printed once, and then the pattern is replaced with a special sign. +Patterns of one and two measures are replaced by percent-like signs, +patterns that divide the measure length are replaced by slashes. +Percent repeats must be declared within a @code{Voice} context. -@cindex direction, of dynamics +@lilypond[quote,verbatim,raggedright] +\new Voice \relative c' { + \repeat "percent" 4 { c4 } + \repeat "percent" 2 { c2 es2 f4 fis4 g4 c4 } +} +@end lilypond @seealso -Program reference: @internalsref{CrescendoEvent}, -@internalsref{DecrescendoEvent}, and -@internalsref{AbsoluteDynamicEvent}. +Program reference: @internalsref{RepeatSlash}, @internalsref{PercentRepeat}, +@internalsref{PercentRepeatedMusic}, and +@internalsref{DoublePercentRepeat}. + -Dynamics are @internalsref{DynamicText} and @internalsref{Hairpin} -objects. Vertical positioning of these symbols is handled by the -@internalsref{DynamicLineSpanner} object.