Re: Doc: mention tuplet-slur in Changes and in NR 1.2.1.2 "Tuplets" (issue 559930043 by address@hidden)

[v . villenave]

Reviewers: lemzwerg,

Message:
On 2020/04/30 19:33:03, lemzwerg wrote:
> LGTM, thanks!

Thanks Werner!  I added your suggestions and pushed it as
https://git.savannah.gnu.org/cgit/lilypond.git/commit/?id=ee56da0f7a68cb6d6c5cd8531a566d81abdc5e59

V.

Description:
Doc: mention tuplet-slur in Changes and in NR 1.2.1.2 "Tuplets"

See issue #5567 for David Nalesnik’s original patch.
Documenting why the bracket-visibility default behavior
isn’t suited to tuplet-slurs allows me to explicitely
point towards the relevant snippet for more clarity,
and to add a couple of additional internal references.

Please review this at https://codereview.appspot.com/559930043/

Affected files (+53, -7 lines):
  M Documentation/changes.tely
  M Documentation/notation/rhythms.itely
  M Documentation/snippets/controlling-tuplet-bracket-visibility.ly


Index: Documentation/changes.tely
diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index 
87e86a372318225913622554ac2efd8e74dc4699..986fda5f0f39dcc12e30579dba02b9aba1d1450a
 100644
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -62,6 +62,20 @@ which scares away people.
 @end ignore
 
 
+@item
+Tuplets can now be printed with slurs instead of brackets:
+@lilypond[quote, verbatim]
+\relative {
+  \tuplet 3/2 4 {
+    \override TupletBracket.tuplet-slur = ##t
+    c'4 e8 d4 f8
+    \override TupletBracket.bracket-visibility = ##t
+    e f g f e d
+  } c1
+}
+@end lilypond
+
+
 @item
 @code{\compressFullBarRests} has been renamed to
 @code{\compressEmptyMeasures}, to avoid
@@ -69,6 +83,7 @@ possible confusion with @code{\compressMMRests}.
 Likewise, @code{\expandFullBarRests} has now become
 @code{\expandEmptyMeasures}.
 
+
 @item
 A gradual change of vowel (or sustained consonant) may
 be indicated by adding a vowel transition between lyric
Index: Documentation/notation/rhythms.itely
diff --git a/Documentation/notation/rhythms.itely 
b/Documentation/notation/rhythms.itely
index 
0b4618e025597402c81b323ad4de379aef6f23a9..3ba86d50febd41830121b8e34c5709e0a7417608
 100644
--- a/Documentation/notation/rhythms.itely
+++ b/Documentation/notation/rhythms.itely
@@ -220,7 +220,7 @@ command, multiplying the speed of the music expression by a 
fraction:
 @noindent
 The fraction's numerator will be printed over or under the notes,
 optionally with a bracket.  The most common tuplets are triplets
-(3@tie{}notes sound within the duration normally allowed for@tie{}2).
+(3@tie{}notes played within the duration normally allowed for@tie{}2).
 
 @lilypond[quote,verbatim]
 \relative {
@@ -268,11 +268,40 @@ Tuplets may be nested:
 }
 @end lilypond
 
+@noindent
 Modifying nested tuplets which begin at the same musical moment must be
-done with @code{\tweak}.
+done with @code{\tweak}; see @ref{The tweak command}.
 
-To modify the duration of notes without printing a tuplet bracket, see
-@ref{Scaling durations}.
+@cindex tuplet slur
+@funindex tuplet-slur
+
+Tuplet brackets may be replaced with slurs, as is preferred in
+many older editions:
+
+@lilypond[quote, verbatim]
+\relative {
+  \tuplet 3/2 4 {
+    \override TupletBracket.tuplet-slur = ##t
+    c'4 e8 d4 f8
+    \override TupletBracket.bracket-visibility = ##t
+    e f g f e d
+  } c1
+}
+@end lilypond
+
+@noindent
+By default, a bracket is only printed if all of the notes it spans
+are not beamed together; in some cases (for example with slurs, as
+in the example above) it may be preferrable to change that behavior,
+through the @code{bracket-visibility} property as detailed in
+one of the following snippets.
+
+@cindex tuplet, visibility
+More generally, either or both the @code{TupletBracket} and
+@code{TupletNumber} objects may be hidden or shown as explained in
+@ref{Visibility of objects}; however, a more flexible way of
+modifying the duration of notes without printing a tuplet
+bracket is also introduced in @ref{Scaling durations}.
 
 @predefined
 @code{\tupletUp},
@@ -328,6 +357,7 @@ Learning Manual:
 
 Notation Reference:
 @ref{Direction and placement},
+@ref{Visibility of objects},
 @ref{Time administration},
 @ref{Scaling durations},
 @ref{The tweak command},
Index: Documentation/snippets/controlling-tuplet-bracket-visibility.ly
diff --git a/Documentation/snippets/controlling-tuplet-bracket-visibility.ly 
b/Documentation/snippets/controlling-tuplet-bracket-visibility.ly
index 
37def3322493465f7c1c66a5b6a88c0fd88d3309..762c40b98ba69284467833ad1c17c923efb895c6
 100644
--- a/Documentation/snippets/controlling-tuplet-bracket-visibility.ly
+++ b/Documentation/snippets/controlling-tuplet-bracket-visibility.ly
@@ -14,8 +14,10 @@ The default behavior of tuplet-bracket visibility is to 
print a bracket
 unless there is a beam of the same length as the tuplet. To control the
 visibility of tuplet brackets, set the property
 @code{'bracket-visibility} to either @code{#t} (always print a
-bracket), @code{#f} (never print a bracket) or @code{#'if-no-beam}
-(only print a bracket if there is no beam).
+bracket), @code{#'if-no-beam} (only print a bracket if there is no beam,
+which is the default behavior), or @code{#f} (never print a bracket).
+The latter is in fact equivalent to omitting the @code{TupletBracket}
+object altogether from the printed output.
 
 "
   doctitle = "Controlling tuplet bracket visibility"
@@ -36,7 +38,6 @@ music = \relative c'' {
     << \music s4^"#t" >>
     \override TupletBracket.bracket-visibility = ##f
     << \music s4^"#f" >>
-    %% v2.18 :
     \omit TupletBracket
     << \music s4^"omit" >>
   }