From: David Kastrup <dak@gnu.org>
Date: Mon, 28 Jan 2013 11:03:26 +0000 (+0100)
Subject: Issue 3147: Make documentation reflect presence of \tuplet
X-Git-Tag: release/2.17.12-1~14
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=5dcfc92089ab4ba59690d59bd6c1dbc2c6520753;p=lilypond.git

Issue 3147: Make documentation reflect presence of \tuplet

This is a followup issue to the changes introduced by issue 3095.
---

diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index 19c93c2a59..d3eb33d83b 100644
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -61,6 +61,19 @@ which scares away people.
 
 @end ignore
 
+@item
+Tuplets are now created with the @code{\tuplet} command, which
+takes a fraction @code{@var{t}/@var{n}} to specify that @var{t}
+notes are played in the time usually allowed for @var{n}. One
+@code{\tuplet} command can create several tuplet groups if their
+duration is typed after the fraction.
+@lilypond[quote,verbatim,relative=2]
+\tuplet 3/2 { c8 d e } \tuplet 3/2 { f e d } c2
+\tuplet 3/2 4 { c8 d e f e d } c2
+@end lilypond
+The @code{\times} command with its inverted fraction order
+@code{@var{n}/@var{t}} is still available.
+
 @item
 Introducing two new markup-commands; @code{\draw-dashed-line} and
 @code{\draw-dotted-line}.
diff --git a/Documentation/contributor/administration.itexi b/Documentation/contributor/administration.itexi
index 6695375807..8be1d903fa 100644
--- a/Documentation/contributor/administration.itexi
+++ b/Documentation/contributor/administration.itexi
@@ -1267,8 +1267,7 @@ convert-ly updates.
 @item
 other than that, everything is on the table.  Is it a problem to
 have the tagline inside \header?  What should the default behavior
-of \include be?  When we abolish \times, do we move to \tuplet 3:2
-or \tuplet 2/3 or what (for typical triplets in 4/4 time)?
+of \include be?
 
 @item
 we need to get standards for command names.  This will help users
diff --git a/Documentation/learning/common-notation.itely b/Documentation/learning/common-notation.itely
index ce77939302..9e392fcd4b 100644
--- a/Documentation/learning/common-notation.itely
+++ b/Documentation/learning/common-notation.itely
@@ -496,16 +496,17 @@ c2 d |
 @cindex tuplets
 @cindex triplets
 
-@funindex \times
-@funindex times
+@funindex \tuplet
+@funindex tuplet
 
 Music Glossary: @rglos{note value}, @rglos{triplet}.
 
-@notation{Tuplets} are made with the @code{\times} keyword.  It
+@notation{Tuplets} are made with the @code{\tuplet} keyword.  It
 takes two arguments: a fraction and a piece of music.  The
-duration of the piece of music is multiplied by the fraction.
-Triplets make notes occupy 2/3 of their notated duration, so a
-@notation{triplet} has 2/3 as its fraction
+fraction is the number of tuplet notes over the number 
+of notes normally filling the same duration.
+For triplets, there are three notes instead of two, so
+@notation{triplets} have 3/2 as their fraction.
 
 @lilypond[verbatim,quote,relative=2]
 \tuplet 3/2 { f8 g a }
diff --git a/Documentation/music-glossary.tely b/Documentation/music-glossary.tely
index 115e75784a..9904deb2c9 100644
--- a/Documentation/music-glossary.tely
+++ b/Documentation/music-glossary.tely
@@ -598,7 +598,7 @@ An accidental alters a note by:
     \context {
       \Score
       \override SpacingSpanner
-        #'base-shortest-duration = #(ly:make-moment 1 32)
+        #'base-shortest-duration = #(ly:make-moment 1/32)
     }
   }
 }
