Doc: NR Section on Upbeats made clearer

Doc: NR Section on Upbeats made clearer

Tracker issue 2189

Created simpler and clearer @lilypond examples.

Used a less complex, more obvious value for \set Timing.measure position
examples and added a specific example after the @knownissue to show
\partial and \set Timing.. being used together (at the beginning and
after the beginning) to help reinforce the point.

Minor cindex changes and linebreak edits as per the CG

[pkx166h, 2012-01-06 19:58:29]

I'm not convinced knowing more than I did back when I originally edited this
part of the doc (it was one of my first patches i ever did so I was taking
advice from others).

--snip from NR --

The property measurePosition contains a rational number
indicating how much of the measure has passed at this point.  Note that this is
set to a negative number by the \partial command: i.e., \partial 4 is internally
translated to -4 ...

--snip--

well while

\partial 4 is the equivalent to

\set Timing.measurePosition = #(ly:make-moment -1 4) or

\set Timing.measurePosition = #(ly:make-moment -2 8)

\set Timing.measurePosition = #(ly:make-moment -4)

does not work.

Also the explanation of using \set Timing.measurePosition is described as

--snip--

\set Timing.measurePosition -duration

--snip--

which is very different from 

\set Timing.measurePosition = #(ly:make-moment X X)

and implies that there are other values that I could use instead of
#(ly:make-moment ... ).

Are we talking through the code here or could we put in another example to help
the more adept at the internals?

[Graham Percival, 2012-01-09 05:08:58]

I like some of the changes here, but I have serious doubts about others.

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

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1353: \time 6/8
huh?!  why is this easier to understand than \partial 4 ?

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1355: e8 | a4 c8 b[ c b] |
what on earth does manual beaming have to do with a \partial?  How does that
improve this example?

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1366: The @code{\partial @var{duration}}
can also be written as;
if this was true, then surely there would be no difference between \partial and
\set blah  after the piece had begun.  However, the @knownissues claims that you
should only use \partial in the beginning.

I think in this case the original material was slightly less misleading.

[Neil Puttock, 2012-01-09 12:58:58]

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

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1366: The @code{\partial @var{duration}}
can also be written as;
On 2012/01/09 05:08:58, Graham Percival wrote:
> if this was true, then surely there would be no difference between \partial
and
> \set blah  after the piece had begun.  However, the @knownissues claims that
you
> should only use \partial in the beginning.

It's almost the same.  The main difference is that \partial uses an iterator to
set measurePosition.  It ensures grace notes don't mess up the timing (which can
affect beaming) and allows \displayMusic to pick up the correct duration.

[Neil Puttock, 2012-01-09 12:59:40]

On 2012/01/09 12:58:58, Neil Puttock wrote:
>
http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
> File Documentation/notation/rhythms.itely (right):
> 
>
http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
> Documentation/notation/rhythms.itely:1366: The @code{\partial @var{duration}}
> can also be written as;
> On 2012/01/09 05:08:58, Graham Percival wrote:
> > if this was true, then surely there would be no difference between \partial
> and
> > \set blah  after the piece had begun.  However, the @knownissues claims that
> you
> > should only use \partial in the beginning.
> 
> It's almost the same.  The main difference is that \partial uses an iterator
to
> set measurePosition.  It ensures grace notes don't mess up the timing (which
can
> affect beaming) and allows \displayMusic to pick up the correct duration.

I mean \displayLilyMusic of course.

[Neil Puttock, 2012-01-09 13:05:54]

Note that this is misleading:

\relative c' {
  \partial 4
  c4
  \applyContext #(lambda (ctx)
                   (newline)
                   (display (ly:context-current-moment ctx)))
  c1
}

-> #<Mom 1/4>

The Rational class doesn't display negative rationals unless they're infinite.

