Doc: mention empty chords; avoid using zero-duration spacers in examples

Doc: avoid using zero-duration spacers in examples

[Keith, 2012-05-10 07:35:30]

http://codereview.appspot.com/6197068/diff/1/Documentation/extending/scheme-t...
File Documentation/extending/scheme-tutorial.itely (right):

http://codereview.appspot.com/6197068/diff/1/Documentation/extending/scheme-t...
Documentation/extending/scheme-tutorial.itely:1289: @{ << \music <> -. -> @}
<< \music <> -. -> >>

[Trevor Daniels, 2012-05-10 08:50:38]

LGTM

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/simultane...
File Documentation/notation/simultaneous.itely (right):

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/simultane...
Documentation/notation/simultaneous.itely:89: r4 e8( g <>) ^"sul D" \f \>
\repeat unfold 8 { c-. } r2\!
Interestingly, s1*0 does not work in this situation to attach the annotations to
the first note in the repeated section, but <> is fine.  Unfortunately, <> is of
no help for attaching the \! to the final note of the repeated section.

[dak, 2012-05-10 09:33:27]

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/simultane...
File Documentation/notation/simultaneous.itely (right):

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/simultane...
Documentation/notation/simultaneous.itely:89: r4 e8( g <>) ^"sul D" \f \>
\repeat unfold 8 { c-. } r2\!
On 2012/05/10 08:50:38, Trevor Daniels wrote:
> Interestingly, s1*0 does not work in this situation to attach the annotations
to
> the first note in the repeated section, but <> is fine.  Unfortunately, <> is
of
> no help for attaching the \! to the final note of the repeated section. 

That example gives me a headache.  s1*0 will work just fine: you just have to
put an explicit duration on { c8-. }.  If the decrescendo should be on the last
note, you would either cut the repeat short by one, or write
{ r4 e8( g << { s8*7) ^"sul D" \f \> s8\! }
                             \repeat unfold 8 { c8-. } >> r2\! }

But I think the whole thing is too clever for the notation manual.  The rather
contrived ways of avoiding to spell out first/last iterations complicate things
rather than simplify them.

[Keith, 2012-05-11 04:28:40]

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/simultane...
File Documentation/notation/simultaneous.itely (right):

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/simultane...
Documentation/notation/simultaneous.itely:89: r4 e8( g <>) ^"sul D" \f \>
\repeat unfold 8 { c-. } r2\!
On 2012/05/10 08:50:38, Trevor Daniels wrote:
> Unfortunately, <> is of no help for attaching 
> the \! to the final note of the repeated section. 

Somehow that never bothered me.  Conceptually I think of decrescendos as
continuing through the last note.  (If the rest were longer, though, I
personally would prefer <>\! R1*12 )

There is an example under Dynamics 
/Documentation/notation/expressive-marks-attached-to-notes.html#dynamics
using a parallel sequence of spacer rests, that shows how to end the crescendo
wherever you want.

