Doc: update dynamics documentation

diff --git a/Documentation/notation/expressive.itely b/Documentation/notation/expressive.itely
index f2fee1c5de8ffee95ee838aaa25932784c948691..295cf49ad0c48ff2a0c645a5b4a95e0dc97df968 100644 (file)
--- a/Documentation/notation/expressive.itely
+++ b/Documentation/notation/expressive.itely
@@ -357,6 +357,22 @@ c2 b4 a
 g1\espressivo
 @end lilypond
 
+@funindex \cresc
+@funindex cresc
+@funindex \decresc
+@funindex decresc
+@funindex \dim
+@funindex dim
+Textual crescendo marks begin with @code{\cresc}.
+Textual decrescendos begin with @code{\decresc} or @code{\dim}.
+Extender lines are engraved as required.
+
+@lilypond[verbatim,quote,relative=2]
+g8\cresc a b c b c d e\mf |
+f8\decresc e d c e\> d c b |
+a1\dim ~ |
+a2. r4\! |
+@end lilypond
 
 @funindex \crescTextCresc
 @funindex crescTextCresc
@@ -371,24 +387,19 @@ g1\espressivo
 @funindex \dimHairpin
 @funindex dimHairpin
 
-Crescendos and decrescendos can be engraved as textual markings
-instead of hairpins.  Dashed lines are printed to indicate their
-extent.  The built-in commands @code{\crescTextCresc},
-@code{\dimTextDecresc}, @code{\dimTextDecr}, and @code{\dimTextDim}
-will tell LilyPond to use such textual marks instead of hairpins
-for all subsequent @code{\<} and @code{\>} commands.  The corresponding
-@code{\crescHairpin} and @code{\dimHairpin} commands will revert
-to hairpins again:
-
+Textual marks for dynamic changes can also replace hairpins:
 @lilypond[verbatim,quote,relative=2]
 \crescTextCresc
-c2\< d | e f\!
+c4\< d e f\! |
 \dimTextDecresc
-e2\> d | c b\!
+g4\> e d c\! |
+\dimTextDecr
+e4\> d c b\! |
+\dimTextDim
+d4\> c b a\! |
 \crescHairpin
-c2\< d | e f\!
 \dimHairpin
-e2\> d\!
+c4\< d\! e\> d\! |
 @end lilypond
 
 
@@ -410,6 +421,29 @@ Vertical positioning of dynamics is handled by
 @funindex \dynamicNeutral
 @funindex dynamicNeutral
 
+A @code{Dynamics} context is available to engrave dynamics on
+their own horizontal line.  Use spacer rests to indicate timing.
+(Notes in a @code{Dynamics} context will also take up
+musical time, but will not be engraved.)
+The @code{Dynamics} context can usefully contain some other
+items such as text scripts, text spanners, and piano pedal marks.
+
+@lilypond[verbatim,quote]
+<<
+  \new Staff \relative c' {
+    c2 d4 e |
+    c4 e e,2 |
+    g'4 a g a |
+    c1 |
+  }
+  \new Dynamics {
+    s1\< |
+    s1\f |
+    s2\dim s2-"rit." |
+    s1\p |
+  }
+>>
+@end lilypond
 
 @predefined
 @code{\dynamicUp},
@@ -470,7 +504,8 @@ Snippets:
 Internals Reference:
 @rinternals{DynamicText},
 @rinternals{Hairpin},
-@rinternals{DynamicLineSpanner}.
+@rinternals{DynamicLineSpanner},
+@rinternals{Dynamics}.
 
 
 @node New dynamic marks

diff --git a/Documentation/notation/keyboards.itely b/Documentation/notation/keyboards.itely
index 7735ef89e8a5dac8380b5ede198c779ac935604f..c93abe76b0b7a2141b2478537090f4d31ae03d00 100644 (file)
--- a/Documentation/notation/keyboards.itely
+++ b/Documentation/notation/keyboards.itely
@@ -51,6 +51,10 @@ keyboard instruments.
 @cindex staves, keyed instruments
 @cindex keyboard instrument staves
 @cindex keyed instrument staves
+@cindex keyboard music, centering dynamics
+@cindex dynamics, centered in keyboard music
+@cindex piano music, centering dynamics
+@cindex centered dynamics in piano music
 
 @funindex PianoStaff
 