@@ -1782,7 +1782,7 @@ the top line high F:
     \context {
       \Score
       \override SpacingSpanner
-        #'base-shortest-duration = #(ly:make-moment 1 1)
+        #'base-shortest-duration = #(ly:make-moment 1/1)
       \override  NonMusicalPaperColumn
         #'line-break-system-details = #'((alignment-distances . (3 3)))
       \override BarLine #'stencil = ##f
@@ -1843,7 +1843,7 @@ have been selected:
     \context {
       \Score
       \override SpacingSpanner
-        #'base-shortest-duration = #(ly:make-moment 2 1)
+        #'base-shortest-duration = #(ly:make-moment 2/1)
       \override  NonMusicalPaperColumn
         #'line-break-system-details = #'((alignment-distances . (3 3)))
       \override BarLine #'stencil = ##f
@@ -1906,7 +1906,7 @@ shown below, where the notes show an arpeggio on a C major chord.
     \context {
       \Score
       \override SpacingSpanner #'base-shortest-duration =
-        #(ly:make-moment 2 1)
+        #(ly:make-moment 2/1)
       \override  NonMusicalPaperColumn
         #'line-break-system-details = #'((alignment-distances . (3 3)))
       \override BarLine #'stencil = ##f
@@ -3956,7 +3956,7 @@ part in modern choral scores).
 @lilypond[quote,notime]
 \relative c'' {
   \override Staff.Clef #'full-size-change = ##t
-    \set Score.proportionalNotationDuration = #(ly:make-moment 1 8)
+    \set Score.proportionalNotationDuration = #(ly:make-moment 1/8)
     \clef french
     g1
     \clef treble
@@ -5853,17 +5853,17 @@ dotted notes are also frequently used.
 @lilypond[quote,line-width=13.0\cm]
 \relative c'' {
   \time 4/4
-  \times 2/3 {g8_"triplets" g g} g4 g8 g g4 \bar "||"
-  \times 2/5 {g8_"quintuplets" g g g g} g4 g8 g g4 \bar "||"
+  \tuplet 3/2 {g8_"triplets" g g} g4 g8 g g4 \bar "||"
+  \tuplet 5/2 {g8_"quintuplets" g g g g} g4 g8 g g4 \bar "||"
 }
 @end lilypond
 
 @lilypond[quote,line-width=13.0\cm]
 \relative c'' {
   \time 3/4
-  \times 3/2 {g4_"duplets" g} |
+  \tuplet 2/3 {g4_"duplets" g} |
   g4 g g \bar "||"
-  \times 6/4 {g8_"quadruplets" g g g} |
+  \tuplet 4/6 {g8_"quadruplets" g g g} |
   g8 g g g g4 \bar "||"
 }
 @end lilypond
@@ -6014,7 +6014,7 @@ the upper note is played first.
   }
   \relative c'' {
     c2. c32 b c b c b c b | c1
-    c2. b32 c b c \times 4/5 { b c b c b } | c1
+    c2. b32 c b c \tuplet 5/4 { b c b c b } | c1
   }
 >>
 @end lilypond
diff --git a/Documentation/notation/rhythms.itely b/Documentation/notation/rhythms.itely
index 1fcdcc3e1f..cc69b76764 100644
--- a/Documentation/notation/rhythms.itely
+++ b/Documentation/notation/rhythms.itely
@@ -186,28 +186,40 @@ rests from 128th to maxima (8 x whole) may be printed.
 @cindex tuplets
 @cindex triplets
 
-@funindex \times
-@funindex times
+@funindex \tuplet
+@funindex tuplet
 
-Tuplets are made from a music expression by multiplying all the
-durations with a fraction:
+Tuplets are made from a music expression with the @code{\tuplet}
+command, multiplying the speed of the music expression by a
+fraction:
 
 @example
-\times @var{fraction} @{ @var{music} @}
+\tuplet @var{fraction} @{ @var{music} @}
 @end example
 
 @noindent
-The duration of @code{@var{music}} will be multiplied by the
-fraction.  The fraction's denominator will be printed over or
+The fraction's numerator will be printed over or
 under the notes, optionally with a bracket.  The most common
-tuplet is the triplet in which 3 notes have the duration of 2, so
-the notes are 2/3 of their written length.
+tuplets are triplets: 3@tie{}notes sound within the duration
+normally allowed for@tie{}2:
 
 @lilypond[quote,verbatim,relative=2]
 a2 \tuplet 3/2 { b4 b b }
 c4 c \tuplet 3/2 { b4 a g }
 @end lilypond
 
+@cindex tuplet grouping
+@noindent
+When entering long passages of tuplets, having to write a separate
+@code{\tuplet} command for each group is inconvenient.  It is
+possible to specify the duration of one tuplet group directly
+before the music in order to have the tuplets grouped
+automatically:
+
+@lilypond[quote,verbatim,relative=2]
+g2 r8 \tuplet 3/2 8 { cis16 d e e f g g f e }
+@end lilypond
+
 @cindex tuplet bracket placement
 
 @funindex \tupletUp
@@ -296,7 +308,7 @@ Internals Reference:
 @knownissues
 Grace notes may be placed within tuplet brackets, @emph{except}
 when a staff begins with a grace note followed by a tuplet.  In this
-particular case, the grace note must be placed before the @code{\times}
+particular case, the grace note must be placed before the @code{\tuplet}
 command to avoid errors.
 
 @cindex tempo marks within tuplet brackets
@@ -1594,8 +1606,8 @@ Explicitly create a @code{Voice} context when starting a piece with
 @funindex timeSignatureFraction
 @funindex \scaleDurations
 @funindex scaleDurations
-@funindex \times
-@funindex times
+@funindex \tuplet
+@funindex tuplet
 
 Polymetric notation is supported explicitly or by manually modifying the
 visible time signature symbol and/or scaling note durations.
diff --git a/Documentation/notation/simultaneous.itely b/Documentation/notation/simultaneous.itely
index 700a00fc5e..4a02d1faa1 100644
--- a/Documentation/notation/simultaneous.itely
+++ b/Documentation/notation/simultaneous.itely
@@ -1049,7 +1049,7 @@ not designed to work with lyrics; such that when one of the voices is
 explicitly named in order to attach lyrics to it, the partcombiner will
 stop working.
 
-@code{\partcombine...} functions cannot be placed inside a @code{\times}
+@code{\partcombine...} functions cannot be placed inside a @code{\tuplet}
 or @code{\relative} block.
 
 If @code{printPartCombineTexts} is set and the two voices play the same
diff --git a/Documentation/snippets/new/changing-the-tuplet-number.ly b/Documentation/snippets/new/changing-the-tuplet-number.ly
new file mode 100644
index 0000000000..dc147fa13c
--- /dev/null
+++ b/Documentation/snippets/new/changing-the-tuplet-number.ly
@@ -0,0 +1,23 @@
+\version "2.17.11"
+
+\header {
+  lsrtags = "rhythms"
+
+  texidoc = "
+By default, only the numerator of the tuplet number is printed over the
+tuplet bracket. Alternatively, num:den of the tuplet number may
+be printed, or the tuplet number may be suppressed altogether.
+
+"
+  doctitle = "Changing the tuplet number"
+}
+
+
+\relative c'' {
+  \tuplet 3/2 { c8 c c }
+  \tuplet 3/2 { c8 c c }
+  \override TupletNumber.text = #tuplet-number::calc-fraction-text
+  \tuplet 3/2 { c8 c c }
+  \override TupletNumber.stencil = ##f
+  \tuplet 3/2 { c8 c c }
+}
diff --git a/Documentation/snippets/new/entering-several-tuplets-using-only-one--times-command.ly b/Documentation/snippets/new/entering-several-tuplets-using-only-one--times-command.ly
new file mode 100644
index 0000000000..0b6af1b368
--- /dev/null
+++ b/Documentation/snippets/new/entering-several-tuplets-using-only-one--times-command.ly
@@ -0,0 +1,28 @@
+\version "2.17.11"
+
+\header {
+  lsrtags = "rhythms, syntax-and-expressions"
+
+  texidoc = "
+The property @code{tupletSpannerDuration} sets how long each of the
+tuplets contained within the brackets after @code{\\tuplet} should last.
+Many consecutive tuplets can then be placed within a single
+@code{\\tuplet} expression, thus saving typing.
+
+There are several ways to set @code{tupletSpannerDuration}.  The command
+@code{\\tupletSpan} sets it to a given duration, and clears it when
+instead of a duration @code{\\default} is specified.  Another way is
+to use an optional argument with @code{\\tuplet}.
+"
+  doctitle = "Entering several tuplets using only one \\tuplet command"
+}
+
+
+\relative c' {
+  \time 2/4
+  \tupletSpan 4
+  \tuplet 3/2 { c8^"\\tupletSpan 4" c c c c c }
+  \tupletSpan \default
+  \tuplet 3/2 { c8^"\\tupletSpan \\default" c c c c c }
+  \tuplet 3/2 4 { c8^"\\tuplet 3/2 4 {...}" c c c c c }
+}