Doc: NR Section on Upbeats made clearer (issue 5520056)

[pkx166h]

Reviewers: ,

Message:
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?



Description:
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

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

Affected files:
  M Documentation/notation/rhythms.itely


Index: Documentation/notation/rhythms.itely
diff --git a/Documentation/notation/rhythms.itely  
b/Documentation/notation/rhythms.itely
index  
5719c73ea7e0eca3c1a02cefc77aeff049756ce3..929bfecee2c06f1a6cceabcdd87baff5fda1e257  
100644
--- a/Documentation/notation/rhythms.itely
+++ b/Documentation/notation/rhythms.itely
@@ -1331,54 +1331,57 @@ Internals Reference:
 @cindex upbeat
 @cindex partial measure
 @cindex measure, partial
address@hidden measure, pickup
 @cindex pickup measure
address@hidden measure, change length

 @funindex measurePosition
 @funindex \partial
 @funindex partial

-Partial or pick-up measures, such as an anacrusis or upbeat, are
-entered using the @code{\partial} command, with the syntax
+Partial or pick-up measures, such as an @emph{anacrusis} or an
address@hidden, are entered using the @code{\partial} command,

 @example
 \partial @var{duration}
 @end example

 @noindent
-where @address@hidden is the rhythmic length of the
-remaining interval of the current measure before the start of the
-next.
+where @address@hidden is the @emph{remaining} length of the
+partial measure @emph{before} the start of the next full measure.

address@hidden,verbatim,relative=2]
-\partial 4 e4 |
-a2. c,4 |
address@hidden,verbatim,relative=1]
+\time 6/8
+\partial 8
+e8 | a4 c8 b[ c b] |
 @end lilypond

-The partial measure can be any duration less than the full measure:
+The partial @var{duration} can be any value less than a full measure:

address@hidden,verbatim,relative=2]
-\partial 8*3 c8 d e |
-a2. c,4 |
address@hidden,verbatim,relative=1]
+\time 6/8
+\partial 4.
+r4 e8 | a4 c8 b[ c b] |
 @end lilypond

-Internally, @code{\partial @var{duration}} is translated into:
+The @code{\partial @var{duration}} can also be written as;

 @example
 \set Timing.measurePosition address@hidden
 @end example

-For example, @code{\partial 8*3} becomes:
+So @code{\partial 8} becomes;

address@hidden
-\set Timing.measurePosition = #(ly:make-moment -3 8)
address@hidden example
address@hidden,verbatim,relative=1]
+\time 6/8
+\set Timing.measurePosition = #(ly:make-moment -1 8)
+e8 | a4 c8 b[ c b] |
address@hidden lilypond

 The property @code{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 @code{\partial} command:
-i.e., @code{\partial 4} is internally translated to @address@hidden, meaning
address@hidden is a quarter note left in the measure.}
+i.e., @code{\partial 4} is internally translated to @address@hidden,
+meaning @qq{there is a quarter note left in the measure.}

 @seealso
 Music Glossary:
@@ -1394,11 +1397,17 @@ Internal Reference:
 @rinternals{Timing_translator}.

 @knownissues
+The @code{\partial} command should be used only at the beginning of a
+piece.  If you use it after the beginning, warnings or problems may
+occur, so use @code{\set Timing.measurePosition} instead.

-The @code{\partial} command is intended to be used only at the
-beginning of a piece.  If you use it after the beginning, some
-odd warnings or effects may occur, in this case use
address@hidden Timing.measurePosition} instead.
address@hidden,verbatim,relative=1]
+\time 6/8
+\partial 8
+e8 | a4 c8 b[ c b] |
+\set Timing.measurePosition = #(ly:make-moment -1 4)
+r8 e,8 | a4 c8 b[ c b] |
address@hidden lilypond

 @node Unmetered music
 @unnumberedsubsubsec Unmetered music