]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/notation/rhythms.itely
Imported Upstream version 2.18.0
[lilypond.git] / Documentation / notation / rhythms.itely
index c2a06b42029b9649b5a2348e4cc5bb9809d5ace3..f6842824a83783ce7c6b880d74fb37411ab6d973 100644 (file)
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.16.0"
+@c \version "2.17.30"
 
 @node Rhythms
 @section Rhythms
@@ -143,7 +143,7 @@ the staff; see @ref{Direction and placement}.
 @snippets
 
 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
-{alternative-breve-note.ly}
+{alternative-breve-notes.ly}
 
 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {changing-the-number-of-augmentation-dots-per-note.ly}
@@ -186,26 +186,38 @@ rests from 128th to maxima (8 x whole) may be printed.
 @cindex tuplets
 @cindex triplets
 
-@funindex \times
-@funindex times
+@funindex \tuplet
+@funindex tuplet
 
-Tuplets are made from a music expression by multiplying all the
-durations with a fraction:
+Tuplets are made from a music expression with the @code{\tuplet}
+command, multiplying the speed of the music expression by a
+fraction:
 
 @example
-\times @var{fraction} @{ @var{music} @}
+\tuplet @var{fraction} @{ @var{music} @}
 @end example
 
 @noindent
-The duration of @code{@var{music}} will be multiplied by the
-fraction.  The fraction's denominator will be printed over or
+The fraction's numerator 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 duration of 2, so
-the notes are 2/3 of their written length.
+tuplets are triplets: 3@tie{}notes sound within the duration
+normally allowed for@tie{}2:
 
 @lilypond[quote,verbatim,relative=2]
-a2 \times 2/3 { b4 b b }
-c4 c \times 2/3 { b4 a g }
+a2 \tuplet 3/2 { b4 b b }
+c4 c \tuplet 3/2 { b4 a g }
+@end lilypond
+
+@cindex tuplet grouping
+@noindent
+When entering long passages of tuplets, having to write a separate
+@code{\tuplet} command for each group is inconvenient.  It is
+possible to specify the duration of one tuplet group directly
+before the music in order to have the tuplets grouped
+automatically:
+
+@lilypond[quote,verbatim,relative=2]
+g2 r8 \tuplet 3/2 8 { cis16 d e e f g g f e }
 @end lilypond
 
 @cindex tuplet bracket placement
@@ -224,7 +236,7 @@ Tuplets may be nested:
 
 @lilypond[quote,verbatim,relative=2]
 \autoBeamOff
-c4 \times 4/5 { f8 e f \times 2/3 { e[ f g] } } f4
+c4 \tuplet 5/4 { f8 e f \tuplet 3/2 { e[ f g] } } f4
 @end lilypond
 
 Modifying nested tuplets which begin at the same musical moment
@@ -296,7 +308,7 @@ Internals Reference:
 @knownissues
 Grace notes may be placed within tuplet brackets, @emph{except}
 when a staff begins with a grace note followed by a tuplet.  In this
-particular case, the grace note must be placed before the @code{\times}
+particular case, the grace note must be placed before the @code{\tuplet}
 command to avoid errors.
 
 @cindex tempo marks within tuplet brackets
@@ -380,6 +392,15 @@ Notation Reference:
 Snippets:
 @rlsr{Rhythms}.
 
+@knownissues
+The calculation of the position within a measure must take into
+account all the scaling factors applied to the notes within that
+measure and any fractional carry-out from earlier measures.  This
+calculation is carried out using rational numbers.  If an intermediate
+numerator or denominator in that calculation exceeds 2^30 the
+execution and typesetting will stop at that point without indicating
+an error.
+
 
 @node Ties
 @unnumberedsubsubsec Ties
@@ -396,10 +417,12 @@ 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{~}).
+A tie is entered by appending a tilde symbol (@code{~}) to the first
+of each pair of notes being tied.  This indicates that the note
+should be tied to the following note, which must be at the same pitch.
 
 @lilypond[quote,verbatim,relative=2]
-a2 ~ a
+a2~ a4~ a16 r r8
 @end lilypond
 
 Ties are used either when the note crosses a bar line, or when
@@ -408,8 +431,8 @@ used when note values cross larger subdivisions of the measure:
 
 @lilypond[verbatim,quote]
 \relative c' {
-  r8 c~ c2 r4 |
-  r8^"not" c2 ~ c8 r4
+  r8 c~ c2 r4 |
+  r8^"not" c2~ c8 r4
 }
 @end lilypond
 
