DOC: NR Dynamics context and postfix dynamics

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.

[Carl, 2010-12-22 04:31:22]

This looks even better to me.  Thanks!

I have a few comments below.

I'm delighted to have you manage the review and updates for this patch.

When it's time to apply the patch, if you'll create a patch using
git-format-patch, and email it to somebody to push (maybe Trevor Daniels, or
me), then we'll  be able to commit it with you as the author.

The snippets in input/regression/ are *not* part of the documentation; they're
just regression tests.  If a snippet is to become part of the documentation, and
is not included inline in the file, then you'll want to have a snippet intended
for documentation use in Documentation/snippets/new.

Thanks,
Carl

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

http://codereview.appspot.com/3743045/diff/1/Documentation/notation/expressiv...
Documentation/notation/expressive.itely:366: Textual crescendo marks begin with
@code{\cresc}
We can even get shorter and simpler here, by saying

"Textual dynamic changes with extender lines can be created using postfix
functions:"

The example shows everything we need to know; we don't need to explain the code
in the text.

http://codereview.appspot.com/3743045/diff/1/Documentation/notation/expressiv...
Documentation/notation/expressive.itely:392: Textual marks can also be produced
by @code{\<} and @code{\>}:
Maybe this should say something like

"Textual markings for dynamic changes can also replace hairpins, although
this usage is deprecated:"

The key issue here is that we're using \*Text* to replace a standard hairpin.

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

http://codereview.appspot.com/3743045/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:84: see @ref{Dynamics}, between the two
@code{Staff} contexts
References should be at the end of sentences where possible.

[Keith, 2010-12-22 21:43:37]

> 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/expressiv...
File Documentation/notation/expressive.itely (right):

http://codereview.appspot.com/3743045/diff/1/Documentation/notation/expressiv...
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/expressiv...
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.

[Carl, 2010-12-22 21:50:27]

On 2010/12/22 21:43:37, Keith wrote:
> > 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).

Perfect!

> 
> 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.

Generally, we just upload a new patch set to the issue, and get a new round of
reviews.


Thanks,

Carl

[Carl, 2010-12-22 22:14:55]

Your thoughts generally look good to me, but I'll need to see a patch before I
can approve.

Thanks,

Carl

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

http://codereview.appspot.com/3743045/diff/1/Documentation/notation/expressiv...
Documentation/notation/expressive.itely:366: Textual crescendo marks begin with
@code{\cresc}
On 2010/12/22 21:43:38, Keith wrote:
> 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.

The text doesn't add anything, if the example is the right example.  Here's my
thought process when I look at the music, then up to the code:

"Let's see, I have a crescendo starting at g and going to e, which has a mf.

Let me look at the code.  Ahh. g has \cresc after it, so \cresc must start a
text crescendo.  And the explicit dynamic must end a text crescendo.

And then  I have a text decrescendo going from f to e, where a hairpin starts. 
Ahh, that makes sense in the code.

And then I have a \dim that goes from a, through the tie, ending before the
rest.  \! must end the text dimuendo."

If the example is too complicated to understand easily, then instead of trying
to explain the example, split it up into multiple examples, each of which only
shows one thing.

Just as a picture is worth a thousand words, a good LilyPond example is worth
multiple paragraphs of text in the NR.

http://codereview.appspot.com/3743045/diff/1/Documentation/notation/expressiv...
Documentation/notation/expressive.itely:392: Textual marks can also be produced
by @code{\<} and @code{\>}:
On 2010/12/22 21:43:38, Keith wrote:
> On 2010/12/22 04:31:23, Carl wrote:
> > "Textual markings for dynamic changes can also replace hairpins, although
> > this usage is deprecated:"

Maybe I have understood incorrectly, but it seems to me that we want to move to
strictly postfix dynamic indications, whether text or hairpin.

The thread below indicates that we want to move that direction for 3.0.  We
might as well get it out in the open right now, IMO.

http://thread.gmane.org/gmane.comp.gnu.lilypond.devel/20614

But I won't hold up approval of the patch until it's identified as 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.

[Trevor Daniels, 2010-12-22 22:58:18]

My comments on the two discussion points below.

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

http://codereview.appspot.com/3743045/diff/1/Documentation/notation/expressiv...
Documentation/notation/expressive.itely:366: Textual crescendo marks begin with
@code{\cresc}
I have to agree with Keith here - the manual will be more helpful if we simply
say what terminates a text crescendo rather than expecting the reader to work it
out.  A reference manual should be a source of accurate and complete information
that can be retrieved easily and quickly, not a puzzle that has to be worked out
and which still leaves the reader wondering if anything else might be a
termination.
Trevor

