@node Changing defaults
@chapter Changing defaults
-@strong{N.B. This Chapter is under heavy development at present.}
+@strong{N.B. This Chapter is still being developed at present.}
-The purpose of LilyPond's design is to provide the finest output
-quality as a default. Nevertheless, it may happen that you need to
+The purpose of LilyPond's design is to provide the finest quality
+output by default. Nevertheless, it may happen that you need to
change this default layout. The layout is controlled through a large
-number of proverbial @q{knobs and switches.} This chapter does not
-list each and every knob. Rather, it outlines what groups of controls
-are available and explains how to lookup which knob to use for a
-particular effect.
-
+number of @q{knobs and switches} collectively called @q{properties}.
+A tutorial introduction to accessing and modifying these properties
+can be found in the Learning Manual, see @rlearning{Tweaking output}.
+This should be read first. This chapter covers similar ground, but
+in a style more appropriate to a reference manual.
@cindex Internals Reference
-The controls available for tuning are described in a separate
-document, the
-@iftex
-Internals Reference manual.
-@end iftex
-@ifnottex
-@ref{Top,Internals Reference,,lilypond-internals}.
-@end ifnottex
-That manual
-lists all different variables, functions and options available in
-LilyPond. It is written as a HTML document, which is available
+The definitive description of the controls available for tuning can
+be found in a separate document: @rinternalsnamed{Top,the Internals
+Reference}. That manual lists all the variables, functions and
+options available in LilyPond. It is written as a HTML document,
+which is available
@c leave the @uref as one long line.
@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
-but is also included with the LilyPond documentation package.
+and is also included with the LilyPond documentation package.
@c TODO The following is at variance to what actually follows. Fix -td
+@ignore
There are four areas where the default settings may be changed:
@itemize
@code{#}.@footnote{@rlearning{Scheme tutorial}, contains a short tutorial
on entering numbers, lists, strings, and symbols in Scheme.}
+@end ignore
+
@menu
* Interpretation contexts::
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
@node Modifying properties
@section Modifying properties
+@c TODO change the menu and subsection node names to use
+@c backslash once the new macro to handle the refs
+@c is available. Need to find and change all refs at
+@c the same time. -td
+
@menu
* Overview of modifying properties::
-* The \set command::
-* The \override command::
-* \set versus \override::
-* Objects connected to the input::
+* The set command::
+* The override command::
+* The tweak command::
+* set versus override::
@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 The tweak command
+@subsection The @code{\tweak} command
+
+@funindex \tweak
+@cindex tweaking
+
+In some cases, it is possible to take a short-cut for tuning
+graphical objects. For objects that are created directly from
+an item in the input file, you can use the @code{\tweak} command.
+For example:
+
+@lilypond[relative=2,verbatim]
+< c
+ \tweak #'color #red
+ d
+ g
+ \tweak #'duration-log #1
+ a
+> 4
+-\tweak #'padding #8
+-^
+@end lilypond
+
+@cindex chord, modifying one note in
+
+But the main use of the @code{\tweak} command is to modify just
+one of a number of notation elements which start at the same musical
+moment, like the notes of a chord, or tuplet brackets which start
+at the same time.
+
+For an introduction to the syntax and uses of the tweak command
+see @rlearning{Tweaking methods}.
+
+The @code{\tweak} command sets a property in the following object
+directly, without requiring the grob name or context to be
+specified. For this to work, it is necessary for the @code{\tweak}
+command to remain immediately adjacent to the object to which it is
+to apply after the input file has been converted to a music stream.
+This is often not the case, as many additional elements are inserted
+into the music stream implicitly. For example, when a note which is
+not part of a chord is processed, Lilypond implicitly inserts a
+@code{ChordEvent} event before the note, so separating the tweak
+from the note. However, if chord symbols are placed round the
+tweak and the note, the @code{\tweak} command comes after the
+@code{ChordEvent} in the music stream, so remaining adjacent to the
+note, and able to modify it.
+
+So, this works:
+
+@lilypond[relative=2,verbatim,quote]
+<\tweak #'color #red c>4
+@end lilypond
+
+@noindent
+but this does not:
+
+@lilypond[relative=2,verbatim,quote]
+\tweak #'color #red c4
+@end lilypond
+
+When several similar items are placed at the same musical moment,
+the @code{\override} command cannot be used to modify just one of
+them -- this is where the @code{\tweak} command must be used.
+Items which may appear more than once at the same musical moment
+include the following:
+
+@c TODO expand to include any further uses of \tweak
+@itemize
+@item note heads of notes inside a chord
+@item articulation signs on a single note
+@item ties between notes in a chord
+@item tuplet brackets starting at the same time
+@end itemize
+
+@c TODO add examples of these
+
+@noindent
+and @code{\tweak} may be used to modify any single occurrence of
+these items.
+
+Notably the @code{\tweak} command cannot be used to modify stems,
+beams or accidentals, since these are generated later by note heads,
+rather than by music elements in the input stream. Nor can a
+@code{\tweak} command be used to modify clefs or time signatures,
+since these become separated from any preceding @code{\tweak}
+command in the input stream by the automatic insertion of extra
+elements required to specify the context.
+
+But the @code{\tweak} command can be used as an alternative to
+the @code{\override} command to modify those notational elements
+that do not cause any additional implicit elements to be added
+before them in the music stream. For example, slurs may be
+modified in this way:
+
+@lilypond[verbatim,quote,relative=1]
+c-\tweak #'thickness #5 ( d e f)
+@end lilypond
+
+Also several @code{\tweak} commands may be placed before a
+notational element -- all affect it:
+
+@lilypond[verbatim,quote,relative=1]
+c
+-\tweak #'style #'dashed-line
+-\tweak #'dash-fraction #0.2
+-\tweak #'thickness #3
+-\tweak #'color #red
+ \glissando
+f'
+@end lilypond
+
+The music stream which is generated from a section of an input file,
+including any automatically inserted elements, may be examined,
+see @ref{Displaying music expressions}. This may be helpful in
+determining what may be modified by a @code{\tweak} command.
+
+@seealso
+
+Learning Manual:
+@rlearning{Tweaking methods}.
+
+Notation Reference:
+@ref{Displaying music expressions}.
+
+@knownissues
+
+@cindex tweaks in a variable
+The @code{\tweak} command cannot be used inside a variable.
+
+@cindex tweaks in lyrics
+The @code{\tweak} commands cannot be used in @code{\lyricmode}.
+
+@cindex tweaking control points
+@cindex control points, tweaking
+
+The @code{\tweak} command cannot be used to modify the control
+points of just one of several ties in a chord, other than the first
+one encountered in the input file.
+
+@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
-
-TODO: can't use \tweak in a variable
-
-@funindex \tweak
-
-In some cases, it is possible to take a short-cut for tuning graphical
-objects. For objects that result directly from a piece of the input,
-you can use the @code{\tweak} function, for example
-
-@lilypond[relative=2,fragment,verbatim,ragged-right]
-<
- c
- \tweak #'color #red d
- g
- \tweak #'duration-log #1 a
->4-\tweak #'padding #10 -.
-@end lilypond
-
-As you can see, properties are set in the objects directly,
-without mentioning the grob name or context where this should be
-applied.
-
-This technique only works for objects that are directly connected to
-an @rinternals{Event} from the input, for example
-
-@itemize
-@item note heads, caused by chord-pitch (i.e., notes inside a chord)
-@item articulation signs, caused by articulation instructions
-@end itemize
-
-It notably does not work for stems and accidentals (these are caused
-by note heads, not by music events) or clefs (these are not caused by
-music inputs, but rather by the change of a property value).
-
-There are very few objects which are @emph{directly} connected to
-output. A normal note (like @code{c4}) is not directly connected
-to output, so
-
-@example
-\tweak #'color #red c4
-@end example
-
-@noindent
-does not change color. See @ref{Displaying music expressions}, for
-details.
-
-
@node Useful concepts and properties
@section Useful concepts and properties
@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
@node 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
any angle about any point, but the method of doing so differs.
@menu
-* Rotating layout objects::
-* Rotating markup::
+* Rotating layout objects::
+* Rotating markup::
@end menu
@node Rotating layout objects
@node Aligning objects
@subsection Aligning objects
-@c FIXME Write this section
+Graphical objects which support the @code{self-alignment-interface} and/or
+the @code{side-position-interface} can be
+aligned to a previously placed object in a variety of ways. For a list of these objects, see
+@rinternals{self-alignment-interface} and @rinternals{side-position-interface}.
+
+All graphical objects have a reference point, a horizontal extent and a
+vertical extent. The horizontal extent is a pair of numbers
+giving the displacements from the reference point of the left and
+right edges, displacements to the left being negative. The
+vertical extent is a pair of numbers giving the displacement from
+the reference point to the bottom and top edges, displacements down
+being negative.
+
+An object's position on a staff is given by the values of the
+@code{X-offset} and @code{Y-offset} properties. The value of
+@code{X-offset} gives the displacement from the x coordinate of
+the reference point of the parent object, and the value of
+@code{Y-offset} gives the displacement from the center line of the
+staff. The values of @code{X-offset} and
+@code{Y-offset} may be set directly or may be set to be calculated
+by procedures in order to achieve alignment with the parent object
+in several ways.
+
+@warning{Many objects have special positioning considerations which
+cause any setting of @code{X-offset} or @code{Y-offset} to be
+ignored or modified, even though the object supports the
+@code{self-alignment-interface}.}
+
+For example, an accidental can be repositioned
+vertically by setting @code{Y-offset} but any changes to
+@code{X-offset} have no effect.
+
+Rehearsal marks may be aligned with
+breakable objects such as bar lines, clef symbols, time signature
+symbols and key signatures. There are special properties to be
+found in the @code{break-aligned-interface} for positioning rehearsal
+marks on such objects.
+
+@menu
+* Setting @code{X-offset} and @code{Y-offset} directly::
+* Using the @code{side-position-interface}::
+* Using the @code{self-alignment-interface}::
+* Using the @code{break-aligned-interface}::
+@end menu
+
+@node Setting @code{X-offset} and @code{Y-offset} directly
+@unnumberedsubsubsec Setting @code{X-offset} and @code{Y-offset} directly
+
+Numerical values may be given to the @code{X-offset} and @code{Y-offset}
+properties of many objects. The following example shows three
+notes with the default fingering position and the positions with @code{X-offset}
+and @code{Y-offset} modified.
+
+@lilypond[verbatim,quote,relative=2]
+a-3
+a
+-\tweak #'X-offset #0
+-\tweak #'Y-offset #0
+-3
+a
+-\tweak #'X-offset #-1
+-\tweak #'Y-offset #1
+-3
+@end lilypond
+
+@c TODO write more
+
+@node Using the @code{side-position-interface}
+@unnumberedsubsubsec Using the @code{side-position-interface}
+
+An object which supports the @code{side-position-interface} can be
+placed next to its parent object so that
+the specified edges of the two objects touch. The object may be
+placed above, below, to the right or to the left of the parent.
+The parent cannot be specified; it is determined by the order of
+elements in the input stream. Most objects have the associated
+note head as their parent.
+
+The values of the @code{side-axis} and @code{direction} properties
+determine where the object is to be placed, as follows:
+@c TODO add an example of each to the table
+
+@multitable @columnfractions .3 .3 .3
+@headitem @code{side-axis} @tab @code{direction} @tab
+@headitem property @tab property @tab Placement
+
+@item @code{0} @tab @code{-1} @tab left
+@item @code{0} @tab @code{1} @tab right
+@item @code{1} @tab @code{-1} @tab below
+@item @code{1} @tab @code{1} @tab above
+
+@end multitable
+
+When @code{side-axis} is @code{0}, @code{X-offset} should be set to
+the procedure @code{ly:side-position-interface::x-aligned-side}.
+This procedure will return the correct value of @code{X-offset} to
+place the object to the left or right side of the parent according
+to value of @code{direction}.
+
+When @code{side-axis} is @code{1}, @code{Y-offset} should be set to
+the procedure @code{ly:side-position-interface::y-aligned-side}.
+This procedure will return the correct value of @code{Y-offset} to
+place the object to the top or bottom of the parent according
+to value of @code{direction}.
+
+@c TODO Add examples
+
+@node Using the @code{self-alignment-interface}
+@unnumberedsubsubsec Using the @code{self-alignment-interface}
+
+@emph{Self-aligning objects horizontally}
+
+The horizontal alignment of an object which supports the
+@code{self-alignment-interface} is controlled by the value of
+the @code{self-alignment-X} property, provided the object's
+@code{X-offset} property is set to
+@code{ly:self-alignment-interface::x-aligned-on-self}.
+@code{self-alignment-X} may be given any
+real value, in units of half the total X extent of the
+object. Negative values move the object to the right, positive
+to the left. A value of @code{0} centers the object on the
+reference point of its parent, a value of @code{-1} aligns the
+left edge of the object on the reference point of its parent,
+and a value of @code{1} aligns the right edge of the object on the
+reference point of its parent. The symbols @code{LEFT},
+@code{CENTER} and @code{RIGHT} may be used instead of the values
+@code{-1, 0, 1} respectively.
+
+Normally the @code{\override} command would be used to modify the
+value of @code{self-alignment-X}, but the @code{\tweak} command
+can be used to separately align several annotations on a single
+note:
+
+@lilypond[quote,verbatim,relative=1]
+a'
+-\tweak #'self-alignment-X #-1
+^"left-aligned"
+-\tweak #'self-alignment-X #0
+^"center-aligned"
+-\tweak #'self-alignment-X #RIGHT
+^"right-aligned"
+-\tweak #'self-alignment-X #-2.5
+^"aligned further to the right"
+@end lilypond
+
+@emph{Self-aligning objects vertically}
+
+Objects may be aligned vertically in an analogous way to aligning
+them horizontally if the @code{Y-offset} property is set to
+@code{ly:self-alignment-interface::y-aligned-on-self}. However,
+other mechanisms are often involved in vertical alignment: the
+value of @code{Y-offset} is just one variable taken into account.
+This may make adjusting the value of some objects tricky.
+The units are just half the vertical extent of the object, which
+is usually quite small, so quite large numbers may be required.
+A value of @code{-1} aligns the lower edge of the object with
+the reference point of the parent object, a value of @code{0}
+aligns the center of the object with the reference point of the
+parent, and a value of @code{1} aligns the top edge of the object
+with the reference point of the parent. The symbols @code{DOWN},
+@code{CENTER}, @code{UP} may be substituted for @code{-1, 0, 1}
+respectively.
+
+@emph{Self-aligning objects in both directions}
+
+By setting both @code{X-offset} and @code{Y-offset}, an object may
+be aligned in both directions simultaneously.
+
+The following example shows how to adjust a fingering mark so
+that it nestles close to the note head.
+
+@lilypond[quote,verbatim,relative=2]
+a
+-\tweak #'self-alignment-X #0.5 % move horizontally left
+-\tweak #'Y-offset #ly:self-alignment-interface::y-aligned-on-self
+-\tweak #'self-alignment-Y #-1 % move vertically up
+-3 % third finger
+@end lilypond
+
+@ignore
+@unnumberedsubsubsec Using the @code{aligned-on-parent} procedures
+
+@c Cannot document as they do not seem to operate consistently on all objects -td
+@c TODO investigate further
+
+The @code{aligned-on-parent} procedures are used in the same way
+as the @code{aligned-on-self} procedures, they difference being
+that they permit an object to be aligned with the @emph{edges} of
+the parent rather than the parent's reference point. The following
+example shows the difference:
+
+@c TODO Add example
+
+@lilypond[verbatim,quote]
+@end lilypond
+
+@end ignore
+
+@ignore
+@unnumberedsubsubsec Using the @code{centered-on-parent} procedures
+
+@c Cannot document as they do not seem to operate consistently on all objects -td
+@c TODO investigate further
+
+@end ignore
+
+@c TODO The align-interface, BassFigureAlignment and VerticalAlignment
+
+@node Using the @code{break-aligned-interface}
+@unnumberedsubsubsec Using the @code{break-aligned-interface}
+
+Rehearsal marks may be aligned with notation objects other
+than bar lines. These objects include @code{ambitus},
+@code{breathing-sign}, @code{clef}, @code{custos}, @code{staff-bar},
+@code{left-edge}, @code{key-cancellation}, @code{key-signature}, and
+@code{time-signature}.
+
+By default, rehearsal marks will be horizontally centered above the
+object:
+
+@lilypond[verbatim,quote,relative=1]
+e1
+% the RehearsalMark will be centered above the Clef
+\override Score.RehearsalMark #'break-align-symbols = #'(clef)
+\key a \major
+\clef treble
+\mark "↓"
+e
+% the RehearsalMark will be centered above the TimeSignature
+\override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
+\key a \major
+\clef treble
+\time 3/4
+\mark "↓"
+e2.
+@end lilypond
+
+The alignment of the rehearsal mark relative to the notation object
+can be changed, as shown in the following example. In a score with
+multiple staves, this setting should be done for all the staves.
+
+@lilypond[verbatim,quote,relative=1]
+% The RehearsalMark will be centered above the KeySignature
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
+\key a \major
+\clef treble
+\time 4/4
+\mark "↓"
+e1
+% The RehearsalMark will be aligned with the left edge of the KeySignature
+\once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
+\mark "↓"
+\key a \major
+e
+% The RehearsalMark will be aligned with the right edge of the KeySignature
+\once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
+\key a \major
+\mark "↓"
+e
+@end lilypond
+
+The rehearsal mark can also be offset to the right or left of the left edge
+by an arbitrary amount. The units are staff-spaces:
+
+@lilypond[verbatim,quote,relative=1]
+% The RehearsalMark will be aligned with the left edge of the KeySignature
+% and then shifted right by 3.5 staff-spaces
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
+\once \override Score.KeySignature #'break-align-anchor = #3.5
+\key a \major
+\mark "↓"
+e
+% The RehearsalMark will be aligned with the left edge of the KeySignature
+% and then shifted left by 2 staff-spaces
+\once \override Score.KeySignature #'break-align-anchor = #-2
+\key a \major
+\mark "↓"
+e
+@end lilypond
@node Advanced tweaks
@section Advanced tweaks
@section Discussion of specific tweaks
@menu
-* old Contexts explained::
+* old Contexts explained::
@end menu
projects / lilypond.git / blobdiff