[doc] Handle leading dash in @code.

[lilypond.git] / Documentation / notation / rhythms.itely

diff --git a/Documentation/notation/rhythms.itely b/Documentation/notation/rhythms.itely
index f0d518d99d1720d3de4b9ef9c82c12e95aaadae8..625d7db4a8abdcbfb1d775236516469c24e35085 100644 (file)
--- a/Documentation/notation/rhythms.itely
+++ b/Documentation/notation/rhythms.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     Guide, node Updating translation committishes..
 @end ignore
 

-@c \version "2.13.44"
+@c \version "2.14.0"

 
 @node Rhythms
 @section Rhythms
 
 @node Rhythms
 @section Rhythms


@@ -142,6 +142,9 @@ the staff; see @ref{Direction and placement}.
 
 @snippets
 
 
 @snippets
 

+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{alternative-breve-note.ly}
+

 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {changing-the-number-of-augmentation-dots-per-note.ly}
 
 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {changing-the-number-of-augmentation-dots-per-note.ly}
 


@@ -1374,7 +1377,7 @@ For example, @code{\partial 8*3} becomes:
 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:
 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 @code{-4}, meaning
+i.e., @code{\partial 4} is internally translated to @w{@code{-4}}, meaning

 @qq{there is a quarter note left in the measure.}
 
 @seealso
 @qq{there is a quarter note left in the measure.}
 
 @seealso


@@ -1439,10 +1442,10 @@ c4 c d8[ d d] f4 g4.
 d4 e d c
 @end lilypond
 
 d4 e d c
 @end lilypond
 

-@cindex beaming in cadenzas
-@cindex beaming in unmetered music
-@cindex cadenza, beaming in
-@cindex unmetered music, beaming in
+@cindex beams, in cadenzas
+@cindex beams, in unmetered music
+@cindex cadenza, with beams
+@cindex unmetered music, with beams

 
 Automatic beaming is disabled by @code{\cadenzaOn} and enabled
 by @code{\cadenzaOff}.  Therefore, all beaming in cadenzas
 
 Automatic beaming is disabled by @code{\cadenzaOn} and enabled
 by @code{\cadenzaOff}.  Therefore, all beaming in cadenzas


@@ -1553,8 +1556,8 @@ signature; see @ref{Time signature}.  The scaling is done with
 @code{\times}, but does not create a tuplet bracket; see
 @ref{Scaling durations}.
 
 @code{\times}, but does not create a tuplet bracket; see
 @ref{Scaling durations}.
 

-@cindex beaming in polymetric music
-@cindex beaming in polymetric meter
+@cindex beams, with polymetric meters
+@cindex polymetric meters, with beams

 
 In this example, music with the time signatures of 3/4, 9/8, and
 10/8 are used in parallel.  In the second staff, shown durations
 
 In this example, music with the time signatures of 3/4, 9/8, and
 10/8 are used in parallel.  In the second staff, shown durations


@@ -1574,7 +1577,7 @@ duration scaling affects the autobeaming rules.
     \time 3/4
     \set Staff.timeSignatureFraction = #'(9 . 8)
     \scaleDurations #'(2 . 3)
     \time 3/4
     \set Staff.timeSignatureFraction = #'(9 . 8)
     \scaleDurations #'(2 . 3)