http://codereview.appspot.com/3743045/diff/1/Documentation/notation/expressiv...
Documentation/notation/expressive.itely:392: Textual marks can also be produced
by @code{\<} and @code{\>}:
I don't object to saying "deprecated".

[Carl, 2010-12-22 23:40:34]

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

http://codereview.appspot.com/3743045/diff/1/Documentation/notation/expressiv...
Documentation/notation/expressive.itely:366: Textual crescendo marks begin with
@code{\cresc}
On 2010/12/22 22:58:18, Trevor Daniels wrote:
> I have to agree with Keith here - the manual will be more helpful if we simply
> say what terminates a text crescendo rather than expecting the reader to work
it
> out.  A reference manual should be a source of accurate and complete
information
> that can be retrieved easily and quickly, not a puzzle that has to be worked
out
> and which still leaves the reader wondering if anything else might be a
> termination.

I hear this argument, but we've already said that cresecendos and decrescendos
are terminated by dynamic marks and \!.  Do you think it needs to be repeated?

Carl

[Trevor Daniels, 2010-12-23 00:21:02]

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

http://codereview.appspot.com/3743045/diff/1/Documentation/notation/expressiv...
Documentation/notation/expressive.itely:366: Textual crescendo marks begin with
@code{\cresc}
I think so.  The earlier mention was in relation to hairpins created with \< and
\>.  Here we talking about textual crescendos created with \cresc, etc.  It's
not a priori obvious these are terminated in the same way, although stating that
they are might be an alternative.

[Carl, 2010-12-23 01:46:36]

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

http://codereview.appspot.com/3743045/diff/1/Documentation/notation/expressiv...
Documentation/notation/expressive.itely:366: Textual crescendo marks begin with
@code{\cresc}
On 2010/12/23 00:21:03, Trevor Daniels wrote:
  
>It's not a priori obvious these are terminated in the same way, although
stating that
> they are might be an alternative. 

I think I'd prefer something like "Textual dynamic changes are ended in the same
manner as hairpin dynamics."

And leave the exact code demonstrations to the example.

Actually, as I read it, the manual says that:

 "A crescendo mark is started with \< and terminated with \!, an absolute
dynamic, or an additional crescendo or decrescendo mark. A decrescendo mark is
started with \> and is also terminated with \!, an absolute dynamic, or another
crescendo or decrescendo mark."   

It draws no distinction between whether the mark is a hairpin or a textual mark.
 And I think it's appropriate that it does so.  Logically, there is no
difference between a hairpin or a "cresc. ..." spanner; it's just a
typographical distinction. 

I think that drawing as many parallels as possible, with as little repetition as
is feasible, would be the best approach here.

However, the patch as proposed is better than the existing docs, so I'm willing
to agree to it.

[Keith, 2010-12-23 04:11:34]

Thanks for the comments. Second patch set is up.

The new patch corresponds to the state *before* makelsr.py, so that it is not
cluttered with version bumps to all the snippets.

Regarding deprecation,
the old *prefix* implementation of \cresc, never documented, is convert-ly-ed to
\deprecatedcresc and soundly deprecated.

The methods in these docs, by contrast, are all post-fix.  The command
\dimTextDecr is not attached to notes.  The method with \dimTextDecr was the
only documented way to get a text decrescendo, convert-ly does not update it,
and converting files that use it is not trivial.

So I do not want to say 'deprecated' about \dimTextDecr.

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

http://codereview.appspot.com/3743045/diff/10001/Documentation/notation/expre...
Documentation/notation/expressive.itely:368: Extender lines are engraved as
required.
The shorter text reads fine, to me, after sleeping on it.
I see no need to document the synonyms of \! (\endcr, \enddim, etc.)

http://codereview.appspot.com/3743045/diff/10001/Documentation/snippets/new/d...
File Documentation/snippets/new/dynamics-text-spanner-postfix.ly (right):

http://codereview.appspot.com/3743045/diff/10001/Documentation/snippets/new/d...
Documentation/snippets/new/dynamics-text-spanner-postfix.ly:6: with hairpin and
text crescendos. @code{\<} and @code{\>} produce
crescendos and crescendi are both good English; I broke the tie by looking at
the closest other use in the manual.

[Carl, 2010-12-23 04:27:06]

On 2010/12/23 04:11:34, Keith wrote:
> Thanks for the comments. Second patch set is up.
> 
> The new patch corresponds to the state *before* makelsr.py, so that it is not
> cluttered with version bumps to all the snippets.
> 
> Regarding deprecation,
> the old *prefix* implementation of \cresc, never documented, is convert-ly-ed
to
> \deprecatedcresc and soundly deprecated.