@@ -423,11 +446,11 @@ ties them across bar lines.
 
 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
+created.  Chords may be partially tied by placing the ties inside
 the chord.
 
 @lilypond[quote,verbatim,relative=1]
-<c e g> ~ <c e g>
+<c e g>~ <c e g c>
 <c~ e g~ b> <c e g b>
 @end lilypond
 
@@ -443,7 +466,7 @@ When a second alternative of a repeat starts with a tied note, you
 have to specify the repeated tie as follows:
 
 @lilypond[quote,relative=2,verbatim]
-\repeat volta 2 { c g <c e>2 ~ }
+\repeat volta 2 { c g <c e>2~ }
 \alternative {
   % First alternative: following note is tied normally
   { <c e>2. r4 }
@@ -475,7 +498,7 @@ be entered as follows:
 @funindex \tieNeutral
 @funindex tieNeutral
 
-Ties may be manually placed above or below the staff; see
+Ties may be made to curve up or down manually; see
 @ref{Direction and placement}.
 
 @cindex ties, appearance
@@ -496,26 +519,26 @@ dashed.
 
 @lilypond[quote, verbatim, relative=1]
 \tieDotted
-c2 ~ c
+c2~ c
 \tieDashed
-c2 ~ c
+c2~ c
 \tieHalfDashed
-c2 ~ c
+c2~ c
 \tieHalfSolid
-c2 ~ c
+c2~ c
 \tieSolid
-c2 ~ c
+c2~ c
 @end lilypond
 
 Custom dash patterns can be specified:
 
 @lilypond[quote, verbatim, relative=1]
 \tieDashPattern #0.3 #0.75
-c2 ~ c
+c2~ c
 \tieDashPattern #0.7 #1.5
-c2 ~ c
+c2~ c
 \tieSolid
-c2 ~ c
+c2~ c
 @end lilypond
 
 Dash pattern definitions for ties have the same structure as dash
@@ -526,11 +549,11 @@ Override @var{whiteout} and @var{layer} layout properties for ties that
 collide with other objects in a staff.
 
 @lilypond[verbatim,quote,ragged-right,relative=2]
-\override Tie #'layer = #-2
-\override Staff.TimeSignature #'layer = #-1
-\override Staff.KeySignature #'layer = #-1
-\override Staff.TimeSignature #'whiteout = ##t
-\override Staff.KeySignature #'whiteout = ##t
+\override Tie.layer = #-2
+\override Staff.TimeSignature.layer = #-1
+\override Staff.KeySignature.layer = #-1
+\override Staff.TimeSignature.whiteout = ##t
+\override Staff.KeySignature.whiteout = ##t
 b2 b~
 \time 3/4
 \key a \major
@@ -623,7 +646,7 @@ commands:
 \new Staff {
   % These two lines are just to prettify this example
   \time 16/1
-  \override Staff.TimeSignature #'stencil = ##f
+  \omit Staff.TimeSignature
   % Print a maxima rest, equal to four breves
   r\maxima
   % Print a longa rest, equal to two breves
@@ -883,10 +906,10 @@ following example:}
 
 @lilypond[quote,verbatim,relative=2]
 % This fails, as the wrong object name is specified
-\override TextScript #'padding = #5
+\override TextScript.padding = #5
 R1^"wrong"
 % This is the correct object name to be specified
-\override MultiMeasureRestText #'padding = #5
+\override MultiMeasureRestText.padding = #5
 R1^"right"
 @end lilypond
 
@@ -1118,37 +1141,6 @@ for the time signature that go beyond ending at every beat, as
 described in @ref{Setting automatic beam behavior}.
 @end enumerate
 
-The context containing @code{\overrideTimeSignatureSettings} must
-be instantiated before the @code{\overrideTimeSignatureSettings}
-call is executed.  That means it must either be explicitly
-instantiated or there must be music in the context before the
-@code{\overrideTimeSignatureSettings} call:
-
-@lilypond[quote,verbatim]
-\score {
-  \relative c' {
-    % This call will fail because the context isn't yet instantiated
-    \overrideTimeSignatureSettings
-      4/4        % timeSignatureFraction
-      1/4        % baseMomentFraction
-      #'(3 1)    % beatStructure
-      #'()       % beamExceptions
-    \time 4/4
-    c8^\markup {"Beamed (2 2)"}
-    \repeat unfold 7 { c8 } |
-    % This call will succeed
-    \overrideTimeSignatureSettings
-      4/4        % timeSignatureFraction
-      1/4        % baseMomentFraction
-      #'(3 1)    % beatStructure
-      #'()       % beamExceptions
-    \time 4/4
-    c8^\markup {"Beamed (3 1)"}
-    \repeat unfold 7 { c8 } |
-  }
-}
-@end lilypond
-
 
 @cindex time signature properties, restoring default values
 @cindex restoring default properties for time signatures