-    \repeat unfold 6 { c8[ c c] }
+      \repeat unfold 6 { c8[ c c] }

   }
   \new Staff {
     \time 3/4
   }
   \new Staff {
     \time 3/4


@@ -1672,28 +1675,35 @@ time signatures.
 
 @cindex notes, splitting
 @cindex splitting notes
 
 @cindex notes, splitting
 @cindex splitting notes

+@cindex rests, splitting
+@cindex splitting rests

 
 @funindex Note_heads_engraver
 @funindex Completion_heads_engraver
 
 @funindex Note_heads_engraver
 @funindex Completion_heads_engraver

+@funindex Completion_rest_engraver

 
 

-Long notes which overrun bar lines can be converted automatically
-to tied notes.  This is done by replacing the
-@code{Note_heads_engraver} with the
-@code{Completion_heads_engraver}.  In the following
-example, notes crossing the bar lines are split and tied.
+Long notes which overrun bar lines can be converted automatically to
+tied notes.  This is done by replacing the @code{Note_heads_engraver}
+with the @code{Completion_heads_engraver}.  Similarly, long rests which
+overrun bar lines are split automatically by replacing the
+@code{Rest_engraver} with the @code{Completion_rest_engraver}.  In the
+following example, notes and rests crossing the bar lines are split,
+notes are also tied.

 
 @lilypond[quote,verbatim,relative=1]
 \new Voice \with {
   \remove "Note_heads_engraver"
   \consists "Completion_heads_engraver"
 
 @lilypond[quote,verbatim,relative=1]
 \new Voice \with {
   \remove "Note_heads_engraver"
   \consists "Completion_heads_engraver"

+  \remove "Rest_engraver"
+  \consists "Completion_rest_engraver"

 }
 
 }
 

-{ c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 }
+{ c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 r1*2 }

 @end lilypond
 
 @end lilypond
 

-This engraver splits all running notes at the bar line, and
-inserts ties.  One of its uses is to debug complex scores: if the
-measures are not entirely filled, then the ties show exactly how
+These engravers split all running notes and rests at the bar line, and
+inserts ties for notes.  One of its uses is to debug complex scores: if
+the measures are not entirely filled, then the ties show exactly how

 much each measure is off.
 
 
 much each measure is off.
 
 


@@ -1711,6 +1721,8 @@ Snippets:
 Internals Reference:
 @rinternals{Note_heads_engraver},
 @rinternals{Completion_heads_engraver},
 Internals Reference:
 @rinternals{Note_heads_engraver},
 @rinternals{Completion_heads_engraver},

+@rinternals{Rest_engraver},
+@rinternals{Completion_rest_engraver},

 @rinternals{Forbid_line_break_engraver}.
 
 
 @rinternals{Forbid_line_break_engraver}.
 
 


@@ -1826,8 +1838,7 @@ By default, beams are inserted automatically:
 
 @cindex beams, manual
 @cindex manual beams
 
 @cindex beams, manual
 @cindex manual beams

-@cindex beams, setting rules for
-@cindex beams, custom rules for
+@cindex beams, customizing rules

 
 @funindex \autoBeamOn
 @funindex autoBeamOn
 
 @funindex \autoBeamOn
 @funindex autoBeamOn


@@ -1854,8 +1865,8 @@ c4 c8 c8. c16 c8.
 c16 c8
 @end lilypond
 
 c16 c8
 @end lilypond
 

-@cindex melismata, beams
-@cindex beams and melismata
+@cindex melismata, with beams
+@cindex beams, with melismata

 
 @warning{If beams are used to indicate melismata in songs, then
 automatic beaming should be switched off with @code{\autoBeamOff}
 
 @warning{If beams are used to indicate melismata in songs, then
 automatic beaming should be switched off with @code{\autoBeamOff}


@@ -1867,35 +1878,30 @@ produce unintended results.  See the snippet below for more information.}
 Beaming patterns that differ from the automatic defaults can be
 created; see @ref{Setting automatic beam behavior}.
 
 Beaming patterns that differ from the automatic defaults can be
 created; see @ref{Setting automatic beam behavior}.
 

-

 @predefined
 @code{\autoBeamOff},
 @code{\autoBeamOn}.
 @endpredefined
 
 @predefined
 @code{\autoBeamOff},
 @code{\autoBeamOn}.
 @endpredefined
 

-
-@snippets
-
-
-@cindex line breaks and beams
-@cindex beams and line breaks
-
+@cindex beams, line breaks
+@cindex line breaks, beams
+@cindex beams, with knee gap
+@cindex knee gap, with beams

 @funindex breakable
 
 @funindex breakable
 

+@snippets

 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {beams-across-line-breaks.ly}
 
 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {changing-beam-knee-gap.ly}
 
 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {beams-across-line-breaks.ly}
 
 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {changing-beam-knee-gap.ly}
 

-@cindex \partcombine and \autoBeamOff
-@cindex \autoBeamOff and \partcombine
-
+@cindex beams, \partcombine with \autoBeamOff
+@cindex voices, \partcombine with \autoBeamOff

 
 @lilypondfile [verbatim, lilyquote, ragged-right, texidoc, doctitle]
 {partcombine-and-autobeamoff.ly}
 
 
 @lilypondfile [verbatim, lilyquote, ragged-right, texidoc, doctitle]
 {partcombine-and-autobeamoff.ly}
 

-

 @seealso
 Notation Reference:
 @ref{Manual beams},
 @seealso
 Notation Reference:
 @ref{Manual beams},


@@ -1916,21 +1922,11 @@ Internals Reference:
 @rinternals{beam-interface},
 @rinternals{unbreakable-spanner-interface}.
 
 @rinternals{beam-interface},
 @rinternals{unbreakable-spanner-interface}.
 

-
-@knownissues
-
-Beams can collide with note heads and accidentals in other voices.
-
-

 @node Setting automatic beam behavior
 @unnumberedsubsubsec Setting automatic beam behavior
 
 @node Setting automatic beam behavior
 @unnumberedsubsubsec Setting automatic beam behavior
 

-
-@cindex automatic beams, tuning
-@cindex tuning automatic beaming
-@cindex automatic beam generation
-@cindex autobeam
-@cindex lyrics and beaming
+@cindex beams, with lyrics
+@cindex lyrics, with beams

 
 @funindex autoBeaming
 @funindex baseMoment
 
 @funindex autoBeaming
 @funindex baseMoment


@@ -2085,12 +2081,12 @@ context to the default behavior.
 \repeat unfold 6 { a8 }
 @end lilypond
 
 \repeat unfold 6 { a8 }
 @end lilypond
 

-These default automatic beaming settings for a time signature
+The default automatic beaming settings for a time signature

 are determined in @file{scm/time-signature-settings.scm}.
 are determined in @file{scm/time-signature-settings.scm}.

-The automatic beaming settings for a time signature can be changed
-as described in @ref{Time signature}.
+Changing the default automatic beaming settings
+for a time signature is described in @ref{Time signature}.

 
 

-Most automatic beaming settings for a time signature contain an
+Many automatic beaming settings for a time signature contain an

 entry for @code{beamExceptions}.  For example, 4/4 time tries to
 beam the measure in two if there are only eighth notes.  The
 @code{beamExceptions} rule can override the @code{beatStructure} setting
 entry for @code{beamExceptions}.  For example, 4/4 time tries to
 beam the measure in two if there are only eighth notes.  The
 @code{beamExceptions} rule can override the @code{beatStructure} setting


@@ -2151,10 +2147,10 @@ end beams at the end of beats.
 
 @end itemize
 
 
 @end itemize
 

-In the rules above, the beam-type is the duration of the
+In the rules above, the @emph{beam-type} is the duration of the

 shortest note in the beamed group.
 
 shortest note in the beamed group.
 

-For reference, the default beaming rules are found in
+The default beaming rules can be found in

 @file{scm/time-signature-settings.scm}.
 
 @snippets
 @file{scm/time-signature-settings.scm}.
 
 @snippets


@@ -2172,8 +2168,8 @@ For reference, the default beaming rules are found in
 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {conducting-signs,-measure-grouping-signs.ly}
 
 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {conducting-signs,-measure-grouping-signs.ly}
 

-@cindex beam, last in score
-@cindex beam, last in polyphonic voice
+@cindex beam, endings in a score
+@cindex beam, endings with multiple voices

 
 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {beam-endings-in-score-context.ly}
 
 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {beam-endings-in-score-context.ly}


@@ -2202,6 +2198,51 @@ automatic beam is still accepting notes, it is not typeset.
 The workaround for these problems is to manually beam the last
 beam in the voice or score.
 
 The workaround for these problems is to manually beam the last
 beam in the voice or score.
 

+By default, the @code{Timing} translator is aliased to the
+@code{Score} context.  This means that setting the time signature
+in one staff will affect the beaming of the other staves as well.
+Thus, a time signature setting in a later staff will reset custom
+beaming that was set in an earlier staff.
+One way to avoid this problem is to set the time signature
+in only one staff.
+
+@lilypond[quote,verbatim,relative=2]
+<<
+  \new Staff {
+    \time 3/4
+    \set Timing.baseMoment = #(ly:make-moment 1 8)
+    \set Timing.beatStructure = #'(1 5)
+    \repeat unfold 6 { a8 }
+  }
+  \new Staff {
+    \repeat unfold 6 { a8 }
+  }
+>>
+@end lilypond
+
+The default beam settings for the time signature can also be changed, so
+that the desired beaming will always be used.  Changes in automatic
+beaming settings for a time signature are described in
+@ref{Time signature}.
+
+@lilypond[quote,verbatim,relative=2]
+<<
+  \new Staff {
+    \overrideTimeSignatureSettings
+      #'(3 . 4)         % timeSignatureFraction
+      #'(1 . 8)         % baseMomentFraction
+      #'(1 5)           % beatStructure
+      #'()             % beamExceptions
+    \time 3/4
+    \repeat unfold 6 { a8 }
+  }
+  \new Staff {
+    \time 3/4
+    \repeat unfold 6 { a8 }
+  }
+>>
+@end lilypond
+

 @node Manual beams
 @unnumberedsubsubsec Manual beams
 
 @node Manual beams
 @unnumberedsubsubsec Manual beams
 


@@ -3166,9 +3207,61 @@ durations in the other staves.  For the above example
 >>
 @end lilypond
 
 >>
 @end lilypond
 

-Grace sections should only be used within sequential music
-expressions.  Nesting or juxtaposing grace sections is not
-supported, and might produce crashes or other errors.
+The use of grace notes within voice contexts confuses the way the voice
+is typeset. This can be overcome by inserting a rest or note between the
+voice command and the grace note.
+
+@lilypond[quote,verbatim]
+accMusic = {
+  \acciaccatura { f8 } e8 r8 \acciaccatura { f8 } e8 r4
+}
+
+\new Staff {
+  <<
+    \new Voice {
+      \relative c'' {
+        r8 r8 \voiceOne \accMusic \oneVoice r8 |
+        r8 \voiceOne r8 \accMusic \oneVoice r8 |
+      }
+    }
+    \new Voice {
+      \relative c' {
+        s8 s8 \voiceTwo \accMusic \oneVoice s8 |
+        s8 \voiceTwo r8 \accMusic \oneVoice s8 |
+      }
+    }
+  >>
+}
+@end lilypond
+
+Grace sections should only be used within sequential music expressions.
+Nesting or juxtaposing grace sections is not supported, and might
+produce crashes or other errors.
+
+Each grace note in MIDI output has a length of 1/4 of its actual
+duration.  If the combined length of the grace notes is greater than the
+length of the preceding note a @qq{@code{Going back in MIDI time}}
+error will be generated.  Either make the grace notes shorter in
+duration, for example:
+
+@example
+\acciaccatura @{ c'8[ d' e' f' g'] @}
+@end example
+
+becomes:
+
+@example
+\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'] @} @}
+@end example
+
+See @ref{Scaling durations}.
+

 
 @node Aligning to cadenzas
 @unnumberedsubsubsec Aligning to cadenzas
 
 @node Aligning to cadenzas
 @unnumberedsubsubsec Aligning to cadenzas