@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
but is also included with the LilyPond documentation package.
+@c TODO The following is at variance to what actually follows. Fix -td
+
There are four areas where the default settings may be changed:
@itemize
@menu
-* Interpretation contexts::
-* Explaining the Internals Reference::
-* Modifying properties::
-* Useful concepts and properties::
-* Common properties::
-* Advanced tweaks::
-* Discussion of specific tweaks::
+* Interpretation contexts::
+* Explaining the Internals Reference::
+* Modifying properties::
+* Useful concepts and properties::
+* Common properties::
+* Advanced tweaks::
+* Discussion of specific tweaks::
@end menu
This section describes what contexts are, and how to modify them.
@menu
-* Contexts explained::
-* Creating contexts::
-* Modifying context plug-ins::
-* Changing context default settings::
-* Defining new contexts::
-* Aligning contexts::
+* Contexts explained::
+* Creating contexts::
+* Modifying context plug-ins::
+* Changing context default settings::
+* Defining new contexts::
+* Aligning contexts::
@end menu
Contexts are arranged heirarchically:
@menu
-* Score - the master of all contexts::
-* Top-level contexts - staff containers::
-* Intermediate-level contexts - staves::
-* Bottom-level contexts - voices::
+* Score - the master of all contexts::
+* Top-level contexts - staff containers::
+* Intermediate-level contexts - staves::
+* Bottom-level contexts - voices::
@end menu
@node Score - the master of all contexts
@subsection Changing context default settings
The adjustments of the previous subsections (
-@ref{The \set command}, @ref{Modifying context plug-ins}, and
+@ref{The set command}, @ref{Modifying context plug-ins}, and
@ref{Overview of modifying properties}) can also be entered
separately from the music in the @code{\layout} block,
All these plug-ins have to cooperate, and this is achieved with a
special plug-in, which must be marked with the keyword @code{\type}.
-This should always be @rinternals{Engraver_group},
+This should always be @code{Engraver_group}.
@example
\type "Engraver_group"
@menu
-* Navigating the program reference::
-* Layout interfaces::
-* Determining the grob property::
-* Naming conventions::
+* Navigating the program reference::
+* Layout interfaces::
+* Determining the grob property::
+* Naming conventions::
@end menu
@node Navigating the program reference
@c outdated info; probably will delete.
@ignore
This fragment points to two parts of the program reference: a page
-on @code{FingerEvent} and one on @code{Fingering}.
+on @code{FingeringEvent} and one on @code{Fingering}.
-The page on @code{FingerEvent} describes the properties of the music
+The page on @code{FingeringEvent} describes the properties of the music
expression for the input @code{-2}. The page contains many links
forward. For example, it says
This engraver creates the following layout objects: @rinternals{Fingering}.
@end quotation
-In other words, once the @code{FingerEvent}s are interpreted, the
+In other words, once the @code{FingeringEvent}s are interpreted, the
@code{Fingering_engraver} plug-in will process them.
@end ignore
@item @rinternals{fingering-event}:
Music event type @code{fingering-event} is in Music expressions named
-@rinternals{FingerEvent}
+@rinternals{FingeringEvent}
@end itemize
This path goes against the flow of information in the program: it
@section Modifying properties
@menu
-* Overview of modifying properties::
-* The \set command::
-* The \override command::
-* \set versus \override::
-* Objects connected to the input::
+* Overview of modifying properties::
+* The set command::
+* The override command::
+* set versus override::
+* The tweak command::
@end menu
-@node The \set command
+@node The set command
@subsection The @code{\set} command
@cindex properties
-@node The \override command
+@node The override command
@subsection The @code{\override} command
Commands which change output generally look like
and the program reference.
-@node \set versus \override
+@node set versus override
@subsection @code{\set} vs. @code{\override}
We have seen two methods of changing properties: @code{\set} and
property (modified with @code{\set}) was created.
-@node Objects connected to the input
-@subsection Objects connected to the input
+@node The tweak command
+@subsection The @code{\tweak} command
TODO: can't use \tweak in a variable
@menu
-* Input modes::
-* Direction and placement::
-* Distances and measurements::
-* Spanners::
+* Input modes::
+* Direction and placement::
+* Distances and measurements::
+* Spanners::
@end menu
@node Input modes
@section Common properties
@menu
-* Controlling visibility of objects::
-* Line styles::
-* Rotating objects::
-* Aligning objects::
+* Controlling visibility of objects::
+* Line styles::
+* Rotating objects::
+* Aligning objects::
@end menu
-@c TODO Add new subsection Shapes of objects
-@c which would include Slur shapes
-@c with a Known issue: can't modify shapes with 'control-points if there are
-@c more than one at the same musical moment
-
@node Controlling visibility of objects
@subsection Controlling visibility of objects
considerations.
@menu
-* Removing the stencil::
-* Making objects transparent::
-* Painting objects white::
-* Using break-visibility::
-* Special considerations::
+* Removing the stencil::
+* Making objects transparent::
+* Painting objects white::
+* Using break-visibility::
+* Special considerations::
@end menu
@node Using break-visibility
@unnumberedsubsubsec Using break-visibility
+@c TODO Add making other objects breakable
+
@cindex break-visibility
Most layout objects are printed only once, but some like
at the end of the previous line as well.
This behaviour is controlled by the @code{break-visibility}
-property, which is explained in @rlearning{Visibility and color of
-objects}. This property takes a vector of three booleans which,
-in order, determine whether the object is printed at the end of,
-within the body of, or at the beginning of a line. Or to be more
-precise, before a line break, where there is no line break, or
-after a line break.
+property, which is explained in
+@c Leave this ref on a newline - formats incorrectly otherwise -td
+@rlearning{Visibility and color of objects}. This property takes
+a vector of three booleans which, in order, determine whether the
+object is printed at the end of, within the body of, or at the
+beginning of a line. Or to be more precise, before a line break,
+where there is no line break, or after a line break.
Alternatively, seven of the eight combinations may be specified
by pre-defined functions, defined in @file{scm/output-lib.scm},
where the last three columns indicate whether the layout objects
will be visible in the positions shown at the head of the columns:
-@multitable @columnfractions .40 .15 .15 .15 .15
+@multitable @columnfractions .40 .15 .1 .1 .1
@c TODO check these more carefully
@headitem Function @tab Vector @tab Before @tab At no @tab After
@headitem form @tab form @tab break @tab break @tab break
@node Rotating objects
@subsection Rotating objects
-@c FIXME Write this section
+Both layout objects and elements of markup text can be rotated by
+any angle about any point, but the method of doing so differs.
+
+@menu
+* Rotating layout objects::
+* Rotating markup::
+@end menu
+
+@node Rotating layout objects
+@unnumberedsubsubsec Rotating layout objects
+
+@cindex rotating objects
+@cindex objects, rotating
+
+All layout objects which support the @code{grob-interface} can be
+rotated by setting their @code{rotation} property. This takes a
+list of three items: the angle of rotation counter-clockwise,
+and the x and y coordinates of the point relative to the object's
+reference point about which the rotation is to be performed. The
+angle of rotation is specified in degrees and the coordinates in
+staff-spaces.
+
+The angle of rotation and the coordinates of the rotation point must
+be determined by trial and error.
+
+@cindex hairpins, angled
+@cindex angled hairpins
+
+There are only a few situations where the rotation of layout
+objects is useful; the following example shows one situation where
+they may be:
+
+@lilypond[quote,verbatim,relative=1]
+g4\< e' d' f\!
+\override Hairpin #'rotation = #'(20 -1 0)
+g,,4\< e' d' f\!
+@end lilypond
+
+@node Rotating markup
+@unnumberedsubsubsec Rotating markup
+
+All markup text can be rotated to lie at any angle by prefixing it
+with the @code{\rotate} command. The command takes two arguments:
+the angle of rotation in degrees counter-clockwise and the text to
+be rotated. The extents of the text are not rotated: they take
+their values from the extremes of the x and y coordinates of the
+rotated text. In the following example the
+@code{outside-staff-priority} property for text is set to @code{#f}
+to disable the automatic collision avoidance, which would push some
+of the text too high.
+
+@lilypond[quote,verbatim,relative=1]
+\override TextScript #'outside-staff-priority = ##f
+g4^\markup { \rotate #30 "a G" }
+b^\markup { \rotate #30 "a B" }
+des^\markup { \rotate #30 "a D-Flat" }
+fis^\markup { \rotate #30 "an F-Sharp" }
+@end lilypond
+
@node Aligning objects
@subsection Aligning objects
@section Advanced tweaks
@menu
-* Vertical grouping of grobs::
-* Modifying ends of spanners::
-* Modifying stencils::
-* Modifying shapes::
+* Vertical grouping of grobs::
+* Modifying ends of spanners::
+* Modifying stencils::
+* Modifying shapes::
@end menu
@subsection Modifying ends of spanners
@c FIXME Write this section
+@c See earlier material in Line styles
@node Modifying stencils
@subsection Modifying stencils
-@c FIXME Write this section
+All layout objects have a @code{stencil} property which is part of
+the @code{grob-interface}. By default, this property is usually
+set to a function specific to the object that is tailor-made to
+render the symbol which represents it in the output. For example,
+the standard setting for the @code{stencil} property of the
+@code{MultiMeasureRest} object is @code{ly:multi-measure-rest::print}.
+
+The standard symbol for any object can be replaced by modifying the
+@code{stencil} property to reference a different, specially-written,
+procedure. This requires a high level of knowledge of the internal
+workings of LilyPond, but there is an easier way which can often
+produce adequate results.
+
+This is to set the @code{stencil} property to the procedure which
+prints text -- @code{ly:text-interface::print} -- and to add a
+@code{text} property to the object which is set to contain the
+markup text which produces the required symbol. Due to the
+flexibility of markup, much can be achieved -- see in particular
+@ref{Graphic notation inside markup}.
+
+The following example demonstrates this by changing the note head
+symbol to a cross within a circle.
+
+@lilypond[verbatim,quote]
+XinO = {
+ \once \override NoteHead #'stencil = #ly:text-interface::print
+ \once \override NoteHead #'text = \markup {
+ \combine
+ \halign #-0.7 \draw-circle #0.85 #0.2 ##f
+ \musicglyph #"noteheads.s2cross"
+ }
+}
+\relative c'' {
+ a a \XinO a a
+}
+@end lilypond
+
+Any of the glyphs in the feta Font can be supplied to the
+@code{\musicglyph} markup command -- see @ref{The Feta font}.
+
+@c TODO Add inserting eps files or ref to later
+
+@c TODO Add inserting Postscript or ref to later
+
+@seealso
+
+Notation Reference:
+@ref{Graphic notation inside markup},
+@ref{Formatting text},
+@ref{Text markup commands},
+@ref{The Feta font}.
+
@node Modifying shapes
@subsection Modifying shapes
-@c FIXME Write this section
-@c Discussion of Bezier curves and the control-points property
+@menu
+* Modifying ties and slurs::
+@end menu
+
+@node Modifying ties and slurs
+@unnumberedsubsubsec Modifying ties and slurs
+
+Ties, slurs and phrasing slurs are 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.
+
+Third-order or cubic Bézier curves are defined by four control
+points. The first and fourth control points are precisely the
+starting and ending points of the curve. The intermediate two
+control points define the shape. Animations showing how the curve
+is drawn can be found on the web, but the following description
+may be helpful. The curve starts from the first control point
+heading directly towards the second, gradually bending over to
+head towards the third and continuing to bend over to head towards
+the fourth, arriving there travelling directly from the third
+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.
+
+@lilypond[verbatim,quote,relative=1]
+<<
+ { e1 ~ e }
+\\
+ { r4 <g c,> <g c,> <g c,> }
+>>
+@end lilypond
+
+One way of improving this tie is to manually modify its control
+points, as follows.
+
+The coordinates of the Bézier control points are specified in units
+of staff-spaces. The X@tie{}coordinate is relative to the reference
+point of the note to which the tie or slur is attached, and the
+Y@tie{}coordinate is relative to the staff center line. The
+coordinates are entered as a list of four pairs of decimal numbers
+(reals). One approach is to estimate the coordinates of the two
+end points, and then guess the two intermediate points. The optimum
+values are then found by trial and error.
+
+It is useful to remember that a symmetric curve requires symmetric
+control points, and that Bézier curves have the useful property that
+transformations of the curve such as translation, rotation and
+scaling can be achieved by applying the same transformation to the
+curve's control points.
+
+For the example above the following override gives a satisfactory
+tie:
+
+@lilypond[verbatim,quote,relative=1]
+<<
+ \once \override Tie
+ #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
+ { e1 ~ e1 }
+\\
+ { r4 <g c,> <g c,> <g c,>4 }
+>>
+@end lilypond
+
+@knownissues
+
+It is not possible to modify shapes of ties or slurs by changing
+the @code{control-points} property if there are more than one at
+the same musical moment, not even by using the @code{\tweak}
+command.
+
+
@node Discussion of specific tweaks
@section Discussion of specific tweaks
@menu
-* old Contexts explained::
+* old Contexts explained::
@end menu
projects / lilypond.git / blobdiff