Doc: NR added @knownissue for beam properties

Doc: NR added @knownissue for beam properties

Used Carl S's wording from comment #3 of Tracker 1566

Also collated to separate @warnings together as they looked odd in the doc
as two separate 'note' boxes one after the other.

[Carl, 2012-01-01 01:55:11]

LGTM.

I have some recommendations, but I won't hold up approval for them.  Just for
your consideration.

Thanks for doing this!  I was going to get to it, but I've been struggling with
getting GUB going.

Thanks,

Carl

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

http://codereview.appspot.com/5504100/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1902: and the beams indicated manually. 
Using @code{@bs{}partcombine} with
I think that the partcombine warning should become a known issue, instead of
being included in this warning.

http://codereview.appspot.com/5504100/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1953: @knownissues
I wonder if it would be better to actually include a snippet, instead of just a
known issue.

http://codereview.appspot.com/5504100/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1956: the beam has been completed will not
take effect until the @emph{next},
I think it would be better to eliminate the , and the word "new", but I don't
feel really strongly about it.

[Keith, 2012-01-01 02:59:06]

LGTM

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

http://codereview.appspot.com/5504100/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1903: @code{@bs{}autoBeamOff} can produce
unintended results.  See the
"can produce unintended results" is a too vague to be helpful.
If I understand, the point is that autoBeamOff affects the current voice only,
which can be surprising when used with features that automatically create voices
like \partcombine.

http://codereview.appspot.com/5504100/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1954: The properties of a beam are
determined at the @emph{start} of its
I had no idea what this was about until going back to the tracker issue.  The
surprising bit is with automatic beams, because you don't see where they start,
so we need an example.  You might just say :
"If you change properties of beam when a beam has already started, that beam
will not be affected.  For example, with the input {\hideNotes c8 f8
\unHideNotes c8 f8} the \hideNotes makes transparent the single automatic beam
across all four notes.  If you want the beam to be visible for the last two
notes you need to specify it explicitly. {\hideNotes c8 f8 \unHideNotes c8[ f8]}
"
This one is more a warning than a knownissue.

[Carl, 2012-01-01 03:08:19]

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

http://codereview.appspot.com/5504100/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1954: The properties of a beam are
determined at the @emph{start} of its
On 2012/01/01 02:59:06, Keith wrote:
> I had no idea what this was about until going back to the tracker issue.  The
> surprising bit is with automatic beams, because you don't see where they
start,
> so we need an example.  You might just say :
> "If you change properties of beam when a beam has already started, that beam
> will not be affected.  For example, with the input {\hideNotes c8 f8
> \unHideNotes c8 f8} the \hideNotes makes transparent the single automatic beam
> across all four notes.  If you want the beam to be visible for the last two
> notes you need to specify it explicitly. {\hideNotes c8 f8 \unHideNotes c8[
f8]}

This is why I recommend a snippet, rather than just the text.  If we need to
show a LilyPond example, we should show it with the output, rather than just
describing it in the text.

[pkx166h, 2012-01-01 11:34:34]

On 2012/01/01 03:08:19, Carl wrote:
>
http://codereview.appspot.com/5504100/diff/1/Documentation/notation/rhythms.i...
> File Documentation/notation/rhythms.itely (right):
> 
>
http://codereview.appspot.com/5504100/diff/1/Documentation/notation/rhythms.i...
> Documentation/notation/rhythms.itely:1954: The properties of a beam are
> determined at the @emph{start} of its
> On 2012/01/01 02:59:06, Keith wrote:
> > I had no idea what this was about until going back to the tracker issue. 
The
> > surprising bit is with automatic beams, because you don't see where they
> start,
> > so we need an example.  You might just say :
> > "If you change properties of beam when a beam has already started, that beam
> > will not be affected.  For example, with the input {\hideNotes c8 f8
> > \unHideNotes c8 f8} the \hideNotes makes transparent the single automatic
beam
> > across all four notes.  If you want the beam to be visible for the last two
> > notes you need to specify it explicitly. {\hideNotes c8 f8 \unHideNotes c8[
> f8]}
> 
> This is why I recommend a snippet, rather than just the text.  If we need to
> show a LilyPond example, we should show it with the output, rather than just
> describing it in the text.

OK, but I think the example of \hideNotes, (that of the tracker) is too
complicated (or unnecessarily so).

Can we show this using a single voice with non-chorded notes and by using
something more 'obvious' than \hideNotes?

[Carl, 2012-01-01 14:56:25]

> Can we show this using a single voice with non-chorded notes and by using
> something more 'obvious' than \hideNotes?

Override the beam color to red?

[dak, 2012-01-01 15:06:05]

On 2012/01/01 14:56:25, Carl wrote:
> > Can we show this using a single voice with non-chorded notes and by using
> > something more 'obvious' than \hideNotes?
> 
> Override the beam color to red?

Also \once\hideNotes might be a bit more snappy.

[Keith, 2012-01-01 21:31:50]

On 2012/01/01 15:06:05, dak wrote:
> On 2012/01/01 14:56:25, Carl wrote:
> > > Can we show this using a single voice with non-chorded notes and by using
> > > something more 'obvious' than \hideNotes?

\relative c' {
  \voiceTwoStyle
  c8 e \voiceNeutralStyle g c
  \voiceTwoStyle 
  c8 e \voiceNeutralStyle g[ c]
}

Remember that the original bug reporter was not trying to "change any properties
of a beam" but only using a pre-defined function.
 
