X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Frepeats.itely;h=3a3fcb44c31c7770d96a5a38a63ace70aa9629f4;hb=77267b700c377fd170abcbf4863728937038eb5e;hp=9e2b53e61db8021610ecbd34622870bee06c9035;hpb=ed748ad93c3b4aebee28dbc078d3f8c388db5cce;p=lilypond.git

diff --git a/Documentation/notation/repeats.itely b/Documentation/notation/repeats.itely
index 9e2b53e61d..3a3fcb44c3 100644
--- a/Documentation/notation/repeats.itely
+++ b/Documentation/notation/repeats.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.12.0"
+@c \version "2.19.21"
 
 @node Repeats
 @section Repeats
@@ -29,7 +29,7 @@ notation for repeats with alternatives.
 
 @item unfold
 The repeated music is fully written out, as many times as
-specified by @var{repeatcount}.  This is useful when
+specified by @code{@var{repeatcount}}.  This is useful when
 entering repetitious music.
 
 @item percent
@@ -52,7 +52,7 @@ This is used to write tremolo beams.
 
 This section discusses how to input long (usually multi-measure)
 repeats.  The repeats can take two forms: repeats enclosed between
-repeat signs; or written out repeats, used to input repetitious music.
+repeat signs; or written-out repeats, used to input repetitious music.
 Repeat signs can also be controlled manually.
 
 @menu
@@ -84,93 +84,261 @@ The syntax for a normal repeat is
 @end example
 
 @noindent
-where @var{musicexpr} is a music expression.  Alternate endings can be
-produced using @code{\alternative}.  In order to delimit the alternate
-endings, the group of alternatives must be enclosed in a set of
-braces.  If there are more repeats than there are alternate endings,
-the earliest repeats are given the first alternative.
+where @code{@var{musicexpr}} is a music expression.
 
-Normal repeats without alternate endings:
+A single repeat without an alternate ending:
 
-@lilypond[verbatim,quote,relative=2]
-\repeat volta 2 { c4 d e f }
-c2 d
-\repeat volta 2 { d4 e f g }
+@lilypond[verbatim,quote]
+\relative {
+  \repeat volta 2 { c''4 d e f }
+  c2 d
+  \repeat volta 2 { d4 e f g }
+}
+@end lilypond
+
+An @q{opening} repeat mark is not, by default, printed in the first full
+measure.  However it is possible to add one by using @code{\bar ".|:"}
+before the first note.
+
+@lilypond[verbatim,fragment,quote]
+\relative {
+  \repeat volta 2 { \bar ".|:" c''4 d e f }
+  c2 d
+  \repeat volta 2 { d4 e f g }
+}
+@end lilypond
+
+Alternative endings can be produced using @code{\alternative}.  Each
+group of alternatives must be themselves, enclosed in a set of braces.
+
+@example
+\repeat volta @var{repeatcount} @var{musicexpr}
+\alternative @{
+  @{ @var{musicexpr} @}
+@}
+@end example
+
+@noindent
+where @code{@var{musicexpr}} is a music expression.
+
+If there are more repeats than there are alternate endings, the earliest
+repeats are given the first alternative.
+
+A single repeat with one alternate ending:
+
+@lilypond[verbatim,quote]
+\relative {
+  \repeat volta 2 { c''4 d e f | }
+  \alternative {
+    { c2 e | }
+    { f2 g | }
+  }
+  c1
+}
+@end lilypond
+
+Multiple repeats with one alternate ending:
+
+@lilypond[verbatim,quote]
+\relative {
+  \repeat volta 4 { c''4 d e f | }
+  \alternative {
+    { c2 e | }
+    { f2 g | }
+  }
+  c1
+}
 @end lilypond
 
-Normal repeats with alternate endings:
+Multiple repeats with more than one alternate ending:
 