Of course a parallel sequence of spacer rests would work here, too, just it
substituted for the other cases of s1*0 in the docs, and like it could for all
the uses by those lazy users whose scores came up in a search for s1*0 at
mutopiaproject.

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/simultane...
Documentation/notation/simultaneous.itely:89: r4 e8( g <>) ^"sul D" \f \>
\repeat unfold 8 { c-. } r2\!
We might not want an example for <> at all.  This one was an amalgam of the
usage I found on mutopiaproject.  Another way to demonstrate the text could be
  music = \relative c'' { e16 d c d }
  { f'4 <>\marcato \music r <>^"smorz." \mp \> \music <>\! }

[Trevor Daniels, 2012-05-11 07:55:48]

Houston, we have a problem.

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/simultane...
File Documentation/notation/simultaneous.itely (right):

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/simultane...
Documentation/notation/simultaneous.itely:89: r4 e8( g <>) ^"sul D" \f \>
\repeat unfold 8 { c-. } r2\!
Going back to the original example and the attempt to use <>\! to terminate the
decresc, it seems there is also a pitfall with <>.  The decresc can be
terminated with a note or rest of any duration, but <>\! can only be used if it
happens to fall on a bar line.  If it doesn't LP complains that the bounds are
not breakable.  This seems a serious drawback to me.

[dak, 2012-05-11 08:07:06]

On 2012/05/11 07:55:48, Trevor Daniels wrote:
> Houston, we have a problem.
> 
>
http://codereview.appspot.com/6197068/diff/1/Documentation/notation/simultane...
> File Documentation/notation/simultaneous.itely (right):
> 
>
http://codereview.appspot.com/6197068/diff/1/Documentation/notation/simultane...
> Documentation/notation/simultaneous.itely:89: r4 e8( g <>) ^"sul D" \f \>
> \repeat unfold 8 { c-. } r2\!
> Going back to the original example and the attempt to use <>\! to terminate
the
> decresc, it seems there is also a pitfall with <>.  The decresc can be
> terminated with a note or rest of any duration, but <>\! can only be used if
it
> happens to fall on a bar line.  If it doesn't LP complains that the bounds are
> not breakable.  This seems a serious drawback to me.

Is that more like a spanner problem or a chord problem?  It is different if you
use something like c1*0?

[Trevor Daniels, 2012-05-11 09:16:01]

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/simultane...
File Documentation/notation/simultaneous.itely (right):

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/simultane...
Documentation/notation/simultaneous.itely:89: r4 e8( g <>) ^"sul D" \f \>
\repeat unfold 8 { c-. } r2\!
> <>\! can only be used if it
> happens to fall on a bar line.

But, as David has pointed out, this is more likely a problem in spanner
management, as c1*0 has exactly the same problem.  So <> is no worse than s1*0
in this regard.

[janek, 2012-05-11 09:51:03]

LGTM

[Keith, 2012-05-11 17:05:16]

On Fri, 11 May 2012 00:55:48 -0700, <tdanielsmusic@googlemail.com> wrote:

> The decresc can be terminated with a note or rest of any duration,but <>\! can
only be used if it happens to fall on a bar line.

..or if the you finish the bar in some other way
    { c2 <>\! r2 } { c2 <>\! s2 }
The <> specifies when to end the hairpin, but LilyPond also wants a reference
graphical object to know where to end its printing.

I was hoping to keep the text above the example short.  It generalizes : Some
notations are placed relative to a note head (or rest or bar-line). These may be
attached to an empty chord, so long as some other input provides the note head
(or rest or bar-line).


I expected complaints about vocal.itely.  It now avoids the tricky
zero-length-spacer-rest in favor of a much longer input.  My evidence for the
longer input being less cryptic is
http://lists.gnu.org/archive/html/lilypond-user/2011-10/msg00118.html   The
documentation for the longer construction is in staff.itely

[dak, 2012-05-13 19:06:42]

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/changing-...
File Documentation/notation/changing-defaults.itely (right):

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:749: s1^"Small, thicker stems, no
time signature"
I don't like this.  It requires \melody to be at least as long as a whole note
in order to work.  But the length of \melody is established elsewhere, and is
not, so to say, a local contract.  The example only works as a whole, but is no
longer copy-and-paste material.

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

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:210: e''2\p\< d''\> | c''1\!
I am not particularly happy about "defusing" the demonstrated problem with
additional material.

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/pitches.i...
File Documentation/notation/pitches.itely (right):

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/pitches.i...
Documentation/notation/pitches.itely:1401: s1^\markup { Switch to B\flat
clarinet }
The markup can't just be attached to the whole bar rest?

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/simultane...
File Documentation/notation/simultaneous.itely (right):

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/simultane...
Documentation/notation/simultaneous.itely:81: An empty chord, @code{<>},
produces no notes and has no duration, but
I think I'll make a more extensive change proposal here instead of an added
section.

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

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1361: \new CueVoice { \set
"instrumentCueName" = "flute" }
It looks fishy to me to start a one-shot \cueVoice just for the instrument name.
 Perhaps we should instead let \cueDuring accept an optional context
modification argument.

http://codereview.appspot.com/6197068/diff/1/input/regression/empty-chord.ly
File input/regression/empty-chord.ly (right):

http://codereview.appspot.com/6197068/diff/1/input/regression/empty-chord.ly#...
input/regression/empty-chord.ly:4: and leave the current duation unchanged."
duation -> duration

[Keith, 2012-05-14 06:55:08]

Absorbed suggestions.  Added snippets.

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/changing-...
File Documentation/notation/changing-defaults.itely (right):

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:749: s1^"Small, thicker stems, no
time signature"
On 2012/05/13 19:06:43, dak wrote:
> I don't like this. [...] no longer copy-and-paste material.

I don't like it either.  The the original was not foolproof copy-and-paste
either, with the duration leakage.

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

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:210: e''2\p\< d''\> | c''1\!
This example is rather dense.  Any other way of defusing the s1*0 problem is
distracting, as was the s1*0 itself.

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/pitches.i...
File Documentation/notation/pitches.itely (right):

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/pitches.i...
Documentation/notation/pitches.itely:1401: s1^\markup { Switch to B\flat
clarinet }
On 2012/05/13 19:06:43, dak wrote:
> The markup can't just be attached to the whole bar rest?

No, because we need the textLengthOn to have effect.  Multimeasure rests, and
their text scripts, have special spacing rules.

The s1, however, splits a compressed multi-measure rest R1*12 into R1 R1*11.

I cannot recommend in good conscience anything but <> here.

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

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1361: \new CueVoice { \set
"instrumentCueName" = "flute" }
On 2012/05/13 19:06:43, dak wrote:
>  Perhaps we should instead let \cueDuring accept an optional context
> modification argument.
Xavier requested this optional argument to \cueDuring, but Trevor has had a
\cueWhile function in the docs for a while, which takes a string to identify who
is giving the cue, so I think it best to stick with that.

http://codereview.appspot.com/6197068/diff/10002/Documentation/notation/simul...
File Documentation/notation/simultaneous.itely (right):

http://codereview.appspot.com/6197068/diff/10002/Documentation/notation/simul...
Documentation/notation/simultaneous.itely:90: { f'4 <>\marcato \music r
<>^"smorz." \mp \> \music <>\! }
maybe this is a better example.

[dak, 2012-05-14 07:26:58]

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

http://codereview.appspot.com/6197068/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1361: \new CueVoice { \set
"instrumentCueName" = "flute" }
On 2012/05/14 06:55:08, Keith wrote:
> On 2012/05/13 19:06:43, dak wrote:
> >  Perhaps we should instead let \cueDuring accept an optional context
> > modification argument.
> Xavier requested this optional argument to \cueDuring, but Trevor has had a
> \cueWhile function in the docs for a while, which takes a string to identify
who
> is giving the cue, so I think it best to stick with that.