@@ -1273,7 +1265,7 @@ e4. d8 c2
 Metronome marks may also be printed as a range of two numbers:
 
 @lilypond[verbatim,quote,relative=1]
-\tempo 4 = 40 ~ 46
+\tempo 4 = 40 - 46
 c4. e8 a4 g
 b,2 d4 r
 @end lilypond
@@ -1310,6 +1302,29 @@ written by including an empty string in the input:
 d4 g e c
 @end lilypond
 
+@funindex \markLengthOn
+@funindex markLengthOn
+@funindex \markLengthOff
+@funindex markLengthOff
+
+In a part for an instrument with long periods of rests,
+tempo indications sometimes follow each other closely.
+The command @code{\markLengthOn} provides extra horizontal space
+to prevent tempo indications from overlapping, and @code{\markLengthOff}
+restores the default behavior of ignoring tempo marks
+for horizontal spacing.
+
+@lilypond[verbatim,quote,relative=0]
+\compressFullBarRests
+\markLengthOn
+\tempo "Molto vivace"
+R1*12
+\tempo "Meno mosso"
+R1*16
+\markLengthOff
+\tempo "Tranquillo"
+R1*20
+@end lilypond
 
 @snippets
 
@@ -1383,25 +1398,26 @@ The @var{duration} can be any value less than a full measure:
 r4 e8 | a4 c8 b c4 |
 @end lilypond
 
-The @code{\partial @var{duration}} can also be written as;
+@code{\partial @var{duration}} can also be written as:
 
 @example
 \set Timing.measurePosition -@var{duration}
 @end example
 
-So @code{\partial 8} becomes:
+So the first example above could be written:
 
 @lilypond[quote,verbatim,relative=1]
 \time 3/4
-\set Timing.measurePosition = #(ly:make-moment -1 8)
+\set Timing.measurePosition = #(ly:make-moment -1/8)
 e8 | a4 c8 b c4 |
 @end lilypond
 
-The property @code{measurePosition} contains a rational number
-indicating how much of the measure has passed at this point.  Note
-that this is set to a negative number by the @code{\partial} command:
-i.e., @code{\partial 4} is internally translated to @w{@code{-4}},
-meaning @qq{there is a quarter note left in the measure.}
+The property @code{measurePosition} contains a rational number, which
+is usually positive and indicates how much of the measure has passed
+at this point.  The @code{\partial @var{duration}} command sets it to
+a negative number, when it has a different meaning: it then says that
+the current (first) bar will be @emph{preceded} by a bar 0 (the partial
+bar) with a duration given by @var{duration}.
 
 @seealso
 Music Glossary:
@@ -1425,7 +1441,7 @@ occur, so use @code{\set Timing.measurePosition} instead.
 \time 6/8
 \partial 8
 e8 | a4 c8 b[ c b] |
-\set Timing.measurePosition = #(ly:make-moment -1 4)
+\set Timing.measurePosition = #(ly:make-moment -1/4)
 r8 e,8 | a4 c8 b[ c b] |
 @end lilypond
 
@@ -1476,7 +1492,7 @@ Bar numbering is resumed at the end of the cadenza.
 
 @lilypond[verbatim,relative=2,quote]
 % Show all bar numbers
-\override Score.BarNumber #'break-visibility = #all-visible
+\override Score.BarNumber.break-visibility = #all-visible
 c4 d e d
 \cadenzaOn
 c4 c d8[ d d] f4 g4.
@@ -1485,15 +1501,20 @@ c4 c d8[ d d] f4 g4.
 d4 e d c
 @end lilypond
 
