GDP: NR 3.1 and 3.2.1 first pass

[lilypond.git] / Documentation / user / repeats.itely

diff --git a/Documentation/user/repeats.itely b/Documentation/user/repeats.itely
index fa53086ce0078005f8268c0b6b2c01d7f54bbfc3..f862ec53097afb3e27dc7404945afb6ee6e3476b 100644 (file)
--- a/Documentation/user/repeats.itely
+++ b/Documentation/user/repeats.itely
@@ -23,7 +23,7 @@ exist for repetitions. LilyPond supports the following kinds of repeats:
 The repeated music is not written out but enclosed between repeat bar
 lines.  If the repeat is at the beginning of a piece, a repeat bar
 line is only printed at the end. Alternative endings (volte) are
 The repeated music is not written out but enclosed between repeat bar
 lines.  If the repeat is at the beginning of a piece, a repeat bar
 line is only printed at the end. Alternative endings (volte) are

-printed, left to right with brackets.  This is the standard notation
+printed left to right with brackets.  This is the standard notation

 for repeats with alternatives.
 
 @item unfold
 for repeats with alternatives.
 
 @item unfold


@@ -32,56 +32,32 @@ specified by @var{repeatcount}.  This is useful when
 entering repetitious music. 
 
 @item percent
 entering repetitious music. 
 
 @item percent

-These are beat or measure repeats.  They look like percent signs.
-Percent repeats must be declared within a @code{Voice} context.
+These are beat or measure repeats.  They look like single slashes or
+percent signs.

 
 @item tremolo
 This is used to write tremolo beams.
 
 @end table
 
 
 @item tremolo
 This is used to write tremolo beams.
 
 @end table
 

-@ignore
-LilyPond has one syntactic construct for specifying different
-types of repeats.  The syntax is
-
-@example
-\repeat @var{variant} @var{repeatcount} @var{musicexpr}
-@end example
-
-where @var{musicexpr} is a music expression.
-
-
-Alternative endings are entered with 
-@funindex \alternative
-@example
-\alternative @{
-  @var{alternative1}
-  @var{alternative2}
-  @var{alternative3}
-  @dots{}
-@}
-@end example
-
-@noindent
-after a @code{\repeat volta} or @code{unfold} block, where each
-@var{alternative} is a music expression.  If you give fewer
-alternatives than @var{repeatcount}, the first alternative is assumed
-to be played more than once.
-@end ignore
-

 
 @menu
 
 @menu

-* Writing long repeats::        
+* Long repeats::                

 * Short repeats::               
 @end menu
 
 * Short repeats::               
 @end menu
 

-@node Writing long repeats
-@subsection Writing long repeats
+@node Long repeats
+@subsection Long repeats
+
+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 can also be controlled manually.

 
 @menu
 * Normal repeats::              
 * Manual repeat marks::         
 
 @menu
 * Normal repeats::              
 * Manual repeat marks::         

-* Written-out repeats::         
+* Written-out repeats::  

 @end menu
 
 @cindex volta
 @end menu
 
 @cindex volta


@@ -123,7 +99,7 @@ c1
 @end lilypond
 
 
 @end lilypond
 
 

-Repeats with upbeats:
+Repeats with upbeats can be entered in two ways:

 
 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
 \new Staff {
 
 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
 \new Staff {


@@ -167,10 +143,10 @@ c1
 
 @snippets
 
 
 @snippets
 

-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]

 {shortening-volta-brackets.ly}
 
 {shortening-volta-brackets.ly}
 

-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]

 {adding-volta-brackets-to-additional-staves.ly}
 
 
 {adding-volta-brackets-to-additional-staves.ly}
 
 


@@ -193,11 +169,11 @@ Music Glossary: @rglos{repeat}, @rglos{volta}.
 
 Notation Reference: @ref{Bar lines}, @ref{Modifying context plug-ins}.
 
 
 Notation Reference: @ref{Bar lines}, @ref{Modifying context plug-ins}.
 

-Snippets: @lsrdir{Repeats,Repeats}.
+Snippets: @rlsr{Repeats}.

 
 

-Internals Reference: @internalsref{VoltaBracket},
-@internalsref{RepeatedMusic}, @internalsref{VoltaRepeatedMusic},
-@internalsref{UnfoldedRepeatedMusic}.
+Internals Reference: @rinternals{VoltaBracket},
+@rinternals{RepeatedMusic}, @rinternals{VoltaRepeatedMusic},
+@rinternals{UnfoldedRepeatedMusic}.

 
 @knownissues
 
 
 @knownissues
 


@@ -220,7 +196,7 @@ 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
 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 or ties are also not repeated.
+@code{\partial}.  Similarly, slurs are also not repeated.

 
 
 
 
 
 


@@ -246,9 +222,9 @@ Print a @code{:|} bar line.
 
 @item @code{(volta @var{text})}
 Print a volta bracket saying @var{text}.  The text can be specified as
 
 @item @code{(volta @var{text})}
 Print 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
+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
 forget to change the font, as the default number font does not contain