We can't "stick" with something that isn't in LilyPond proper but just in some
snippet.

I'll take a look at what this would entail.  An optional context mod would
appear to make for a rather straightforward and easy to remember interface.

[Keith, 2012-06-02 01:27:31]

http://codereview.appspot.com/6197068/diff/10002/Documentation/snippets/new/m...
File Documentation/snippets/new/multi-measure-rest-markup.ly (left):

http://codereview.appspot.com/6197068/diff/10002/Documentation/snippets/new/m...
Documentation/snippets/new/multi-measure-rest-markup.ly:82: s1*0^\markup {
[MAJOR GENERAL] }
Changes to this snippet come via a different path, because this snipped came
from the LSR.  Also, in this case, the one known bad side-effect of s1*0 is even
less likely to cause any problem.

[Graham Percival, 2012-06-13 03:01:20]

ok.

http://codereview.appspot.com/6197068/diff/24001/Documentation/notation/keybo...
File Documentation/notation/keyboards.itely (right):

http://codereview.appspot.com/6197068/diff/24001/Documentation/notation/keybo...
Documentation/notation/keyboards.itely:210: e''2\p\< d''\> | c''1\!
we normally only allow one bar per line unless you're specifically showing
something with lots of bars and have only whole notes.

Unless you want a specific exemption from that policy, could you put the c1 on
the next line?  (also the later c1 and f'1)

[Keith, 2012-06-13 18:47:57]

http://codereview.appspot.com/6197068/diff/24001/Documentation/notation/chang...
File Documentation/notation/changing-defaults.itely (right):

http://codereview.appspot.com/6197068/diff/24001/Documentation/notation/chang...
Documentation/notation/changing-defaults.itely:749: s^"Small, thicker stems, no
time signature"
I've also made the implicit duration explicit, s4, in two places here.

http://codereview.appspot.com/6197068/diff/24001/Documentation/notation/keybo...
File Documentation/notation/keyboards.itely (right):

http://codereview.appspot.com/6197068/diff/24001/Documentation/notation/keybo...
Documentation/notation/keyboards.itely:210: e''2\p\< d''\> | c''1\!
On 2012/06/13 03:01:20, Graham Percival wrote:
> we normally only allow one bar per line

I've added the three line-breaks.

[janek, 2012-06-13 19:21:48]

http://codereview.appspot.com/6197068/diff/24001/Documentation/notation/keybo...
File Documentation/notation/keyboards.itely (right):

http://codereview.appspot.com/6197068/diff/24001/Documentation/notation/keybo...
Documentation/notation/keyboards.itely:210: e''2\p\< d''\> | c''1\!
On 2012/06/13 18:47:57, Keith wrote:
> On 2012/06/13 03:01:20, Graham Percival wrote:
> > we normally only allow one bar per line
> 
> I've added the three line-breaks.

I don't see them.

[Graham Percival, 2012-06-15 03:00:45]

On 2012/06/13 19:21:48, janek wrote:
> On 2012/06/13 18:47:57, Keith wrote:
> > I've added the three line-breaks.
> 
> I don't see them.

I don't think it's worth re-uploading a new patch just for this.

Please push to staging.