X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fchanging-defaults.itely;h=3e57280c0fedccc4a75be5f83508c0cf70a32472;hb=c6554467b0a9beddf0d7ef12746ae31a25fe36e7;hp=301f34374dfd7c3f02b2374032648260748d3a3b;hpb=78eb8695d44a5a5775457a14770093299b6d5fa6;p=lilypond.git diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely index 301f34374d..3e57280c0f 100644 --- a/Documentation/user/changing-defaults.itely +++ b/Documentation/user/changing-defaults.itely @@ -7,59 +7,30 @@ version that you are working on. See TRANSLATION for details. @end ignore -@c \version "2.11.51" +@c \version "2.11.61" @node Changing defaults @chapter Changing defaults - -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. - -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 @@ -74,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 @@ -94,14 +63,31 @@ This section describes what contexts are, and how to modify them. * Aligning contexts:: @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 -@c FIXME Rethink and rewrite +@ignore +@c TODO Rethink and rewrite >> > > - list of contexts: my *danger unmaintainable* ->> > > alarm just went off. I'm +>> > > alarm just went off. I'm I knew it would... And leaving out some of them is perfectly fine with me. @@ -114,118 +100,159 @@ unmanageable), should be there, and then we could simply list the remaining ones without further explanation and with links to the IR. +@end ignore + +@c TODO Improve layout, order and consistency of wording -td + +@c TODO Add introduction which explains contexts in generality -td + +@c TODO Describe propagation of property values -td + +Contexts are arranged heirarchically: + +@menu +* 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 +@unnumberedsubsubsec Score - the master of all contexts + +This is the top level notation context. No other context can +contain a Score context. By default the Score context handles +the administration of time signatures and makes sure that items +such as clefs, time signatures, and key-signatures are aligned +across staves. + +A Score context is instantiated implicitly when a +@code{\score @{@dots{}@}} or @code{\layout @{@dots{}@}} block is +processed, or explicitly when a @code{\new Score} command is +executed. + +@node Top-level contexts - staff containers +@unnumberedsubsubsec Top-level contexts - staff containers + +@strong{@emph{StaffGroup}} + +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 +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. + +@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 +connected vertically. + +@strong{@emph{PianoStaff}} + +@c 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. + +@ignore +@strong{@emph{InnerStaffGroup}} + +TODO -td + +@strong{@emph{InnerChoirStaff}} + +TODO -td + +@end ignore + +@node Intermediate-level contexts - staves +@unnumberedsubsubsec Intermediate-level contexts - staves + +@strong{@emph{Staff}} + +Handles clefs, bar lines, keys, accidentals. It can contain +Voice contexts. + +@strong{@emph{RhythmicStaff}} + +Like 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 +expression out as a guitar tablature, printed on six lines. + +@strong{@emph{DrumStaff}} + +Handles typesetting for percussion. Can contain DrumVoice + +@strong{@emph{VaticanaStaff}} + +Same as 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 +a piece in mensural style. + +@node Bottom-level contexts - voices +@unnumberedsubsubsec Bottom-level contexts - voices + +Voice-level contexts initialise certain properties and start +appropriate engravers. Being bottom-level contexts, they cannot +contain other contexts. + +@strong{@emph{Voice}} + +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. + +@strong{@emph{MensuralVoice}} + +Same as Voice, with modifications for typesetting a piece in +mensural style. + +@strong{@emph{Lyrics}} + +Corresponds to a voice with lyrics. Handles the printing of a +single line of lyrics. + +@strong{@emph{DrumVoice}} + +The voice context used in a percussion staff. + +@strong{@emph{FiguredBass}} + +The context in which 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. + +@strong{@emph{ChordNames}} + +Typesets chord names. + +@ignore +TODO -The Master Of All Contexts -========================== - - * Score - This is the top level notation context. No other context -can - contain a Score context. This context handles the - administration of time signatures. It also makes sure that - items such as clefs, time signatures, and key-signatures -are - aligned across staves. - You cannot explicitly instantiate a Score context (since -it is - not contained in any other context). It is instantiated - automatically when an output definition (a \score or -\layout - block) is processed. - (it should also be made clear somewhere what the -difference is between - \score and \Score). - -Top-level contexts: Staff containers -==================================== - * StaffGroup - 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 of staves, with a bracket in front and spanning -bar - lines. - * ChoirStaff - Identical to StaffGroup except that the contained staves -are - not connected vertically. - * GrandStaff - 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. - * PianoStaff - Just like GrandStaff but with a forced distance between -the - staves, so cross staff beaming and slurring can be used. - * DrumStaff - Handles typesetting for percussion. Can contain DrumVoice - * InnerStaffGroup - * InnerChoirStaff - -Staff-level contexts -==================== - * Staff - Handles clefs, bar lines, keys, accidentals. It can -contain - Voice contexts. - * RhythmicStaff - Like Staff but for printing rhythms. Pitches are - ignored; the notes are printed on one line. - * TabStaff - Context for generating tablature. By default lays the -music - expression out as a guitar tablature, printed on six -lines. - * VaticanaStaff - Same as Staff, except that it is accommodated for - typesetting a piece in gregorian style. - * MensuralStaff - Same as Staff, except that it is accommodated for - typesetting a piece in mensural style. - -Voice-level (bottom) contexts -============================= -What is generated by default here? The voice-level contexts -initiate -certain properties and start engravers. - - * Voice - Corresponds to a voice on a staff. This context handles -the - conversion of dynamic signs, stems, beams, super- and - subscripts, slurs, ties, and rests. - You have to instantiate this explicitly if you want to -have - multiple voices on the same staff. - Bottom context. - * VaticanaVoice - Same as Voice, except that it is accommodated for - typesetting a piece in gregorian style. - * MensuralVoice - Same as Voice, except that it is accommodated for - typesetting a piece in mensural style. - * Lyrics - Corresponds to a voice with lyrics. Handles the printing -of a - single line of lyrics. - Bottom context. - * DrumVoice - A voice on a percussion staff. - * FiguredBass - - * ChordNames - Typesets chord names. This context is a `bottom' context; -it - cannot contain other contexts. - ------------------------------- Then the following, which I don't know what to do with: - * TabVoice * GregorianTranscriptionVoice * GregorianTranscriptionStaff @@ -244,7 +271,7 @@ documented. Silently discards all musical information given to this context. - +@end ignore @node Creating contexts @subsection Creating contexts @@ -494,55 +521,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 - -The @code{\Staff} command brings in the existing definition of the -staff context so that it can be modified. +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 statements -@example -\set fontSize = #-2 -\override Stem #'thickness = #4.0 -\remove "Time_signature_engraver" -@end example +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. -@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 @@ -564,7 +593,7 @@ after calling @code{\RemoveEmptyStaffContext}, ie @} @end example -TODO: add \with in here. +@c TODO: add \with in here. @@ -661,7 +690,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" @@ -740,8 +769,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 } @@ -756,16 +785,63 @@ ossia = { f4 f f 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 @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 @@ -797,9 +873,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 @@ -815,7 +891,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 @@ -861,7 +937,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 @@ -1059,7 +1135,7 @@ Fingering_engraver is part of contexts: @dots{} @rinternals{Voice} @subsection Naming conventions Another thing that is needed, is an overview of the various naming -conventions: +conventions: scheme functions: lowercase-with-hyphens (incl. one-word names) @@ -1082,12 +1158,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:: +* Overview of modifying properties:: +* The set command:: +* The override command:: +* The tweak command:: +* set versus override:: @end menu @@ -1205,7 +1286,7 @@ or crashes, or both. -@node The \set command +@node The set command @subsection The @code{\set} command @cindex properties @@ -1330,7 +1411,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 @@ -1372,7 +1453,146 @@ 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 @@ -1423,55 +1643,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 @@ -1480,7 +1651,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 @@ -1606,17 +1781,18 @@ up or down based on the stem direction (like slurs or accents). @c TODO Add table showing these -@strong{Context layout} +@strong{Context layout order} -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. +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. -@c TODO Add example ? - -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} @@ -1677,131 +1853,325 @@ 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 + +@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. -TODO: staff spaces. Maybe move into tweaks? +@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. +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}. -@node Common properties -@section Common properties +@unnumberedsubsubsec Using the @code{spanner-interface} -@menu -* Controlling visibility of objects:: -* Line styles:: -* Rotating objects:: -* Aligning objects:: -@end menu +This interface provides two properties that apply to several spanners. -@node Controlling visibility of objects -@subsection Controlling visibility of objects +@strong{@i{The @code{minimum-length} property}} -@c FIXME Write this section +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. -@node Line styles -@subsection Line styles +@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 -@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 +@end ignore -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. +@lilypond[verbatim,quote,relative=2] +a~a +a +% increase the length of the tie +-\tweak #'minimum-length #5 +~a +@end lilypond -These all use the same routines as the glissando for drawing the -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. +@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 -Here is an example of the different line styles available, and how -to tune them. +@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 -@lilypond[relative=2,ragged-right,verbatim,fragment] -d2 \glissando d'2 -\once \override Glissando #'style = #'dashed-line -d,2 \glissando d'2 -\override Glissando #'style = #'dotted-line -d,2 \glissando d'2 -\override Glissando #'style = #'zigzag -d,2 \glissando d'2 -\override Glissando #'style = #'trill -d,2 \glissando d'2 +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 -The information that determines the end-points is computed -on-the-fly for every graphic object, but it is possible to -override these. +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 -@lilypond[relative=2,ragged-right,verbatim,fragment] -e2 \glissando f +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}} + +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: + +@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 f +e2 \glissando b @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 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 right attachment point of the spanner. +position of the corresponding 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 +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 #'breakable = ##t \override Glissando #'bound-details #'right-broken #'Y = #-3 c1 \glissando \break f1 @end lilypond -The following properties can be used for the + +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 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. +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 spanner and trill spanners, +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 X-direction, +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 coordinate of the end point. It is usually -computed on the fly, and there is little use in overriding it. +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 to use @code{text}. +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 stencil. It is used -to put @i{cresc.} and @i{tr} on horizontal spanners. +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 @@ -1811,50 +2181,58 @@ c2\startTextSpan b c a\stopTextSpan @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 +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 = #DOWN + #'left #'stencil-align-dir-y = #-2 \override TextSpanner #'bound-details #'right #'stencil-align-dir-y = #UP \override TextSpanner #'bound-details - #'left #'text = #"gggg" + #'left #'text = #"ggg" \override TextSpanner #'bound-details - #'right #'text = #"hhhh" + #'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} produce an arrowhead at the +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 +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. +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 \< c2 +c2 \startTextSpan c2 c2 +\endSpanners +c2 \< c2 c2 @end lilypond -When using \endSpanners it is not necessary to close +When using @code{\endSpanners} it is not necessary to close \startTextSpan with \stopTextSpan, nor is it necessary to close -hairpins with \!. +hairpins with @code{\!}. @@ -1866,26 +2244,774 @@ Internals Reference: @rinternals{TextSpanner}, @rinternals{line-spanner-interface}. +@node Visibility of objects +@subsection Visibility of objects + +@cindex objects, visibility of +@cindex grobs, visibility of +@cindex visibility of objects + +There are four main ways in which the visibility of layout objects +can be controlled: their stencil can be removed, they can be made +transparent, they can be colored white, or their +@code{break-visibility} property can be overridden. The first +three apply to all layout objects; the last to just a few -- the +@emph{breakable} objects. The Learning Manual introduces these +four techniques, see @rlearning{Visibility and color of objects}. + +There are also a few other techniques which are specific to +certain layout objects. These are covered under Special +considerations. + +@menu +* Removing the stencil:: +* Making objects transparent:: +* Painting objects white:: +* Using break-visibility:: +* Special considerations:: +@end menu + + +@node Removing the stencil +@unnumberedsubsubsec Removing the stencil + +@cindex stencil, removing + +Every layout object has a stencil property. By default this is set +to the specific function which draws that object. If this property +is overridden to @code{#f} no function will be called and the object +will not be drawn. The default action can be recovered with +@code{\revert}. + +@lilypond[quote,verbatim,relative=1] +a1 a +\override Score.BarLine #'stencil = ##f +a a +\revert Score.BarLine #'stencil +a a a +@end lilypond + +@node Making objects transparent +@unnumberedsubsubsec Making objects transparent + +@cindex transparent, making objects + +Every layout object has a transparent property which by default is +set to @code{#f}. If set to @code{#t} the object still occupies +space but is made invisible. + +@lilypond[quote,verbatim,relative=2] +a4 a +\once \override NoteHead #'transparent = ##t +a a +@end lilypond + +@node Painting objects white +@unnumberedsubsubsec Painting objects white + +@cindex objects, coloring +@cindex coloring objects +@cindex layers +@cindex printing order +@cindex overwriting objects +@cindex objects, overwriting +@cindex grobs, overwriting + +Every layout object has a color property which by default is set +to @code{black}. If this is overridden to @code{white} the object +will be indistinguishable from the white background. However, +if the object crosses other objects the color of the crossing +points will be determined by the order in which they are drawn, +and this may leave a ghostly image of the white object, as shown +here: + +@lilypond[quote,verbatim,relative=2] +\override Staff.Clef #'color = #white +a1 +@end lilypond + +This may be avoided by changing the order of printing the objects. +All layout objects have a @code{layer} property which should be set +to an integer. Objects with the lowest value of @code{layer} are +drawn first, then objects with progressively higher values are drawn, +so objects with higher values overwrite objects with lower values. +By default most objects are assigned a @code{layer} value of +@code{1}, although a few objects, including @code{StaffSymbol} and +@code{BarLine}, are assigned a value of @code{0}. The order of +printing objects with the same value of @code{layer} is indeterminate. + +In the example above the white clef, with a default @code{layer} +value of @code{1}, is drawn after the staff lines (default +@code{layer} value @code{0}), so overwriting them. To change this, +the @code{Clef} object must be given in a lower value of +@code{layer}, say @code{-1}, so that it is drawn earlier: + +@lilypond[quote,verbatim,relative=2] +\override Staff.Clef #'color = #white +\override Staff.Clef #'layer = #-1 +a1 +@end lilypond + +@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 +bar lines, clefs, time signatures and key signatures, may need +to be printed twice when a line break occurs -- once at the end +of the line and again at the start of the next line. Such +objects are called @emph{breakable}, and have a property, the +@code{break-visibility} property to control their visibility +at the three positions in which they may appear -- at the +start of a line, within a line if they are changed, and at the +end of a line if a change takes place there. + +For example, the time signature +by default will be printed at the start of the first line, but +nowhere else unless it changes, when it will be printed at the +point at which the change occurs. If this change occurs at the +end of a line the new time signature will be printed at the start +of the next line and a cautionary time signature will be printed +at the end of the previous line as well. + +This behaviour is controlled by the @code{break-visibility} +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, 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 {@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-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{begin-of-line-invisible} @tab @code{'#(#t #t #f)} @tab yes @tab yes @tab no +@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 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 +default setting of this property: + +@multitable @columnfractions .3 .3 .4 + +@headitem Layout object @tab Usual context @tab Default setting + +@c omit Ambitus as it appears not to be affected by break-visibility -td +@c @item @code{Ambitus} @tab as specified @tab @code{begin-of-line-visible} +@item @code{BarLine} @tab @code{Score} @tab calculated +@item @code{BarNumber} @tab @code{Score} @tab @code{begin-of-line-visible} +@c omit the following item until it can be explained -td +@c @item @code{BreakAlignGroup} @tab @code{Score} @tab calculated +@item @code{BreathingSign} @tab @code{Voice} @tab @code{begin-of-line-invisible} +@item @code{Clef} @tab @code{Staff} @tab @code{begin-of-line-visible} +@item @code{Custos} @tab @code{Staff} @tab @code{end-of-line-visible} +@item @code{DoublePercentRepeat} @tab @code{Voice} @tab @code{begin-of-line-invisible} +@c omit KeyCancellation until it can be explained -td +@c @item @code{KeyCancellation} @tab ?? @tab @code{begin-of-line-invisible} +@item @code{KeySignature} @tab @code{Staff} @tab @code{begin-of-line-visible} +@c omit LeftEdge until it can be explained -td +@c @item @code{LeftEdge} @tab @code{Score} @tab @code{center-invisible} +@item @code{OctavateEight} @tab @code{Staff} @tab @code{begin-of-line-visible} +@item @code{RehearsalMark} @tab @code{Score} @tab @code{end-of-line-invisible} +@item @code{TimeSignature} @tab @code{Staff} @tab @code{all-visible} + +@end multitable + +The example below shows the use of the vector form to control the +visibility of barlines: + +@lilypond[quote,verbatim,relative=1,ragged-right] +f4 g a b +f4 g a b +% Remove bar line at the end of the current line +\once \override Score.BarLine #'break-visibility = #'#(#f #t #t) +\break +f4 g a b +f4 g a b +@end lilypond + +Although all three components of the vector used to override +@code{break-visibility} must be present, not all of them are +effective with every layout object, and some combinations may +even give errors. The following limitations apply: + +@itemize @bullet +@item Bar lines cannot be printed at start of line. +@item A bar number cannot be printed at the start of the first +line unless it is set to be different from 1. +@item Clef -- see below +@item Double percent repeats are either all printed or all +suppressed. Use begin-of line-invisible to print and +all-invisible to suppress. +@item Key signature -- see below +@item OctavateEight -- see below +@end itemize + +@node Special considerations +@unnumberedsubsubsec Special considerations + +@strong{@emph{Visibility following explicit changes}} + +@cindex key signature, visibility following explicit change +@cindex explicitKeySignatureVisibility +@cindex clef, visibility following explicit change +@cindex explicitClefVisibility + +The @code{break-visibility} property controls the visibility of +key signatures and changes of clef only at the start of lines, +i.e. after a break. It has no effect on the visibility of the +key signature or clef following an explicit key change or an +explicit clef change within or at the end of a line. In the +following example the key signature following the explicit change +to B-flat major is still visible, even though @code{all-invisible} +is set. + +@lilypond[quote,verbatim,relative=1,ragged-right] +\key g \major +f4 g a b +% Try to remove all key signatures +\override Staff.KeySignature #'break-visibility = #all-invisible +\key bes \major +f4 g a b +\break +f4 g a b +f4 g a b +@end lilypond + +The visibility of such explicit key signature and clef changes is +controlled by the @code{explicitKeySignatureVisibility} and +@code{explicitClefVisibility} properties. These are the equivalent +of the @code{break-visibility} property and both take a vector of +three booleans or the predefined functions listed above, exactly like +@code{break-visibility}. Both are properties of the Staff context, +not the layout objects themselves, and so they are set using the +@code{\set} command. Both are set by default to @code{all-visible}. +These properties control only the visibility of key signatures and +clefs resulting from explicit changes and do not affect key +signatures and clefs at the beginning of lines; +@code{break-visibility} must still be overridden in the appropriate +object to remove these. + +@lilypond[quote,verbatim,relative=1,ragged-right] +\key g \major +f4 g a b +\set Staff.explicitKeySignatureVisibility = #all-invisible +\override Staff.KeySignature #'break-visibility = #all-invisible +\key bes \major +f4 g a b \break +f4 g a b +f4 g a b +@end lilypond + +@strong{@emph{Visibility of cautionary accidentals}} + +To remove the cautionary accidentals printed at an explicit key +change, set the Staff context property @code{printKeyCancellation} +to @code{#f}: + +@lilypond[quote,verbatim,relative=1,ragged-right] +\key g \major +f4 g a b +\set Staff.explicitKeySignatureVisibility = #all-invisible +\set Staff.printKeyCancellation = ##f +\override Staff.KeySignature #'break-visibility = #all-invisible +\key bes \major +f4 g a b \break +f4 g a b +f4 g a b +@end lilypond + +With these overrides only the accidentals before the notes remain +to indicate the change of key. + +@c TODO Add visibility of cautionary accidentals before notes + +@strong{@emph{Automatic bars}} + +@cindex automaticBars +@cindex bar lines, suppressing + +As a special case, the printing of bar lines can also be turned off +by setting the @code{automaticBars} property in the Score context. +If set to @code{#f}, bar lines will not be printed automatically; +they must be explicitly created with a @code{\bar} command. Unlike +the @code{\cadenzaOn} predefined command, measures are still counted. +Bar generation will resume according to that count if this property +is later set to @code{#t}. When set to @code{#f}, line breaks can +occur only at explicit @code{\bar} commands. + +@c TODO Add example + +@strong{@emph{Octavated clefs}} + +@cindex octavated clefs, visibility of +@cindex visibility of octavated clefs +@cindex clefs, visibility of octavation + +The small octavation symbol on octavated clefs is produced by the +@code{OctavateEight} layout object. Its visibility is controlled +independently from that of the @code{Clef} object, so it is +necessary to apply any required @code{break-visibility} overrides +to both the @code{Clef} and the @code{OctavateEight} layout objects +to fully suppress such clef symbols at the start of each line. + +For explicit clef changes, the @code{explicitClefVisibility} +property controls both the clef symbol and any octavation symbol +associated with it. + + +@seealso +Learning Manual: +@rlearning{Visibility and color of objects} + + +@node Line styles +@subsection Line styles + +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. + +These all use the same routines as the glissando for drawing the +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 +between them, in the style requested. + +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 +\once \override Glissando #'style = #'dashed-line +d,2 \glissando d'2 +\override Glissando #'style = #'dotted-line +d,2 \glissando d'2 +\override Glissando #'style = #'zigzag +d,2 \glissando d'2 +\override Glissando #'style = #'trill +d,2 \glissando d'2 +@end lilypond + +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: + +@c FIXME Complete +@lilypond[relative=2,ragged-right,verbatim,fragment] +e2 \glissando f +\once \override Glissando #'bound-details #'right #'Y = #-2 +e2 \glissando f +@end lilypond + +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 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 -@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. -@node Aligning objects -@subsection Aligning objects +@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 -@c FIXME Write this section +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 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-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 @@ -1902,89 +3028,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}. +@c TODO Add inserting eps files or ref to later -@node Discussion of specific tweaks -@section Discussion of specific tweaks +@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 @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 + +One way of improving this tie is to manually modify its control +points, as follows. -@node old Contexts explained -@subsection old Contexts explained +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. -@c FIXME Delete this section? It is in LM -@c Or leave heading and go on from LM? +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. -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: +For the example above the following override gives a satisfactory +tie: -@lilypond[quote,verbatim,relative=2,fragment] -cis4 cis2. g4 +@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 -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. - -@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]