X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fchanging-defaults.itely;h=1e78fe338395e74f986be73876599f4db5698d25;hb=5b2bdf8c532aa1b4aa8626f6847938f2ef4ba1be;hp=719e0fb89858001f83577a77649676040c8846f2;hpb=091e3f8f91e1eff1e81f25896ca3736be5560149;p=lilypond.git diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely index 719e0fb898..1e78fe3383 100644 --- a/Documentation/user/changing-defaults.itely +++ b/Documentation/user/changing-defaults.itely @@ -7,62 +7,30 @@ version that you are working on. See TRANSLATION for details. @end ignore -@c \version "2.11.55" +@c \version "2.12.0" @node Changing defaults @chapter Changing defaults -@strong{N.B. This Chapter is under heavy development 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. - -@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 -@item -Automatic notation: changing the automatic creation of notation -elements. For example, changing the beaming rules. - -@item -Output: changing the appearance of individual -objects. For example, changing stem directions or the location of -subscripts. - -@item -Context: changing aspects of the translation from music events to -notation. For example, giving each staff a separate time signature. - -@item -Page layout: changing the appearance of the spacing, line -breaks, and page dimensions. These modifications are discussed -@c in @ref{notation}, and @ref{Spacing issues}. -@end itemize +and is also included with the LilyPond documentation package. Internally, LilyPond uses Scheme (a LISP dialect) to provide infrastructure. Overriding layout decisions in effect accesses the @@ -77,9 +45,7 @@ on entering numbers, lists, strings, and symbols in Scheme.} * Explaining the Internals Reference:: * Modifying properties:: * Useful concepts and properties:: -* Common properties:: * Advanced tweaks:: -* Discussion of specific tweaks:: @end menu @@ -98,6 +64,22 @@ This section describes what contexts are, and how to modify them. @end menu +@seealso +Learning Manual: +@rlearning{Contexts and engravers}. + +Installed files: +@file{ly/@/engraver@/-init@/.ly}, +@file{ly/@/performer@/-init@/.ly}. + +Snippets: +@rlsr{Contexts and engravers}. + +Internals Reference: +@rinternals{Contexts}, +@rinternals{Engravers and Performers}. + + @node Contexts explained @subsection Contexts explained @@ -124,7 +106,9 @@ further explanation and with links to the IR. @c TODO Add introduction which explains contexts in generality -td -Contexts are arranged heirarchically: +@c TODO Describe propagation of property values -td + +Contexts are arranged hierarchically: @menu * Score - the master of all contexts:: @@ -154,65 +138,55 @@ executed. Groups staves while adding a bracket on the left side, grouping the staves together. The bar lines of the contained staves are -connected vertically. StaffGroup only consists of a collection +connected vertically. @code{StaffGroup} only consists of a collection of staves, with a bracket in front and spanning bar lines. @strong{@emph{ChoirStaff}} -Identical to StaffGroup except that the bar lines of the contained -staves are not connected vertically. +Identical to @code{StaffGroup} except that the bar lines of the +contained staves are not connected vertically. @strong{@emph{GrandStaff}} -A group of staves, with a brace on the left side, grouping -the staves together. The bar lines of the contained staves are +A group of staves, with a brace on the left side, grouping the +staves together. The bar lines of the contained staves are connected vertically. @strong{@emph{PianoStaff}} -TODO No longer correct? Check. -td - -Just like GrandStaff but with a forced distance between the -staves, so cross staff beaming and slurring can be used. - -@strong{@emph{InnerStaffGroup}} - -TODO -td - -@strong{@emph{InnerChoirStaff}} - -TODO -td +Just like @code{GrandStaff}, but with support for instrument names +to the left of each system. @node Intermediate-level contexts - staves @unnumberedsubsubsec Intermediate-level contexts - staves @strong{@emph{Staff}} -Handles clefs, bar lines, keys, accidentals. It can contain -Voice contexts. +Handles clefs, bar lines, keys, accidentals. It can contain +@code{Voice} contexts. @strong{@emph{RhythmicStaff}} -Like Staff but for printing rhythms. Pitches are ignored; +Like @code{Staff} but for printing rhythms. Pitches are ignored; the notes are printed on one line. @strong{@emph{TabStaff}} -Context for generating tablature. By default lays the music +Context for generating tablature. By default lays the music expression out as a guitar tablature, printed on six lines. @strong{@emph{DrumStaff}} -Handles typesetting for percussion. Can contain DrumVoice +Handles typesetting for percussion. Can contain @code{DrumVoice} @strong{@emph{VaticanaStaff}} -Same as Staff, except that it is designed for typesetting +Same as @code{Staff}, except that it is designed for typesetting a piece in gregorian style. @strong{@emph{MensuralStaff}} -Same as Staff, except that it is designed for typesetting +Same as @code{Staff}, except that it is designed for typesetting a piece in mensural style. @node Bottom-level contexts - voices @@ -224,24 +198,24 @@ contain other contexts. @strong{@emph{Voice}} -Corresponds to a voice on a staff. This context handles the +Corresponds to a voice on a staff. This context handles the conversion of dynamic signs, stems, beams, super- and sub-scripts, slurs, ties, and rests. You have to instantiate this explicitly if you require multiple voices on the same staff. @strong{@emph{VaticanaVoice}} -Same as Voice, except that it is designed for typesetting a piece -in gregorian style. +Same as @code{Voice}, except that it is designed for typesetting +a piece in gregorian style. @strong{@emph{MensuralVoice}} -Same as Voice, with modifications for typesetting a piece in +Same as @code{Voice}, with modifications for typesetting a piece in mensural style. @strong{@emph{Lyrics}} -Corresponds to a voice with lyrics. Handles the printing of a +Corresponds to a voice with lyrics. Handles the printing of a single line of lyrics. @strong{@emph{DrumVoice}} @@ -250,20 +224,19 @@ The voice context used in a percussion staff. @strong{@emph{FiguredBass}} -The context in which BassFigure objects are created from +The context in which @code{BassFigure} objects are created from input entered in @code{\figuremode} mode. @strong{@emph{TabVoice}} -The voice context used within a TabStaff context. Usually left to -be created implicitly. +The voice context used within a @code{TabStaff} context. Usually +left to be created implicitly. @strong{@emph{ChordNames}} Typesets chord names. ------------------------------- - +@ignore TODO Then the following, which I don't know what to do with: @@ -286,6 +259,7 @@ documented. Silently discards all musical information given to this context. +@end ignore @node Creating contexts @subsection Creating contexts @@ -535,55 +509,57 @@ time signature. >> @end lilypond +@knownissues -@node Changing context default settings -@subsection Changing context default settings - -The adjustments of the previous subsections ( -@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, - -@example -\layout @{ - @dots{} - \context @{ - \Staff - - \set fontSize = #-2 - \override Stem #'thickness = #4.0 - \remove "Time_signature_engraver" - @} -@} -@end example +Usually the order in which the engravers are specified +does not matter, but in a few special cases the order +is important, for example where one engraver writes +a property and another reads it, or where one engraver +creates a grob and another must process it. The order in +which the engravers are specified is the order in which +they are called to carry out their processing. -The @code{\Staff} command brings in the existing definition of the -staff context so that it can be modified. +The following orderings are important: the +@code{Bar_engraver} must normally be first, and +the @code{New_fingering_engraver} must come before +the @code{Script_column_engraver}. There may be others +with ordering dependencies. -The statements -@example -\set fontSize = #-2 -\override Stem #'thickness = #4.0 -\remove "Time_signature_engraver" -@end example - -@noindent -affect all staves in the score. Other contexts can be modified -analogously. +@node Changing context default settings +@subsection Changing context default settings -The @code{\set} keyword is optional within the @code{\layout} block, so +The context settings which are to be used by default in +@code{Score}, @code{Staff} and @code{Voice} contexts may be specified +in a @code{\layout} block, as illustrated in the following example. +The @code{\layout} block should be placed within the @code{\score} +block to which it is to apply, but outside any music. -@example -\context @{ - @dots{} - fontSize = #-2 -@} -@end example +Note that the @code{\set} command itself and the context must be +omitted when the context default values are specified in this way: -@noindent -will also work. +@lilypond[quote,verbatim] +\score { + \relative c'' { + a4^"Really small, thicker stems, no time signature" a a a + a a a a + } + \layout { + \context { + \Staff + fontSize = #-4 + \override Stem #'thickness = #4.0 + \remove "Time_signature_engraver" + } + } +} +@end lilypond +In this example, the @code{\Staff} command specifies that the +subsequent specifications are to be applied to all staves within +this score block. +Modifications can be made to the @code{Score} context or all +@code{Voice} contexts in a similar way. @knownissues @@ -605,7 +581,7 @@ after calling @code{\RemoveEmptyStaffContext}, ie @} @end example -TODO: add \with in here. +@c TODO: add \with in here. @@ -702,7 +678,7 @@ The notes look like a slash, and have no stem, 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" @@ -781,8 +757,8 @@ in ossia, @c TODO Better example needed. Ref LM, and expand on it. @cindex ossia -@findex alignAboveContext -@findex alignBelowContext +@funindex alignAboveContext +@funindex alignBelowContext @lilypond[quote,ragged-right] ossia = { f4 f f f } @@ -790,13 +766,60 @@ ossia = { f4 f f f } \relative c' \new Staff = "main" { c4 c c c << - \new Staff \with {alignAboveContext=main} \ossia + \new Staff \with { alignAboveContext = #"main" } \ossia { d8 f d f d f d f } >> } } @end lilypond +@cindex nested contexts +@cindex contexts, nested + +@funindex \accepts +@funindex \denies + +Contexts like @code{PianoStaff} can contain other contexts +nested within them. Contexts which are acceptable for nesting +are defined by the @qq{accepts} list of a context. Contexts +which are not in this list are placed below the outer context +in the printed score. +For example, the @code{PianoStaff} context is defined by default +to accept @code{Staff} and @code{FiguredBass} contexts within +it, but not (for example) a @code{Lyrics} context. So in the +following structure the lyrics are placed below the piano staff +rather than between the two staves: + +@lilypond[verbatim,quote,relative=1] +\new PianoStaff +<< + \new Staff { e4 d c2 } + \addlyrics { Three blind mice } + \new Staff { + \clef "bass" + { c,1 } + } +>> +@end lilypond + +The @qq{accepts} list of a context can be modified to include +additional nested contexts, so if we wanted the lyrics to appear +between the two staves we could use: + +@lilypond[verbatim,quote,relative=1] +\new PianoStaff \with { \accepts Lyrics } +<< + \new Staff { e4 d c2 } + \addlyrics { Three blind mice } + \new Staff { + \clef "bass" + { c,1 } + } +>> +@end lilypond + +The opposite of @code{\accepts} is @code{\denies}; this removes a +context from the @qq{accepts} list. @node Explaining the Internals Reference @section Explaining the Internals Reference @@ -838,9 +861,9 @@ Internals Reference: @rinternals{Fingering}. @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 @@ -856,7 +879,7 @@ plug-in, which 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 @@ -902,7 +925,7 @@ Music types accepted: @rinternals{fingering-event} @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 @@ -1123,12 +1146,17 @@ LP-specific? @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 @@ -1227,12 +1255,11 @@ properties. To tweak those, use commands of the form such as @example -\override Stem #'details #'beamed-lengths = #'(4 4 3) +\override Stem #'(details beamed-lengths) = #'(4 4 3) @end example @seealso - Internals: @rinternals{OverrideProperty}, @rinternals{RevertProperty}, @rinternals{PropertySet}, @rinternals{Backend}, and @rinternals{All layout objects}. @@ -1246,7 +1273,7 @@ or crashes, or both. -@node The \set command +@node The set command @subsection The @code{\set} command @cindex properties @@ -1371,7 +1398,7 @@ Translation @expansion{} Tunable context properties. -@node The \override command +@node The override command @subsection The @code{\override} command Commands which change output generally look like @@ -1394,7 +1421,7 @@ Some tweakable options are called @q{subproperties} and reside inside properties. To tweak those, use commands in the form @example -\override Stem #'details #'beamed-lengths = #'(4 4 3) +\override Stem #'(details beamed-lengths) = #'(4 4 3) @end example @cindex internal documentation @@ -1413,7 +1440,147 @@ We demonstrate how to glean this information from the notation manual 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 @@ -1464,55 +1631,6 @@ objects. Since this is a common change, the special 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 @@ -1521,7 +1639,11 @@ details. * Input modes:: * Direction and placement:: * Distances and measurements:: +* Staff symbol properties:: * Spanners:: +* Visibility of objects:: +* Line styles:: +* Rotating objects:: @end menu @node Input modes @@ -1647,17 +1769,18 @@ up or down based on the stem direction (like slurs or accents). @c TODO Add table showing these -@strong{Context layout} - -Contexts are positioned in a system from top to bottom in the -order in which they are encountered. Note, however, that a -context will be created implicitly if a command is encountered -when there is no suitable context available to contain it. +@strong{Context layout order} -@c TODO Add example ? +Contexts are normally positioned in a system from top to bottom +in the order in which they are encountered. Note, however, that +a context will be created implicitly if a command is encountered +when there is no suitable context available to contain it. When +contexts are nested, the outer context will exclude inner contexts +which are not included in its @qq{accepts} list; excluded contexts +will be repositioned below the outer context. -The default order in which contexts are laid out can be changed, -see @ref{Aligning contexts} +The default order in which contexts are laid out and the +@qq{accepts} list can be changed, see @ref{Aligning contexts}. @strong{Articulation direction indicators} @@ -1718,38 +1841,397 @@ TrillPitchGroup - not tried @node Distances and measurements @subsection Distances and measurements -DISCUSS after working on other sections. +@cindex distances, absolute +@cindex distances, scaled + +@funindex \mm +@funindex \cm +@funindex \in +@funindex \pt + +Distances in LilyPond are of two types: absolute and scaled. + +Absolute distances are used for specifying margins, indents, and +other page layout details, and are by default specified in +millimeters. Distances may be specified in other units by +following the quantity by @code{\mm}, @code{\cm}, +@code{\in}@tie{}(inches), or @code{\pt}@tie{}(points, 1/72.27 +of an inch). Page layout distances can also be specified in +scalable units (see the following paragraph) by appending +@code{\staff-space} to the quantity. +Page layout is described in detail in @ref{Page formatting}. + +Scaled distances are always specified in units of the staff-space +or, rarely, the half staff-space. The staff-space is the distance +between two adjacent staff lines. The default value can be changed +globally by setting the global staff size, or it can be overridden +locally by changing the @code{staff-space} property of +@code{StaffSymbol}. Scaled distances automatically scale with any +change to the either the global staff size or the +@code{staff-space} property of @code{StaffSymbol}, but fonts scale +automatically only with changes to the global staff size. +The global staff size thus enables the overall size of a rendered +score to be easily varied. For the methods of setting the global +staff size see @ref{Setting the staff size}. + +@funindex magstep + +If just a section of a score needs to be rendered to a different +scale, for example an ossia section or a footnote, the global staff +size cannot simply be changed as this would affect the entire score. +In such cases the change in size is made by overriding both the +@code{staff-space} property of @code{StaffSymbol} and the size of +the fonts. A Scheme function, @code{magstep}, is available to +convert from a font size change to the equivalent change in +@code{staff-space}. For an explanation and an example of its use, +see @rlearning{Length and thickness of objects}. + + +@seealso +Learning Manual: +@rlearning{Length and thickness of objects}. + +Notation Reference: +@ref{Page formatting}, +@ref{Setting the staff size}. + + +@node Staff symbol properties +@subsection Staff symbol properties + +@cindex adjusting staff symbol +@cindex drawing staff symbol +@cindex staff symbol, setting of -TODO: staff spaces. Maybe move into tweaks? +@c TODO Extend or remove this section. See also NR 1.6.2 Staff symbol +@c Need to think of uses for these properties. Eg 'line-positions +@c is used in a snippet to thicken centre line. +@c If retained, add @ref to here in 1.6.2 -td + +The vertical position of staff lines and the number of staff lines +can be defined at the same time. As the following example shows, +note positions are not influenced by the staff line positions. + +@warning{The @code{'line-positions} property overrides the +@code{'line-count} property. The number of staff lines is +implicitly defined by the number of elements in the list of values +for @code{'line-positions}.} + +@lilypond[verbatim,quote,relative=1] +\new Staff \with { + \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7) +} +{ a4 e' f b | d1 } +@end lilypond + +The width of a staff can be modified. The units are staff +spaces. The spacing of objects inside the staff is not affected by +this setting. + +@lilypond[verbatim,quote,relative=1] +\new Staff \with { + \override StaffSymbol #'width = #23 +} +{ a4 e' f b | d1 } +@end lilypond @node Spanners @subsection Spanners Many objects of musical notation extend over several notes or even -several bars. Examples are crescendi, trills, tuplet brackets, and -volta repeat brackets. Such objects are called @qq{spanners}, and -have special properties to control their appearance and behaviour. -Some of these properties are common to all spanners; others are -restricted to a sub-set of the spanners. +several bars. Examples are slurs, beams, tuplet brackets, volta +repeat brackets, crescendi, trills, and glissandi. Such objects +are collectively called @qq{spanners}, and have special properties to control +their appearance and behaviour. Some of these properties are common +to all spanners; others are restricted to a sub-set of the spanners. -@node Common properties -@section Common properties +All spanners support the @code{spanner-interface}. A few, esentially +those that draw a straight line between the two objects, support in +addition the @code{line-spanner-interface}. -@menu -* Controlling visibility of objects:: -* Line styles:: -* Rotating objects:: -* Aligning objects:: -@end menu +@unnumberedsubsubsec Using the @code{spanner-interface} + +This interface provides two properties that apply to several spanners. + +@strong{@i{The @code{minimum-length} property}} + +The minimum length of the spanner is specified by the +@code{minimum-length} property. Increasing this usually has the +necessary effect of increasing the spacing of the notes between the +two end points. However, this override has no effect on +many spanners, as their length is determined by other considerations. +A few examples where it is effective are shown below. + +@ignore +Works for: + Tie + MultiMeasureRest + Hairpin + Slur + PhrasingSlur + +Works as long as callback is made: + Glissando + Beam + +Works not at all for: + LyricSpace + LyricHyphen + LyricExtender + TextSpanner + System + +@end ignore + +@lilypond[verbatim,quote,relative=2] +a~a +a +% increase the length of the tie +-\tweak #'minimum-length #5 +~a +@end lilypond + +@lilypond[verbatim,quote,relative=2] +a1 +\compressFullBarRests +R1*23 +% increase the length of the rest bar +\once \override MultiMeasureRest #'minimum-length = #20 +R1*23 +a1 +@end lilypond + +@lilypond[verbatim,quote,relative=2] +a \< a a a \! +% increase the length of the hairpin +\override Hairpin #'minimum-length = #20 +a \< a a a \! +@end lilypond + +This override can also be used to increase the length of slurs and +phrasing slurs: + +@lilypond[verbatim,quote,relative=2] +a( a) +a +-\tweak #'minimum-length #5 +( a) + +a\( a\) +a +-\tweak #'minimum-length #5 +\( a\) +@end lilypond + +For some layout objects, the @code{minimum-length} property becomes +effective only if the @code{set-spacing-rods} procedure is called +explicitly. To do this, the @code{springs-and-rods} property should +be set to @code{ly:spanner::set-spacing-rods}. For example, +the minimum length of a glissando has no effect unless the +@code{springs-and-rods} property is set: + +@lilypond[verbatim,quote,relative=1] +% default +e \glissando c' + +% not effective alone +\once \override Glissando #'minimum-length = #20 +e, \glissando c' + +% effective only when both overrides are present +\once \override Glissando #'minimum-length = #20 +\once \override Glissando #'springs-and-rods = #ly:spanner::set-spacing-rods +e, \glissando c' +@end lilypond + +The same is true of the @code{Beam} object: + +@lilypond[verbatim,quote,relative=1] +% not effective alone +\once \override Beam #'minimum-length = #20 +e8 e e e + +% effective only when both overrides are present +\once \override Beam #'minimum-length = #20 +\once \override Beam #'springs-and-rods = #ly:spanner::set-spacing-rods +e8 e e e +@end lilypond + +@strong{@i{The @code{to-barline} property}} -@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 +The second useful property of the @code{spanner-interface} is +@code{to-barline}. By default this is true, causing hairpins and +other spanners which are terminated on the first note of a measure to +end instead on the immediately preceding bar line. If set to false, +the spanner will extend beyond the bar line and end on the note +itself: -@node Controlling visibility of objects -@subsection Controlling visibility of objects +@lilypond[verbatim,quote,relative=2] +a \< a a a a \! a a a \break +\override Hairpin #'to-barline = ##f +a \< a a a a \! a a a +@end lilypond + +This property is not effective for all spanners. For example, +seting it to @code{#t} has no effect on slurs or phrasing slurs +or on other spanners for which terminating on the bar line would +not be meaningful. + +@unnumberedsubsubsec Using the @code{line-spanner-interface} + +Objects which support the @code{line-spanner-interface} include + +@itemize +@item @code{DynamicTextSpanner} +@item @code{Glissando} +@item @code{TextSpanner} +@item @code{TrillSpanner} +@item @code{VoiceFollower} +@end itemize + +The routine responsible for drawing the stencils for these spanners is +@code{ly:line-interface::print}. This routine determines the +exact location of the two end points and draws a line +between them, in the style requested. The locations of the two +end points of the spanner are computed on-the-fly, but it is +possible to override their Y-coordinates. The +properties which need to be specified are nested +two levels down within the property hierarchy, but the syntax of +the @code{\override} command is quite simple: + +@lilypond[relative=2,quote,verbatim] +e2 \glissando b +\once \override Glissando #'(bound-details left Y) = #3 +\once \override Glissando #'(bound-details right Y) = #-2 +e2 \glissando b +@end lilypond + +The units for the @code{Y} property are @code{staff-space}s, +with the center line of the staff being the zero point. +For the glissando, this is the value for @code{Y} at the +X-coordinate corresponding to the center point of each note head, +if the line is imagined to be extended to there. + +If @code{Y} is not set, the value is computed from the vertical +position of the corresponding attachment point of the spanner. + +In case of a line break, the values for the end points are +specified by the @code{left-broken} and @code{right-broken} +sub-lists of @code{bound-details}. For example: + +@lilypond[relative=2,ragged-right,verbatim,fragment] +\override Glissando #'breakable = ##t +\override Glissando #'(bound-details right-broken Y) = #-3 +c1 \glissando \break +f1 +@end lilypond + + +A number of further properties of the @code{left} and +@code{right} sub-lists of the @code{bound-details} property +may be modified in the same way as @code{Y}: + +@table @code +@item Y +This sets the Y-coordinate of the end point, in @code{staff-space}s +offset from the staff center line. By default, it is the center of +the bound object, so a glissando points to the vertical center of +the note head. + +For horizontal spanners, such as text spanners and trill spanners, +it is hardcoded to 0. + +@item attach-dir +This determines where the line starts and ends in the X-direction, +relative to the bound object. So, a value of @code{-1} (or +@code{LEFT}) makes the line start/end at the left side of the note +head it is attached to. + +@item X +This is the absolute X-coordinate of the end point. It is usually +computed on the fly, and overriding it has little useful effect. + +@item stencil +Line spanners may have symbols at the beginning or end, which is +contained in this sub-property. This is for internal use; it is +recommended that @code{text} be used instead. + +@item text +This is a markup that is evaluated to yield the stencil. It is used +to put @i{cresc.}, @i{tr} and other text on horizontal spanners. + +@lilypond[quote,ragged-right,fragment,relative=2,verbatim] +\override TextSpanner #'(bound-details left text) + = \markup { \small \bold Slower } +c2\startTextSpan b c a\stopTextSpan +@end lilypond + +@item stencil-align-dir-y +@item stencil-offset +Without setting one of these, the stencil is simply put at the +end-point, centered on the line, as defined by the @code{X} and +@code{Y} sub-properties. Setting either @code{stencil-align-dir-y} +or @code{stencil-offset} will move the symbol at the edge vertically +relative to the end point of the line: + +@lilypond[relative=1,fragment,verbatim] +\override TextSpanner + #'(bound-details left stencil-align-dir-y) = #-2 +\override TextSpanner + #'(bound-details right stencil-align-dir-y) = #UP + +\override TextSpanner + #'(bound-details left text) = #"ggg" +\override TextSpanner + #'(bound-details right text) = #"hhh" +c4^\startTextSpan c c c \stopTextSpan +@end lilypond + +Note that negative values move the text @emph{up}, contrary to the +effect that might be expected, as a value of @code{-1} or +@code{DOWN} means align the @emph{bottom} edge of the text with +the spanner line. A value of @code{1} or @code{UP} aligns +the top edge of the text with the spanner line. + +@item arrow +Setting this sub-property to @code{#t} produces an arrowhead at the +end of the line. + +@item padding +This sub-property controls the space between the specified +end point of the line and the actual end. Without padding, a +glissando would start and end in the center of each note head. + +@end table + +The music function @code{\endSpanners} terminates the spanner +which starts on the immediately following note prematurely. It +is terminated after exactly one note, or at the following bar line +if @code{to-barline} is true and a bar line occurs before the next +note. + +@lilypond[verbatim,quote,ragged-right,relative=2,fragment] +\endSpanners +c2 \startTextSpan c2 c2 +\endSpanners +c2 \< c2 c2 +@end lilypond + +When using @code{\endSpanners} it is not necessary to close +\startTextSpan with \stopTextSpan, nor is it necessary to close +hairpins with @code{\!}. + + +@seealso +Internals Reference: @rinternals{TextSpanner}, +@rinternals{Glissando}, @rinternals{VoiceFollower}, +@rinternals{TrillSpanner}, +@rinternals{line-spanner-interface}. + + +@node Visibility of objects +@subsection Visibility of objects @cindex objects, visibility of @cindex grobs, visibility of @@ -1890,29 +2372,25 @@ 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 +Alternatively, these 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 .1 .1 .1 -@c TODO check these more carefully +@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {yes} {yes} {yes} @headitem Function @tab Vector @tab Before @tab At no @tab After @headitem form @tab form @tab break @tab break @tab break -@item @code{all-invisible} @tab @code{'#(#f #f #f)} @ @ @tab no @tab no @tab no +@item @code{all-visible} @tab @code{'#(#t #t #t)} @tab yes @tab yes @tab yes @item @code{begin-of-line-visible} @tab @code{'#(#f #f #t)} @tab no @tab no @tab yes +@item @code{center-visible} @tab @code{'#(#f #t #f)} @tab no @tab yes @tab no @item @code{end-of-line-visible} @tab @code{'#(#t #f #f)} @tab yes @tab no @tab no -@item @code{all-visible} @tab @code{'#(#t #t #t)} @tab yes @tab yes @tab yes -@c The center-visible function is not defined -@c @item @code{center-visible} @tab @code{'#(#f #t #f)} @tab no @tab yes @tab no @item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)} @tab yes @tab yes @tab no -@item @code{end-of-line-invisible} @tab @code{'#(#f #t #t)} @tab no @tab yes @tab yes @item @code{center-invisible} @tab @code{'#(#t #f #t)} @tab yes @tab no @tab yes +@item @code{end-of-line-invisible} @tab @code{'#(#f #t #t)} @tab no @tab yes @tab yes +@item @code{all-invisible} @tab @code{'#(#f #f #f)} @tab no @tab no @tab no @end multitable -The @code{center-visible} function is not pre-defined. - The default settings of @code{break-visibility} depend on the layout object. The following table shows all the layout objects of interest which are affected by @code{break-visibility} and the @@ -2094,10 +2572,6 @@ Learning Manual: @node Line styles @subsection Line styles -@c TODO: split the following explanations between expressive marks and -@c text-related stuff. Perhaps create a new subsection named -@c "Spanner limits", "Spanner boundaries"? -vv - Some performance indications, e.g., @i{rallentando} and @i{accelerando} and @i{trills} are written as text and are extended over many measures with lines, sometimes dotted or wavy. @@ -2107,11 +2581,11 @@ texts and the lines, and tuning their behavior is therefore also done in the same way. It is done with a spanner, and the routine responsible for drawing the spanners is @code{ly:line-interface::print}. This routine determines the -exact location of the two @i{span points} and draws a line in -between, in the style requested. +exact location of the two @i{span points} and draws a line +between them, in the style requested. -Here is an example of the different line styles available, and how -to tune them. +Here is an example showing the different line styles available, +and how to tune them. @lilypond[relative=2,ragged-right,verbatim,fragment] d2 \glissando d'2 @@ -2125,129 +2599,26 @@ d,2 \glissando d'2 d,2 \glissando d'2 @end lilypond -The information that determines the end-points is computed +The locations of the end-points of the spanner are computed on-the-fly for every graphic object, but it is possible to -override these. +override these: +@c FIXME Complete @lilypond[relative=2,ragged-right,verbatim,fragment] e2 \glissando f -\once \override Glissando #'bound-details #'right #'Y = #-2 +\once \override Glissando #'(bound-details right Y) = #-2 e2 \glissando f @end lilypond -The @code{Glissando} object, like any other using the -@code{ly:line-interface::print} routine, carries a nested -association list. In the above statement, the value for @code{Y} -is set to @code{-2} for the association list corresponding to the -right end point. Of course, it is also possible to adjust the -left side with @code{left} instead of @code{right}. +The value for @code{Y} is set to @code{-2} for the right end +point. The left side may be similarly adjusted by specifying +@code{left} instead of @code{right}. If @code{Y} is not set, the value is computed from the vertical -position of right attachment point of the spanner. - -In case of a line break, the values for the span-points are -extended with contents of the @code{left-broken} and -@code{right-broken} sublists, for example - -@lilypond[relative=2,ragged-right,verbatim,fragment] -\override Glissando #'breakable = ##T -\override Glissando #'bound-details #'right-broken #'Y = #-3 -c1 \glissando \break -f1 -@end lilypond - -The following properties can be used for the - -@table @code -@item Y -This sets the Y-coordinate of the end point, in staff space. By -default, it is the center of the bound object, so for a glissando -it points to the vertical center of the note head. - -For horizontal spanners, such as text spanner and trill spanners, -it is hardcoded to 0. - -@item attach-dir -This determines where the line starts and ends in X-direction, -relative to the bound object. So, a value of @code{-1} (or -@code{LEFT}) makes the line start/end at the left side of the note -head it is attached to. - -@item X -This is the absolute coordinate of the end point. It is usually -computed on the fly, and there is little use in overriding it. - -@item stencil -Line spanners may have symbols at the beginning or end, which is -contained in this sub-property. This is for internal use, it is -recommended to use @code{text}. - -@item text -This is a markup that is evaluated to yield stencil. It is used -to put @i{cresc.} and @i{tr} on horizontal spanners. - -@lilypond[quote,ragged-right,fragment,relative=2,verbatim] -\override TextSpanner #'bound-details #'left #'text - = \markup { \small \bold Slower } -c2\startTextSpan b c a\stopTextSpan -@end lilypond - -@item stencil-align-dir-y -@item stencil-offset -Without setting this, the stencil is simply put there at the -end-point, as defined by the @code{X} and @code{Y} sub properties. -Setting either @code{stencil-align-dir-y} or @code{stencil-offset} -will move the symbol at the edge relative to the end point of the -line - -@lilypond[relative=1,fragment,verbatim] -\override TextSpanner #'bound-details - #'left #'stencil-align-dir-y = #DOWN -\override TextSpanner #'bound-details - #'right #'stencil-align-dir-y = #UP - -\override TextSpanner #'bound-details - #'left #'text = #"gggg" -\override TextSpanner #'bound-details - #'right #'text = #"hhhh" -c4^\startTextSpan c c c \stopTextSpan -@end lilypond - -@item arrow -Setting this sub property to @code{#t} produce an arrowhead at the -end of the line. - -@item padding -This sub property controls the space between the specified -end-point of the line and the actual end. Without padding, a -glissando would start and end in the center of each note head. - -@end table - -@c TODO: Move to 5.4.4 - -The music function \endSpanners terminates spanners and hairpins -after exactly one note. - -@lilypond[verbatim,quote,ragged-right,relative=2,fragment] -\endSpanners -c2 \startTextSpan c2 -c2 \< c2 -@end lilypond - -When using \endSpanners it is not necessary to close -\startTextSpan with \stopTextSpan, nor is it necessary to close -hairpins with \!. - - - -@seealso - -Internals Reference: @rinternals{TextSpanner}, -@rinternals{Glissando}, @rinternals{VoiceFollower}, -@rinternals{TrillSpanner}, -@rinternals{line-spanner-interface}. +position of the left and right attachment points of the spanner. +Other adjustments of spanners are possible, for details, see +@ref{Spanners}. @node Rotating objects @subsection Rotating objects @@ -2311,24 +2682,352 @@ des^\markup { \rotate #30 "a D-Flat" } fis^\markup { \rotate #30 "an F-Sharp" } @end lilypond - -@node Aligning objects -@subsection Aligning objects - -@c FIXME Write this section - - @node Advanced tweaks @section Advanced tweaks +This section discusses various approaches to fine tuning the +appearance of the printed score. + @menu +* Aligning objects:: * Vertical grouping of grobs:: -* Modifying ends of spanners:: * Modifying stencils:: * Modifying shapes:: @end menu +@seealso +Learning Manual: +@rlearning{Tweaking output}, +@rlearning{Other sources of information}. + +Notation Reference: +@ref{Explaining the Internals Reference}, +@ref{Modifying properties}, +@ref{Interfaces for programmers}. + +Installed Files: +@file{scm/@/define@/-grobs@/.scm}. + +Snippets: +@rlsr{Tweaks and overrides}. + +Internals Reference: +@rinternals{All layout objects}. + + +@node Aligning objects +@subsection Aligning objects + +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-alignable-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-alignable-interface} +@unnumberedsubsubsec Using the @code{break-alignable-interface} + +@cindex align to objects +@cindex break-align-symbols + +Rehearsal marks and bar numbers 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 and bar numbers 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 + +A list of possible target alignment objects may be specified. If +some of the objects are invisible at that point due to the setting +of @code{break-visibility} or the explicit visibility settings for +keys and clefs, the rehearsal mark or bar number is aligned to the +first object in the list which is visible. If no objects in the +list are visible the object is aligned to the bar line. If the bar +line is invisible the object is aligned to the place where the bar +line would be. + +@lilypond[verbatim,quote,relative=1] +e1 +% the RehearsalMark will be centered above the Key Signature +\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef) +\key a \major +\clef treble +\mark "↓" +e +% the RehearsalMark will be centered above the Clef +\set Staff.explicitKeySignatureVisibility = #all-invisible +\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef) +\key a \minor +\clef bass +\mark "↓" +e, +@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 Vertical grouping of grobs @@ -2344,94 +3043,139 @@ VerticalAlignment per score but every Staff, Lyrics, etc. has its own VerticalAxisGroup. -@node Modifying ends of spanners -@subsection Modifying ends of spanners - -@c FIXME Write this section - @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}. -@node Modifying shapes -@subsection Modifying shapes +@c TODO Add inserting eps files or ref to later + +@c TODO Add inserting Postscript or ref to later -@c FIXME Write this section -@c Discussion of Bezier curves and the control-points property -@node Discussion of specific tweaks -@section Discussion of specific tweaks +@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 @menu -* old Contexts explained:: +* 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 } +>> +@end lilypond -@node old Contexts explained -@subsection old Contexts explained +One way of improving this tie is to manually modify its control +points, as follows. -@c FIXME Delete this section? It is in LM -@c Or leave heading and go on from LM? +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. -When music is printed, a lot of notational elements must be added to the -output. For example, compare the input and output of the following example: +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. -@lilypond[quote,verbatim,relative=2,fragment] -cis4 cis2. g4 -@end lilypond +For the example above the following override gives a satisfactory +tie: -The input is rather sparse, but in the output, bar lines, accidentals, -clef, and time signature are added. LilyPond @emph{interprets} the -input. During this step, the musical information is inspected in time -order, similar to reading a score from left to right. While reading -the input, the program remembers where measure boundaries are, and which -pitches require explicit accidentals. This information can be presented on -several levels. For example, the effect of an accidental is limited -to a single staff, while a bar line must be synchronized across the -entire score. - -Within LilyPond, these rules and bits of information are grouped in -@emph{Contexts}. Some examples of contexts are @code{Voice}, -@code{Staff}, and @code{Score}. They are hierarchical, for -example: a @code{Staff} can contain many @code{Voice}s, and a -@code{Score} can contain many @code{Staff} contexts. +@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 4 } +>> +@end lilypond -@quotation -@sourceimage{context-example,5cm,,} -@end quotation +@knownissues -Each context has the responsibility for enforcing some notation rules, -creating some notation objects and maintaining the associated -properties. For example, the @code{Voice} context may introduce an -accidental and then the @code{Staff} context maintains the rule to -show or suppress the accidental for the remainder of the measure. The -synchronization of bar lines is handled at @code{Score} context. - -However, in some music we may not want the bar lines to be -synchronized -- consider a polymetric score in 4/4 and 3/4 time. In -such cases, we must modify the default settings of the @code{Score} -and @code{Staff} contexts. - -For very simple scores, contexts are created implicitly, and you need -not be aware of them. For larger pieces, such as anything with more -than one staff, they must be -created explicitly to make sure that you get as many staves as you -need, and that they are in the correct order. For typesetting pieces -with specialized notation, it can be useful to modify existing or -to define new contexts. - - -A complete description of all available contexts is in the program -reference, see -@ifhtml -@rinternals{Contexts}. -@end ifhtml -@ifnothtml -Translation @expansion{} Context. -@end ifnothtml +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. -@c [TODO: describe propagation]