@node Rhythms
@section Rhythms
-This section discusses rhythms, durations, and bars.
+@lilypondfile[ragged-right,line-width=16\cm,staffsize=14,quote]
+{rhythms-headword.ly}
+
+This section discusses rhythms, rests, durations, beaming and bars.
@menu
* Writing rhythms::
@menu
* Durations::
-* Augmentation dots::
* Tuplets::
* Scaling durations::
+* Ties::
@end menu
@node Durations
-@unnumberedsubsubsec Durations
+@subsubsection Durations
+
+@cindex durations, of notes
+@cindex note durations
-@cindex duration
@funindex \longa
@funindex \breve
@funindex \maxima
-In Note, Chord, and Lyrics mode, durations are designated by
-numbers and dots: durations are entered as their reciprocal
-values. For example, a quarter note is entered using a @code{4}
-(since it is a 1/4 note), while a half note is entered using a
-@code{2} (since it is a 1/2 note). For notes longer than a whole
-you must use the @code{\longa} and @code{\breve} commands
-
-@example
-c'\breve
-c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
-r\longa r\breve
-r1 r2 r4 r8 r16 r32 r64 r64
-@end example
+Durations are designated by numbers and dots.
+Durations are entered as their reciprocal values. For example, a
+quarter note is entered using a @code{4} (since it is a 1/4 note),
+and a half note is entered using a @code{2} (since it is a 1/2
+note). For notes longer than a whole you must use the
+@code{\longa} (a double breve) and @code{\breve} commands.
+Durations as short as 64th notes may be specified. Shorter values
+are possible, but only as beamed notes.
+
+@c Two 64th notes are needed to obtain beams
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+\time 8/1
+c\longa c\breve c1 c2
+c4 c8 c16 c32 c64 c64
+@end lilypond
-@lilypond[quote]
-\score {
-\relative c'' {
- a\breve*1/2 \autoBeamOff
- a1 a2 a4 a8 a16 a32 a64 a64
- \bar "empty"
- \break
- r\longa*1/4 r\breve *1/2
- r1 r2 r4 r8 r16 r32 r64 r64
- }
- \layout {
- ragged-right = ##t
- indent=0\mm
- \context {
- \Score
- \remove "Bar_number_engraver"
- }
- \context {
- \Staff
- \remove "Clef_engraver"
- \override StaffSymbol #'transparent = ##t
- \override TimeSignature #'transparent = ##t
- \override BarLine #'transparent = ##t
- \consists "Pitch_squash_engraver"
- }
- }
-}
+@noindent
+Here are the same durations with automatic beaming turned off.
+
+@c not strictly "writing rhythms"; more of a "displaying" thing,
+@c but it's ok here. -gp
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+\time 8/1
+\autoBeamOff
+c\longa c\breve c1 c2
+c4 c8 c16 c32 c64 c64
@end lilypond
-If the duration is omitted then it is set to the previously
+A note with the duration of a quadruple breve may be entered with
+@code{\maxima}, but this is supported only within ancient music
+notation. For details, see @ref{Ancient notation}.
+
+If the duration is omitted, it is set to the previously
entered duration. The default for the first note is a quarter
note.
-@lilypond[quote,ragged-right,verbatim,fragment]
-{ a a a2 a a4 a a1 a }
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+a a a2 a a4 a a1 a
@end lilypond
-
-@node Augmentation dots
-@unnumberedsubsubsec Augmentation dots
+@cindex notes, dotted
+@cindex dotted notes
@funindex .
-To obtain dotted note lengths, simply add a dot (@samp{.}) to the
-number. Double-dotted notes are produced in a similar way.
+To obtain dotted note lengths, place a dot (@code{.}) after the
+duration. Double-dotted notes are specified by appending two
+dots, and so on.
-@lilypond[quote,ragged-right,fragment,verbatim]
-a'4 b' c''4. b'8 a'4. b'4.. c''8.
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+a4 b c4. b8 a4. b4.. c8.
@end lilypond
+Some durations cannot be represented with just binary durations
+and dots; they can be represented only by tying two or more
+notes together. For details, see @ref{Ties}.
+
+For ways of specifying durations for the syllables of lyrics and
+ways of aligning lyrics to notes, see @ref{Vocal music}.
+
+Optionally, notes can be spaced strictly proportionately to their
+duration. For details of this and other settings which control
+proportional notation, see @ref{Proportional notation}.
+
@refcommands
Dots are normally moved up to avoid staff lines, except in
polyphonic situations. The following commands may be used to
-force a particular direction manually
+force a particular direction manually, and to return to the
+default behaviour:
@funindex \dotsUp
@code{\dotsUp},
@funindex \dotsNeutral
@code{\dotsNeutral}.
+
@seealso
-Program reference: @internalsref{Dots}, and
+Music Glossary: @rglos{breve}, @rglos{longa}, @rglos{note value}
+@rglos{Duration names notes and rests}.
+
+Notation Reference: @ref{Automatic beams}, @ref{Ties},
+@ref{Writing rhythms}, @ref{Writing rests}, @ref{Vocal music},
+@ref{Ancient notation}, @ref{Proportional notation}.
+
+Snippets: @lsrdir{Rhythms,Rhythms}
+
+Internals Reference: @internalsref{Dots},
@internalsref{DotColumn}.
+@refbugs
+
+@c Deliberately duplicated in Durations and Rests. -gp
+There is no fundamental limit to rest durations (both in terms of
+longest and shortest), but the number of glyphs is limited:
+rests from 128th to maxima (8 x whole) may be printed.
+
+
@node Tuplets
-@unnumberedsubsubsec Tuplets
+@subsubsection Tuplets
@cindex tuplets
@cindex triplets
@funindex \times
Tuplets are made out of a music expression by multiplying all
-durations with a fraction
+durations with a fraction:
@example
\times @var{fraction} @var{musicexpr}
@end example
@noindent
-The duration of @var{musicexpr} will be multiplied by the
-fraction. The fraction's denominator will be printed over the
-notes, optionally with a bracket. The most common tuplet is the
-triplet in which 3 notes have the length of 2, so the notes are
-2/3 of their written length
+The duration of @var{musicexpr} will be multiplied by the
+fraction. The fraction's denominator will be printed over or
+under the notes, optionally with a bracket. The most common
+tuplet is the triplet in which 3 notes have the length of 2, so
+the notes are 2/3 of their written length.
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+a2 \times 2/3 {b4 b b}
+c4 c \times 2/3 {b4 a g}
-@lilypond[quote,ragged-right,fragment,verbatim]
-g'4 \times 2/3 {c'4 c' c'} d'4 d'4
@end lilypond
-Tuplets may be nested, for example,
+Tuplets may be nested:
@lilypond[fragment,ragged-right,verbatim,relative=2]
-\override TupletNumber #'text = #tuplet-number::calc-fraction-text
-\times 4/6 {
- a4 a
- \times 3/5 { a a a a a }
+\relative c'' {
+ \autoBeamOff
+ c4 \times 4/5 { f8 e f \times 2/3 {e[ f g] } } f4 |
}
@end lilypond
@commonprop
-@funindex tupletNumberFormatFunction
@cindex tuplet formatting
+@cindex triplet formatting
+@funindex tupletNumberFormatFunction
+@funindex tupletSpannerDuration
+
+@c when available
+@c @lilypondfile [ragged-right,line-width=16\cm,staffsize=14,quote]
+@c {Entering-several-tuplets-using-only-one-\times-command.ly}
+
+@ignore
+@c TODO Remove when snippet works ok
+@c Sent to Snippet 5 Feb 08
The property @code{tupletSpannerDuration} specifies how long each
bracket should last. With this, you can make lots of tuplets
while typing @code{\times} only once, thus saving lots of typing.
In the next example, there are two triplets shown, while
-@code{\times} was only used once
+@code{\times} was only used once.
@lilypond[quote,fragment,relative=2,ragged-right,verbatim]
\set tupletSpannerDuration = #(ly:make-moment 1 4)
\times 2/3 { c8 c c c c c }
@end lilypond
+@end ignore
@noindent
For more information about @code{make-moment}, see
@ref{Time administration}.
-The format of the number is determined by the property @code{text}
-in @code{TupletNumber}. The default prints only the denominator,
-but if it is set to the function
-@code{tuplet-number::calc-fraction-text}, @var{num}:@var{den} will
-be printed instead.
+@funindex TupletNumber
+
+By default, only the numerator of the tuplet number
+is printed over the tuplet bracket, i.e. the denominator
+of the argument to the @code{\times} command. Alternatively,
+@var{num}:@var{den} of the tuplet number may be printed, or
+the tuplet number may be suppressed altogether.
-To avoid printing tuplet numbers, use
@lilypond[quote,fragment,relative=2,ragged-right,verbatim]
\times 2/3 { c8 c c } \times 2/3 { c8 c c }
+\override TupletNumber #'text = #tuplet-number::calc-fraction-text
+\times 2/3 { c8 c c }
\override TupletNumber #'transparent = ##t
-\times 2/3 { c8 c c } \times 2/3 { c8 c c }
+\times 2/3 { c8 c c }
@end lilypond
-Use the @code{\tweak} function to override nested tuplets
-beginning at the same music moment. In this example,
-@code{\tweak} specifies fraction text for the outer
-@code{TupletNumber} and denominator text for the
-@code{TupletNumber} of the first of the three inner tuplets.
-
-@lilypond[quote,ragged-right,verbatim]
-\new Staff {
- \tweak #'text #tuplet-number::calc-fraction-text
- \times 4/3 {
- \tweak #'text #tuplet-number::calc-denominator-text
- \times 2/3 { c'8[ c'8 c'8] }
- \times 2/3 { c'8[ c'8 c'8] }
- \times 2/3 { c'8[ c'8 c'8] }
- }
+@c TODO Add snippet to show this
+Tuplets may extend over bar lines, but they will inhibit a
+line break unless the @code{Forbid_line_break_engraver} is
+removed from the @code{Voice context}.
+
+@subheading Modifying nested tuplets
+
+@cindex tuplets, nested
+@cindex triplets, nested
+@cindex bracket, tuplet
+@cindex tuplet bracket
+@cindex triplet bracket
+@funindex TupletBracket
+
+If nested tuplets do not begin at the same moment their
+appearance may be modified in the usual way with
+@code{\override} commands:
+
+@c NOTE Tuplet brackets collide if notes are high on staff
+@c See issue 509
+@lilypond[quote,ragged-right,verbatim,fragment,relative=1]
+\times 2/3 { c8[ c c]}
+\once \override TupletNumber #'text = #tuplet-number::calc-fraction-text
+\times 2/3 {
+ c[ c]
+ c[ c]
+ \once \override TupletNumber #'transparent = ##t
+ \times 2/3 { c8[ c c] }
+\times 2/3 { c8[ c c]}
}
@end lilypond
-Here @code{\tweak} and @code{\override} work together to specify
-@code{TupletBracket} direction. The first @code{\tweak} positions
-the @code{TupletBracket} of the outer tuplet above the staff. The
-second @code{\tweak} positions the @code{TupletBracket} of the
-first of the three inner tuplets below the staff. Note that this
-pair of @code{\tweak} functions affects only the outer tuplet and
-the first of the three inner tuplets because only those two
-tuplets begin at the same music moment. We use @code{\override}
-in the usual way to position the @code{TupletBrackets} of the
-second and third of the inner tuplets below the staff.
+However, if the nested tuplets begin at the same musical moment,
+@code{\override} commands cannot be applied to just one of them
+-- they apply to both. So to change the appearance of nested
+tuplets beginning at the same musical moment individually, the
+@code{\tweak} function must be used (see @ref{Objects connected
+to the input}). The @code{\tweak} function is applied to the
+following @code{\times} command as it appears in the input stream,
+and so can distinguish between separate @code{\times} commands
+even if their tuplets begin at the same musical moment.
+
+In this example, the @code{\tweak} command is used to specify
+fraction text for the outer @code{TupletNumber} and denominator
+text for the @code{TupletNumber} of the first of the three
+inner tuplets.
+
+@c NOTE Tuplet brackets collide if notes are high on staff
+@c so use relative=1 until this is fixed
+@c See issue 509
+@lilypond[quote,ragged-right,verbatim,fragment,relative=1]
+\tweak #'text #tuplet-number::calc-fraction-text
+\times 4/3 {
+ \tweak #'text #tuplet-number::calc-denominator-text
+ \times 2/3 { c8[ c8 c8] }
+ \times 2/3 { c8[ c8 c8] }
+ \times 2/3 { c8[ c8 c8] }
+}
+@end lilypond
-@lilypond[quote,ragged-right,verbatim]
-\new Staff {
- \tweak #'text #tuplet-number::calc-fraction-text
- \tweak #'direction #up
- \times 4/3 {
- \tweak #'direction #down
- \times 2/3 { c'8[ c'8 c'8] }
- \override TupletBracket #'direction = #down
- \times 2/3 { c'8[ c'8 c'8] }
- \times 2/3 { c'8[ c'8 c'8] }
- }
+In the next example, @code{\tweak} and @code{\override} work
+together to specify @code{TupletBracket} direction. The first
+@code{\tweak} positions the @code{TupletBracket} of the outer
+tuplet above the staff. The second @code{\tweak} positions the
+@code{TupletBracket} of the first of the three inner tuplets below
+the staff. Note that the @code{\tweak} command needs to be used
+only for events that begin at the same music moment: the outer
+tuplet and the first of the three inner tuplets. To position the
+@code{TupletBracket}s of the second and third of the inner tuplets
+below the staff, we can use @code{\override} in the usual way.
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+\tweak #'text #tuplet-number::calc-fraction-text
+\tweak #'direction #up
+\times 4/3 {
+ \tweak #'direction #down
+ \times 2/3 { c8[ c8 c8] }
+ \override TupletBracket #'direction = #down
+ \times 2/3 { c8[ c8 c8] }
+ \times 2/3 { c8[ c8 c8] }
}
@end lilypond
-Tuplet brackets can be made to run to prefatory matter or the next
-note
+@subheading Modifying tuplet bracket length
+
+@cindex tuplet bracket length
+@cindex triplet bracket length
+@cindex bracket length, tuplets
+@funindex tupletFullLength
+@funindex tupletFullLengthNote
+
+Tuplet brackets can be made to run to prefatory matter or the
+next note.
+Default tuplet brackets end at the right edge of the final note
+of the tuplet; full-length tuplet brackets extend farther to the
+right, either to cover all the non-rhythmic notation up to the
+following note, or to cover only the whitespace before the next
+item of notation, be that a clef, time signature, key signature,
+or another note. The example shows how to switch tuplets to
+full length mode and how to modify what material they cover.
+
-@lilypond[ragged-right]
+@lilypond[ragged-right,verbatim,quote]
\new RhythmicStaff {
+ % Set tuplets to be extendable ..
\set tupletFullLength = ##t
- \time 4/4
- \times 4/5 {
- c4 c1
- }
+ % .. to cover all items up to the next note
\set tupletFullLengthNote = ##t
\time 2/4
- \times 2/3 {
- c4 c c
- }
+ \times 2/3 { c4 c c }
+ % .. or to cover just whitespace
+ \set tupletFullLengthNote = ##f
+ \time 4/4
+ \times 4/5 { c4 c1 }
\time 3/4
- c4
+ c4
}
@end lilypond
+@subheading Compressing music
+
+@cindex compressing music
+@funindex \compressMusic
+
+@code{\compressMusic} works similarly to \times, but does not
+create a tuplet bracket. One application is in polymetric
+notation, as shown in the following example. See
+@ref{Polymetric notation}.
+
+@c when available
+@c @lilypondfile [ragged-right,line-width=16\cm,staffsize=14,quote]
+@c {printing-music-with-different-time-signatures.ly}
+
@seealso
-Program reference: @internalsref{TupletBracket},
-@internalsref{TupletNumber}, and @internalsref{TimeScaledMusic}.
+Music Glossary: @rglos{triplet}, @rglos{tuplet},
+@rglos{polymetric}.
+
+Notation Reference: @ref{Time administration},
+@ref{Objects connected to the input}, @ref{Polymetric notation}.
+
+Snippets: @lsrdir{Rhythms,Rhythms}.
+
+Internals Reference: @internalsref{TupletBracket},
+@internalsref{TupletNumber}, @internalsref{TimeScaledMusic}.
+
+@refbugs
+Lines may be broken within a tuplet with @code{\bar "" \break},
+but the tuplet bracket does not correctly carry over.
@node Scaling durations
-@unnumberedsubsubsec Scaling durations
+@subsubsection Scaling durations
-You can alter the length of duration by a fraction @var{N/M}
-appending @samp{*@var{N/M}} (or @samp{*@var{N}} if @var{M=1}).
+You can alter the length of a duration by a fraction @var{N/M}
+by 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. These may be combined such as @samp{*M*N}.
+produced, but the altered duration will be used in calculating the
+position within the measure and setting the duration in the MIDI
+output. Multiplying factors may be combined
+such as @code{*M*N}.
In the following example, the first three notes take up exactly
two beats, but no triplet bracket is printed.
b16*4 c4
@end lilypond
+The duration of skip or spacing notes may also be modified by
+a multiplier. This is useful for skipping many measures, e.g.,
+@code{s1*23}.
+
+@seealso
+
+Notation Reference: @ref{Tuplets}, @ref{Skips}, @ref{Polymetric notation}.
+
+Snippets: @lsrdir{Rhythms,Rhythms}
+
+@node Ties
+@subsubsection Ties
+
+@cindex tie
+@funindex ~
+
+A tie connects two adjacent note heads of the same pitch. The tie
+in effect extends the length of a note.
+
+@warning{Ties should not be confused with @emph{slurs}, which
+indicate articulation, or @emph{phrasing slurs}, which indicate
+musical phrasing. A tie is just a way of extending a note
+duration, similar to the augmentation dot.}
+
+A tie is entered using the tilde symbol @code{~}
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+e' ~ e'
+@end lilypond
+
+
+@noindent
+Ties are used either when the note crosses a bar line, or when
+dots cannot be used to denote the rhythm. Ties should also be
+used when note values cross larger subdivisions of the measure:
+
+@lilypond[fragment,quote,ragged-right]
+\relative {
+ r8 c8 ~ c2 r4 | r8^"not" c2 ~ c8 r4
+}
+@end lilypond
+
+If you need to tie a lot of notes across bar lines, 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.
+
+@funindex \repeatTie
+@cindex repeating ties
+@cindex volta brackets and ties
+
+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. Chords may be partially tied by placing the tie inside
+the chord.
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
+ <c e g> ~ <c e g>
+<c~ e g~ b> <c e g b>
+@end lilypond
+
+When a second alternative of a repeat starts with a tied note, you
+have to repeat the tie. This can be achieved with
+@code{\repeatTie},
+
+@lilypond[fragment,quote,ragged-right,relative=2,verbatim]
+\repeat volta 2 { c g <c e>2 ~ }
+\alternative {{ <c e>2. r4 } {<c e>2\repeatTie d4 c }}
+@end lilypond
+
+@cindex laissez vibrer
+@cindex ties, laissez vibrer
+@funindex \laissezVibrer
+@funindex \tieUp
+@funindex \tieDown
+@funindex \tieNeutral
+
+@notation{L.v.} ties (@notation{laissez vibrer}) indicate that
+notes must not be damped at the end. It is used in notation for
+piano, harp and other string and percussion instruments. They can
+be entered using @code{\laissezVibrer}:
+
+@lilypond[fragment,ragged-right,verbatim,relative=1]
+<c f g>\laissezVibrer
+@end lilypond
+
+The vertical placement of ties may be controlled; see
+@ref{Controlling direction}.
+
+@quotation
+DELETE THIS ?
+@code{\tieDown} (see example below). @code{\tieNeutral} reverts
+to the default behaviour again.
+
+However, as with other music elements of this kind, there is a
+convenient shorthand for forcing tie directions. By adding
+@code{_} or @code{^} before the tilde, the direction is also set:
+
+@lilypond[relative=2,ragged-right,quote,verbatim,fragment]
+c4_~ c c^~ c)
+@end lilypond
+@end quotation
+
+@refcommands
+
+@funindex \tieUp
+@code{\tieUp},
+@funindex \tieDown
+@code{\tieDown},
+@funindex \tieNeutral
+@code{\tieNeutral},
+@funindex \tieDotted
+@code{\tieDotted},
+@funindex \tieDashed
+@code{\tieDashed},
+@funindex \tieSolid
+@code{\tieSolid}.
+
+
+@commonprop
+
+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. The same
+feature is also useful, for example, to tie a tremolo to a chord,
+but in principle, it can also be used for ordinary, consecutive
+notes:
+
+@lilypond[fragment,verbatim,relative=1,ragged-right,quote]
+\set tieWaitForNote = ##t
+\grace { c16[~ e~ g]~ } <c, e g>2
+\repeat tremolo 8 { c32~ c'~ } <c c,>1
+e8~ c~ a~ f~ <e' c a f>2
+\tieUp c8~ a \tieDown \tieDotted g~ c g2
+@end lilypond
+
+Ties may be engraved manually by changing the
+@code{tie-configuration} property of the @code{TieColumn} object.
+The first number indicates the distance from the center of the
+staff in staff-spaces, and the second number indicates the
+direction (1=up, -1=down).
+
+@lilypond[fragment,verbatim,relative=1,ragged-right,quote]
+<c e g>2~ <c e g> |
+\override TieColumn #'tie-configuration =
+ #'((0.0 . 1) (-2.0 . 1) (-4.0 . 1))
+<c e g>~ <c e g> |
+@end lilypond
+
+
@seealso
-This manual: @ref{Tuplets}.
+Music Glossary: @rglos{tie},
+@c [TODO]add @rglos{laissez vibrer}. when there is a glossary entry.
+
+Snippets: @lsrdir{Rhythms,Rhythms}
+
+Internals Reference:
+@internalsref{LaissezVibrerTie}
+@internalsref{LaissezVibrerTieColumn}
+
+Example files:
+@c @lsr{connecting,laissez-vibrer-ties.ly}
+
+
+
+
+Notation Reference: @ref{Automatic note splitting}.
+
+Snippets: @lsrdir{Rhythms,Rhythms}
+
+Internals Reference: @internalsref{Tie}.
+
+
+@refbugs
+
+Switching staves when a tie is active will not produce a slanted
+tie.
+
+Changing clefs or octavations during a tie is not really
+well-defined. In these cases, a slur may be preferable.
+
+
+
@node Writing rests
@subsection Writing rests
@menu
-* Rests::
-* Skips::
-* Multi measure rests::
+* Rests::
+* Skips::
+* Full measure rests::
@end menu
@node Rests
-@unnumberedsubsubsec Rests
-@cindex Rests
+@subsubsection Rests
+@cindex rest
+@cindex maxima
+@cindex longa
+@cindex breve
@funindex \rest
@funindex r
+@funindex \maxima
+@funindex \longa
+@funindex \breve
-Rests are entered like notes with the note name @code{r}
+Rests are entered like notes with the note name @code{r}:
+@c \time 16/1 is used to avoid spurious bar lines
+@c and long tracts of empty measures
@lilypond[fragment,quote,ragged-right,verbatim]
-r1 r2 r4 r8
+\new Staff {
+ \time 16/1
+ \override Staff.TimeSignature #'stencil = ##f
+ r\maxima
+ r\longa r\breve r1 r2
+ r4 r8 r16 r32 r64
+}
@end lilypond
-Whole bar rests, centered in middle of the bar, must be done with
-multi-measure rests. They can be used for a single bar as well as
-many bars, and are discussed in @ref{Multi measure rests}.
+Whole measure rests, centered in middle of the measure, must be entered as
+multi-measure rests. They can be used for a single measure as well as
+many measures and are discussed in @ref{Full measure rests}.
To explicitly specify a rest's vertical position, write a note
followed by @code{\rest}. A rest will be placed in the position
-where the note would appear,
+where the note would appear. This allows for precise manual
+formatting of polyphonic music, since the automatic rest collision
+formatter will leave these rests alone.
-@lilypond[fragment,quote,ragged-right,verbatim]
-a'4\rest d'4\rest
+@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
+a4\rest d4\rest
@end lilypond
-@noindent
-This makes manual formatting of polyphonic music much easier,
-since the automatic rest collision formatter will leave these
-rests alone.
@seealso
-Program reference: @internalsref{Rest}.
+Notation Reference: @ref{Full measure rests}.
+
+Snippets: @lsrdir{Rhythms,Rhythms}.
+
+Internals Reference: @internalsref{Rest}.
+
+@refbugs
+
+@c Deliberately duplicated in Durations and Rests. -gp
+There is no fundamental limit to rest durations (both in terms of
+longest and shortest), but the number of glyphs is limited: there
+are rests from 128th to maxima (8 x whole).
@node Skips
-@unnumberedsubsubsec Skips
+@subsubsection Skips
-@cindex Skip
-@cindex Invisible rest
-@cindex Space note
+@cindex skip
+@cindex invisible rest
+@cindex space note
@funindex \skip
@funindex s
An invisible rest (also called a @q{skip}) can be entered like a
-note with note name @samp{s} or with @code{\skip @var{duration}}
+note with note name @code{s} or with @code{\skip @var{duration}}
@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
a4 a4 s4 a4 \skip 1 a4
@end lilypond
+@cindex lyrics, skip
+
The @code{s} syntax is only available in note mode and chord mode.
-In other situations, for example, when entering lyrics, you should
-use the @code{\skip} command
+In other situations, for example, when entering lyrics, one must
+use the @code{\skip} command:
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[quote,ragged-right,verbatim,relative=2]
<<
- \relative { a'2 a2 }
+ { a2 a2 }
\new Lyrics \lyricmode { \skip 2 bla2 }
>>
@end lilypond
@internalsref{Voice} when necessary, similar to note and rest
commands. For example, the following results in an empty staff.
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[quote,verbatim]
{ s4 }
@end lilypond
+@c with ragged-right, the staff lines are cut BEFORE the time
+@c signature, which makes for a VERY empty staff
-The fragment @code{@{ \skip 4 @} } would produce an empty page.
+@c The fragment @code{@{ \skip 4 @} } would produce an empty page.
+@c Misleading -- it doesn't produce anything, not even an empty page.
+@c Ppl who want to make empty sheets will see this and wonder what's
+@c happening. -eo
@seealso
-Program reference: @internalsref{SkipMusic}.
+Snippets: @lsrdir{Rhythms,Rhythms}
+
+Internals Reference: @internalsref{SkipMusic}.
-@node Multi measure rests
-@unnumberedsubsubsec Multi measure rests
+@node Full measure rests
+@subsubsection Full measure rests
@cindex multi measure rests
@cindex full measure rests
-@cindex Rests, multi measure
-@cindex Rests, full measure
-@cindex whole rests for a full measure
+@cindex rest, multi measure
+@cindex rest, full measure
+@cindex whole rest for a full measure
@funindex R
-Rests for one full measure (or many bars) are entered using
-@samp{R}. It is specifically meant for full bar rests and for
-entering parts: the rest can expand to fill a score with rests, or
-it can be printed as a single multi-measure rest. This expansion
+Rests for one or more full measures are entered using @code{R}
+followed by a duration (see @ref{Durations}). The duration should
+correspond to an integral number of measures, otherwise a barcheck
+warning is printed. A @rglos{multi-measure rest} is used
+principally to indicate that a part in a multi-part score should
+be silent:
+
+@lilypond[quote,fragment,verbatim,relative=2]
+\set Score.skipBars = ##t
+R1*4
+R1*24
+R1*4
+b2^"Tutti" b4 a4
+@end lilypond
+
+A multi-measure rest can be expanded in the printed score
+to show all the rest measures explicitly, or, as above, it can be
+condensed to a single measure
+containing a multi-measure rest symbol, with the number of
+measures of rest printed above the measure. This expansion
is controlled by the property @code{Score.skipBars}. If this is
-set to true, empty measures will not be expanded, and the
-appropriate number is added automatically
+set to true, empty measures will be condensed to a single measure.
@lilypond[quote,ragged-right,fragment,verbatim]
-\time 4/4 r1 | R1 | R1*2 \time 3/4 R2. \time 2/4 R2 \time 4/4
-\set Score.skipBars = ##t R1*17 R1*4
+\time 4/4 r1 | R1 | R1*2 |
+\time 2/4 R2 |
+\time 4/4
+\set Score.skipBars = ##t
+R1*17 | R1*4 |
@end lilypond
-The @code{1} in @code{R1} is similar to the duration notation used
-for notes. Hence, for time signatures other than 4/4, you must
-enter other durations. This can be done with augmentation dots or
-fractions
+The @code{1} in @code{R1} is similar to the duration notation
+used for notes and is the length of a measure in 2/2 or 4/4 time.
+The duration in a multi-measure rest must always be an integral
+number of measure-lengths, so in other time signatures augmentation
+dots or fractions must be used:
@lilypond[quote,ragged-right,fragment,verbatim]
\set Score.skipBars = ##t
\time 3/4
R2. | R2.*2
\time 13/8
-R1*13/8
-R1*13/8*12 |
-\time 10/8 R4*5*4 |
+R1*13/8 | R1*13/8*12 |
+\time 10/8
+R4*5*4 |
@end lilypond
An @code{R} spanning a single measure is printed as either a whole
-rest or a breve, centered in the measure regardless of the time
+or breve rest, centered in the measure, regardless of the time
signature.
-If there are only a few measures of rest, LilyPond prints
-@q{church rests} (a series of rectangles) in the staff. To
-replace that with a simple rest, use
+@cindex church rest
+@cindex rest, church
+@cindex kirchenpausen
+
+If there are 10 or fewer measures of rest, LilyPond prints
+a series of longa and breve rests (called in German
+Kirchenpausen - @q{church rests}) within the staff and
+prints a simple line otherwise. This default number of 10
+may be changed by overriding
@code{MultiMeasureRest.expand-limit}.
@lilypond[quote,ragged-right,fragment,verbatim]
\set Score.skipBars = ##t
R1*2 | R1*5 | R1*9
-\override MultiMeasureRest #'expand-limit = 1
+\override MultiMeasureRest #'expand-limit = 3
R1*2 | R1*5 | R1*9
@end lilypond
+Note that unlike ordinary rests, the vertical position on the
+staff of the multi-measure rest symbol of either form cannot be
+changed.
+
@cindex text on multi-measure rest
@cindex script on multi-measure rest
@cindex fermata on multi-measure rest
-Texts can be added to multi-measure rests by using the
-@var{note}-@code{markup} syntax @ref{Text markup}. A variable
-(@code{\fermataMarkup}) is provided for adding fermatas
+Text can be added to multi-measure rests by using the
+@var{note}-@code{markup} syntax described in @ref{Text markup}.
+The variable @code{\fermataMarkup} is provided for adding
+fermatas.
@lilypond[quote,ragged-right,verbatim,fragment]
\set Score.skipBars = ##t
R2.^\fermataMarkup
@end lilypond
-Warning! This text is created by @code{MultiMeasureRestText}, not
-@code{TextScript}.
+@warning{Text attached to a multi-measure rest is created
+by @code{MultiMeasureRestText}, not
+@code{TextScript}. Overrides must be directed to the correct
+object, or they will be ignored. See the following example.}
@lilypond[quote,ragged-right,verbatim,fragment]
\override TextScript #'padding = #5
R1^"high"
@end lilypond
-If you want to have text on the left end of a multi-measure rest,
-attach the text to a zero-length skip note, i.e.,
+Text attached to a multi-measure rest will be centered above or
+below it. Long text attached in this way does not cause the
+measure to expand, and may collide with text in adjacent measures.
+Long text is better attached to a zero-length skip note preceding
+the rest, preceded by @code{\textLengthOn} (turn off again with
+@code{\textLengthOff}), since this will cause the measure to expand to
+accommodate the length of the text:
-@example
-s1*0^"Allegro"
-R1*4
-@end example
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+\set Score.skipBars = ##t
+\textLengthOn
+s1*0^\markup {[MAJOR GENERAL]}
+R1*19
+s1*0^\markup {[MABEL] }
+s1*0_\markup {\italic {Cue: ... it is yours}}
+R1*30
+\textLengthOff
+c4^\markup {CHORUS} d f c
+@end lilypond
+@noindent
+Text attached to a skip note in this way is left-aligned to the
+position where the note would be placed in the bar, and placed
+above the bar count numeral, but because the bar length is
+determined by the length of the text, the text will appear to be
+centered. If two (or more) texts are
+attached to skip notes in a bar the bar length is determined by
+the longer text, and the shorter text is then clearly
+left-aligned, as shown in the second bar above. If the shorter
+text of two marks is short enough to fit it will be placed
+alongside and to the left of the bar count numeral.
@seealso
-Program reference: @internalsref{MultiMeasureRestMusicGroup},
-@internalsref{MultiMeasureRest}.
+Notation Reference: @ref{Durations}, @ref{Text},
+@ref{Text markup}, @ref{Text scripts}.
+
+Snippets: @lsrdir{Rhythms,Rhythms}
+
+Internals Reference: @internalsref{MultiMeasureRest}.
The layout object @internalsref{MultiMeasureRestNumber} is for the
default number, and @internalsref{MultiMeasureRestText} for user
@refbugs
-It is not possible to use fingerings (e.g., @code{R1-4}) to put
-numbers over multi-measure rests. And the pitch of multi-measure
-rests (or staff-centered rests) can not be influenced.
+If an attempt is made to use fingerings (e.g.,
+@code{R1*10-4}) to put numbers over multi-measure rests, the
+fingering numeral (4) may collide with the bar counter
+numeral (10).
@cindex condensing rests
Be careful when entering multi-measure rests followed by whole
notes. The following will enter two notes lasting four measures
-each
+each:
@example
R1*4 cis cis
@end example
-When @code{skipBars} is
-set, the result will look OK, but the bar numbering will be off.
-
-
@node Displaying rhythms
@subsection Displaying rhythms
@end menu
@node Time signature
-@unnumberedsubsubsec Time signature
+@subsubsection Time signature
-@cindex Time signature
+@cindex time signature
@cindex meter
@funindex \time
-Time signature indicates the metrum of a piece: a regular pattern
-of strong and weak beats. It is denoted by a fraction at the
-start of the staff.
+The time signature is set with the @code{\time} command:
-The time signature is set with the @code{\time} command
-
-@lilypond[quote,ragged-right,fragment,verbatim]
-\time 2/4 c'2 \time 3/4 c'2.
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+\time 2/4 c2 \time 3/4 c2.
@end lilypond
@commonprop
property. Setting it to @code{#'()} uses fraction style for 4/4
and 2/2 time,
-@lilypond[fragment,quote,ragged-right,verbatim]
-\time 4/4 c'1
-\time 2/2 c'1
+@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
+\time 4/4 c1
+\time 2/2 c1
\override Staff.TimeSignature #'style = #'()
-\time 4/4 c'1
-\time 2/2 c'1
+\time 4/4 c1
+\time 2/2 c1
+@end lilypond
+
+A time signature symbol is normally printed whenever the time
+signature changes. If this takes place at the end of a line a
+warning time signature sign is printed at the end of the line and
+again at the start of a new line. This default behaviour can be
+modified by setting the value of the @code{break-visibility}
+property. This takes three values which may be set to @code{#t}
+or @code{#f} to specify whether the corresponding time signature
+is visible or not. The order of the three values is @code{end of
+line visible}, @code{middle of line visible}, @code{beginning of
+line visible}.
+
+@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
+% Do not print any time signatures at end of line
+\override Staff.TimeSignature #'break-visibility = ##(#f #t #t)
+\time 4/4 c1
+\time 3/4 c2.
+% Do not print the following 9/8 time signature
+\once \override Staff.TimeSignature #'break-visibility = ##(#t #f #t)
+\time 9/8 c4. c c
+\time 2/2 c1
+\break
+\time 9/8 c4. c c
+\time 12/8 c2. c2.
@end lilypond
There are many more options for its layout. See @ref{Ancient time
signatures}, for more examples.
-@code{\time} sets the property @code{timeSignatureFraction},
-@code{beatLength} and @code{measureLength} in the @code{Timing}
+@code{\time} sets the properties @code{timeSignatureFraction},
+@code{beatLength}, and @code{measureLength} in the @code{Timing}
context, which is normally aliased to @internalsref{Score}. The
property @code{measureLength} determines where bar lines should be
inserted, and how automatic beams should be generated. Changing
the value of @code{timeSignatureFraction} also causes the symbol
to be printed.
+@cindex measure groupings
+
More options are available through the Scheme function
-@code{set-time-signature}. In combination with the
-@internalsref{Measure_grouping_engraver}, it will create
+@code{set-time-signature}, which takes three arguments: the number
+of beats, the beat length, and the internal grouping of beats in
+the measure. If the @internalsref{Measure_grouping_engraver} is
+included, the function will also create
@internalsref{MeasureGrouping} signs. Such signs ease reading
rhythmically complex modern music. In the following example, the
9/8 measure is subdivided in 2, 2, 2 and 3. This is passed to
-@code{set-time-signature} as the third argument @code{(2 2 2 3)}
+@code{set-time-signature} as the third argument @code{(2 2 2 3)}:
@lilypond[quote,ragged-right,verbatim]
\score {
@seealso
-Program reference: @internalsref{TimeSignature}, and
+Snippets: @lsrdir{Rhythms,Rhythms}
+
+Internals Reference: @internalsref{TimeSignature}, and
@internalsref{Timing_translator}.
-Examples: @lsr{contemporary,compound-time-signature.ly}.
+Examples: @c @lsr{contemporary,compound-time-signature.ly}.
@refbugs
@node Upbeats
-@unnumberedsubsubsec Upbeats
+@subsubsection Upbeats
@cindex anacrusis
@cindex upbeat
@cindex partial measure
@cindex measure, partial
+@cindex pickup measure
@cindex shorten measures
@funindex \partial
-Partial measures, such as an anacrusis or upbeat, are entered using the
-
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-\partial 16*5 c16 cis d dis e | a2. c,4 | b2
-@end lilypond
-
-The syntax for this command is
+Partial or pickup measures, such as an anacrusis or upbeat, are
+entered using the @code{\partial} command, with the syntax
@example
\partial @var{duration}
@end example
where @code{duration} is the rhythmic length to be added before
-the next bar.
+the next measure:
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+\partial 16*5 c16 cis d dis e | a2. c,4 | b2
+@end lilypond
-This is internally translated into
+Internally, this is translated into
@example
\set Timing.measurePosition = -@var{length of duration}
@refbugs
This command does not take into account grace notes at the start
-of the music. When a piece starts with graces notes in the
-pickup, then the @code{\partial} should follow the grace notes
+of the music. When a piece starts with grace notes in the
+pickup, then the @code{\partial} should follow the grace notes:
@lilypond[verbatim,quote,ragged-right,relative,fragment]
\grace f16
piece. If you use it after the beginning, some odd warnings may
occur.
+@seealso
+
+Snippets: @lsrdir{Rhythms,Rhythms}
@node Unmetered music
-@unnumberedsubsubsec Unmetered music
+@subsubsection Unmetered music
@cindex cadenza
@funindex \cadenzaOn
d4 e d c
@end lilypond
+Bar numbering is resumed at the end of the cadenza as if the
+cadenza were not there:
+
+@lilypond[verbatim,quote,ragged-right,relative=2,fragment]
+\override Score.BarNumber #'break-visibility = ##( #t #t #t )
+c4 d e d
+\cadenzaOn
+c4 c d8 d d f4 g4.
+\cadenzaOff
+\bar "|"
+d4 e d c
+@end lilypond
@refbugs
LilyPond will only insert line breaks and page breaks at a
-barline. Unless the unmetered music ends before the end of the
-staff line, you will need to insert invisible bar lines
+bar line. Unless the unmetered music ends before the end of the
+staff line, you will need to insert invisible bar lines with
@example
\bar ""
@noindent
to indicate where breaks can occur.
+@seealso
+
+Snippets: @lsrdir{Rhythms,Rhythms}
+
@node Polymetric notation
-@unnumberedsubsubsec Polymetric notation
+@subsubsection Polymetric notation
@cindex double time signatures
@cindex signatures, polymetric
@cindex polymetric signatures
@cindex meter, polymetric
+Music Glossary:
+@rglos{polymetric}
+@rglos{polymetric time signature}
+@rglos{meter}
+
Double time signatures are not supported explicitly, but they can
be faked. In the next example, the markup for the time signature
is created with a markup text. This markup text is inserted in
-the @internalsref{TimeSignature} grob. See also
-@lsr{contemporary,compound-time-signature}.
+the @internalsref{TimeSignature} grob. See also
+@c @lsr{contemporary,compound-time-signature}.
@lilypond[verbatim,ragged-right]
% create 2/4 + 5/8
-tsMarkup =\markup {
+tsMarkup = \markup {
\override #'(baseline-skip . 2) \number {
\column { "2" "4" }
\vcenter "+"
}
{
- \override Staff.TimeSignature #'stencil = #ly:text-interface::print
+ \override Staff.TimeSignature #'stencil =
+ #ly:text-interface::print
\override Staff.TimeSignature #'text = #tsMarkup
\time 3/2
c'2 \bar ":" c'4 c'4.
moving the @internalsref{Timing_translator} to the
@internalsref{Staff} context.
-@example
-\layout @{
- \context @{ \Score
- \remove "Timing_translator"
- \remove "Default_bar_line_engraver"
- @}
- \context @{
+@lilypond[quote,verbatim,ragged-right]
+\layout {
+ \context {
+ \Score
+ \remove "Timing_translator"
+ \remove "Default_bar_line_engraver"
+ }
+ \context {
\Staff
\consists "Timing_translator"
\consists "Default_bar_line_engraver"
- @}
-
-@}
-@end example
-
-
-Now, each staff has its own time signature.
-
-@example
-<<
- \new Staff @{
- \time 3/4
- c4 c c | c c c |
- @}
- \new Staff @{
- \time 2/4
- c4 c | c c | c c
- @}
- \new Staff @{
- \time 3/8
- c4. c8 c c c4. c8 c c
- @}
->>
-@end example
-
-@lilypond[quote,ragged-right]
-\layout{
- \context{
- \Score
- \remove "Timing_translator"
- \remove "Default_bar_line_engraver"
- }
- \context{ \Staff
- \consists "Timing_translator"
- \consists "Default_bar_line_engraver"
}
}
+%Now, each staff has its own time signature.
\relative c' <<
\new Staff {
A different form of polymetric notation is where note lengths have
-different values across staves.
+different values across staves, but the measures are all the same
+length.
This notation can be created by setting a common time signature
for each staff but replacing it manually using
@code{timeSignatureFraction} to the desired fraction. Then the
printed durations in each staff are scaled to the common time
signature. The latter is done with @code{\compressMusic}, which
-is used similar to @code{\times}, but does not create a tuplet
-bracket. The syntax is @example \compressMusic #'(@var{numerator}
-. @var{denominator}) @var{musicexpr} @end example
+is used in a similar way to @code{\times}, but does not create
+a tuplet bracket. The syntax is
+
+@funindex \compressMusic
+
+@example
+\compressMusic
+#'(@var{numerator} . @var{denominator}) @var{musicexpr}
+@end example
When using different time signatures in parallel, the spacing is
aligned vertically, but bar lines distort the regular spacing.
+@seealso
+
+Snippets: @lsrdir{Rhythms,Rhythms}, @c @lsr{contemporary,compound-time-signature}.
+
+Internals Reference: @internalsref{TimeSignature}, @internalsref{Timing-translator}, @internalsref{Staff}.
+
@node Automatic note splitting
-@unnumberedsubsubsec Automatic note splitting
+@subsubsection Automatic note splitting
-Long notes can be converted automatically to tied notes. This is
-done by replacing the @internalsref{Note_heads_engraver} by the
+Long notes which overrun bar lines can be converted automatically
+to tied notes. This is done by replacing the
+@internalsref{Note_heads_engraver} by the
@internalsref{Completion_heads_engraver}. In the following
examples, notes crossing the bar line are split and tied.
@seealso
-Program reference: @internalsref{Completion_heads_engraver}.
+Snippets: @lsrdir{Rhythms,Rhythms}
+
+Internals Reference: @internalsref{Note_heads_engraver},
+@internalsref{Completion_heads_engraver},
+@internalsref{Forbid_line_break_engraver}.
+
@menu
* Automatic beams::
+* Setting automatic beam behavior::
* Manual beams::
* Feathered beams::
@end menu
@node Automatic beams
-@unnumberedsubsubsec Automatic beams
+@subsubsection Automatic beams
+
+By default, beams are inserted automatically:
-LilyPond inserts beams automatically
+@cindex beams, manual
+@cindex manual beams
@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-\time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
+\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. See @ref{Setting
-automatic beam behavior}, for details.
+If these automatic decisions are not satisfactory, beaming can be
+entered explicitly; see @ref{Manual beams}. It is also possible
+to define beaming patterns that differ from the defaults; see
+@ref{Setting automatic beam behavior}. The default beaming rules
+are defined in @file{scm/@/auto@/-beam@/.scm}.
-Individual notes may be marked with @code{\noBeam} to prevent them
-from being beamed
+@cindex autoBeamOn
+@cindex autoBeamOff
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-\time 2/4 c8 c\noBeam c c
-@end lilypond
+@noindent
+Automatic beaming may be turned off and on with
+@code{\autoBeamOff} and @code{\autoBeamOn} commands:
+@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
+c4 c8 c8. c16 c8. c16 c8
+\autoBeamOff
+c4 c8 c8. c16 c8.
+\autoBeamOn
+c16 c8
+@end lilypond
-@seealso
-Program reference: @internalsref{Beam}.
+@commonprop
+Beaming patterns may be altered with the @code{beatGrouping} property,
-@node Manual beams
-@unnumberedsubsubsec Manual beams
+@lilypond[quote,verbatim,relative=2,fragment,ragged-right]
+\time 5/16
+\set beatGrouping = #'(2 3)
+c8[^"(2+3)" c16 c8]
+\set beatGrouping = #'(3 2)
+c8[^"(3+2)" c16 c8]
+@end lilypond
-@cindex beams, manual
-@funindex ]
-@funindex [
-
-In some cases it may be necessary to override the automatic
-beaming algorithm. For example, the autobeamer will not put beams
-over rests or bar lines. Such beams are specified manually by
-marking the begin and end point with @code{[} and @code{]}
-
-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
-{
- r4 r8[ g' a r8] r8 g[ | a] r8
-}
-@end lilypond
-
-
-@commonprop
-
-@funindex stemLeftBeamCount
-@funindex stemRightBeamCount
-
-
-LilyPond can automatically determine beaming patterns within a
-beam, but this automatic behavior can sometimes produce odd
-results; therefore the @code{stemLeftBeamCount} and
-@code{stemRightBeamCount} properties can be used to override the
-defaults. If either property is set, its value will be used only
-once, and then it is erased.
-
-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
-{
- f8[ r16
- f g a]
- f8[ r16
- \set stemLeftBeamCount = #1
- f g a]
-}
-@end lilypond
-
-The property @code{subdivideBeams} can be set in order to
-subdivide all 16th or shorter beams at beat positions, as defined
-by the @code{beatLength} property.
-
-@lilypond[fragment,quote,relative=2,verbatim]
-c16[ c c c c c c c]
+The beams of consecutive 16th (or shorter) notes are, by default,
+not sub-divided. That is, the three (or more) beams stretch
+unbroken over entire groups of notes. This behaviour can
+be modified to sub-divide the beams into sub-groups by setting
+the property @code{subdivideBeams}. When set, multiple beams
+will be sub-divided at intervals defined by the current value of
+@code{beatLength} by reducing the multiple beams to just one beam
+between the sub-groups. Note that @code{beatLength} lives in the
+@code{Score} context and defaults to a quarter note. It must be
+set to a fraction giving the duration of the beam sub-group
+using the @code{make-moment} function, as shown here:
+
+@lilypond[fragment,ragged-right,quote,relative=2,verbatim]
+c32[ c c c c c c c]
\set subdivideBeams = ##t
-c16[ c c c c c c c]
+c32[ c c c c c c c]
+% Set beam sub-group length to an eighth note
\set Score.beatLength = #(ly:make-moment 1 8)
-c16[ c c c c c c c]
+c32[ c c c c c c c]
+% Set beam sub-group length to a sixteenth note
+\set Score.beatLength = #(ly:make-moment 1 16)
+c32[ c c c c c c c]
@end lilypond
@funindex subdivideBeams
For more information about @code{make-moment}, see
@ref{Time administration}.
+@funindex breakable
+@cindex break, line
+@cindex line breaks
+
Line breaks are normally forbidden when beams cross bar lines.
-This behavior can be changed by setting @code{breakable}.
+This behavior can be changed by setting the @code{breakable}
+property: @code{\override Beam #'breakable = ##t}.
-@funindex breakable
+@lilypond[ragged-right,relative=2,fragment,verbatim,quote]
+\override Beam #'breakable = ##t
+c8 \repeat unfold 15 {c[ c] } c
+@end lilypond
@cindex beams and line breaks
@cindex beams, kneed
Kneed beams are inserted automatically when a large gap is
detected between the note heads. This behavior can be tuned
-through the @code{auto-knee-gap} object.
+through the @code{auto-knee-gap} property. A kneed beam is
+drawn if the gap is larger than the value of
+@code{auto-knee-gap} plus the width of the beam object (which
+depends on the duration of the notes and the slope of the beam).
+By default @code{auto-knee-gap} is set to 5.5 staff spaces.
+
+@lilypond[fragment,ragged-right,quote,verbatim]
+f8 f''8 f8 f''8
+\override Beam #'auto-knee-gap = #6
+f8 f''8 f8 f''8
+@end lilypond
+
+
+@seealso
+
+Notation Reference: @ref{Manual beams}, @ref{Setting automatic beam behavior}.
+
+Snippets: @lsrdir{Rhythms,Rhythms}
+
+Internals Reference: @internalsref{Beam}.
@refbugs
Automatically kneed cross-staff beams cannot be used together with
hidden staves. See @ref{Hiding staves}.
-@c Is this still true with skyline spacing stuff? -J.Mandereau
-Beams do not avoid collisions with symbols around the notes, such
-as texts and accidentals.
+Beams can collide with note heads and accidentals in other voices
-@node Feathered beams
-@unnumberedsubsubsec Feathered beams
+@node Setting automatic beam behavior
+@subsubsection Setting automatic beam behavior
-Feathered beams are printed by setting the @code{grow-direction}
-property of a @code{Beam}. The @code{\featherDurations} function
-can be used to adjust note durations.
+@funindex autoBeamSettings
+@funindex (end * * * *)
+@funindex (begin * * * *)
+@cindex automatic beams, tuning
+@cindex tuning automatic beaming
-@lilypond[ragged-right,relative=1,fragment,verbatim,quote]
-\override Beam #'grow-direction = #LEFT
-\featherDurations #(ly:make-moment 5 4)
+@c [TODO: use \applyContext]
+
+In normal time signatures, automatic beams can start on any note
+but can end in only a few positions within the measure: beams can
+end on a beat, or at durations specified by the properties in
+@code{autoBeamSettings}. The properties in
+@code{autoBeamSettings} consist of a list of rules for where beams
+can begin and end. The default @code{autoBeamSettings} rules are
+defined in @file{scm/@/auto@/-beam@/.scm}.
+
+In order to add a rule to the list, use
+@example
+#(override-auto-beam-setting '(be p q n m) a b [context])
+@end example
+
+@itemize
+
+@item @code{be} is either @code{begin} or @code{end}.
+
+@item @code{p/q} is the duration of the note for which you want
+to add a rule. A beam is considered to have the duration of its
+shortest note. Set @code{p} and @code{q} to @code{'*'} to
+have this apply to any beam.
+
+@item @code{n/m} is the time signature to which
+this rule should apply. Set @code{n} and @code{m} to @code{'*'}
+to have this apply in any time signature.
+
+@item @code{a/b} is the position in the bar at which the beam should
+begin/end.
+
+@item @code{context} is optional, and it specifies the context at which
+the change should be made. The default is @code{'Voice}.
+
+@code{#(score-override-auto-beam-setting '(A B C D) E F)} is equivalent to
+@code{#(override-auto-beam-setting '(A B C D) E F 'Score)}.
+
+@end itemize
+
+For example, if automatic beams should always end on the first quarter
+note, use
+
+@example
+#(override-auto-beam-setting '(end * * * *) 1 4)
+@end example
+
+You can force the beam settings to only take effect on beams whose shortest
+note is a certain duration
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\time 2/4
+#(override-auto-beam-setting '(end 1 16 * *) 1 16)
+a16 a a a a a a a |
+a32 a a a a16 a a a a a |
+#(override-auto-beam-setting '(end 1 32 * *) 1 16)
+a32 a a a a16 a a a a a |
+@end lilypond
+
+You can force the beam settings to only take effect in certain time
+signatures
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\time 5/8
+#(override-auto-beam-setting '(end * * 5 8) 2 8)
+c8 c d d d
+\time 4/4
+e8 e f f e e d d
+\time 5/8
+c8 c d d d
+@end lilypond
+
+You can also remove a previously set beam-ending rule by using
+
+@example
+#(revert-auto-beam-setting '(be p q n m) a b [context])
+@end example
+
+@noindent
+be, p, q, n, m, a, b and context are the same as above. Note that the
+default rules are specified in @file{scm/@/auto@/-beam@/.scm},
+so you can revert rules that you did not explicitly create.
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\time 4/4
+a16 a a a a a a a a a a a a a a a
+#(revert-auto-beam-setting '(end 1 16 4 4) 1 4)
+a16 a a a a a a a a a a a a a a a
+@end lilypond
+
+The rule in a revert-auto-beam-setting statement must exactly match the
+original rule. That is, no wildcard expansion is taken into account.
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\time 1/4
+#(override-auto-beam-setting '(end 1 16 1 4) 1 8)
+a16 a a a
+#(revert-auto-beam-setting '(end 1 16 * *) 1 8) % this won't revert it!
+a a a a
+#(revert-auto-beam-setting '(end 1 16 1 4) 1 8) % this will
+a a a a
+@end lilypond
+
+
+
+@c TODO: old material -- not covered by above stuff, I think.
+If automatic beams should end on every quarter in 5/4 time, specify
+all endings
+@example
+#(override-auto-beam-setting '(end * * * *) 1 4 'Staff)
+#(override-auto-beam-setting '(end * * * *) 1 2 'Staff)
+#(override-auto-beam-setting '(end * * * *) 3 4 'Staff)
+#(override-auto-beam-setting '(end * * * *) 5 4 'Staff)
+@dots{}
+@end 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)
+#(override-auto-beam-setting '(end * * * *) 1 2)
+#(override-auto-beam-setting '(end * * * *) 7 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).
+
+If any unexpected beam behaviour occurs, check the default automatic beam
+settings in @file{scm/@/auto@/-beam@/.scm}
+for possible interference, because the beam
+endings defined there will still apply on top of your own overrides. Any
+unwanted endings in the default vales must be reverted for your time
+signature(s).
+
+For example, to typeset @code{(3 4 3 2)}-beam endings in 12/8, begin
+with
+
+@example
+%%% revert default values in scm/auto-beam.scm regarding 12/8 time
+#(revert-auto-beam-setting '(end * * 12 8) 3 8)
+#(revert-auto-beam-setting '(end * * 12 8) 3 4)
+#(revert-auto-beam-setting '(end * * 12 8) 9 8)
+
+%%% your new values
+#(override-auto-beam-setting '(end 1 8 12 8) 3 8)
+#(override-auto-beam-setting '(end 1 8 12 8) 7 8)
+#(override-auto-beam-setting '(end 1 8 12 8) 10 8)
+@end example
+
+@cindex automatic beam generation
+@cindex autobeam
+@funindex autoBeaming
+@cindex lyrics
+
+If beams are used to indicate melismata in songs, then automatic
+beaming should be switched off with @code{\autoBeamOff}.
+
+
+@refcommands
+
+@funindex \autoBeamOff
+@code{\autoBeamOff},
+@funindex \autoBeamOn
+@code{\autoBeamOn}.
+
+
+@refbugs
+
+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 for polyphonic voices, entered with @code{<<
+@dots{} \\ @dots{} >>}. If a polyphonic voice ends while an
+automatic beam is still accepting notes, it is not typeset.
+
+@seealso
+
+Snippets: @lsrdir{Rhythms,Rhythms}
+
+
+@node Manual beams
+@subsubsection Manual beams
+
+@cindex beams, manual
+
+In some cases it may be necessary to override the automatic
+beaming algorithm. For example, the autobeamer will not put beams
+over rests or bar lines, and in choral scores the beaming is
+often set to follow the meter of the lyrics rather than the
+notes. Such beams can be specified manually by
+marking the begin and end point with @code{[} and @code{]}
+
+@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
+{
+ r4 r8[ g' a r8] r8 g[ | a] r8
+}
+@end lilypond
+
+
+Individual notes may be marked with @code{\noBeam} to prevent them
+from being beamed:
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+\time 2/4 c8 c\noBeam c c
+@end lilypond
+
+@funindex ]
+@funindex [
+
+@funindex stemLeftBeamCount
+@funindex stemRightBeamCount
+
+Even more strict manual control with the beams can be achieved by
+setting the properties @code{stemLeftBeamCount} and
+@code{stemRightBeamCount}. They specify the number of beams to
+draw on the left and right side, respectively, of the next note.
+If either property is set, its value will be used only once, and
+then it is erased. In this example, the last @code{f} is printed
+with only one beam on the left side, i.e. the eigth-note beam of
+the group as a whole.
+
+@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
{
- c16[ c c c c c c]
+ f8[ r16 f g a]
+ f8[ r16
+ \set stemLeftBeamCount = #1
+ f g a]
}
@end lilypond
+
+@commonprop
+
+@node Feathered beams
+@subsubsection Feathered beams
+
+@cindex beams, feathered
+@funindex \featherDurations
+
+Feathered beams are used to indicate that a small group of notes
+should be played at an increasing (or decreasing) tempo, without
+changing the overall tempo of the piece. The extent of the
+feathered beam must be indicated manually using @code{[} and
+@code{]}, and the beam feathering is turned on by specifying a
+direction to the Beam property @code{grow-direction}.
+
+If the placement of the notes and the sound in the MIDI output
+is to reflect the ritardando or accelerando indicated by the
+feathered beam the notes must be grouped as a
+music expression delimited by braces and preceded by a
+@code{featheredDurations} command which specifies the ratio
+between the durations of the first and last notes in the group.
+
+The square brackets
+show the extent of the beam and the braces show
+which notes are to have their durations modified. Normally
+these would delimit the same group of notes, but this is not
+required: the two commands are independent.
+
+In the following example the eight 16th notes occupy exactly the
+same time as a half note, but the first note is one half as long
+as the last one, with the intermediate notes gradually
+lengthening. The first four 32nd notes gradually speed up, while
+the last four 32nd notes are at a constant tempo.
+
+@lilypond[ragged-right,relative=1,fragment,verbatim,quote]
+\override Beam #'grow-direction = #LEFT
+\featherDurations #(ly:make-moment 2 1)
+{ c16[ c c c c c c c] }
+\override Beam #'grow-direction = #RIGHT
+\featherDurations #(ly:make-moment 2 3)
+{ c32[ d e f] }
+% revert to non-feathered beams
+\override Beam #'grow-direction = #'()
+{ g32[ a b c] }
+@end lilypond
+
+@noindent
+The spacing in the printed output represents the
+note durations only approximately, but the midi output is exact.
+
@refbugs
The @code{\featherDurations} command only works with very short
-music snippets.
+music snippets, and when numbers in the fraction are small.
+
+@seealso
+
+Snippets: @lsrdir{Rhythms,Rhythms}
+
@node Bars
@menu
-* Bar check::
* Bar lines::
* Bar numbers::
-* Barnumber check::
+* Bar and bar number checks::
* Rehearsal marks::
@end menu
-@node Bar check
-@unnumberedsubsubsec Bar check
+@node Bar lines
+@subsubsection Bar lines
-@cindex Bar check
-@funindex barCheckSynchronize
-@funindex |
+@cindex bar lines
+@funindex \bar
+@cindex measure lines
+@cindex repeat bars
-Bar checks help detect errors in the durations. A bar check is
-entered using the bar symbol, @samp{|}. Whenever it is
-encountered during interpretation, it should fall on a measure
-boundary. If it does not, a warning is printed. In the next
-example, the second bar check will signal an error
+Bar lines delimit measures, and are also used to indicate
+repeats. Normally, simple bar lines are automatically inserted
+into the printed output at places based on the current time
+signature.
-@example
-\time 3/4 c2 e4 | g2 |
-@end example
+The simple bar lines inserted automatically can be changed to
+other types with the @code{\bar} command. For example, a closing
+double bar line is usually placed at the end of a piece:
-Bar checks can also be used in lyrics, for example
+@lilypond[quote,ragged-right,relative=1,fragment,verbatim]
+e4 d c2 \bar "|."
+@end lilypond
+
+@warning{An incorrect duration can lead to poorly formatted
+music.}
+
+It is not invalid if the final note in a bar does not
+end on the automatically entered bar line: the note is assumed
+to carry over into the next bar. But if a long sequence
+of such carry-over bars appears the music can appear compressed
+or even flowing off the page. This is because automatic line
+breaks happen only at the end of complete bars, i.e. where
+the end of a note coincides with the end of a bar.
+
+@cindex line breaks
+@cindex bar lines, invisible
+@cindex measure lines, invisible
+
+Line breaks are also permitted at manually inserted bar lines
+even within incomplete bars. To allow a line break without
+printing a bar line, use
@example
-\lyricmode @{
- \time 2/4
- Twin -- kle | Twin -- kle
-@}
+\bar ""
@end example
-Failed bar checks are caused by entering incorrect durations.
-Incorrect durations often completely garble up the score,
-especially if the score is polyphonic, so a good place to start
-correcting input is by scanning for failed bar checks and
-incorrect durations.
-
-@funindex |
-@funindex pipeSymbol
-
-It is also possible to redefine the meaning of @code{|}. This is
-done by assigning a music expression to @code{pipeSymbol},
-
-@lilypond[quote,ragged-right,verbatim]
-pipeSymbol = \bar "||"
+@noindent
+This will insert an invisible bar line and allow (but not
+force) a line break to occur at this point. The bar number
+counter is not increased. To force a line break see
+@ref{Line breaking}.
+
+This and other special bar lines may be inserted manually at any
+point. When they coincide with the end of a bar they replace
+the simple bar line which would have been inserted there
+automatically. When they do not coincide
+with the end of a bar the specified bar line is inserted at that
+point in the printed output. Such insertions do not affect
+the calculation and placement of subsequent automatic bar lines.
+
+The simple bar line and four types of double bar line are available
+for manual insertion:
-{ c'2 c' | c'2 c' }
+@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
+f1 \bar "|" g \bar "||" a \bar ".|" b \bar ".|." c \bar "|." d
@end lilypond
+@noindent
+together with dotted and dashed bar lines:
-@node Bar lines
-@unnumberedsubsubsec Bar lines
-
-@cindex Bar lines
-@funindex \bar
-@cindex measure lines
-@cindex repeat bars
-
-Bar lines delimit measures, but are also used to indicate repeats.
-Normally they are inserted automatically. Line breaks may only
-happen on bar lines.
+@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
+f1 \bar ":" g \bar "dashed" a
+@end lilypond
-Special types of bar lines can be forced with the @code{\bar} command
+@noindent
+and three types of repeat bar line:
-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
-c4 \bar "|:" c4
+@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
+f1 \bar "|:" g \bar ":|:" a \bar ":|" b
@end lilypond
-The following bar types are available
+@cindex repeats
-@lilypondfile[ragged-right,quote]{bar-lines.ly}
+Although the bar line types signifying repeats may be inserted
+manually they do not in themselves cause LilyPond to recognise
+a repeated section. Such repeated sections are better entered
+using the various repeat commands (see @ref{Repeats}), which
+automatically print the appropriate bar lines.
In addition, you can specify @code{"||:"}, which is equivalent to
@code{"|:"} except at line breaks, where it gives a double bar
line at the end of the line and a start repeat at the beginning of
the next line.
-To allow a line break where there is no visible bar line, use
-
-@example
-\bar ""
-@end example
-
-@noindent
-This will insert an invisible bar line and allow line breaks at
-this point (without increasing the bar number counter).
+@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+\override Score.RehearsalMark #'padding = #3
+c c c c
+\bar "||:"
+c c c c \break
+\bar "||:"
+c c c c
+@end lilypond
In scores with many staves, a @code{\bar} command in one staff is
automatically applied to all staves. The resulting bar lines are
@commonprop
@funindex whichBar
-@funindex repeatCommands
@funindex defaultBarType
-The command @code{\bar }@var{bartype} is a short cut for doing
-@code{\set Timing.whichBar = }@var{bartype}. Whenever
-@code{whichBar} is set to a string, a bar line of that type is
-created.
-
-A bar line is created whenever the @code{whichBar} property is
-set. At the start of a measure it is set to the contents of
-@code{Timing.defaultBarType}. The contents of
-@code{repeatCommands} are used to override default measure bars.
-
-You are encouraged to use @code{\repeat} for repetitions. See
-@ref{Repeats}.
+The command @code{\bar }@var{bartype} is a shortcut for
+@code{\set Timing.whichBar = }@var{bartype}. A bar line is
+created whenever the @code{whichBar} property is
+set.
+The default bar type used for automatically inserted bar lines is
+@code{"|"}. This may be changed at any time
+with @code{\set Timing.defaultBarType = }@var{bartype}.
@seealso
-In this manual: @ref{Repeats}, @ref{System start delimiters}.
+Notation Reference: @ref{Line breaking}, @ref{Repeats},
+@ref{System start delimiters}.
+
+Snippets: @lsrdir{Rhythms,Rhythms}
-Program reference: @internalsref{BarLine} (created at
+Internals Reference: @internalsref{BarLine} (created at
@internalsref{Staff} level), @internalsref{SpanBar} (across
-staves).
+staves), @internalsref{Timing_translator} (for Timing
+properties).
@node Bar numbers
-@unnumberedsubsubsec Bar numbers
+@subsubsection Bar numbers
-@cindex Bar numbers
+@cindex bar numbers
@cindex measure numbers
@funindex currentBarNumber
-Bar numbers are printed by default at the start of the line. The
-number itself is stored in the @code{currentBarNumber} property,
-which is normally updated automatically for every measure.
+Bar numbers are typeset by default at the start of every line except
+the first line. The number itself is stored in the
+@code{currentBarNumber} property, which is normally updated
+automatically for every measure. It may also be set manually:
@lilypond[verbatim,ragged-right,quote,fragment,relative]
-\repeat unfold 4 {c4 c c c} \break
+c1 c c c
+\break
\set Score.currentBarNumber = #50
-\repeat unfold 4 {c4 c c c}
+c1 c c c
@end lilypond
-Bar numbers may only be printed at bar lines; to print a bar
-number at the beginning of a piece, an empty bar line must be
-added
+
+@commonprop
+
+@funindex barNumberVisibility
+@cindex bar numbers, regular spacing
+
+Bar numbers can be typeset at regular intervals instead of just at
+the beginning of every line. To do this the default behaviour
+must be overridden to permit bar numbers to be printed at places
+other than the start of a line. This is controlled by the
+@code{break-visibility} property of @code{BarNumber}. This takes
+three values which may be set to @code{#t} or @code{#f} to specify
+whether the corresponding bar number is visible or not. The order
+of the three values is @code{end of line visible}, @code{middle of
+line visible}, @code{beginning of line visible}. In the following
+example bar numbers are printed at all possible places:
@lilypond[verbatim,ragged-right,quote,fragment,relative]
-\set Score.currentBarNumber = #50
-\bar ""
-\repeat unfold 4 {c4 c c c} \break
-\repeat unfold 4 {c4 c c c}
+\override Score.BarNumber #'break-visibility = ##(#t #t #t)
+\set Score.currentBarNumber = #11
+\bar "" % Permit first bar number to be printed
+c1 c c c
+\break
+c c c c
+@end lilypond
+
+@c All the rest of these examples will be added to LSR
+@c and moved into the Snippets. -gp
+
+@noindent
+and here the bar numbers are printed every two bars
+except at the end of the line:
+
+@lilypond[verbatim,ragged-right,quote,fragment,relative]
+\override Score.BarNumber #'break-visibility = ##(#f #t #t)
+\set Score.currentBarNumber = #11
+\bar "" % Permit first bar number to be printed
+% Print a bar number every 2nd bar
+\set Score.barNumberVisibility = #(every-nth-bar-number-visible 2)
+c1 c c c c
+\break
+c c c c c
@end lilypond
-Bar numbers can be typeset at regular intervals instead of at the
-beginning of each line. This is illustrated in the following
-example, whose source is available as
-@lsr{staff,making-bar-numbers-appear-at-regular-intervals.ly}.
+@cindex measure number, format
+@cindex bar number, format
-@lilypondfile[ragged-right,quote]{bar-number-regular-interval.ly}
+The size of the bar number may be changed. This is illustrated
+in the following example, which also shows how to enclose bar
+numbers in boxes and circles, and shows an alternative way
+of specifying @code{#(#f #t #t)} for @code{break-visibility}.
+
+@lilypond[verbatim,ragged-right,quote,fragment,relative]
+% Prevent bar numbers at the end of a line and permit them elsewhere
+\override Score.BarNumber #'break-visibility
+ = #end-of-line-invisible
+
+% Increase the size of the bar number by 2
+\override Score.BarNumber #'font-size = #2
+\repeat unfold 3 { c1 } \bar "|"
+
+% Draw a box round the following bar number(s)
+\override Score.BarNumber #'stencil
+ = #(make-stencil-boxer 0.1 0.25 ly:text-interface::print)
+\repeat unfold 3 { c1 } \bar "|"
+
+% Draw a circle round the following bar number(s)
+\override Score.BarNumber #'stencil
+ = #(make-stencil-circler 0.1 0.25 ly:text-interface::print)
+\repeat unfold 4 { c1 } \bar "|."
+@end lilypond
+
+@cindex bar number alignment
+
+Bar numbers by default are left-aligned to their parent object.
+This is usually the left edge of a line or, if numbers are printed
+within a line, the left bar line of the bar. The numbers may also
+be positioned directly on the bar line or right-aligned to the
+bar line:
+
+@lilypond[verbatim,ragged-right,quote,fragment,relative]
+\set Score.currentBarNumber = #111
+\override Score.BarNumber #'break-visibility = ##(#t #t #t)
+% Increase the size of the bar number by 2
+\override Score.BarNumber #'font-size = #2
+% Print a bar number every 2nd bar
+\set Score.barNumberVisibility = #(every-nth-bar-number-visible 2)
+c1 c1
+% Centre-align bar numbers
+\override Score.BarNumber #'self-alignment-X = #0
+c1 c1
+% Right-align bar numbers
+\override Score.BarNumber #'self-alignment-X = #-1
+c1 c1
+@end lilypond
Bar numbers can be removed entirely by removing the Bar number
-engraver from the score.
+engraver from the score context.
@lilypond[verbatim,ragged-right,quote]
\layout {
}
}
\relative c''{
-c4 c c c \break
-c4 c c c
+ c4 c c c \break
+ c4 c c c
}
@end lilypond
@seealso
-Program reference: @internalsref{BarNumber}.
+Snippets: @lsrdir{Rhythms,Rhythms}
-Examples: @lsrdir{staff}
+Internals Reference: @internalsref{BarNumber}.
@refbugs
-Bar numbers can collide with the @internalsref{StaffGroup}
-bracket, if there is one at the top. To solve this, the
-@code{padding} property of @internalsref{BarNumber} can be used to
-position the number correctly.
+Bar numbers may collide with the top of the
+@internalsref{StaffGroup} bracket, if there is one. To solve
+this, the @code{padding} property of @internalsref{BarNumber} can
+be used to position the number correctly.
+Bar numbers may only be printed at bar lines; to print a bar
+number at the beginning of a piece, an empty bar line must be
+inserted there, and a value other than @code{1} must be placed
+in @code{currentBarNumber}:
+
+@lilypond[verbatim,ragged-right,quote,fragment,relative]
+\set Score.currentBarNumber = #50
+\bar ""
+c1 c c c
+c1 c c c
+\break
+@end lilypond
-@node Barnumber check
-@unnumberedsubsubsec Barnumber check
+
+
+@node Bar and bar number checks
+@subsubsection Bar and bar number checks
+
+@cindex bar check
+@funindex barCheckSynchronize
+@funindex |
+
+Bar checks help detect errors in the entered durations.
+A bar check may be entered using the bar symbol, @code{|},
+at any place where a bar line is expected to fall.
+If bar check lines are encountered at other places,
+a list of warnings is printed in the log file,
+showing the line numbers and lines
+in which the bar checks failed. In the next
+example, the second bar check will signal an error.
+
+@example
+\time 3/4 c2 e4 | g2 |
+@end example
+
+Bar checks can also be used in lyrics, for example
+
+@example
+\lyricmode @{
+ \time 2/4
+ Twin -- kle | Twin -- kle |
+@}
+@end example
+
+An incorrect duration can result in a completely garbled score,
+especially if the score is polyphonic, so a good place to start
+correcting input is by scanning for failed bar checks and
+incorrect durations.
+
+@funindex |
+@funindex pipeSymbol
+
+It is also possible to redefine the action taken when a bar check
+or pipe symbol, @code{|}, is encountered in the input, so that
+it does something other than a bar check. This is done by
+assigning a music expression to @code{pipeSymbol}.
+In the following example @code{|} is set to insert a double bar
+line wherever it appears in the input, rather than checking
+for end of bar.
+
+@lilypond[quote,ragged-right,verbatim]
+pipeSymbol = \bar "||"
+{
+ c'2 c'2 |
+ c'2 c'2
+ c'2 | c'2
+ c'2 c'2
+}
+@end lilypond
When copying large pieces of music, it can be helpful to check
that the LilyPond bar number corresponds to the original that you
will print a warning if the @code{currentBarNumber} is not 123
when it is processed.
+@seealso
+
+Snippets: @lsrdir{Rhythms,Rhythms}
+
@node Rehearsal marks
-@unnumberedsubsubsec Rehearsal marks
+@subsubsection Rehearsal marks
-@cindex Rehearsal marks
+@cindex rehearsal marks
+@cindex mark, rehearsal
@funindex \mark
To print a rehearsal mark, use the @code{\mark} command
mark manually. The value to use is stored in the property
@code{rehearsalMark}.
+@cindex rehearsal mark format
+@cindex rehearsal mark style
+@cindex style, rehearsal mark
+@cindex format, rehearsal mark
+@cindex mark, rehearsal, style
+@cindex mark, rehearsal, format
+
The style is defined by the property @code{markFormatter}. It is
a function taking the current mark (an integer) and the current
context as argument. It should return a markup object. In the
-following example, @code{markFormatter} is set to a canned
-procedure. After a few measures, it is set to function that
+following example, @code{markFormatter} is set to a pre-defined
+procedure. After a few measures, it is set to a procedure that
produces a boxed number.
@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
@seealso
-This manual: @ref{Text marks}.
+Snippets: @lsrdir{Rhythms,Rhythms}
+
+This manual: @ref{The Feta font}, @ref{Text marks}.
-Program reference: @internalsref{RehearsalMark}.
+Internals Reference: @internalsref{RehearsalMark}.
Init files: @file{scm/@/translation@/-functions@/.scm} contains
the definition of @code{format-mark-numbers} and
@code{format-mark-letters}. They can be used as inspiration for
other formatting functions.
-Examples: @lsr{parts,rehearsal-mark-numbers.ly}
+Examples: @c @lsr{parts,rehearsal-mark-numbers.ly}
@node Special rhythmic concerns
* Grace notes::
* Aligning to cadenzas::
* Time administration::
-* Proportional notation (introduction)::
@end menu
@node Grace notes
-@unnumberedsubsubsec Grace notes
+@subsubsection Grace notes
@funindex \grace
@cindex ornaments
@cindex appoggiatura
@cindex acciaccatura
-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
+Grace notes are ornaments that are written out. They are made with
+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.
@lilypond[quote,ragged-right,relative=2,verbatim,fragment]
-b4 \acciaccatura d8 c4 \appoggiatura e8 d4
-\acciaccatura { g16[ f] } e4
+c4 \grace c16 c4
+\grace { c16[ d16] } c2 c4
@end lilypond
-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.
+Two special forms of the @code{\grace} command exist.
+An @emph{acciaccatura}, which should be played as very short,
+is denoted by a slurred small note with a slashed stem. The
+@emph{appoggiatura}, a grace note that takes a fixed fraction of the
+main note, 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:
@lilypond[quote,ragged-right,relative=2,verbatim,fragment]
-c4 \grace c16 c4
-\grace { c16[ d16] } c2 c4
+b4 \acciaccatura d8 c4
+\appoggiatura e8 d4
+\acciaccatura { g16[ f] } e4
@end lilypond
@noindent
-Unlike @code{\acciaccatura} and @code{\appoggiatura}, the
-@code{\grace} command does not start a slur.
-
-@cindex timing, internal
-
-Internally, timing for grace notes is done using a second,
-@q{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
-
-@lilypond[quote,ragged-right]
-<<
- \relative c''{
- c4 \grace c16 c4 \grace {
- c16[ d16] } c2 c4
- }
- \new Lyrics \lyricmode {
- \override LyricText #'font-family = #'typewriter
-
- \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
+@code{\acciaccatura} and @code{\appoggiatura} start a slur,
+@code{\grace} does not.
The placement of grace notes is synchronized between different
staves. In the following example, there are two sixteenth grace
@funindex \afterGrace
+@cindex grace notes, following
+
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.
@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.
+half-note), the space between the main-note and the grace
+may be adjusted.
A @code{\grace} music expression will introduce special
typesetting settings, for example, to produce smaller type, and
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}.
+@code{stopAppoggiaturaMusic}. The default values of these can be
+seen in the file @file{ly/@/grace@/-init@/.ly}. By redefining
+them other effects may be obtained.
+
+@cindex stem, with slash
@noindent
-The slash through the stem in acciaccaturas can be obtained in
+The slash through the stem in @emph{acciaccatura}s can be obtained in
other situations by @code{\override Stem #'stroke-style =
#"grace"}.
@commonprop
-Grace notes may be forced to use floating spacing,
+Grace notes may be forced to use align with regular notes
+in other staves by setting @code{strict-grace-spacing} to
+##t:
@lilypond[relative=2,ragged-right]
<<
@seealso
-Program reference: @internalsref{GraceMusic}.
+Music Glossary:
+@rglos{grace notes},
+@rglos{acciaccatura},
+@rglos{appoggiatura}
+
+Snippets: @lsrdir{Rhythms,Rhythms}
+
+Internals Reference: @internalsref{GraceMusic}.
@refbugs
-A score that starts with a @code{\grace} expression needs an
-explicit @code{\new Voice} declaration, otherwise the main note
-and the grace note end up on different staves.
+A multi-note beamed @emph{acciaccatura} is printed without a slash,
+and looks exactly the same as a multi-note beamed
+@emph{appoggiatura}.
+@c TODO Add link to LSR snippet to add slash when available
Grace note synchronization can also lead to surprises. Staff
notation, such as key signatures, bar lines, etc., are also
@noindent
This can be remedied by inserting grace skips of the corresponding
-durations in the other staves. For the above example
+durations in the other staves. For the above example
@lilypond[quote,ragged-right,relative=2,verbatim,fragment]
<< \new Staff { e4 \bar "|:" \grace c16 d4 }
expressions. Nesting or juxtaposing grace sections is not
supported, and might produce crashes or other errors.
-
@node Aligning to cadenzas
-@unnumberedsubsubsec Aligning to cadenzas
+@subsubsection Aligning to cadenzas
+
+@cindex cadenza
+@cindex cadenza, aligning to
+@cindex aligning to cadenza
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.
-A solution to this problem are the functions
+A solution to this problem is to use 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.
+functions take a piece of music as argument, and generate a multi-rest
+or @code{\skip}, exactly as long as the piece. The use of
+@code{mmrest-of-length} is demonstrated in the following example.
@lilypond[verbatim,ragged-right,quote]
cadenza = \relative c' {
>>
@end lilypond
+@seealso
+
+Snippets: @lsrdir{Rhythms,Rhythms}
+
@node Time administration
-@unnumberedsubsubsec Time administration
+@subsubsection Time administration
-@cindex Time administration
+@cindex time administration
+@cindex timing (within the score)
+@cindex music, unmetered
+@cindex unmetered music
-Time is administered by the
-@internalsref{Time_signature_engraver}, which usually lives in the
-@internalsref{Score} context. The bookkeeping deals with the
-following variables
+@funindex currentBarNumber
+@funindex measurePosition
+@funindex measureLength
+
+Time is administered by the @code{Timing_translator}, which by
+default is to be found in the @code{Score} context. An alias,
+@code{Timing}, is added to the context in which the
+@code{Timing_translator} is placed.
+
+The following properties of @code{Timing} are used
+to keep track of timing within the score.
+
+@cindex bar number
+@cindex measure number
@table @code
@item currentBarNumber
-The measure number.
+The current measure number. For an example showing the
+use of this property see @ref{Bar numbers}.
@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.
+4/4 time this is@tie{}1, and for 6/8 it is 3/4. Its value
+determines when bar lines are inserted and how automatic beams
+should be generated.
@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.
+quantity is reset by subtracting @code{measureLength} whenever
+@code{measureLength} is reached or exceeded. When that happens,
+@code{currentBarNumber} is incremented.
@item timing
If set to true, the above variables are updated for every time
@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.
+explicitly. In the next example, the default 4/4 time
+signature is printed, but @code{measureLength} is set to 5/4.
+At 4/8 through the third measure, the @code{measurePosition} is
+advanced by 1/8 to 5/8, shortening that bar by 1/8.
+The next bar line then falls at 9/8 rather than 5/4.
@lilypond[quote,ragged-right,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
+\set Score.measurePosition = #(ly:make-moment 5 8)
+b4 b4 b8
c4 c1
@end lilypond
notes.
-@node Proportional notation (introduction)
-@unnumberedsubsubsec Proportional notation (introduction)
-@cindex Proportional notation
-
-See @ref{Proportional notation}.
-
+@seealso
-TODO: remove all this stuff?
+This manual: @ref{Bar numbers}, @ref{Unmetered music}
-Notes can be spaced proportionally to their time-difference by
-assigning a duration to @code{proportionalNotationDuration}
+Snippets: @lsrdir{Rhythms,Rhythms}
-@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
-<<
- \set Score.proportionalNotationDuration = #(ly:make-moment 1 16)
- \new Staff { c8[ c c c c c] c4 c2 r2 }
- \new Staff { c2 \times 2/3 { c8 c c } c4 c1 }
->>
-@end lilypond
+Internals Reference: @internalsref{Timing_translator},
+@internalsref{Score}
-Setting this property only affects the ideal spacing between
-consecutive notes. For true proportional notation, the following
-settings are also required.
-@itemize @bullet
-@item True proportional notation requires that symbols are allowed
-to overstrike each other. That is achieved by removing the
-@internalsref{Separating_line_group_engraver} from
-@internalsref{Staff} context.
-@item Spacing influence of prefatory matter (clefs, bar lines,
-etc.) is removed by setting the @code{strict-note-spacing}
-property to @code{#t} in @internalsref{SpacingSpanner} grob.
-@item Optical spacing tweaks are switched by setting
-@code{uniform-stretching} in @internalsref{SpacingSpanner} to
-true.
-
-@end itemize
-
-@seealso
-Examples: @lsr{spacing,proportional@/-spacing@/.ly},
-@lsr{spacing,proportional@/-strict@/-grace@/-notes@/.ly}, and
-@lsr{spacing,proportional@/-strict@/-notespacing@/.ly}
-An example of strict proportional notation is in the
-example file @file{input/proportional.ly}.
projects / lilypond.git / blobdiff