-A new bar is never started within a cadenza, even if one or more
-@code{\bar} commands are inserted within it.  Therefore, reminder
-accidentals will need to be added manually.  See @ref{Accidentals}.
+Inserting a @code{\bar} command within a cadenza does not start a new
+measure, even if a bar line is printed.  So any accidentals -- which
+are usually assumed to remain in force until the end of the measure --
+will still be valid after the bar line printed by @code{\bar}.  If
+subsequent accidentals should be printed, forced accidentals or
+reminder accidentals need to be inserted manually, see
+@ref{Accidentals}.
 
 @lilypond[verbatim,relative=2,quote]
 c4 d e d
 \cadenzaOn
 cis4 d cis d
 \bar "|"
+% First cis is printed without alteration even if it's after a \bar
 cis4 d cis! d
 \cadenzaOff
 \bar "|"
@@ -1554,20 +1575,6 @@ stretches of unmetered music to permit breaking:
 \bar ""
 @end example
 
-Explicitly create a @code{Voice} context when starting a piece with
-@code{\cadenzaOn}, else unexpected errors may occur.
-
-@example
-\new Voice @{
-  \relative c' @{
-    \cadenzaOn
-    c16[^"Solo Free Time" d e f] g2.
-    \bar "||"
-    \cadenzaOff
-  @}
-@}
-@end example
-
 
 @node Polymetric notation
 @unnumberedsubsubsec Polymetric notation
@@ -1585,8 +1592,8 @@ Explicitly create a @code{Voice} context when starting a piece with
 @funindex timeSignatureFraction
 @funindex \scaleDurations
 @funindex scaleDurations
-@funindex \times
-@funindex times
+@funindex \tuplet
+@funindex tuplet
 
 Polymetric notation is supported explicitly or by manually modifying the
 visible time signature symbol and/or scaling note durations.
@@ -1627,7 +1634,7 @@ affect the autobeaming rules.
     \scaleDurations 3/5 {
       \repeat unfold 2 { c8[ c c] }
       \repeat unfold 2 { c8[ c] } |
-      c4. c \times 2/3 { c8[ c c] } c4
+      c4. c \tuplet 3/2 { c8[ c c] } c4
     }
   }
 >>
@@ -1940,7 +1947,7 @@ c16 c8
 @cindex beams, with melismata
 
 @warning{If beams are used to indicate melismata in songs, then
-automatic beaming should be switched off with @code{\autoBeamOff}
+automatic beaming should be switched off with @code{@bs{}autoBeamOff}
 and the beams indicated manually.  Using @code{@bs{}partcombine} with
 @code{@bs{}autoBeamOff} can produce unintended results.  See the
 snippets for more information.}
@@ -2023,13 +2030,18 @@ below, or alternatively the default values themselves may be changed
 as explained in @ref{Time signature}.
 
 If a @code{beamExceptions} rule is defined for the time signature in
-force, that rule is used to determine the beam placement.  If no
-@code{beamExceptions} rule is defined for the time signature in force,
-the beam placement is determined by the settings of @code{baseMoment}
-and @code{beatStructure}.
+force, that rule alone is used to determine the beam placement; the
+values of @code{baseMoment} and @code{beatStructure} are ignored.
+
+If no @code{beamExceptions} rule is defined for the time signature
+in force, the beam placement is determined by the values of
+@code{baseMoment} and @code{beatStructure}.
+
+
+@subsubsubheading Beaming based on @code{baseMoment} and @code{beatStructure}
 
 By default, @code{beamExceptions} rules are defined for most common
-time signatures, so the @code{beamException} rules must be disabled
+time signatures, so the @code{beamExceptions} rules must be disabled
 if automatic beaming is to be based on @code{baseMoment} and
 @code{beatStructure}.  The @code{beamExceptions} rules are disabled
 by
@@ -2038,41 +2050,35 @@ by
 \set Timing.beamExceptions = #'()
 @end example
 