[janek, 2012-01-10 22:23:28]

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

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1350: partial measure @emph{before} the
start of the next full measure.
What about 
"where @code{@var{duration}} is the duration that will be added before the first
measure.  In other words, it is the @emph{remaining} length of the partial
measure @emph{before} the start of the first full measure."
?

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1353: \time 6/8
On 2012/01/09 05:08:58, Graham Percival wrote:
> huh?!  why is this easier to understand than \partial 4 ?

+1

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1355: e8 | a4 c8 b[ c b] |
On 2012/01/09 05:08:58, Graham Percival wrote:
> what on earth does manual beaming have to do with a \partial?  How does that
> improve this example?

+1

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1358: The partial @var{duration} can be any
value less than a full measure:
I'm not sure about "partial duration" thing.

But i like the "value" part.

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1363: r4 e8 | a4 c8 b[ c b] |
i think original example was better because it showed use of 8*3 construct.

[pkx166h, 2012-01-24 08:33:49]

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

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1350: partial measure @emph{before} the
start of the next full measure.
On 2012/01/10 22:23:29, janek wrote:
> What about 
> "where @code{@var{duration}} is the duration that will be added before the
first
> measure.  In other words, it is the @emph{remaining} length of the partial
> measure @emph{before} the start of the first full measure."
> ?

Because partials can occur in any part of the score. So saying 'first' measure
is not correct. It could be the 200th measure. I know we say don't use \partials
in the beginning of a piece but we can and they work and if I have different
\score constructs in my score it still might not be the 'first' measure. So we
need to be boringly, technically accurate.

Also if you have to write 'in other words' in a document then you probably
haven't articulated clearly enough what you should have said in the first place.

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1353: \time 6/8
On 2012/01/09 05:08:58, Graham Percival wrote:
> huh?!  why is this easier to understand than \partial 4 ?

This specific example no, but because I had changed the first example and wanted
to keep it the same throughout... anyway I have changed the time sig so it makes
more sense (I think).

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1355: e8 | a4 c8 b[ c b] |
On 2012/01/09 05:08:58, Graham Percival wrote:
> what on earth does manual beaming have to do with a \partial?  How does that
> improve this example?

Done.

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1358: The partial @var{duration} can be any
value less than a full measure:
On 2012/01/10 22:23:29, janek wrote:
> I'm not sure about "partial duration" thing.
> 
> But i like the "value" part.

Reworded slightly.

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1358: The partial @var{duration} can be any
value less than a full measure:
On 2012/01/10 22:23:29, janek wrote:
> I'm not sure about "partial duration" thing.
> 
> But i like the "value" part.

changed this slightly.

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1363: r4 e8 | a4 c8 b[ c b] |
On 2012/01/10 22:23:29, janek wrote:
> i think original example was better because it showed use of 8*3 construct.

I disagree. We can show that construct elsewhere, that has nothing to do with
partials. I wanted to remove that mutiplyer from the examples (just because was
can do it doesn't always mean we should do it).

Maybe 6/8 time is a time sig to use in this case. 

If I were using 3/4 and wanted a whole note in my partial I would use 4 not 8*2
- heck I could use 16*4 and still be right.

http://codereview.appspot.com/5520056/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:1366: The @code{\partial @var{duration}}
can also be written as;
On 2012/01/09 12:58:58, Neil Puttock wrote:
> On 2012/01/09 05:08:58, Graham Percival wrote:
> > if this was true, then surely there would be no difference between \partial
> and
> > \set blah  after the piece had begun.  However, the @knownissues claims that
> you
> > should only use \partial in the beginning.
> 
> It's almost the same.  The main difference is that \partial uses an iterator
to
> set measurePosition.  It ensures grace notes don't mess up the timing (which
can
> affect beaming) and allows \displayMusic to pick up the correct duration.

Well I have asked on this tracker issue why we use

\set Timing.measurePosition -@var{duration}

as an example here because we never actually use it literally.

#(ly:make-moment -1 4) != -duration

#(ly:make-moment -1 4) == #(ly:make-moment {var1} {var2})
where var1 is etc. etc.