I don't see a patch to convertrules.py.

> 
> The methods in these docs, by contrast, are all post-fix.  The command
> \dimTextDecr is not attached to notes.  The method with \dimTextDecr was the
> only documented way to get a text decrescendo, convert-ly does not update it,
> and converting files that use it is not trivial.
> 
> So I do not want to say 'deprecated' about \dimTextDecr.

To me, that's exactly why we should say 'deprecated'.  Deprecated doesn't mean
removed, it means "still in place, but we recommend that it not be used in new
code."

http://en.wikipedia.org/wiki/Deprecation

That's what I think we want to do with \dimTextDecr.  We don't want people
writing new code using it, because when we finally remove it (for version 3.0)
it will require manual conversion (i.e. have a NOT_SMART rule).  

I feel like this patch is not complete -- like there are other changes to the
code that are not part of this patch set (e.g. the rename of \cresc to
\deprecatedcresc).  Am I missing something?

Thanks,

Carl

[Keith, 2010-12-23 04:41:43]

> I don't see a patch to convertrules.py.
> [...] Am I missing something?

Reinhold created the rule months ago, along with the implementation of the new
\cresc.  (I should have said "is *already* convert-ly-ed".)

> Deprecated doesn't mean removed, it means "still in 
> place, but we recommend that it not be used in new
> code."

True.

> [...] when we finally remove it (for version 3.0)

That is the part that I doubted.  The syntax and usage of \dimTextDecr looks to
me the same as many other commands, like \dynamicUp

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

http://codereview.appspot.com/3743045/diff/10001/Documentation/notation/expre...
Documentation/notation/expressive.itely:390: Textual marks for dynamic changes
can also replace haripins:
=> "hairpins"

http://codereview.appspot.com/3743045/diff/10001/Documentation/snippets/new/d...
File Documentation/snippets/new/dynamics-text-spanner-postfix.ly (right):

http://codereview.appspot.com/3743045/diff/10001/Documentation/snippets/new/d...
Documentation/snippets/new/dynamics-text-spanner-postfix.ly:7: hairpins by
default, \cresc etc. produce text spanners by default."
@code{\cresc}

[Carl, 2010-12-23 04:54:03]

On 2010/12/23 04:41:43, Keith wrote:
> > I don't see a patch to convertrules.py.
> > [...] Am I missing something?
> 
> Reinhold created the rule months ago, along with the implementation of the new
> \cresc.  (I should have said "is *already* convert-ly-ed".)
> 
> > Deprecated doesn't mean removed, it means "still in 
> > place, but we recommend that it not be used in new
> > code."
> 
> True.
> 
> > [...] when we finally remove it (for version 3.0)
> 
> That is the part that I doubted.  The syntax and usage of \dimTextDecr looks
to
> me the same as many other commands, like \dynamicUp

OK.  I guess we haven't formally decided to deprecate it. 

LGTM.

[Trevor Daniels, 2010-12-23 13:49:50]

OK, I think we've haggled over this enough :)

Keith, could you please fix the haripins, decide on the wording you prefer, and
let me have a patch to push.

Many thanks.

Trevor

[k-ohara5A5A_oco.net, 2010-12-23 23:03:09]

-------- Original Message --------
> From: tdanielsmusic@googlemail.com
> Keith, could you please fix the haripins, decide on the wording you
> prefer, and let me have a patch to push.
> 

Patch attached, and issue closed.
-Keith

[t.daniels_treda.co.uk, 2010-12-24 00:29:58]

Thanks Keith - checked and pushed to origin/master.

Trevor

----- Original Message ----- 
From: "Keith OHara" <k-ohara5A5A@oco.net>
To: <carl.d.sorensen@gmail.com>; <tdanielsmusic@googlemail.com>; 
<percival.music.ca@gmail.com>; <lilypond-devel@gnu.org>; 
<reply@codereview.appspotmail.com>; <carl.d.sorensen@gmail.com>; 
<percival.music.ca@gmail.com>
Cc: <lilypond-devel@gnu.org>; <reply@codereview.appspotmail.com>
Sent: Thursday, December 23, 2010 11:02 PM
Subject: Re: DOC: NR Dynamics context and postfix dynamics 
(issue3743045)


> -------- Original Message --------
>> From: tdanielsmusic@googlemail.com
>> Keith, could you please fix the haripins, decide on the wording 
>> you
>> prefer, and let me have a patch to push.
>>
>
> Patch attached, and issue closed.
> -Keith
>