From 948bd1184bd3f3b44c0e9a5c34a72d99eb371012 Mon Sep 17 00:00:00 2001
From: Graham Percival <graham@percival-music.ca>
Date: Mon, 16 Jun 2008 19:37:55 -0700
Subject: [PATCH] Update from Ralph with changes.

---
 Documentation/user/repeats.itely | 97 +++++++++++++++++++-------------
 1 file changed, 59 insertions(+), 38 deletions(-)

diff --git a/Documentation/user/repeats.itely b/Documentation/user/repeats.itely
index b448e1ddc4..4124ad0f07 100644
--- a/Documentation/user/repeats.itely
+++ b/Documentation/user/repeats.itely
@@ -212,38 +212,38 @@ example, by setting @code{Score.measurePosition} or entering
 
 @funindex repeatCommands
 
-@c FIXME: Markup does not work in the "text" field
-@c And how does one change the font?
-@c On the whole, this section needs better documentation (why the
-@c double parentheses around the volta expressions?)
+In some cases, manual repeat marks can be created by simply
+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.
+Print a @code{|:} bar line:
 
-@item @code{end-repeat}
-Print a @code{:|} bar line.
-
-@item @code{(volta @var{text})}
-Print a volta bracket saying @var{text}.
-
-@item @code{(volta #f)}
-Stop a running volta bracket.
-@end table
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c1
+\set Score.repeatCommands = #'( start-repeat )
+d4 e f g
+c1
+@end lilypond
 
-Printing a @code{|:} bar line:
+In order to print a @code{|:} bar line at the beginning, a skip must
+be used:
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
-c1
+% FIXME: I can't believe this is right.
+s1*1/10
 \set Score.repeatCommands = #'( start-repeat )
+c1*1/10
 d4 e f g
 c1
 @end lilypond
 
-Printing a @code{:|} bar line:
+@item @code{end-repeat}
+Print a @code{:|} bar line:
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 c1
@@ -252,49 +252,70 @@ d4 e f g
 c1
 @end lilypond
 
-Printing a volta bracket saying @var{text}.  The text can be specified
-as a text string or as a markup text, see @ref{Formatting text}.  Do
-not forget to change the font, as the default number font does not
-contain alphabetic characters.
+@item @code{(volta #f)}
+Stop a running volta bracket.
 
+FIXME: example?
+
+@item @code{(volta @var{text})}
+Print a volta bracket saying @var{text}.
+
+FIXME: simple example?
+
+@end table
+
+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.
+
+Manual control of the volte, including a @code{|:} bar line at the
+beginning and explicit volta numbers:
 
 @lilypond[verbatim,quote,relative=2]
-c1
+% FIXME: I can't believe this is right.
+s1*1/10
+\set Score.repeatCommands = #'( start-repeat )
+c1*9/10
 d4 e f g
-\override Staff.VoltaBracket #'font-name = #"sans"
-\set Score.repeatCommands = #'( ( volta "1. Repeat to CHORUS" ) )
+\set Score.repeatCommands = #'( ( volta "1, 2, 5" ) )
 f4 g a b
-\set Score.repeatCommands = #'( ( volta #f ) \text ( volta "2., 3. To VERSE" ) end-repeat )
+\set Score.repeatCommands = #'( ( volta #f ) ( volta "95" ) end-repeat )
 g4 a g a
+\set Score.repeatCommands = #'( ( volta #f ) )
 c1
 @end lilypond
 
-Note: unless explicitly stopped as in the next example, the volta
-bracket will continue indefinitely.
-
-Stopping a running volta bracket:
+Manual control of the volte, including markup text:
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 c1
+\set Score.repeatCommands = #'( start-repeat )
+d1
 d4 e f g
-\set Score.repeatCommands = #'( ( volta #f ) ( volta  "2" ) end-repeat )
+% 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
-f4 e f
 \set Score.repeatCommands = #'( ( volta #f ) )
-d4
 c1
 @end lilypond 
 
-@c FIXME: improve visibility of bar lines link?
-
 @seealso
 
-Notation Reference: @ref{Bar lines}, @ref{Formatting text}.
+Notation Reference:
+@ref{Bar lines},
+@ref{Formatting text}.
 
-Snippets: @rlsr{Repeats}.
+Snippets:
+@rlsr{Repeats}.
 
-Internals Reference: @rinternals{VoltaBracket},
-@rinternals{RepeatedMusic}, @rinternals{VoltaRepeatedMusic}.
+Internals Reference:
+@rinternals{VoltaBracket},
+@rinternals{RepeatedMusic},
+@rinternals{VoltaRepeatedMusic}.
 
 
 @node Written-out repeats
-- 
2.39.5