Doc: improve documentation of Bézier curves (2858)

Doc: improve documentation of Bézier curves (2858)

 - add \shape function
 - show example of two curves being shaped
 - show example of line-broken slur
 - show example of S-shaped slur
 - relegate setting absolute values to end
   and give a more realistic example

[Keith, 2012-09-28 06:45:50]

Maybe just dump the waste of time that was
   \override 'control-points

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

http://codereview.appspot.com/6561064/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:3953: values are then found by
trial and error.
.. and trial and error again if you change anything, or if the line-breaking
changes, or if you need to switch between A4 and US letter paper ...

http://codereview.appspot.com/6561064/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:3977: If cubic-shaped curve is
required the control points must be set
A curve shaped like a cube ? 
You mean S-shaped, or sigmoidal, or 'curve with inflection' or 'curve that
changes the direction of its bend'?

http://codereview.appspot.com/6561064/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:3988: { c4 e, f' d }
A tiny bit ugly.

\relative c'' {
    c8( e b-> f d' a e-> g)
    \shape Slur #'((0 . 0) (5.5 . 0) (-5.5 . -10) (0 . -6))
    c8( e b-> f d' a e-> g)
  }

Accents make the point that the newly-shaped Slur is integrated into the usual
collision-avoidance (distinct from other hand-tweaks like rotation and
extra-offset).

http://codereview.appspot.com/6561064/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:3996: the ones calculated
automatically, remembering that a translation of
You can probably skip the "remembering that.."
Discussions of Bezier curves always mention this, but it seems implicit in
having the curves parametrized by "control points".

[david.nalesnik, 2012-09-28 21:43:10]

Trevor--

Thank you so much for taking this on!  I've been pecking at documenting this for
awhile, but got hung up on finding the perfect examples... What you have is
clearer than what I cam up with.

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

https://codereview.appspot.com/6561064/diff/1/Documentation/notation/changing...
Documentation/notation/changing-defaults.itely:4027: 
Perhaps at this point it would be helpful to include an example of \shape
applied to a curve across a line break.  Something like this:

"The \shape function can also displace the control points of curves which
stretch across line breaks.  Each piece of the broken curve can receive its own
list of offsets.  In case changes to a particular segment are not needed, the
empty list can serve as a placeholder."

\relative c'' {
  % () may be used as a shorthand for ((0 . 0) (0 . 0) (0 . 0) (0 . 0))
  \shape Slur #'(() ((0.5 . -1.5) (1 . 0.5) (0 . 0.5) (0 . -1.5)))
  c4( f g c
  \break
  d,4 c' f, c)
}

\layout {
  ragged-right = ##t
}

[Trevor Daniels, 2012-10-06 22:35:40]

I've added an example showing two curves that start
at the same musical moment being shaped, as well as
the changes suggested by Keith and David.

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

http://codereview.appspot.com/6561064/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:3953: values are then found by
trial and error.
On 2012/09/28 06:45:50, Keith wrote:
> .. and trial and error again if you change anything, or if the line-breaking
> changes, or if you need to switch between A4 and US letter paper ...

I take the point.  I've down-played this section by moving
it to the end and illustrated it with an example that
better shows its utility (allbeit a rather hackish one).

http://codereview.appspot.com/6561064/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:3977: If cubic-shaped curve is
required the control points must be set
On 2012/09/28 06:45:50, Keith wrote:
> A curve shaped like a cube ? 
> You mean S-shaped, or sigmoidal, or 'curve with inflection' or 'curve that
> changes the direction of its bend'? 
Yes, but third-order Bézier curves are also called cubic.
Changed to "S-shaped".

http://codereview.appspot.com/6561064/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:3988: { c4 e, f' d }
On 2012/09/28 06:45:50, Keith wrote:
> A tiny bit ugly.
> 
> \relative c'' {
>     c8( e b-> f d' a e-> g)
>     \shape Slur #'((0 . 0) (5.5 . 0) (-5.5 . -10) (0 . -6))
>     c8( e b-> f d' a e-> g)
>   }
> 
> Accents make the point that the newly-shaped Slur is integrated into the usual
> collision-avoidance (distinct from other hand-tweaks like rotation and
> extra-offset).

Excellent - thanks!

http://codereview.appspot.com/6561064/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:3996: the ones calculated
automatically, remembering that a translation of
On 2012/09/28 06:45:50, Keith wrote:
> You can probably skip the "remembering that.."
> Discussions of Bezier curves always mention this, but it seems implicit in
> having the curves parametrized by "control points".

Done.

http://codereview.appspot.com/6561064/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:4027: 
On 2012/09/28 21:43:10, david.nalesnik wrote:
> Perhaps at this point it would be helpful to include an example of \shape
> applied to a curve across a line break.  Something like this:
> 
> "The \shape function can also displace the control points of curves which
> stretch across line breaks.  Each piece of the broken curve can receive its
own
> list of offsets.  In case changes to a particular segment are not needed, the
> empty list can serve as a placeholder."
> 
> \relative c'' {
>   % () may be used as a shorthand for ((0 . 0) (0 . 0) (0 . 0) (0 . 0))
>   \shape Slur #'(() ((0.5 . -1.5) (1 . 0.5) (0 . 0.5) (0 . -1.5)))
>   c4( f g c
>   \break
>   d,4 c' f, c)
> }
> 
> \layout {
>   ragged-right = ##t
> }

Done.

[david.nalesnik, 2012-10-07 03:14:31]

Trevor--

This looks great to me.  I like the reordering, and I think the explanations are
very clear.

I've tweaked the curves a little in the examples (do what you like with my
suggestions!), but otherwise:

LGTM.

https://codereview.appspot.com/6561064/diff/6001/Documentation/notation/chang...
File Documentation/notation/changing-defaults.itely (right):

https://codereview.appspot.com/6561064/diff/6001/Documentation/notation/chang...
Documentation/notation/changing-defaults.itely:4014: @end lilypond
The PhrasingSlur looks a little distorted to me here.  What about changing the
example to something like this:

\relative c'' {
  c8(\( a) a'4 e c\)
  \shape #'((0.8 . -0.5) (0.5 . -0.4) (0.3 . -0.3) (0 . -0.2)) Slur
  \shape #'((0 . 0) (0 . 0.5) (0 . 0.5) (0 . 0)) PhrasingSlur
  c8(\( a) a'4 e c\)
}

https://codereview.appspot.com/6561064/diff/6001/Documentation/notation/chang...
Documentation/notation/changing-defaults.itely:4052: @end lilypond
I think the shaped PhrasingSlur should hug the contour of the line a little more
closely here.  I think this still shows collision avoidance working with the
accent marks:

\relative c'' {
  c8( e b-> f d' a e-> g)
  \shape #'((0 . -1) (5.5 . -0.5) (-5.5 . -10.5) (0 . -5.5)) PhrasingSlur
  c8\( e b-> f d' a e-> g\)
}

https://codereview.appspot.com/6561064/diff/6001/Documentation/notation/chang...
Documentation/notation/changing-defaults.itely:4091: @end lilypond
I think that the slurs shouldn't touch the notes in the alternatives.  Maybe the
values here are too fine (whole numbers and 0.5 look nice as input), but see
what you think:

\relative c'' {
  c1
  \repeat volta 3 { c4 d( e f }
  \alternative {
    { g2) d }
    {
    g2
    % create a slur and move it to a new position
    -\tweak #'control-points #'((-2 . 3.7) (-1 . 4) (0 . 4) (1 . 3.4)) ( <> )
    f,
    }
    {
    e'2
    % create a slur and move it to a new position
    -\tweak #'control-points #'((-2 . 2.8) (-1 . 3.2) (0 . 3.2) (1 . 2.4)) ( <>
)
    f,
    }
  }
}

[Trevor Daniels, 2012-10-07 06:58:04]

On 2012/10/07 03:14:31, david.nalesnik wrote:

> This looks great to me.  I like the reordering, and 
> I think the explanations are very clear.
> 
> I've tweaked the curves a little in the examples (do 
> what you like with my suggestions!), 

Thanks.  I've adopted them, but with just a little further
tweaking.  Showing the use of fine tuning is good, I think.

> but otherwise:
> LGTM.

:)

[david.nalesnik, 2012-10-08 02:14:30]

LGTM.

And thanks again for doing this!

-David

[janek, 2012-10-08 04:37:53]

LGTM

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

http://codereview.appspot.com/6561064/diff/10001/Documentation/notation/chang...
Documentation/notation/changing-defaults.itely:3961: control-point.  If
@var{item} is a string, the result is
mention that the unit is staff-spaces (or did i miss the information?)

[Trevor Daniels, 2012-10-08 06:46:59]

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

http://codereview.appspot.com/6561064/diff/10001/Documentation/notation/chang...
Documentation/notation/changing-defaults.itely:3961: control-point.  If
@var{item} is a string, the result is
On 2012/10/08 04:37:54, janek wrote:
> mention that the unit is staff-spaces (or did i miss the information?)

You missed it - it's in the following paragraph.

[Keith, 2012-10-08 07:46:09]

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

http://codereview.appspot.com/6561064/diff/10001/Documentation/notation/chang...
Documentation/notation/changing-defaults.itely:4087: -\tweak #'control-points
#'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
 g2( <>) f   is the same as   g2( f)
so any implication that the <> does something different might mislead.

For a single-note example you might prefer
  \tweak...
  \repeatTie g1

[Trevor Daniels, 2012-10-08 15:21:30]

On 2012/10/08 07:46:09, Keith wrote:
> Documentation/notation/changing-defaults.itely:4087: -\tweak #'control-points
> #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
>  g2( <>) f   is the same as   g2( f)
> so any implication that the <> does something different might mislead.

They are, of course, equivalent, but the slur has no connection
with the second note and I found it more confusing to involve
the second note.  This is the way I would do it, and the way I
would recommend it be done, so I'd rather leave it at it is.
I could add a comment, maybe ... I'll think about that.
 
> For a single-note example you might prefer
>   \tweak...
>   \repeatTie g1

I don't think this is appropriate in a section on Bézier curves,
but it should go into the Known issues section of NR 1.4.1,
together with a ref to here.  I'll add that to this patch-set in
the next upload.

Thanks, Trevor

[Graham Percival, 2012-10-08 20:04:21]

LGTM

https://codereview.appspot.com/6561064/diff/10001/Documentation/notation/chan...
File Documentation/notation/changing-defaults.itely (right):

https://codereview.appspot.com/6561064/diff/10001/Documentation/notation/chan...
Documentation/notation/changing-defaults.itely:3901: @itemize
technically this would be better as an @enumerate a, but this isn't a big deal.

[janek, 2012-10-08 20:09:41]

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

http://codereview.appspot.com/6561064/diff/10001/Documentation/notation/chang...
Documentation/notation/changing-defaults.itely:3961: control-point.  If
@var{item} is a string, the result is
On 2012/10/08 06:46:59, Trevor Daniels wrote:
> On 2012/10/08 04:37:54, janek wrote:
> > mention that the unit is staff-spaces (or did i miss the information?)
> 
> You missed it - it's in the following paragraph.

Indeed, sorry.

[Trevor Daniels, 2012-10-08 21:53:43]

On 2012/10/08 20:04:21, Graham Percival wrote:
> LGTM

Thanks!

> Documentation/notation/changing-defaults.itely:3901: @itemize
> technically this would be better as an @enumerate a, but this isn't a big
deal.

Ah yes, I'd forgotten that.  I'll change it in the next patch set,
since I have to submit one anyway.

Trevor

[pkx166h, 2012-10-09 05:44:52]

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

http://codereview.appspot.com/6561064/diff/17001/Documentation/notation/chang...
Documentation/notation/changing-defaults.itely:3916: @subsubsubheading Cubic
Bézier curves
Are there too many 'subs' here? I only mention it because the headings are bold
_italic_ which really jars on  the eye when it's not used anywhere else (at
least when I make a quick scroll through the resulting pdf). Ditto for the other
headings.

[Trevor Daniels, 2012-10-09 07:29:16]

On 2012/10/09 05:44:52, J_lowe wrote:
> Are there too many 'subs' here?

No.  This is the standard level 5 heading.  See
http://www.lilypond.org/doc/v2.17/Documentation/contributor/sectioning-commands
 
> I only mention it because the headings are bold
> _italic_ which really jars on  the eye when it's 
> not used anywhere else (at
> least when I make a quick scroll through the 
> resulting pdf). Ditto for the other
> headings.

It is used elsewhere, although level 5 headings are
quite rare.  For example, see
http://www.lilypond.org/doc/v2.17/Documentation/notation/beams#setting-automa...
Italics are necessary to distinguish level 5 and level 4
headings.

Trevor

[Trevor Daniels, 2012-10-12 11:00:33]

Pushed to staging as
40a103eeec6999f35ccba10395901904a97fe395
Closing ...