-@lilypond[verbatim,quote,relative=2]
-\repeat volta 4 { c4 d e f }
-\alternative {
-  { d2 e }
-  { f2 g }
+@lilypond[verbatim,quote]
+\relative {
+  \repeat volta 3 { c''4 d e f | }
+  \alternative {
+    { c2 e | }
+    { f2 g | }
+    { a2 g | }
+  }
+  c1
 }
-c1
 @end lilypond
 
-@warning{Do not include @code{@bs{}relative} inside a
-@code{@bs{}repeat}.  It will cause unwanted staves to appear.
-See @rprogram{An extra staff appears}.}
+@warning{If there are two or more alternatives, nothing should appear
+between the closing brace of one and the opening brace of the next
+in an @code{@bs{}alternative} block, otherwise you will not get the
+expected number of endings.}
+
+@warning{If you include @code{@bs{}relative} inside a
+@code{@bs{}repeat} without explicitly instantiating the
+@code{Voice} context, extra (unwanted) staves will appear.  See
+@rprogram{An extra staff appears}.}
 
 @cindex repeat with upbeat
 @cindex upbeat in a repeat
-@cindex anacrucis in a repeat
-@cindex repeat with anacrucis
+@cindex anacrusis in a repeat
+@cindex repeat with anacrusis
 @cindex repeat with pickup
 @cindex pickup in a repeat
 @funindex \partial
+@cindex bar checks with repeats
+@cindex repeats with bar checks
+
+If a repeat that has no alternate endings starts in the middle of a
+measure, it will usually end at a corresponding place in the middle of a
+later measure (so that the two ends add up to one complete measure).  In
+this case the repeat signs are not @q{true} bar lines so neither bar
+checks nor @code{\partial} commands should be placed there:
+
+@lilypond[verbatim,quote,relative=1]
+c'4 e g
+\repeat volta 4 {
+  e4 |
+  c2 e |
+  g4 g g
+}
+  g4 |
+  a2 a |
+  g1 |
+@end lilypond
 
-Repeats with upbeats can be entered in two ways:
+If a repeat that has no alternate endings starts with a partial measure,
+then the same principles apply, except that a @code{\partial} command is
+required at the start of the measure:
 
-@lilypond[verbatim,quote,relative=2]
+@lilypond[verbatim,quote,relative=1]
 \partial 4
-e |
-\repeat volta 4 { c2 d | e2 f | }
-\alternative {
-  { g4 g g e }
-  { a4 a a a | b2. }
+\repeat volta 4 {
+  e'4 |
+  c2 e |
+  g4 g g
 }
+  g4 |
+  a2 a |
+  g1 |
 @end lilypond
 
-@noindent
-or
+@cindex repeats, with ties
+@cindex alternative endings, with ties
+@cindex ties, in repeats
+@cindex ties, alternative endings
+@funindex \repeatTie
 
-@lilypond[verbatim,quote,relative=2]
-\partial 4
-\repeat volta 4 { e4 | c2 d | e2 f | }
-\alternative {
-  { \partial 4*3 g4 g g }
-  { a4 a a a | b2. }
+Ties may be added to a second ending:
+
+@lilypond[verbatim,quote]
+\relative {
+  c''1
+  \repeat volta 2 { c4 d e f~ }
+  \alternative {
+    { f2 d }
+    { f2\repeatTie f, }
+  }
 }
 @end lilypond
 
+@funindex \inStaffSegno
+@cindex repeats, with segno
+@cindex segno, with repeats
 
-@cindex repeats with ties
-@cindex alternative endings with ties
-@cindex ties in repeats
-@cindex ties in alternative endings
-@funindex \repeatTie
+The @code{\inStaffSegno} command can be used to generate a composite
+bar line incorporating the segno symbol with the appropriate repeat
+bar line when used with the @code{\repeat volta} command.  The
+correct type of repeat bar line, viz. start repeat, end repeat or
+double repeat, is selected automatically.  Note that the
+corresponding @qq{D.S.} mark must be added manually.
 
-Ties may be added to a second ending:
+Away from a repeat:
 
-@lilypond[verbatim,quote,relative=2]
-c1
-\repeat volta 2 { c4 d e f ~ }
-\alternative {
-  { f2 d }
-  { f2\repeatTie f, }
+@lilypond[verbatim,quote]
+\relative {
+  e'1
+  \inStaffSegno
+  f2 g a b
+  c1_"D.S." \bar "|."
 }
 @end lilypond
 
-@snippets
+At the start of a repeat:
+
+@lilypond[verbatim,quote]
+\relative {
+  e'1
+  \repeat volta 2 {
+    \inStaffSegno  % start repeat
+    f2 g a b
+  }
+  c1_"D.S." \bar "|."
+}
+@end lilypond
+
+At the end of a repeat:
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypond[verbatim,quote]
+\relative {
+  e'1
+  \repeat volta 2 {
+    f2 g a b
+    \inStaffSegno  % end repeat
+  }
+  f2 g a b
+  c1_"D.S." \bar "|."
+}
+@end lilypond
+
+Between two repeats:
+
+@lilypond[verbatim,quote]
+\relative {
+  e'1
+  \repeat volta 2 {
+    f2 g a b
+  }
+  \inStaffSegno  % double repeat
+  \repeat volta 2 {
+    f2 g a b
+  }
+  c1_"D.S." \bar "|."
+}
+@end lilypond
+
+Alternative bar line symbols can be obtained by setting (in the Score
+context) the properties @code{segnoType}, @code{startRepeatSegnoType},
+@code{endRepeatSegnoType} or @code{doubleRepeatSegnoType} to the
+required bar line type.  The alternative bar line types must be
+selected from the pre-defined types or types previously defined
+with the @code{\defineBarLine} command (see @ref{Bar lines}).
+
+@lilypond[verbatim,quote]
+\defineBarLine ":|.S[" #'(":|." "S[" "")
+\defineBarLine "]" #'("]" "" "")
+\relative {
+  e'1
+  \repeat volta 2 {
+    f2 g a b
+    \once \set Score.endRepeatSegnoType = ":|.S["
+    \inStaffSegno
+  }
+  f2 g \bar "]" a b
+  c1_"D.S." \bar "|."
+}
+@end lilypond
+
+@snippets
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {shortening-volta-brackets.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {adding-volta-brackets-to-additional-staves.ly}
 
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{setting-the-double-repeat-default-for-volte.ly}
+
+@cindex repeats, bar numbers letters
+@cindex repeats, alternative bar numbers
+
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{alternative-bar-numbering.ly}
 
 @seealso
 Music Glossary:
@@ -179,7 +347,12 @@ Music Glossary:
 
 Notation Reference:
 @ref{Bar lines},
-@ref{Modifying context plug-ins}.
+@ref{Modifying context plug-ins},
+@ref{Modifying ties and slurs},
+@ref{Time administration}.
+
+Installed Files:
+@file{ly/engraver-init.ly}.
 
 Snippets:
 @rlsr{Repeats}.
@@ -190,9 +363,7 @@ Internals Reference:
 @rinternals{VoltaRepeatedMusic},
 @rinternals{UnfoldedRepeatedMusic}.
 
-
 @knownissues
-
 @cindex repeat, ambiguous
 @cindex nested repeat
 @cindex repeat, nested
@@ -200,8 +371,36 @@ Internals Reference:
 @cindex repeat and measure number
 @cindex timing information and repeats
 @cindex measure number and repeats
-@cindex repeat and slur
-@cindex slur and repeat
+@cindex repeats and slur
+@cindex slur and repeats
+@cindex glissandi and repeats
+@cindex repeats and glissandi
+
+Slurs that span from a @code{\repeat} block into an
+@code{\alternative} block will only work for the first alternative
+ending.  The visual appearance of a continuing slur in other
+alternative blocks may be simulated with @code{\repeatTie} if the
+slur extends into only one note in the alternative block, although
+this method does not work in @code{TabStaff}.  Other methods which
+may be tailored to indicate continuing slurs over several notes in
+alternative blocks, and which also work in @code{TabStaff} contexts,
+are shown in @ref{Modifying ties and slurs}.
+
+Also, slurs cannot wrap around from the end of one
+alternative back to the beginning of the repeat.
+
+Glissandi that span from a @code{\repeat} block into an
+@code{\alternative} block will only work for the first alternative
+ending.  The visual appearance of a continuing glissando in other
+alternative blocks may be indicated by coding a glissando starting
+on a hidden grace note.  For an example, see
+@qq{Extending glissandi across repeats} under Selected Snippets
+in @ref{Glissando}.
+
+If a repeat that begins with an incomplete measure has an
+@code{\alternative} block that contains modifications to the
+@code{measureLength} property, using @code{\unfoldRepeats} will
+result in wrongly-placed bar lines and bar check warnings.
 
 A nested repeat like
 
@@ -217,12 +416,6 @@ is ambiguous, since it is not clear to which @code{\repeat} the
 having the @code{\alternative} belong to the inner @code{\repeat}.
 For clarity, it is advisable to use braces in such situations.
 
-Timing information is not remembered at the start of an alternative,
-so after a repeat timing information must be reset by hand; for
-example, by setting @code{Score.measurePosition} or entering
-@code{\partial}.  Similarly, slurs are also not repeated.
-
-
 
 @node Manual repeat marks
 @unnumberedsubsubsec Manual repeat marks
@@ -242,7 +435,7 @@ example, by setting @code{Score.measurePosition} or entering
 
 @warning{These methods are only used for displaying unusual repeat
 constructs, and may produce unexpected behavior.  In most cases,
-repeats should be created using the standard @code{\\repeat} command
+repeats should be created using the standard @code{@bs{}repeat} command
 or by printing the relevant bar lines.  For more information, see
 @ref{Bar lines}.}
 
@@ -251,52 +444,60 @@ layout of repeats.  Its value is a Scheme list of repeat commands.
 
 @table @code
 @item start-repeat
-Print a @code{|:} bar line.
+Print a @code{.|:} bar line.
 
-@lilypond[verbatim,quote,relative=2]
-c1
-\set Score.repeatCommands = #'(start-repeat)
-d4 e f g
-c1
+@lilypond[verbatim,quote]
+\relative {
+  c''1
+  \set Score.repeatCommands = #'(start-repeat)
+  d4 e f g
+  c1
+}
 @end lilypond
 
 As per standard engraving practice, repeat signs are not printed
 at the beginning of a piece.
 
 @item end-repeat
-Print a @code{:|} bar line:
+Print a @code{:|.} bar line:
 
-@lilypond[verbatim,quote,relative=2]
-c1
-d4 e f g
-\set Score.repeatCommands = #'(end-repeat)
-c1
+@lilypond[verbatim,quote]
+\relative {
+  c''1
+  d4 e f g
+  \set Score.repeatCommands = #'(end-repeat)
+  c1
+}
 @end lilypond
 
-@item (volta @var{number}) ... (volta #f)
+@item (volta @var{number}) @dots{} (volta #f)
 Create a new volta with the specified number.  The volta bracket must
 be explicitly terminated, or it will not be printed.
 
-@lilypond[verbatim,quote,relative=2]
-f4 g a b
-\set Score.repeatCommands = #'((volta "2"))
-g4 a g a
-\set Score.repeatCommands = #'((volta #f))
-c1
+@lilypond[verbatim,quote]
+\relative {
+  f''4 g a b
+  \set Score.repeatCommands = #'((volta "2"))
+  g4 a g a
+  \set Score.repeatCommands = #'((volta #f))
+  c1
+}
 @end lilypond
 
 @end table
 
 Multiple repeat commands may occur at the same point:
 
-@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
-\set Score.repeatCommands = #'((volta #f))
+@lilypond[verbatim,quote]
+\relative {
+  f''4 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
+  \set Score.repeatCommands = #'((volta #f))
+}
 @end lilypond
 
 @cindex volta bracket with text
@@ -309,9 +510,10 @@ then include 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)
+\relative {
+  c''1
+  \set Score.repeatCommands =
+    #(list(list 'volta voltaAdLib) 'start-repeat)
   c4 b d e
   \set Score.repeatCommands = #'((volta #f) (volta "4.") end-repeat)
   f1
@@ -319,13 +521,6 @@ voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
 }
 @end lilypond
 
-
-@snippets
-
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
-{printing-a-repeat-sign-at-the-beginning-of-a-piece.ly}
-
-
 @seealso
 Notation Reference:
 @ref{Bar lines},
@@ -344,49 +539,120 @@ Internals Reference:
 @unnumberedsubsubsec Written-out repeats
 
 @cindex written-out repeats
-@cindex repetitious music
 @cindex repeats, written-out
-@cindex repeat, unfold
-@cindex unfold music
+@cindex repeats, unfold
+@cindex repeats, alternative
 @cindex unfold repeat
-@cindex unfold repeat with alternate endings
-@cindex unfold music with alternate endings
-@cindex alternate ending in written-out repeats
+@cindex unfold repeat, alternate endings
+@cindex alternate repeats
+@cindex alternate endings, repeats
 @funindex unfold
 
-By using the @code{unfold} command, repeats can be used to simplify
-the writing out of repetitious music.  The syntax is
+By using the @code{unfold} command, repeats can be used to simplify the
+writing out of repetitious music.  The syntax is
 
 @example
 \repeat unfold @var{repeatcount} @var{musicexpr}
 @end example
 
 @noindent
-where @var{musicexpr} is a music expression and @var{repeatcount} is
-the number of times @var{musicexpr} is repeated.
+where @code{@var{musicexpr}} is a music expression and
+@code{@var{repeatcount}} is the number of times
+@code{@var{musicexpr}} is repeated.
+
+@lilypond[verbatim,quote]
+\relative {
+  \repeat unfold 2 { c''4 d e f }
+  c1
+}
+@end lilypond
+
+In some cases, especially in a @code{\relative} context, the
+@code{\repeat unfold} function is not the same as writing out the
+music expression multiple times. E.g,
+
+@example
+\repeat unfold 2 @{ a'4 b c @}
+@end example
+
+is not equivalent to
+
+@example
+a'4 b c | a'4 b c
+@end example
+
+Unfold repeats can be made with alternate endings.
 
-@lilypond[verbatim,quote,relative=2]
-c1
-\repeat unfold 2 { c4 d e f }
-c1
+@lilypond[verbatim,quote]
+\relative {
+  \repeat unfold 2 { c''4 d e f }
+  \alternative {
+    { c2 g' }
+    { c,2 b }
+  }
+  c1
+}
 @end lilypond
 
-Unfold repeats can be made with alternate endings.  If there are
-more repeats than there are alternate endings, the first
-alternative ending is applied to the earliest endings.
+If there are more repeats than there are alternate endings, the first
+alternative is applied multiple times until the remaining alternatives
+make up the total number of repeats.
 
-@lilypond[verbatim,quote,relative=2]
-c1
-\repeat unfold 2 { g4 f e d }
+@lilypond[verbatim,quote]
+\relative {
+  \repeat unfold 4 { c''4 d e f }
   \alternative {
-    { cis2 g' }
-    { cis,2 b }
+    { c2 g' }
+    { c,2 b }
+    { e2 d }
+   }
+  c1
+}
+@end lilypond
+
+If there are more alternate endings than repeats then only the first
+alternatives are applied.  The remaining alternatives will be ignored
+and not printed.
+
+@lilypond[verbatim,quote]
+\relative {
+  \repeat unfold 2 { c''4 d e f }
+  \alternative {
+    { c2 g' }
+    { c,2 b }
+    { e2 d }
   }
-c1
+  c1
+}
 @end lilypond
 
+It is also possible to nest multiple @code{unfold} functions (with or
+without alternate endings).
+
+@lilypond[verbatim,quote]
+\relative {
+  \repeat unfold 2 {
+    \repeat unfold 2 { c''4 d e f }
+    \alternative {
+      { c2 g' }
+      { c,2 b }
+    }
+  }
+  c1
+}
+@end lilypond
+
+Chord constructs can be repeated by the chord repetition symbol
+@code{q}.  See @ref{Chord repetition}.
+
+@warning{If you include @code{@bs{}relative} inside a @code{@bs{}repeat}
+without explicitly instantiating the @code{Voice} context, extra
+(unwanted) staves will appear.  See @rprogram{An extra staff appears}.}
 
 @seealso
+Notation Reference:
+@ref{Chord repetition}.
+
 Snippets:
 @rlsr{Repeats}.
 
@@ -399,8 +665,8 @@ Internals Reference:
 @subsection Short repeats
 
 This section discusses how to input short repeats.  Short repeats can
-take two basic forms: repeats of a single note to two measures,
-represented by slashes or percent signs; and tremolos.
+take two forms: slashes or percent signs to represent repeats of a
+single note, a single measure or two measures, and tremolos otherwise.
 
 @menu
 * Percent repeats::
@@ -418,36 +684,69 @@ represented by slashes or percent signs; and tremolos.
 @funindex \repeat percent
 @funindex percent
 
-Repeated short patterns of notes are supported.  The music is printed
-once, and the pattern is replaced with a special sign.  Patterns that
-are shorter than one measure are replaced by slashes, and patterns of
-one or two measures are replaced by percent-like signs.  The syntax is
+Repeated short patterns are printed once, and the repeated pattern
+is replaced with a special sign.
+
+The syntax is
 
 @example
-@code{\repeat percent @var{number} @var{musicexpr}}
+\repeat percent @var{number} @var{musicexpr}
 @end example
 
 @noindent
-where @var{musicexpr} is a music expression.
+where @code{@var{musicexpr}} is a music expression.
+
+Patterns that are shorter than one measure are replaced by slashes.
 
-@lilypond[verbatim,quote,relative=2]
-\repeat percent 4 { c4 }
-\repeat percent 2 { b4 a g f }
-\repeat percent 2 { c2 es | f4 fis g c | }
+@lilypond[verbatim,quote]
+\relative c'' {
+  \repeat percent 4 { c128 d e f }
+  \repeat percent 4 { c64 d e f }
+  \repeat percent 5 { c32 d e f }
+  \repeat percent 4 { c16 d e f }
+  \repeat percent 4 { c8 d }
+  \repeat percent 4 { c4 }
+  \repeat percent 2 { c2 }
+}
+@end lilypond
+
+Patterns of one or two measures are replaced by percent-like symbols.
+
+@lilypond[verbatim,quote]
+\relative c'' {
+  \repeat percent 2 { c4 d e f }
+  \repeat percent 2 { c2 d }
+  \repeat percent 2 { c1 }
+}
+@end lilypond
+
+@lilypond[verbatim,quote]
+\relative {
+  \repeat percent 3 { c''4 d e f | c2 g' }
+}
+@end lilypond
+
+Patterns that are shorter than one measure but contain mixed durations
+use a double-percent symbol.
+
+@lilypond[verbatim,quote]
+\relative {
+  \repeat percent 4 { c''8. <d f>16 }
+  \repeat percent 2 { \tuplet 3/2 { r8 c d } e4 }
+}
 @end lilypond
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {percent-repeat-counter.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {percent-repeat-count-visibility.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {isolated-percent-repeats.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{percent repeat},
@@ -458,23 +757,37 @@ Snippets:
 
 Internals Reference:
 @rinternals{RepeatSlash},
+@rinternals{RepeatSlashEvent},
+@rinternals{DoubleRepeatSlash},
 @rinternals{PercentRepeat},
+@rinternals{PercentRepeatCounter},
+@rinternals{PercentRepeatedMusic},
+@rinternals{Percent_repeat_engraver},
+@rinternals{DoublePercentEvent},
 @rinternals{DoublePercentRepeat},
 @rinternals{DoublePercentRepeatCounter},
-@rinternals{PercentRepeatCounter},
-@rinternals{PercentRepeatedMusic}.
-
+@rinternals{Double_percent_repeat_engraver},
+@rinternals{Slash_repeat_engraver}.
 
 @knownissues
+Percent repeats will not contain anything else apart from the percent
+sign itself; in particular, timing changes will not be repeated.
 
-Only three kinds of percent repeats are supported: a single slash
-representing a single beat (regardless of the duration of the repeated
-notes); a single slash with dots representing one full measure; and
-two slashes with dots crossing a bar line representing two full
-measures.  Neither multiple slashes representing single beat repeats
-consisting of sixteenth or shorter notes, nor two slashes with dots
-representing single beat repeats consisting of notes of varying
-durations, are supported.
+@lilypond[quote,verbatim,relative=2]
+\repeat percent 3 { \time 5/4 c2. 2 \time 4/4 2 2 }
+@end lilypond
+
+@noindent
+Any meter changes or @code{\partial} commands need to occur in parallel
+passages @emph{outside} of any percent repeat, e.g in a separate
+timing track.
+
+@lilypond[quote,verbatim,relative=2]
+<<
+  \repeat percent 3 { c2. 2 2 2 }
+  \repeat unfold 3 { \time 5/4 s4*5 \time 4/4 s1 }
+>>
+@end lilypond
 
 
 @node Tremolo repeats
@@ -487,7 +800,7 @@ durations, are supported.
 @funindex tremolo
 
 Tremolos can take two forms: alternation between two chords or two
-notes, and rapid repetition of a single note or chord. Tremolos
+notes, and rapid repetition of a single note or chord.  Tremolos
 consisting of an alternation are indicated by adding beams between the
 notes or chords being alternated, while tremolos consisting of the
 rapid repetition of a single note are indicated by adding beams or
@@ -496,10 +809,12 @@ slashes to a single note.
 To place tremolo marks between notes, use @code{\repeat} with
 tremolo style:
 
-@lilypond[quote,verbatim,relative=2]
-\repeat tremolo 8 { c16 d }
-\repeat tremolo 6 { c16 d }
-\repeat tremolo 2 { c16 d }
+@lilypond[quote,verbatim]
+\relative c'' {
+  \repeat tremolo 8 { c16 d }
+  \repeat tremolo 6 { c16 d }
+  \repeat tremolo 2 { c16 d }
+}
 @end lilypond
 
 The @code{\repeat tremolo} syntax expects exactly two notes within
@@ -522,35 +837,29 @@ the note should not be surrounded by braces:
 @end lilypond
 
 @cindex tremolo marks
-@funindex tremoloFlags
 @funindex :
 
-The same output can be obtained by adding
-@q{@code{:}[@var{number}]} after the note.  The number indicates
-the duration of the subdivision, and it must be at least 8.  A
-@var{number} value of 8 gives one line across the note stem.  If
-the length is omitted, the last value (stored in
-@code{tremoloFlags}) is used:
+The same output can be obtained by adding @code{:@var{N}} after
+the note, where @code{@var{N}} indicates the duration of the
+subdivision (it must be at least 8).  If @code{@var{N}} is 8, one
+beam is added to the note's stem.  If @code{@var{N}} is omitted,
+the last value is used:
 
-@lilypond[quote,verbatim,relative=2]
-c2:8 c:32
-c: c:
+@lilypond[quote,verbatim]
+\relative {
+  c''2:8 c:32
+  c: c:
+}
 @end lilypond
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {cross-staff-tremolos.ly}
 
-
 @seealso
 Snippets:
 @rlsr{Repeats}.
 
 @cindex tremolo, cross-staff
 @cindex cross-staff tremolo
-
-@knownissues
-
-Cross-staff tremolos do not work well.
-