-alphabetic characters.
+alphabetic characters;

 
 
 @item @code{(volta #f)}
 
 
 @item @code{(volta #f)}


@@ -269,10 +245,10 @@ d4 e
 
 Notation Reference: @ref{Bar lines}, @ref{Formatting text}.
 
 
 Notation Reference: @ref{Bar lines}, @ref{Formatting text}.
 

-Snippets: @lsrdir{Repeats,Repeats}.
+Snippets: @rlsr{Repeats}.

 
 

-Internals Reference: @internalsref{VoltaBracket},
-@internalsref{RepeatedMusic}, @internalsref{VoltaRepeatedMusic}.
+Internals Reference: @rinternals{VoltaBracket},
+@rinternals{RepeatedMusic}, @rinternals{VoltaRepeatedMusic}.

 
 
 @node Written-out repeats
 
 
 @node Written-out repeats


@@ -290,9 +266,8 @@ the writing out of repetitious music.  The syntax is
 @end example
 
 where @var{musicexpr} is a music expression.  Unfold repeats can be
 @end example
 
 where @var{musicexpr} is a music expression.  Unfold repeats can be

-made with or without alternate endings.
-
-Unfold repeats without alternate endings:
+made with or without alternate endings.  Unfold repeats without
+alternate endings:

 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 c1
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 c1


@@ -314,14 +289,18 @@ c1
 
 @seealso
 
 
 @seealso
 

-Snippets: @lsrdir{Repeats,Repeats}.
+Snippets: @rlsr{Repeats}.

 
 

-Internals Reference: @internalsref{RepeatedMusic},
-@internalsref{UnfoldedRepeatedMusic}.
+Internals Reference: @rinternals{RepeatedMusic},
+@rinternals{UnfoldedRepeatedMusic}.

 
 @node Short repeats
 @subsection Short repeats
 
 
 @node Short repeats
 @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.
+

 @menu
 * Percent repeats::             
 * Tremolo repeats::             
 @menu
 * Percent repeats::             
 * Tremolo repeats::             


@@ -333,12 +312,10 @@ Internals Reference: @internalsref{RepeatedMusic},
 @cindex percent repeats
 @cindex measure repeats
 
 @cindex percent repeats
 @cindex measure repeats
 

-Repeated short patterns of notes are also supported.  The music is
-printed once, and the pattern is replaced with a special sign.
-Patterns of one and two measures are replaced by percent-like signs,
-patterns that are shorter than one measure are replaced by slashes.
-Percent repeats must be declared within a @code{Voice} context.  The
-syntax is
+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

 
 @example
 @code{\repeat percent @var{number} @var{musicexpr}}
 
 @example
 @code{\repeat percent @var{number} @var{musicexpr}}


@@ -347,18 +324,18 @@ syntax is
 where @var{musicexpr} is a music expression. 
 
 @lilypond[quote,verbatim,ragged-right]
 where @var{musicexpr} is a music expression. 
 
 @lilypond[quote,verbatim,ragged-right]

-\new Voice \relative c' {
+\relative c' {

   \repeat percent 4 { c4 }
   \repeat percent 4 { c4 }

-  \repeat percent 2 { b4 a g f }
+  \repeat percent 2 { b'4 a g f }

   \repeat percent 2 { c2 es | f4 fis g c | }
 }
 @end lilypond
 
   \repeat percent 2 { c2 es | f4 fis g c | }
 }
 @end lilypond
 

-Measure repeats of more than two measures get a counter if you
-switch on the @code{countPercentRepeats} property:
+Measure repeats of more than two repeats get a counter if you switch
+on the @code{countPercentRepeats} property:

 
 @lilypond[relative=2,fragment,quote,verbatim,ragged-right]
 
 @lilypond[relative=2,fragment,quote,verbatim,ragged-right]

-\new Voice {
+\relative c' {

   \set countPercentRepeats = ##t
   \repeat percent 4 { c1 }
 }
   \set countPercentRepeats = ##t
   \repeat percent 4 { c1 }
 }


@@ -375,26 +352,46 @@ R1
 @end lilypond
 
 
 @end lilypond
 
 

+@knownissues
+
+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.
+
+

 @seealso
 
 @seealso
 

-Snippets: @lsrdir{Repeats,Repeats}.
+Music Glossary: @rglos{percent repeat}, @rglos{simile}.

 
 

-Internals Reference: @internalsref{RepeatSlash},
-@internalsref{PercentRepeat}, @internalsref{DoublePercentRepeat},
-@internalsref{DoublePercentRepeatCounter},
-@internalsref{PercentRepeatCounter},
-@internalsref{PercentRepeatedMusic}.
+Snippets: @rlsr{Repeats}.
+
+Internals Reference: @rinternals{RepeatSlash},
+@rinternals{PercentRepeat}, @rinternals{DoublePercentRepeat},
+@rinternals{DoublePercentRepeatCounter},
+@rinternals{PercentRepeatCounter}, @rinternals{PercentRepeatedMusic}.

 
 @node Tremolo repeats
 @subsubsection Tremolo repeats
 
 
 @node Tremolo repeats
 @subsubsection Tremolo repeats
 

+Tremolos can take two forms: alternation between two chords or two
+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 slashes to a single note.
+

 @cindex tremolo beams
 
 To place tremolo marks between notes, use @code{\repeat} with
 tremolo style:
 
 @lilypond[quote,verbatim,ragged-right]
 @cindex tremolo beams
 
 To place tremolo marks between notes, use @code{\repeat} with
 tremolo style:
 
 @lilypond[quote,verbatim,ragged-right]

-\new Voice \relative c' {
+\relative c' {

   \repeat tremolo 8 { c16 d }
   \repeat tremolo 4 { c16 d }
   \repeat tremolo 2 { c16 d }
   \repeat tremolo 8 { c16 d }
   \repeat tremolo 4 { c16 d }
   \repeat tremolo 2 { c16 d }


@@ -444,17 +441,4 @@ into the MIDI output.
 
 @seealso
 
 
 @seealso
 

-Music Glossary: @rglos{tremolo}.
-
-Notation Reference: @ref{Tremolo repeats}.
-
-Internals Reference: @internalsref{Beam}, @internalsref{StemTremolo}.
-
-Snippets: @lsrdir{Repeats,Repeats}.
-
-
-
-
-
-
-
+@c Notation Reference: @re