Small update from Ralph, big changes by Graham.

diff --git a/Documentation/user/repeats.itely b/Documentation/user/repeats.itely
index 53814ba104de471894fc40e3935ee7e5dd004c0a..250bd3792e1e86742e79b9fef233b26feea7a49a 100644 (file)
--- a/Documentation/user/repeats.itely
+++ b/Documentation/user/repeats.itely
@@ -150,10 +150,10 @@ c1
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {shortening-volta-brackets.ly}
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {adding-volta-brackets-to-additional-staves.ly}
 
 
@@ -214,16 +214,17 @@ example, by setting @code{Score.measurePosition} or entering
 
 @funindex repeatCommands
 
-In some cases, manual repeat marks can be created by simply
-printing the relevant bar lines.  For more information, see
-@ref{Bar lines}.
+@warning{These methods are only used for displaying unusual repeat
+constructs.  In most cases, repeats should be created using the
+standard @code{\\repeat} command or by printing the relevant bar
+lines.  For more information, see @ref{Bar lines}.}
 
 The property @code{repeatCommands} can be used to control the
 layout of repeats.  Its value is a Scheme list of repeat commands.
 
-@table @asis
-@item @code{start-repeat}
-Print a @code{|:} bar line:
+@table @code
+@item start-repeat
+Print a @code{|:} bar line.
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 c1
@@ -232,31 +233,10 @@ d4 e f g
 c1
 @end lilypond
 
-In order to print a @code{|:} bar line at the beginning of a piece,
-the @code{BreakAlignment} property must be overridden:
-
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
-\once \override Score.BreakAlignment #'break-align-orders =
-#(make-vector 3 '(
-instrument-name
-left-edge
-ambitus
-span-bar
-breathing-sign
-clef
-key-signature
-time-signature
-staff-bar
-custos
-span-bar
-))
-\bar "|:"
-c1
-d1
-d4 e f g
-@end lilypond
+As per standard engraving practice, repeat signs are not printed
+at the beginning of a piece.
 
-@item @code{end-repeat}
+@item end-repeat
 Print a @code{:|} bar line:
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
@@ -266,34 +246,63 @@ d4 e f g
 c1
 @end lilypond
 
-@item @code{(volta #f)}
-Stop a running volta bracket.
+@item (volta @var{number})
+Create a new volta with the specified number:
 
-@c FIXME: example?
-@c TODO: Modify and insert <Test volta.ly>.
+@lilypond[verbatim,quote,relative=2]
+f4 g a b
+\set Score.repeatCommands = #'( ( volta "2" ) )
+g4 a g a
+c1
+@end lilypond
 
-@item @code{(volta @var{number})}
-Change the volta number.
+@item (volta #f)
+Stops a running volta bracket:
 
-FIXME: simple example?
-@c Test volta text.ly works
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c1
+\set Score.repeatCommands = #'( ( volta "2" ) )
+f4 g a b
+\set Score.repeatCommands = #'( ( volta #f ) )
+a4 g f e
+c1
+@end lilypond
 
-@c @lilypond[verbatim,quote,relative=2]
+@end table
 
-@c @end lilypond
+Multiple repeat commands may occur at the same point:
 
-@end table
+@lilypond[verbatim,quote,relative=2]
+f4 g a b
+\set Score.repeatCommands = #'( ( volta "2, 5" ) end-repeat )
+g4 a g a
+c1
+\set Score.repeatCommands = #'( ( volta #f ) ( volta "95" ) end-repeat )
+b1
+@end lilypond
+
+Text can be included with the volta bracket.  The text can be a
+number or numbers or markup text, see @ref{Formatting text}.  The
+simplest way to use markup text is to define the markup first,
+then include the the markup in a Scheme list.
+
+@lilypond[verbatim,quote]
+voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
+\relative c'' {
+  c1
+  \set Score.repeatCommands = #(list (list 'volta voltaAdLib) 'start-repeat)
+  c4 b d e
+  \set Score.repeatCommands = #'((volta #f) (volta "4.") end-repeat)
+  f1
+  \set Score.repeatCommands = #'((volta #f))
+}
+@end lilypond
 
-@c FIXME: Should this be a ``selected snippet''?
-@c TODO: the example will be fixed.
 
-By using Scheme, @var{text} can be included with the volta
-bracket.  The text can be a number or numbers or markup text, see
-@ref{Formatting text}.  The simplest way to use markup text is to
-define the markup first, then include the the markup in a Scheme
-list. When manually creating a volta bracket, the bracket must be
-explicitly terminated or an error will be generated.
+@snippets
 
+@c FIXME: send these to Neil or Valentin to be added as snippets,
+@c delete them.
 Manual control of the volte, including a @code{|:} bar line at the
 beginning and explicit volta numbers:
 
@@ -314,21 +323,30 @@ g4 a g a
 c1
 @end lilypond
 
-Manual control of the volte, including markup text:
+In order to print a @code{|:} bar line at the beginning of a piece,
+the @code{BreakAlignment} property must be overridden:
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+\once \override Score.BreakAlignment #'break-align-orders =
+#(make-vector 3 '(
+instrument-name
+left-edge
+ambitus
+span-bar
+breathing-sign
+clef
+key-signature
+time-signature
+staff-bar
+custos
+span-bar
+))
+\bar "|:"
 c1
-\set Score.repeatCommands = #'( start-repeat )
 d1
 d4 e f g
-% FIXME: broken
-%\set Score.repeatCommands = #(list (list 'volta voltaChorus ) )
-f4 g a b
-\set Score.repeatCommands = #'( ( volta #f ) ( volta "4" ) end-repeat )
-g4 a g a
-\set Score.repeatCommands = #'( ( volta #f ) )
-c1
-@end lilypond 
+@end lilypond
+
 
 @seealso