@@ -76,6 +80,11 @@ number of voices may change regularly; this is described in
 @item Keyboard music can be written in parallel, as described in
 @ref{Writing music in parallel}.
 
+@item Dynamics may be placed in a @code{Dynamics} context,
+between the two @code{Staff} contexts
+to align the dynamic marks on a horizontal line
+centered between the staves; see @ref{Dynamics}.
+
 @item Fingerings are indicated with @ref{Fingering instructions}.
 
 @item Organ pedal indications are inserted as articulations, see
@@ -128,21 +137,6 @@ Internals Reference:
 Snippets:
 @rlsr{Keyboards}.
 
-
-@knownissues
-
-@cindex keyboard music, centering dynamics
-@cindex dynamics, centered in keyboard music
-@cindex piano music, centering dynamics
-@cindex centered dynamics in piano music
-@funindex staff-padding
-
-Dynamics are not automatically centered, but workarounds do exist.  One
-option is the @q{piano centered dynamics} template under
-@rlearning{Piano templates}; another option is to increase the
-@code{staff-padding} of dynamics as discussed in @rlearning{Moving
-objects}.
-
 @node Changing staff manually
 @unnumberedsubsubsec Changing staff manually
 
@@ -514,6 +508,8 @@ The placement of the pedal commands matches the physical movement of the
 sustain pedal during piano performance.  Pedalling to the final bar line
 is indicated by omitting the final pedal off command.
 
+Pedal indications may be placed in a @code{Dynamics} context,
+which aligns them on a horizontal line.
 
 @seealso
 Notation Reference:

diff --git a/Documentation/notation/text.itely b/Documentation/notation/text.itely
index f7aa545f0fd0eb91ca303bb42a42465774d62c54..d9f82d886fbd9f8a8f8ec7f17e8ed311387d350a 100644 (file)
--- a/Documentation/notation/text.itely
+++ b/Documentation/notation/text.itely
@@ -167,9 +167,6 @@ e,\stopTextSpan
 
 The line style, as well as the text string, can be defined as an
 object property.  This syntax is described in @ref{Line styles}.
-Text spanners are part of the @code{Dynamics} context; see
-@rinternals{Dynamics}.
-
 
 @funindex \textSpannerUp
 @funindex textSpannerUp
@@ -206,8 +203,7 @@ Snippets:
 @rlsr{Expressive marks}.
 
 Internals Reference:
-@rinternals{TextSpanner},
-@rinternals{Dynamics}.
+@rinternals{TextSpanner}.
 
 
 @node Text marks

diff --git a/Documentation/snippets/new/dynamics-text-spanner-postfix.ly b/Documentation/snippets/new/dynamics-text-spanner-postfix.ly
index 81d33a7e1342666ac1cdbadf161b4ed74ebc8c20..fff0e7170a6738a17525653ab05e20b170422e2b 100644 (file)
--- a/Documentation/snippets/new/dynamics-text-spanner-postfix.ly
+++ b/Documentation/snippets/new/dynamics-text-spanner-postfix.ly
@@ -2,11 +2,9 @@
 
 \header {
   lsrtags = "expressive-marks, tweaks-and-overrides"
-  texidoc = "The \cresc, \dim and \decresc spanners can now be redefined as
-postfix operators and produce one text spanner.  Defining custom spanners is
-also easy.  Hairpin and text crescendi can be easily mixed. \< and \> produce
-hairpins by default, \cresc etc. produce text spanners by default.
-"
+  texidoc = "Custom text spanners can be defined and used with hairpin
+  and text crescendos.  @code{\<} and @code{\>} produce hairpins by
+  default, @code{\cresc} etc. produce text spanners by default."
   doctitle = "Dynamics text spanner postfix"
 }
 
@@ -16,22 +14,6 @@ crpoco =
              'span-direction START
              'span-type 'text
              'span-text "cresc. poco a poco")
-% Redefine the existing \cresc, \dim and \decresc commands to use postfix syntax
-cresc =
-#(make-music 'CrescendoEvent
-             'span-direction START
-             'span-type 'text
-             'span-text "cresc.")
-dim =
-#(make-music 'DecrescendoEvent
-             'span-direction START
-             'span-type 'text
-             'span-text "dim.")
-decresc =
-#(make-music 'DecrescendoEvent
-             'span-direction START
-             'span-type 'text
-             'span-text "decresc.")
 
 \relative c' {
   c4\cresc d4 e4 f4 |