> Also \once\hideNotes might be a bit more snappy.

Hey, that works now!  Thanks, David.  
To make the desired point, it would need to hide the first note and the beam,
which would need some explanation to point out what is going on.

[pkx166h, 2012-01-01 22:33:15]

On 2012/01/01 21:31:50, Keith wrote:
> On 2012/01/01 15:06:05, dak wrote:
> > On 2012/01/01 14:56:25, Carl wrote:
> > > > Can we show this using a single voice with non-chorded notes and by
using
> > > > something more 'obvious' than \hideNotes?
> 
> \relative c' {
>   \voiceTwoStyle
>   c8 e \voiceNeutralStyle g c
>   \voiceTwoStyle 
>   c8 e \voiceNeutralStyle g[ c]
> }

Seriously?

> 
> Remember that the original bug reporter was not trying to "change any
properties
> of a beam" but only using a pre-defined function.

Yes but also remember that this is not an attempt to fix the reporters issue but
document it for others that do not necessarily use complex constructions like
\voiceTwoStyle and \voiceNeutralStyle.
>  
> > Also \once\hideNotes might be a bit more snappy.
> 
> Hey, that works now!  Thanks, David.  
> To make the desired point, it would need to hide the first note and the beam,
> which would need some explanation to point out what is going on.

Or we could just show a simple case of beams not being colored in when the
override happens mid-beam (so to speak).

[pkx166h, 2012-01-01 22:33:33]

See comments below, thanks.

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

http://codereview.appspot.com/5504100/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1953: @knownissues
On 2012/01/01 01:55:11, Carl wrote:
> I wonder if it would be better to actually include a snippet, instead of just
a
> known issue.

See comment below

http://codereview.appspot.com/5504100/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1954: The properties of a beam are
determined at the @emph{start} of its
On 2012/01/01 02:59:06, Keith wrote:
> I had no idea what this was about until going back to the tracker issue.  The
> surprising bit is with automatic beams, because you don't see where they
start,
> so we need an example.  You might just say :
> "If you change properties of beam when a beam has already started, that beam
> will not be affected.  For example, with the input {\hideNotes c8 f8
> \unHideNotes c8 f8} the \hideNotes makes transparent the single automatic beam
> across all four notes.  If you want the beam to be visible for the last two
> notes you need to specify it explicitly. {\hideNotes c8 f8 \unHideNotes c8[
f8]}
> "
> This one is more a warning than a knownissue.

Happy with @warning vs @knownissues

http://codereview.appspot.com/5504100/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1954: The properties of a beam are
determined at the @emph{start} of its
On 2012/01/01 03:08:19, Carl wrote:
> On 2012/01/01 02:59:06, Keith wrote:
> > I had no idea what this was about until going back to the tracker issue. 
The
> > surprising bit is with automatic beams, because you don't see where they
> start,
> > so we need an example.  You might just say :
> > "If you change properties of beam when a beam has already started, that beam
> > will not be affected.  For example, with the input {\hideNotes c8 f8
> > \unHideNotes c8 f8} the \hideNotes makes transparent the single automatic
beam
> > across all four notes.  If you want the beam to be visible for the last two
> > notes you need to specify it explicitly. {\hideNotes c8 f8 \unHideNotes c8[
> f8]}
> 
> This is why I recommend a snippet, rather than just the text.  If we need to
> show a LilyPond example, we should show it with the output, rather than just
> describing it in the text.

I disagree.

The example in the tracker is overly complicated for what (I still maintain) is
easily explained. However *if* we really do need an example then the \hideNotes
one is not ideal. I struggled myself with that one in the tracker, it isn't a
'tiny example' by any stretch of the imagination and I knew perfectly well what
was meant by the problem only *after* I read the text explanation, the picture
on the tracker added nothing for me.

http://codereview.appspot.com/5504100/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1956: the beam has been completed will not
take effect until the @emph{next},
On 2012/01/01 01:55:11, Carl wrote:
> I think it would be better to eliminate the , and the word "new", but I don't
> feel really strongly about it.

No problem with that.

[Keith, 2012-01-01 23:38:37]

On Sun, 01 Jan 2012 14:33:33 -0800, <pkx166h@gmail.com> wrote:

> I disagree.
>
> The example in the tracker is overly complicated for what (I still
> maintain) is easily explained. However *if* we really do need an example
> then the \hideNotes one is not ideal. I struggled myself with that one
> in the tracker, it isn't a 'tiny example' by any stretch of the
> imagination and I knew perfectly well what was meant by the problem only
> *after* I read the text explanation, the picture on the tracker added
> nothing for me.
>

Okay, then.  You are addressing the fact that the beam was not un-hidden
mid-stroke, because no properties are changed mid-stroke.  So this makes sense
as a knownissue

The other way looking at the bug report is that \hideNotes seems to have removed
the automatic beam.  ( What is your man going on about with the "beam
properties"?  I don't see any beam.  Do you see a beam? )

For that aspect, I'll add a few words and beamed notes to the second example of
NR 1.7.1 \hideNotes :
+ Note heads, stems, flags, and beams are invisible, but other
= objects that are attached to invisible notes are still visible.

[Graham Percival, 2012-01-30 12:10:35]

LGTM

[pkx166h, 2012-02-01 20:27:58]

committer	James Lowe <pkx166h@gmail.com>	

	 Wed, 1 Feb 2012 20:27:11 +0000 (20:27 +0000)

commit	d9d8de32b213adfcaf4ff318d79c2872e470578d