Re: Doc: improve documentation of Bézier curves (28 58) (issue 6561064)

[tdanielsmusic]

Reviewers: Keith, david.nalesnik,

Message:
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-defaults.itely
File Documentation/notation/changing-defaults.itely (right):

http://codereview.appspot.com/6561064/diff/1/Documentation/notation/changing-defaults.itely#newcode3953
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-defaults.itely#newcode3977
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-defaults.itely#newcode3988
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-defaults.itely#newcode3996
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-defaults.itely#newcode4027
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.

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

 - add \shape function
 - show example of cubic-shaped slur

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

Affected files:
  M Documentation/notation/changing-defaults.itely


Index: Documentation/notation/changing-defaults.itely
diff --git a/Documentation/notation/changing-defaults.itely  
b/Documentation/notation/changing-defaults.itely
index  
26672bd791094b7e26d86e9c99124ae8716b473b..7b35497e99ce7569307ef73d271bf76cf36bd38a  
100644
--- a/Documentation/notation/changing-defaults.itely
+++ b/Documentation/notation/changing-defaults.itely
@@ -3892,11 +3892,27 @@ Notation Reference:
 @cindex Bézier curves, control points
 @cindex control points, Bézier curves

-Ties, slurs and phrasing slurs are drawn as third-order Bézier
address@hidden, @code{Slur}s, @code{PhrasingSlur}s, @code{LaissezVibrerTie}s  
and @code{RepeatTie}s are all drawn as third-order Bézier
 curves.  If the shape of the tie or slur which is calculated
 automatically is not optimum, the shape may be modified manually by
-explicitly specifying the four control points required to define
-a third-order Bézier curve.
+either
+
address@hidden
address@hidden
+a) explicitly specifying the four control points required to define
+a third-order Bézier curve, or
+
address@hidden
+b) specifying the displacements to be made to the control points of
+the automatically calculated Bézier curve.
address@hidden itemize
+
+Both methods are explained below.  The second method is more suitable
+if only slight adjustments to the curve are required; the first is
+better for creating curves which are quite different from the one
+which would be calculated automatically.
+
address@hidden Cubic Bézier curves

 Third-order or cubic Bézier curves are defined by four control
 points.  The first and fourth control points are precisely the
@@ -3911,7 +3927,8 @@ control point.  The curve is entirely contained in the
 quadrilateral defined by the four control points.

 Here is an example of a case where the tie is not optimum, and
-where @code{\tieDown} would not help.
+where @code{\tieDown} would not help.  Changing the control points
+of the tie is necessary.

 @lilypond[verbatim,quote,relative=1]
 <<
@@ -3921,7 +3938,9 @@ where @code{\tieDown} would not help.
 >>
 @end lilypond

-One way of improving this tie is to manually modify its control
address@hidden Specifying control points explicitly
+
+One way of improving this tie is to manually specify its control
 points, as follows.

 The coordinates of the Bézier control points are specified in units
@@ -3955,6 +3974,57 @@ to which the start of the tie (or slur) is attached.
 >>
 @end lilypond

+If cubic-shaped curve is required the control points must be set
+manually --- LilyPond will not select such shapes automatically.
+
address@hidden,quote,relative=1]
+<<
+  {
+    \once \override Slur
+      #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . -0.6) (14.5 . 1))
+     e1( e')
+  }
+\\
+  { c4 e, f' d }
+>>
address@hidden lilypond
+
address@hidden Specifying displacements from current control points
+
+Rather than finding the absolute control points by trial and error
+it is often easier to specify how much they should be displaced from
+the ones calculated automatically, remembering that a translation of
+all the control points results in exactly the same translation of the
+curve.  The @code{\shape} function is available for doing this.
+Using the same example as above, this raises the slur by half a staff
+space:
+
address@hidden,quote,relative=1]
+<<
+  {
+    \shape Tie #'((0 . 0.5) (0 . 0.5) (0 . 0.5) (0 . 0.5))
+    e1~ e
+  }
+\\
+  { r4 <g c,> <g c,> <g c,> }
+>>
address@hidden lilypond
+
+This is better, but maybe it should be raised more in the center:
+
address@hidden,quote,relative=1]
+<<
+  {
+    \shape Tie #'((0 . 0.5) (0 . 1) (0 . 1) (0 . 0.5))
+    e1~ e
+  }
+\\
+  { r4 <g c,> <g c,> <g c,> }
+>>
address@hidden lilypond
+
+Changes to the horizontal positions may be made in the same way.
+
 @knownissues
 It is not possible to modify shapes of ties or slurs by changing
 the @code{control-points} property if there are multiple ties or slurs