Re: DOC: NR Dynamics context and postfix dynamics (issue3743045)

[k-ohara5a5a]

Reviewers: carl.d.sorensen_gmail.com, Trevor Daniels, Graham Percival,

Message:
> The snippets in input/regression/ are *not* part of the documentation

Now I see. I updated the file in /snippets/new so it uses the predefined
\cresc (just like updated the reg-test does).

I have this and the tweaks noted below ready for a revised patch to
either upload, or just email to a doc editor if other reviewers say the
rest looks good.



http://codereview.appspot.com/3743045/diff/1/Documentation/notation/expressive.itely
File Documentation/notation/expressive.itely (right):

http://codereview.appspot.com/3743045/diff/1/Documentation/notation/expressive.itely#newcode366
Documentation/notation/expressive.itely:366: Textual crescendo marks
begin with @code{\cresc}
On 2010/12/22 04:31:23, Carl wrote:
> We can even get shorter and simpler here,
I resist, here, because I would need the text to know what to look for
in the code.  Plus, the new \cresc is a big deal, as it fills a
long-felt need.

http://codereview.appspot.com/3743045/diff/1/Documentation/notation/expressive.itely#newcode392
Documentation/notation/expressive.itely:392: Textual marks can also be
produced by @code{\<} and @code{\>}:
On 2010/12/22 04:31:23, Carl wrote:
> "Textual markings for dynamic changes can also replace hairpins,
although
> this usage is deprecated:"
Yes, 'replace' is the right verb.
I do not know that \dimTextDim is deprecated, though -- mightily
inconvenient, yes, but consistent with other syntax and not in the way
of any future plans, so far as I have heard.

Description:
DOC: NR Dynamics context and postfix dynamics

Add description of the new Dynamics context,
and of the new postfix \cresc, etc.

No rearranging or streamlining in this patch.
I can submit a follow-on patch for that later, if there is desire.

You might see a redundant redefinition of \cresc, ect, in first
Snippet for Sec. 1.8.1 "Writing Text Spanners".  The source snippet,
however, was updated several months ago.  Its current version in
input\regression\dynamics-text-spanner-postfix.ly
will be great for sec.1.8.1, and unless told otherwise I will
assume the new version will appear after it gets texidoc translation,
and not worry.

Please review this at http://codereview.appspot.com/3743045/

Affected files:
  M Documentation/notation/expressive.itely
  M Documentation/notation/keyboards.itely
  M Documentation/notation/text.itely


Index: Documentation/notation/expressive.itely
diff --git a/Documentation/notation/expressive.itely  
b/Documentation/notation/expressive.itely
index  
f2fee1c5de8ffee95ee838aaa25932784c948691..6612b4c559978e0a6dd5b563d3062743590cd341  
100644
--- a/Documentation/notation/expressive.itely
+++ b/Documentation/notation/expressive.itely
@@ -357,6 +357,24 @@ c2 b4 a
 g1\espressivo
 @end lilypond

address@hidden \cresc
address@hidden cresc
address@hidden \decresc
address@hidden decresc
address@hidden \dim
address@hidden dim
+Textual crescendo marks begin with @code{\cresc}
+and continue, with dashed extender lines as required,
+until the next dynamic mark,
+or @code{\!} or its synonym @code{\endcresc}.
+Text decrescendos begin with @code{\decresc} or @code{\dim}.
+
address@hidden,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\! |
address@hidden lilypond

 @funindex \crescTextCresc
 @funindex crescTextCresc
@@ -371,24 +389,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},
address@hidden, @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
address@hidden and @code{\dimHairpin} commands will revert
-to hairpins again:
-
+Textual marks can also be produced by @code{\<} and @code{\>}:
 @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 +423,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.
+
address@hidden,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 |
+  }
+>>
address@hidden lilypond

 @predefined
 @code{\dynamicUp},
@@ -470,7 +506,8 @@ Snippets:
 Internals Reference:
 @rinternals{DynamicText},
 @rinternals{Hairpin},
address@hidden
address@hidden,
address@hidden


 @node New dynamic marks
Index: Documentation/notation/keyboards.itely
diff --git a/Documentation/notation/keyboards.itely  
b/Documentation/notation/keyboards.itely
index  
7735ef89e8a5dac8380b5ede198c779ac935604f..ef986c828059f2486107fe891b3ffcf91849d6a5  
100644
--- 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
address@hidden keyboard music, centering dynamics
address@hidden dynamics, centered in keyboard music
address@hidden piano music, centering dynamics
address@hidden 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}.

address@hidden Dynamics may be placed in a @code{Dynamics} context,
+see @ref{Dynamics}, between the two @code{Staff} contexts
+to align the dynamic marks on a horizontal line
+centered between the staves.
+
 @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}.

-
address@hidden
-
address@hidden keyboard music, centering dynamics
address@hidden dynamics, centered in keyboard music
address@hidden piano music, centering dynamics
address@hidden centered dynamics in piano music
address@hidden staff-padding
-
-Dynamics are not automatically centered, but workarounds do exist.  One
-option is the @q{piano centered dynamics} template under
address@hidden templates}; another option is to increase the
address@hidden 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:
Index: Documentation/notation/text.itely
diff --git a/Documentation/notation/text.itely  
b/Documentation/notation/text.itely
index  
f7aa545f0fd0eb91ca303bb42a42465774d62c54..d9f82d886fbd9f8a8f8ec7f17e8ed311387d350a  
100644
--- 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
address@hidden
-

 @funindex \textSpannerUp
 @funindex textSpannerUp
@@ -206,8 +203,7 @@ Snippets:
 @rlsr{Expressive marks}.

 Internals Reference:
address@hidden,
address@hidden
address@hidden


 @node Text marks