Hence why I asked if this is the only construct we can use for \set
Timing.measurePosition (at least in this case) in which case we can remove this
whole para and just leave the @knownissue.

[Graham Percival, 2012-01-24 11:21:33]

looks mostly good.

http://codereview.appspot.com/5520056/diff/7001/Documentation/notation/rhythm...
File Documentation/notation/rhythms.itely (right):

http://codereview.appspot.com/5520056/diff/7001/Documentation/notation/rhythm...
Documentation/notation/rhythms.itely:1358: The @var{duration} can also be any
value less than a full measure:
\partial 8 is already less than a full measure.  What are you trying to say/show
in this second example?

http://codereview.appspot.com/5520056/diff/7001/Documentation/notation/rhythm...
Documentation/notation/rhythms.itely:1372: So @code{\partial 8} becomes;
grammatically I really think a full colon: is correct here.

[janek, 2012-01-24 21:38:17]

mostly LGTM

http://codereview.appspot.com/5520056/diff/7001/Documentation/notation/rhythm...
File Documentation/notation/rhythms.itely (right):

http://codereview.appspot.com/5520056/diff/7001/Documentation/notation/rhythm...
Documentation/notation/rhythms.itely:1358: The @var{duration} can also be any
value less than a full measure:
I think it would be good without that "also".
I think the purpose of the second example is to show that partial can contain
more than one note.

http://codereview.appspot.com/5520056/diff/7001/Documentation/notation/rhythm...
Documentation/notation/rhythms.itely:1363: r4 e8 | a4 c8 b c4 |
it's a bit weird to have 3/4 time sig and 4. partial, consisting of r4 and e8
(3/4 measure doesn't divide in two parts).  but i don't think it's that
important.

http://codereview.appspot.com/5520056/diff/7001/Documentation/notation/rhythm...
Documentation/notation/rhythms.itely:1372: So @code{\partial 8} becomes;
On 2012/01/24 11:21:33, Graham Percival wrote:
> grammatically I really think a full colon: is correct here.

+1

[pkx166h, 2012-01-29 11:06:24]

http://codereview.appspot.com/5520056/diff/7001/Documentation/notation/rhythm...
File Documentation/notation/rhythms.itely (right):

http://codereview.appspot.com/5520056/diff/7001/Documentation/notation/rhythm...
Documentation/notation/rhythms.itely:1358: The @var{duration} can also be any
value less than a full measure:
On 2012/01/24 21:38:18, janek wrote:
> I think it would be good without that "also".
> I think the purpose of the second example is to show that partial can contain
> more than one note.

Correct.

http://codereview.appspot.com/5520056/diff/7001/Documentation/notation/rhythm...
Documentation/notation/rhythms.itely:1363: r4 e8 | a4 c8 b c4 |
On 2012/01/24 21:38:18, janek wrote:
> it's a bit weird to have 3/4 time sig and 4. partial, consisting of r4 and e8
> (3/4 measure doesn't divide in two parts).  but i don't think it's that
> important.

Hmm.. well maybe the music I play in our windband is weird. :0 it seems to be
quite common for different instruments start in different places in an upbeat. 

Anyway I was just trying to show something with a dotted partial value as an
example instead of the '*' construction which I think is more confusing - at
least in a 3/4 construction.

http://codereview.appspot.com/5520056/diff/7001/Documentation/notation/rhythm...
Documentation/notation/rhythms.itely:1372: So @code{\partial 8} becomes;
On 2012/01/24 11:21:33, Graham Percival wrote:
> grammatically I really think a full colon: is correct here.

Done.

[Graham Percival, 2012-01-30 12:11:30]

LGTM

[pkx166h, 2012-02-01 20:25:56]

committer	James Lowe <pkx166h@gmail.com>	

	 Wed, 1 Feb 2012 20:25:00 +0000 (20:25 +0000)

commit	86c9165e160f731023859aa57292b30f7436ef6f