-
-@subsubsubheading Beaming based on @code{baseMoment} and @code{beatStructure}
-
-In most instances, automatic beams will end at the end of a beat.
-The ending points for beats are determined by the context properties
-@code{baseMoment} and @code{beatStructure}.  @code{beatStructure}
-is a scheme list that defines the length of each beat in the measure
-in units of @code{baseMoment}.  By default, @code{baseMoment} is
-one over the denominator of the time signature.  By default,
-each unit of length @code{baseMoment} is a single beat.
+When @code{beamExceptions} is set to @code{#'()}, either due to an
+explicit setting or because no @code{beamExceptions} rules are defined
+internally for the time signature in force, the ending points for
+beams are on beats as specified by the context properties
+@code{baseMoment} and @code{beatStructure}.  @code{beatStructure} is
+a scheme list that defines the length of each beat in the measure in
+units of @code{baseMoment}.  By default, @code{baseMoment} is one
+over the denominator of the time signature.  By default, each unit of
+length @code{baseMoment} is a single beat.
 
 @lilypond[quote,relative=2,verbatim]
 \time 5/16
 c16^"default" c c c c |
+% beamExceptions are unlikely to be defined for 5/16 time,
+% but let's disable them anyway to be sure
+\set Timing.beamExceptions = #'()
 \set Timing.beatStructure = #'(2 3)
 c16^"(2+3)" c c c c |
 \set Timing.beatStructure = #'(3 2)
 c16^"(3+2)" c c c c |
 @end lilypond
 
-If a common time signature is being used, @code{beamExceptions}
-@emph{must} be disabled to enable @code{beatStructure} to work.
-The @code{\set Timing.beamExceptions = #'()} command can always
-be included if beaming is being determined by @code{beatStructure}.
-
 @lilypond[quote,relative=2,verbatim]
 \time 4/4
 a8^"default" a a a a a a a
-
-\set Timing.baseMoment = #(ly:make-moment 1 4)
-\set Timing.beatStructure = #'(1 1 1 1)
-a8^"no change" a a a a a a a
-
+% Disable beamExceptions because they are definitely
+% defined for 4/4 time
 \set Timing.beamExceptions = #'()
-\set Timing.baseMoment = #(ly:make-moment 1 4)
+\set Timing.baseMoment = #(ly:make-moment 1/4)
 \set Timing.beatStructure = #'(1 1 1 1)
 a8^"changed" a a a a a a a
 @end lilypond
@@ -2084,6 +2090,8 @@ enclosing context will apply.
 @lilypond[quote, verbatim,relative=1]
 \new Staff {
   \time 7/8
+  % No need to disable beamExceptions
+  % as they are not defined for 7/8 time
   \set Staff.beatStructure = #'(2 3 2)
   <<
     \new Voice = one {
@@ -2127,7 +2135,9 @@ compatible with the new value of @code{baseMoment}.
 
 @lilypond[quote,verbatim,relative=2]
 \time 5/8
-\set Timing.baseMoment = #(ly:make-moment 1 16)
+% No need to disable beamExceptions
+% as they are not defined for 5/8 time
+\set Timing.baseMoment = #(ly:make-moment 1/16)
 \set Timing.beatStructure = #'(7 3)
 \repeat unfold 10 { a16 }
 @end lilypond
@@ -2218,7 +2228,7 @@ if @code{beamExceptions} is not reset.
 
 @lilypond[quote,verbatim,relative=2]
 \time 4/4
-\set Timing.baseMoment = #(ly:make-moment 1 8)
+\set Timing.baseMoment = #(ly:make-moment 1/8)
 \set Timing.beatStructure = #'(3 3 2)
 % This won't beam (3 3 2) because of beamExceptions
 \repeat unfold 8 {c8} |
@@ -2235,7 +2245,7 @@ reset @code{beamExceptions}.
 \time 3/4
 % by default we beam in (6) due to beamExceptions
 \repeat unfold 6 {a8} |
-% This will beam (1 1 1) due to beatLength
+% This will beam (1 1 1) due to default baseMoment and beatStructure
 \set Timing.beamExceptions = #'()
 \repeat unfold 6 {a8}
 @end lilypond
@@ -2265,7 +2275,7 @@ the appearance of beams:
 
 @itemize
 @item
-If a manual beam is specified with @code{[..]} set the beam
+If a manual beam is specified with @code{[@dots{}]} set the beam
 as specified, otherwise
 
 @item
@@ -2275,7 +2285,7 @@ beams may end, otherwise
 
 @item
 if a beam-ending rule is defined in @code{beamExceptions}
-for a longer beam-type, use it to determined the valid places
+for a longer beam-type, use it to determine the valid places
 where beams may end, otherwise
 
 @item
@@ -2354,7 +2364,7 @@ in only one staff.
 <<
   \new Staff {
     \time 3/4
-    \set Timing.baseMoment = #(ly:make-moment 1 8)
+    \set Timing.baseMoment = #(ly:make-moment 1/8)
     \set Timing.beatStructure = #'(1 5)
     \repeat unfold 6 { a8 }
   }
@@ -2433,7 +2443,7 @@ Unbeamed grace notes are not put into normal note beams.
 
 @lilypond[quote,verbatim,relative=2]
 c4 d8[
-\grace { e32[ d c d] }
+\grace { e32 d c d }
 e8] e[ e
 \grace { f16 }
 e8 e]
@@ -2524,14 +2534,14 @@ lengthening.  The first four 32nd notes gradually speed up, while
 the last four 32nd notes are at a constant tempo.
 
 @lilypond[relative=1,verbatim,quote]
-\override Beam #'grow-direction = #LEFT
-\featherDurations #(ly:make-moment 2 1)
+\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)
+\override Beam.grow-direction = #RIGHT
+\featherDurations #(ly:make-moment 2/3)
 { c32[ d e f] }
 % revert to non-feathered beams
-\override Beam #'grow-direction = #'()
+\override Beam.grow-direction = #'()
 { g32[ a b c] }
 @end lilypond
 
@@ -2646,7 +2656,7 @@ f1 \bar "|"
 f1 \bar "."
 g1 \bar "||"
 a1 \bar ".|"
-b1 \bar ".|."
+b1 \bar ".."
 c1 \bar "|.|"
 d1 \bar "|."
 e1
@@ -2656,31 +2666,43 @@ e1
 together with dotted and dashed bar lines:
 
 @lilypond[quote,relative=1,verbatim]
-f1 \bar ":"
-g1 \bar "dashed"
+f1 \bar ";"
+g1 \bar "!"
 a1
 @end lilypond
 
 @noindent
-and five types of repeat bar line:
+and nine types of repeat bar lines:
 
 @lilypond[quote,relative=1,verbatim]
-f1 \bar "|:"
-g1 \bar ":|:"
+f1 \bar ".|:"
+g1 \bar ":..:"
 a1 \bar ":|.|:"
 b1 \bar ":|.:"
-c1 \bar ":|"
-e1
+c1 \bar ":.|.:"
+d1 \bar "[|:"
+e1 \bar ":|][|:"
+f1 \bar ":|]"
+g1 \bar ":|."
+a1
 @end lilypond
 
 Additionally, a bar line can be printed as a simple tick:
 @lilypond[quote,relative=1,verbatim]
-f1 \bar "'"
+f1 \bar "'" g1
 @end lilypond
 However, as such ticks are typically used in Gregorian chant, it is
 preferable to use @code{\divisioMinima} there instead, described in
 the section @ref{Divisiones} in Gregorian chant.
 
+Lilypond supports kievan notation and provides a special kievan
+bar line:
+@lilypond[quote,relative=1,verbatim]
+f1 \bar "k"
+@end lilypond
+Further details of this notation are explained in
+@ref{Typesetting Kievan square notation}.
+
 @cindex segno
 
 For in-line segno signs, there are three types of bar lines which
@@ -2692,13 +2714,13 @@ c4 c c c
 c4 c c c \break
 \bar "S"
 c4 c c c
-\bar "|S"
+\bar "S-|"
 c4 c c c \break
-\bar "|S"
+\bar "S-|"
 c4 c c c
-\bar "S|"
+\bar "S-S"
 c4 c c c \break
-\bar "S|"
+\bar "S-S"
 c1
 @end lilypond
 
@@ -2710,16 +2732,16 @@ 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
+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.
 
 @lilypond[quote,relative=2,verbatim]
 c4 c c c
-\bar "||:"
+\bar ".|:-||"
 c4 c c c \break
-\bar "||:"
+\bar ".|:-||"
 c4 c c c
 @end lilypond
 
@@ -2728,29 +2750,29 @@ variations:
 
 @lilypond[quote,relative=2,verbatim]
 c4 c c c
-\bar ":|S"
+\bar ":|.S"
 c4 c c c \break
-\bar ":|S"
+\bar ":|.S"
 c4 c c c
-\bar ":|S."
+\bar ":|.S-S"
 c4 c c c \break
-\bar ":|S."
+\bar ":|.S-S"
 c4 c c c
-\bar "S|:"
+\bar "S.|:-S"
 c4 c c c \break
-\bar "S|:"
+\bar "S.|:-S"
 c4 c c c
-\bar ".S|:"
+\bar "S.|:"
 c4 c c c \break
-\bar ".S|:"
+\bar "S.|:"
 c4 c c c
-\bar ":|S|:"
+\bar ":|.S.|:"
 c4 c c c \break
-\bar ":|S|:"
+\bar ":|.S.|:"
 c4 c c c
-\bar ":|S.|:"
+\bar ":|.S.|:-S"
 c4 c c c \break
-\bar ":|S.|:"
+\bar ":|.S.|:-S"
 c1
 @end lilypond
 
@@ -2758,6 +2780,100 @@ Additionally there is an @code{\inStaffSegno} command which
 creates a segno bar, placed in cooperation
 with the @code{\repeat volta} command.
 
+@funindex \defineBarLine
+@funindex defineBarLine
+@cindex bar lines, defining
+@cindex defining bar lines
+
+New bar line types can be defined with @code{\defineBarLine}:
+
+@example
+\defineBarLine @var{bartype} #'(@var{end} @var{begin} @var{span})
+@end example
+
+The @code{\defineBarline} variables can include the
+@q{empty} string @code{""}, which is equivalent to an invisible
+bar line being printed.  Or they can be set to @code{#f} which
+prints no bar line at all.
+
+After the definiton, the new bar line can be used by
+@code{\bar} @var{bartype}.
+
+There are currently ten bar line elements available:
+
+@lilypond[quote,verbatim]
+\defineBarLine ":" #'("" ":" "")
+\defineBarLine "=" #'("=" "" "")
+\defineBarLine "[" #'("" "[" "")
+\defineBarLine "]" #'("]" "" "")
+
+\new Staff {
+  s1 \bar "|"
+  s1 \bar "."
+  s1 \bar "!"
+  s1 \bar ";"
+  s1 \bar ":"
+  s1 \bar "k"
+  s1 \bar "S"
+  s1 \bar "="
+  s1 \bar "["
+  s1 \bar "]"
+  s1 \bar ""
+}
+@end lilypond
+
+The @code{"="} bar line provides the double span bar line, used
+in combination with the segno sign.  Do not use it as a standalone
+double thin bar line; here, @code{\bar} @var{"||"} is
+preferred.
+
+The @code{"-"} sign starts annotations to bar lines which
+are useful to distinguish those with identical appearance
+but different behavior at line breaks and/or different span bars.
+The part following the @code{"-"} sign is not used for building up
+the bar line.
+
+@lilypond[quote,relative=2,verbatim]
+\defineBarLine "||-dashedSpan" #'("||" "" "!!")
+
+\new StaffGroup <<
+  \new Staff {
+    c1 \bar "||"
+    c1 \bar "||-dashedSpan"
+    c1
+  }
+  \new Staff {
+    c1
+    c1
+    c1
+  }
+>>
+@end lilypond
+
+Furthermore, the space character @code{" "} serves as a placeholder
+for defining span bars correctly aligned to the main bar lines:
+
+@lilypond[quote,relative=2,verbatim]
+\defineBarLine ":|.-wrong" #'(":|." "" "|.")
+\defineBarLine ":|.-right" #'(":|." "" " |.")
+
+\new StaffGroup <<
+  \new Staff {
+    c1 \bar ":|.-wrong"
+    c1 \bar ":|.-right"
+    c1
+  }
+  \new Staff {
+    c1
+    c1
+    c1
+  }
+>>
+@end lilypond
+
+If additional elements are needed, LilyPond provides a simple
+way to define them.  For more informations on modifying or adding
+bar lines, see file @file{scm/bar-line.scm}.
 
 In scores with many staves, a @code{\bar} command in one staff is
 automatically applied to all staves.  The resulting bar lines are
@@ -2782,8 +2898,6 @@ connected between different staves of a @code{StaffGroup},
 @cindex default bar lines, changing
 @cindex bar lines, default, changing
 
-@snippets
-
 @funindex whichBar
 @funindex defaultBarType
 @funindex \bar
@@ -2804,6 +2918,9 @@ Notation Reference:
 @ref{Repeats},
 @ref{Grouping staves}.
 
+Installed Files:
+@file{scm/bar-line.scm}.
+
 Snippets:
 @rlsr{Rhythms}.
 
@@ -2852,7 +2969,7 @@ line visible}, @code{beginning of line visible}.  In the following
 example bar numbers are printed at all possible places:
 
 @lilypond[verbatim,quote,relative=1]
-\override Score.BarNumber #'break-visibility = #'#(#t #t #t)
+\override Score.BarNumber.break-visibility = ##(#t #t #t)
 \set Score.currentBarNumber = #11
 % Permit first bar number to be printed
 \bar ""
@@ -2948,18 +3065,18 @@ warning to focus on the source of the timing error.
 
 
 @funindex |
-@funindex pipeSymbol
+@funindex "|"
 
 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}.
+assigning a music expression to @code{"|"}.
 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,verbatim]
-pipeSymbol = \bar "||"
+"|" = \bar "||"
 {
   c'2 c' |
   c'2 c'
@@ -3178,7 +3295,7 @@ up no additional logical time in a measure.
 
 @lilypond[quote,relative=2,verbatim]
 c4 \grace b16 a4(
-\grace { b16[ c16] } a2)
+\grace { b16 c16 } a2)
 @end lilypond
 
 There are three other types of grace notes possible; the
@@ -3193,7 +3310,7 @@ between notes that are slurred themselves, using the
 @lilypond[quote,relative=2,verbatim]
 \acciaccatura d8 c4
 \appoggiatura e8 d4
-\acciaccatura { g16[ f] } e2
+\acciaccatura { g16 f } e2
 \slashedGrace a,8 g4
 \slashedGrace b16 a4(
 \slashedGrace b8 a2)
@@ -3205,8 +3322,8 @@ eighth grace note
 
 @lilypond[quote,relative=2,verbatim]
 <<
-  \new Staff { e2 \grace { c16[ d e f] } e2 }
-  \new Staff { c2 \grace { g8[ b] } c2 }
+  \new Staff { e2 \grace { c16 d e f } e2 }
+  \new Staff { c2 \grace { g8 b } c2 }
 >>
 @end lilypond
 
@@ -3253,7 +3370,7 @@ note after a space lasting 7/8 of the main note.
 \new Voice {
   <<
     { d1^\trill_( }
-    { s2 s4. \grace { c16[ d] } }
+    { s2 s4. \grace { c16 d } }
   >>
   c1)
 }
@@ -3319,6 +3436,7 @@ Snippets:
 Internals Reference:
 @rinternals{GraceMusic},
 @rinternals{Grace_beam_engraver},
+@rinternals{Grace_auto_beam_engraver},
 @rinternals{Grace_engraver},
 @rinternals{Grace_spacing_engraver}.
 
@@ -3341,8 +3459,8 @@ staves without, for example,
 
 @lilypond[quote,relative=2,verbatim]
 <<
-  \new Staff { e4 \bar "|:" \grace c16 d2. }
-  \new Staff { c4 \bar "|:" d2. }
+  \new Staff { e4 \bar ".|:" \grace c16 d2. }
+  \new Staff { c4 \bar ".|:" d2. }
 >>
 @end lilypond
 
@@ -3352,8 +3470,8 @@ durations in the other staves.  For the above example
 
 @lilypond[quote,relative=2,verbatim]
 <<
-  \new Staff { e4 \bar "|:" \grace c16 d2. }
-  \new Staff { c4 \bar "|:" \grace s16 d2. }
+  \new Staff { e4 \bar ".|:" \grace c16 d2. }
+  \new Staff { c4 \bar ".|:" \grace s16 d2. }
 >>
 @end lilypond
 
@@ -3395,19 +3513,19 @@ error will be generated.  Either make the grace notes shorter in
 duration, for example:
 
 @example
-\acciaccatura @{ c'8[ d' e' f' g'] @}
+c'8 \acciaccatura @{ c'8[ d' e' f' g'] @}
 @end example
 
 becomes:
 
 @example
-\acciaccatura @{ c'16[ d' e' f' g'] @}
+c'8 \acciaccatura @{ c'16[ d' e' f' g'] @}
 @end example
 
 Or explicitly change the musical duration:
 
 @example
-\acciaccatura @{ \scaleDurations 1/2 @{ c'8[ d' e' f' g'] @} @}
+c'8 \acciaccatura @{ \scaleDurations 1/2 @{ c'8[ d' e' f' g'] @} @}
 @end example
 
 See @ref{Scaling durations}.
@@ -3517,11 +3635,11 @@ The next bar line then falls at 9/8 rather than 5/4.
 
 @lilypond[quote,verbatim]
 \new Voice \relative c' {
-  \set Timing.measureLength = #(ly:make-moment 5 4)
+  \set Timing.measureLength = #(ly:make-moment 5/4)
   c1 c4 |
   c1 c4 |
   c4 c
-  \set Timing.measurePosition = #(ly:make-moment 5 8)
+  \set Timing.measurePosition = #(ly:make-moment 5/8)
   b4 b b8 |
   c4 c1 |
 }