X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fchanging-defaults.itely;h=551c56d91ae0a9424e8e8e5b8e98010b60b95d11;hb=da12a3eb8e07ec4e910ead9f39f477920251190a;hp=92959d86676f1e30494a2df02b281ff5967d613b;hpb=80ac826fa969c9e1a0a4980d612b3711f2a21312;p=lilypond.git diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely index 92959d8667..551c56d91a 100644 --- a/Documentation/user/changing-defaults.itely +++ b/Documentation/user/changing-defaults.itely @@ -7,6 +7,8 @@ version that you are working on. See TRANSLATION for details. @end ignore +@c \version "2.11.38" + @node Changing defaults @chapter Changing defaults @@ -20,15 +22,15 @@ are available and explains how to lookup which knob to use for a particular effect. -@cindex Program reference +@cindex Internals Reference The controls available for tuning are described in a separate document, the @iftex -Program reference manual. +Internals Reference manual. @end iftex @ifnottex -@ref{Top,Program reference,,lilypond-internals}. +@ref{Top,Internals Reference,,lilypond-internals}. @end ifnottex That manual lists all different variables, functions and options available in @@ -56,7 +58,7 @@ 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 -in @ref{Non-musical notation}, and @ref{Spacing issues}. +@c in @ref{notation}, and @ref{Spacing issues}. @end itemize Internally, LilyPond uses Scheme (a LISP dialect) to provide @@ -68,8 +70,14 @@ on entering numbers, lists, strings, and symbols in Scheme.} @menu -* Interpretation contexts:: -* The \override command:: +* Interpretation contexts:: +* Explaining the Internals Reference:: +* Modifying properties:: +* Useful concepts and properties:: +* Common properties:: +* Advanced tweaks:: +* old The \override command:: +* Discussion of specific tweaks:: @end menu @@ -79,79 +87,159 @@ on entering numbers, lists, strings, and symbols in Scheme.} This section describes what contexts are, and how to modify them. @menu -* Contexts explained:: -* Creating contexts:: -* Changing context properties on the fly:: -* Modifying context plug-ins:: -* Layout tunings within contexts:: -* Changing context default settings:: -* Defining new contexts:: -* Aligning contexts:: -* Vertical grouping of grobs:: +* Contexts explained:: +* Creating contexts:: +* Modifying context plug-ins:: +* Changing context default settings:: +* Defining new contexts:: +* Aligning contexts:: @end menu @node Contexts explained @subsection Contexts explained -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: - -@lilypond[quote,verbatim,relative=2,fragment] -cis4 cis2. g4 -@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 @context{Voice}, -@context{Staff}, and @context{Score}. They are hierarchical, for -example: a @context{Staff} can contain many @context{Voice}s, and a -@context{Score} can contain many @context{Staff} contexts. - -@quotation -@image{context-example,5cm,,} -@end quotation - -Each context has the responsibility for enforcing some notation rules, -creating some notation objects and maintaining the associated -properties. For example, the @context{Voice} context may introduce an -accidental and then the @context{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 @context{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 @context{Score} -and @context{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 -@internalsref{Contexts}. -@end ifhtml -@ifnothtml -Translation @expansion{} Context. -@end ifnothtml +>> > > - list of contexts: my *danger unmaintainable* +>> > > alarm just went off. I'm + +I knew it would... And leaving out some of them is perfectly fine +with me. +I do think that a list like this, with the main contexts and a +brief +description of what they do (perhaps also with a note about what +default +behavior is associated with each of them, but this may be +unmanageable), +should be there, and then we could simply list the remaining ones +without +further explanation and with links to the IR. + + +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 + + * FretBoards + Engraves fretboards from chords. Not easy... Not +documented. + * NoteNames + + * CueVoice Not documented + * Global + Hard coded entry point for LilyPond. Cannot be tuned. + * Devnull + Silently discards all musical information given to this +context. -@c [TODO: describe propagation] @node Creating contexts @@ -239,7 +327,7 @@ music = @{ c4 c4 @} arts = @{ s4-. s4-> @} @end example -They are combined by sending both to the same @context{Voice} context, +They are combined by sending both to the same @code{Voice} context, @example << @@ -276,13 +364,13 @@ any context of type @var{type}, regardless of its given name. This variant is used with music expressions that can be interpreted at several levels. For example, the @code{\applyOutput} command (see @ref{Running a function on all layout objects}). Without an explicit -@code{\context}, it is usually applied to @context{Voice} +@code{\context}, it is usually applied to @code{Voice} @example \applyOutput #'@var{context} #@var{function} % apply to Voice @end example -To have it interpreted at the @context{Score} or @context{Staff} level use +To have it interpreted at the @code{Score} or @code{Staff} level use these forms @example @@ -293,130 +381,6 @@ these forms @end itemize -@node Changing context properties on the fly -@subsection Changing context properties on the fly - -@cindex properties -@funindex \set -@cindex changing properties - -Each context can have different @emph{properties}, variables contained -in that context. They can be changed during the interpretation step. -This is achieved by inserting the @code{\set} command in the music, - -@example -\set @var{context}.@var{prop} = #@var{value} -@end example - -For example, -@lilypond[quote,verbatim,relative=2,fragment] -R1*2 -\set Score.skipBars = ##t -R1*2 -@end lilypond - -This command skips measures that have no notes. The result is that -multi-rests are condensed. The value assigned is a Scheme object. In -this case, it is @code{#t}, the boolean True value. - -If the @var{context} argument is left out, then the current bottom-most -context (typically @context{ChordNames}, @context{Voice}, or -@context{Lyrics}) is used. In this example, - -@lilypond[quote,verbatim,relative=2,fragment] -c8 c c c -\set autoBeaming = ##f -c8 c c c -@end lilypond - -@noindent -the @var{context} argument to @code{\set} is left out, so automatic -beaming is switched off in the current @internalsref{Voice}. Note that -the bottom-most context does not always contain the property that you -wish to change -- for example, attempting to set the @code{skipBars} -property (of the bottom-most context, in this case @code{Voice}) will -have no effect. - -@lilypond[quote,verbatim,relative=2,fragment] -R1*2 -\set skipBars = ##t -R1*2 -@end lilypond - -Contexts are hierarchical, so if a bigger context was specified, for -example @context{Staff}, then the change would also apply to all -@context{Voice}s in the current stave. The change is applied -@q{on-the-fly}, during the music, so that the setting only affects the -second group of eighth notes. - -@funindex \unset - -There is also an @code{\unset} command, -@example -\unset @var{context}.@var{prop} -@end example - -@noindent -which removes the definition of @var{prop}. This command removes -the definition only if it is set in @var{context}, so - -@example -\set Staff.autoBeaming = ##f -@end example - -@noindent -introduces a property setting at @code{Staff} level. The setting also -applies to the current @code{Voice}. However, - -@example -\unset Voice.autoBeaming -@end example - -@noindent -does not have any effect. To cancel this setting, the @code{\unset} -must be specified on the same level as the original @code{\set}. In -other words, undoing the effect of @code{Staff.autoBeaming = ##f} -requires -@example -\unset Staff.autoBeaming -@end example - -Like @code{\set}, the @var{context} argument does not have to be -specified for a bottom context, so the two statements - -@example -\set Voice.autoBeaming = ##t -\set autoBeaming = ##t -@end example - -@noindent -are equivalent. - - -@cindex \once -Settings that should only apply to a single time-step can be entered -with @code{\once}, for example in - -@lilypond[quote,verbatim,relative=2,fragment] -c4 -\once \set fontSize = #4.7 -c4 -c4 -@end lilypond - -the property @code{fontSize} is unset automatically after the second -note. - -A full description of all available context properties is in the -program reference, see -@ifhtml -@internalsref{Tunable context properties}. -@end ifhtml -@ifnothtml -Translation @expansion{} Tunable context properties. -@end ifnothtml - - @node Modifying context plug-ins @subsection Modifying context plug-ins @@ -429,17 +393,17 @@ elements. For example, the @code{Voice} context contains a For a full a description of each plug-in, see @ifhtml -@internalsref{Engravers}. +@rinternals{Engravers and Performers}. @end ifhtml @ifnothtml -Program reference @expansion{} Translation @expansion{} Engravers. +Internals Reference @expansion{} Translation @expansion{} Engravers. @end ifnothtml Every context described in @ifhtml -@internalsref{Contexts} +@rinternals{Contexts} @end ifhtml @ifnothtml -Program reference @expansion{} Translation @expansion{} Context. +Internals Reference @expansion{} Translation @expansion{} Context. @end ifnothtml lists the engravers used for that context. @@ -485,14 +449,14 @@ example which removes @code{Time_signature_engraver} and In the second staff there are no time signature or clef symbols. This is a rather crude method of making objects disappear since it will affect the entire staff. This method also influences the spacing, which may or -may not be desirable. A more -sophisticated method of blanking objects is shown in @rlearning{Common tweaks}. +may not be desirable. More sophisticated methods of blanking objects +are shown in @rlearning{Visibility and color of objects}. The next example shows a practical application. Bar lines and time signatures are normally synchronized across the score. This is done by the @code{Timing_translator} and @code{Default_bar_line_engraver}. This plug-in keeps an administration of time signature, location -within the measure, etc. By moving thes engraver from @code{Score} to +within the measure, etc. By moving these engraver from @code{Score} to @code{Staff} context, we can have a score where each staff has its own time signature. @@ -522,198 +486,89 @@ time signature. @end lilypond -@node Layout tunings within contexts -@subsection Layout tunings within contexts - -Each context is responsible for creating certain types of graphical -objects. The settings used for printing these objects are also stored by -context. By changing these settings, the appearance of objects can be -altered. +@node Changing context default settings +@subsection Changing context default settings -The syntax for this is +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 -\override @var{context}.@var{name} #'@var{property} = #@var{value} -@end example +\layout @{ + @dots{} + \context @{ + \Staff -Here @var{name} is the name of a graphical object, like @code{Stem} or -@code{NoteHead}, and @var{property} is an internal variable of the -formatting system (@q{grob property} or @q{layout property}). The latter is a -symbol, so it must be quoted. The subsection @ref{Constructing a -tweak}, explains what to fill in for @var{name}, @var{property}, and -@var{value}. Here we only discuss the functionality of this command. + \set fontSize = #-2 + \override Stem #'thickness = #4.0 + \remove "Time_signature_engraver" + @} +@} +@end example -The command +The @code{\Staff} command brings in the existing definition of the +staff context so that it can be modified. -@verbatim -\override Staff.Stem #'thickness = #4.0 -@end verbatim +The statements +@example +\set fontSize = #-2 +\override Stem #'thickness = #4.0 +\remove "Time_signature_engraver" +@end example @noindent -makes stems thicker (the default is 1.3, with staff line thickness as a -unit). Since the command specifies @context{Staff} as context, it only -applies to the current staff. Other staves will keep their normal -appearance. Here we see the command in action: +affect all staves in the score. Other contexts can be modified +analogously. -@lilypond[quote,verbatim,relative=2,fragment] -c4 -\override Staff.Stem #'thickness = #4.0 -c4 -c4 -c4 -@end lilypond +The @code{\set} keyword is optional within the @code{\layout} block, so -The @code{\override} command changes the definition of the @code{Stem} -within the current @context{Staff}. After the command is interpreted -all stems are thickened. +@example +\context @{ + @dots{} + fontSize = #-2 +@} +@end example -Analogous to @code{\set}, the @var{context} argument may be left out, -causing the default context @context{Voice} to be used. Adding -@code{\once} applies the change during one timestep only. +@noindent +will also work. -@lilypond[quote,fragment,verbatim,relative=2] -c4 -\once \override Stem #'thickness = #4.0 -c4 -c4 -@end lilypond -The @code{\override} must be done before the object is -started. Therefore, when altering @emph{Spanner} objects such as slurs -or beams, the @code{\override} command must be executed at the moment -when the object is created. In this example, -@lilypond[quote,fragment,verbatim,relative=2] -\override Slur #'thickness = #3.0 -c8[( c -\override Beam #'thickness = #0.6 -c8 c]) -@end lilypond +@knownissues -@noindent -the slur is fatter but the beam is not. This is because the command for -@code{Beam} comes after the Beam is started, so it has no effect. +It is not possible to collect context changes in a variable and apply +them to a @code{\context} definition by referring to that variable. -Analogous to @code{\unset}, the @code{\revert} command for a context -undoes an @code{\override} command; like with @code{\unset}, it only -affects settings that were made in the same context. In other words, the -@code{\revert} in the next example does not do anything. - -@example -\override Voice.Stem #'thickness = #4.0 -\revert Staff.Stem #'thickness -@end example - -Some tweakable options are called @q{subproperties} and reside inside -properties. To tweak those, use commands of the form - -@c leave this as a long long -@example -\override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value} -@end example - -@noindent -such as - -@example -\override Stem #'details #'beamed-lengths = #'(4 4 3) -@end example - - -@seealso - -Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty}, -@internalsref{PropertySet}, @internalsref{Backend}, and -@internalsref{All layout objects}. - - -@refbugs - -The back-end is not very strict in type-checking object properties. -Cyclic references in Scheme values for properties can cause hangs -or crashes, or both. - - -@node Changing context default settings -@subsection Changing context default settings - -The adjustments of the previous subsections (@ref{Changing context -properties on the fly}, @ref{Modifying context plug-ins}, and -@ref{Layout tunings within contexts}) can also be entered separately -from the music in the @code{\layout} block, +The @code{\RemoveEmptyStaffContext} will overwrite your current +@code{\Staff} settings. If you wish to change the defaults for a +staff which uses @code{\RemoveEmptyStaffContext}, you must do so +after calling @code{\RemoveEmptyStaffContext}, ie @example \layout @{ - @dots{} \context @{ - \Staff + \RemoveEmptyStaffContext - \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. - -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. - -The @code{\set} keyword is optional within the @code{\layout} block, so - -@example -\context @{ - @dots{} - fontSize = #-2 -@} -@end example - -@noindent -will also work. - - - -@refbugs - -It is not possible to collect context changes in a variable and apply -them to a @code{\context} definition by referring to that variable. - -The @code{\RemoveEmptyStaffContext} will overwrite your current -@code{\Staff} settings. If you wish to change the defaults for a -staff which uses @code{\RemoveEmptyStaffContext}, you must do so -after calling @code{\RemoveEmptyStaffContext}, ie - -@example -\layout @{ - \context @{ - \RemoveEmptyStaffContext +TODO: add \with in here. - \override Stem #'thickness = #4.0 - @} -@} -@end example @node Defining new contexts @subsection Defining new contexts -Specific contexts, like @context{Staff} and @code{Voice}, are made of +Specific contexts, like @code{Staff} and @code{Voice}, are made of simple building blocks. It is possible to create new types of contexts with different combinations of engraver plug-ins. The next example shows how to build a different type of -@context{Voice} context from scratch. It will be similar to -@code{Voice}, but only prints centered slash noteheads. It can be used +@code{Voice} context from scratch. It will be similar to +@code{Voice}, but only prints centered slash note heads. It can be used to indicate improvisation in jazz pieces, @lilypond[quote,ragged-right] @@ -760,9 +615,9 @@ First it is necessary to define a name for the new context: \name ImproVoice @end example -Since it is similar to the @context{Voice}, we want commands that work -on (existing) @context{Voice}s to remain working. This is achieved by -giving the new context an alias @context{Voice}, +Since it is similar to the @code{Voice}, we want commands that work +on (existing) @code{Voice}s to remain working. This is achieved by +giving the new context an alias @code{Voice}, @example \alias Voice @@ -783,8 +638,8 @@ but we only need this on the center line, squashedPosition = #0 @end example -The @internalsref{Pitch_squash_engraver} modifies note heads (created -by @internalsref{Note_heads_engraver}) and sets their vertical +The @rinternals{Pitch_squash_engraver} modifies note heads (created +by @rinternals{Note_heads_engraver}) and sets their vertical position to the value of @code{squashedPosition}, in this case@tie{}@code{0}, the center line. @@ -797,7 +652,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 @internalsref{Engraver_group}, +This should always be @rinternals{Engraver_group}, @example \type "Engraver_group" @@ -820,8 +675,8 @@ Put together, we get @end example @funindex \accepts -Contexts form hierarchies. We want to hang the @context{ImproVoice} -under @context{Staff}, just like normal @code{Voice}s. Therefore, we +Contexts form hierarchies. We want to hang the @code{ImproVoice} +under @code{Staff}, just like normal @code{Voice}s. Therefore, we modify the @code{Staff} definition with the @code{\accepts} command, @@ -869,10 +724,12 @@ Then the output at the start of this subsection can be entered as @node Aligning contexts @subsection Aligning contexts -New contexts may be aligned above or below exisiting contexts. This +New contexts may be aligned above or below existing contexts. This could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and in ossia, +FIXME: this section doesn't work in pdf. (?) + @cindex ossia @findex alignAboveContext @findex alignBelowContext @@ -891,89 +748,17 @@ ossia = { f4 f f f } @end lilypond -@node Vertical grouping of grobs -@subsection Vertical grouping of grobs - -The VerticalAlignment and VerticalAxisGroup grobs work together. -VerticalAxisGroup groups together different grobs like Staff, Lyrics, -etc. VerticalAlignment then vertically aligns the different grobs -grouped together by VerticalAxisGroup. There is usually only one -VerticalAlignment per score but every Staff, Lyrics, etc. has its own -VerticalAxisGroup. - - -@node The \override command -@section The @code{\override} command - -In the previous section, we have already touched on a command that -changes layout details: the @code{\override} command. In this section, -we will look in more detail at how to use the command in practice. The -general syntax of this command is: - -@example -\override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value} -@end example +@node Explaining the Internals Reference +@section Explaining the Internals Reference -This will set the @var{layout_property} of the specified @var{layout_object}, -which is a member of the @var{context}, to the @var{value}. @menu -* Constructing a tweak:: * Navigating the program reference:: * Layout interfaces:: * Determining the grob property:: -* Objects connected to the input:: -* Using Scheme code instead of \tweak:: -* \set versus \override:: -* Difficult tweaks:: +* Naming conventions:: @end menu - - -@node Constructing a tweak -@subsection Constructing a tweak - -Commands which change output generally look like - -@example -\override Voice.Stem #'thickness = #3.0 -@end example - -@noindent -To construct this tweak we must determine these bits of information: - -@itemize -@item the context: here @context{Voice}. -@item the layout object: here @code{Stem}. -@item the layout property: here @code{thickness}. -@item a sensible value: here @code{3.0}. -@end itemize - -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) -@end example - -@cindex internal documentation -@cindex finding graphical objects -@cindex graphical object descriptions -@cindex tweaking -@funindex \override -@cindex internal documentation - -For many properties, regardless of the data type of the property, setting the -property to false ( @code{##f} ) will result in turning it off, causing -Lilypond to ignore that property entirely. This is particularly useful for -turning off grob properties which may otherwise be causing problems. - -We demonstrate how to glean this information from the notation manual -and the program reference. - - - - @node Navigating the program reference @subsection Navigating the program reference @@ -990,9 +775,9 @@ If you visit the documentation on fingering instructions (in @ref{Fingering instructions}), you will notice: @quotation -@seealso +@strong{See also} -Program reference: @internalsref{Fingering}. +Internals Reference: @rinternals{Fingering}. @end quotation @@ -1007,7 +792,7 @@ expression for the input @code{-2}. The page contains many links forward. For example, it says @quotation -Accepted by: @internalsref{Fingering_engraver}, +Accepted by: @rinternals{Fingering_engraver}, @end quotation @noindent @@ -1015,7 +800,7 @@ That link brings us to the documentation for the Engraver, the plug-in, which says @quotation -This engraver creates the following layout objects: @internalsref{Fingering}. +This engraver creates the following layout objects: @rinternals{Fingering}. @end quotation In other words, once the @code{FingerEvent}s are interpreted, the @@ -1026,7 +811,7 @@ In other words, once the @code{FingerEvent}s are interpreted, the @c I can't figure out what this is supposed to mean. -gp The @code{Fingering_engraver} is also listed to create -@internalsref{Fingering} objects, +@rinternals{Fingering} objects, @c old info? it doesn't make any sense to me with our current docs. This is also the @@ -1042,12 +827,12 @@ difficult to understand if you are using the PDF manual. @end ifnothtml -Follow the link to @internalsref{Fingering}. At the top of the +Follow the link to @rinternals{Fingering}. At the top of the page, you will see @quotation -Fingering objects are created by: @internalsref{Fingering_engraver} and -@internalsref{New_fingering_engraver}. +Fingering objects are created by: @rinternals{Fingering_engraver} and +@rinternals{New_fingering_engraver}. @end quotation By following related links inside the program reference, we can follow the @@ -1055,16 +840,16 @@ flow of information within the program: @itemize -@item @internalsref{Fingering}: -@internalsref{Fingering} objects are created by: -@internalsref{Fingering_engraver} +@item @rinternals{Fingering}: +@rinternals{Fingering} objects are created by: +@rinternals{Fingering_engraver} -@item @internalsref{Fingering_engraver}: -Music types accepted: @internalsref{fingering-event} +@item @rinternals{Fingering_engraver}: +Music types accepted: @rinternals{fingering-event} -@item @internalsref{fingering-event}: +@item @rinternals{fingering-event}: Music event type @code{fingering-event} is in Music expressions named -@internalsref{FingerEvent} +@rinternals{FingerEvent} @end itemize This path goes against the flow of information in the program: it @@ -1075,12 +860,12 @@ information, eventually ending up at the output object(s). The program reference can also be browsed like a normal document. It contains chapters on @ifhtml -@internalsref{Music definitions}, +@rinternals{Music definitions}, @end ifhtml @ifnothtml @code{Music definitions} @end ifnothtml -on @internalsref{Translation}, and the @internalsref{Backend}. Every +on @rinternals{Translation}, and the @rinternals{Backend}. Every chapter lists all the definitions used and all properties that may be tuned. @@ -1093,11 +878,11 @@ tuned. @cindex grob The HTML page that we found in the previous section describes the -layout object called @internalsref{Fingering}. Such an object is a +layout object called @rinternals{Fingering}. Such an object is a symbol within the score. It has properties that store numbers (like thicknesses and directions), but also pointers to related objects. A layout object is also called a @emph{Grob}, which is short for Graphical -Object. For more details about Grobs, see @internalsref{grob-interface}. +Object. For more details about Grobs, see @rinternals{grob-interface}. The page for @code{Fingering} lists the definitions for the @code{Fingering} object. For example, the page says @@ -1129,7 +914,7 @@ That piece of text is typeset with a font, unlike slurs or beams. @item Horizontally, the center of the symbol should be aligned to the -center of the notehead. +center of the note head. @item Vertically, the symbol is placed next to the note and the staff. @@ -1140,15 +925,15 @@ and subscript symbols. @end itemize Each of these aspects is captured in so-called @emph{interface}s, -which are listed on the @internalsref{Fingering} page at the bottom +which are listed on the @rinternals{Fingering} page at the bottom @quotation This object supports the following interfaces: -@internalsref{item-interface}, -@internalsref{self-alignment-interface}, -@internalsref{side-position-interface}, @internalsref{text-interface}, -@internalsref{text-script-interface}, @internalsref{font-interface}, -@internalsref{finger-interface}, and @internalsref{grob-interface}. +@rinternals{item-interface}, +@rinternals{self-alignment-interface}, +@rinternals{side-position-interface}, @rinternals{text-interface}, +@rinternals{text-script-interface}, @rinternals{font-interface}, +@rinternals{finger-interface}, and @rinternals{grob-interface}. @end quotation Clicking any of the links will take you to the page of the respective @@ -1158,7 +943,7 @@ can be modified. We have been talking of @emph{the} @code{Fingering} object, but actually it does not amount to much. The initialization file (see -@rlearning{Default files}) +@rlearning{Other sources of information}) @file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object}, @example @@ -1186,7 +971,7 @@ does not amount to much. The initialization file (see @noindent As you can see, the @code{Fingering} object is nothing more than a -bunch of variable settings, and the webpage in the Program Reference +bunch of variable settings, and the webpage in the Internals Reference is directly generated from this definition. @@ -1228,7 +1013,7 @@ Add this much extra space between objects that are next to each other. @end quotation By increasing the value of @code{padding}, we can move the -fingering away from the notehead. The following command inserts +fingering away from the note head. The following command inserts 3 staff spaces of white between the note and the fingering: @example @@ -1246,110 +1031,334 @@ f @end lilypond -In this case, the context for this tweak is @context{Voice}. This +In this case, the context for this tweak is @code{Voice}. This fact can also be deduced from the program reference, for the page for -the @internalsref{Fingering_engraver} plug-in says +the @rinternals{Fingering_engraver} plug-in says @quotation -Fingering_engraver is part of contexts: @dots{} @internalsref{Voice} +Fingering_engraver is part of contexts: @dots{} @rinternals{Voice} @end quotation -@node Objects connected to the input -@subsection Objects connected to the input +@node Naming conventions +@subsection Naming conventions -@funindex \tweak +Another thing that is needed, is an overview of the various naming +conventions: -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 + scheme functions: lowercase-with-hyphens (incl. one-word +names) + scheme functions: ly:plus-scheme-style + music events, music classes and music properties: +as-scheme-functions + Grob interfaces: scheme-style + backend properties: scheme-style (but X and Y!) + contexts (and MusicExpressions and grobs): Capitalized or +CamelCase + context properties: lowercaseFollowedByCamelCase + engravers: +Capitalized_followed_by_lowercase_and_with_underscores -@lilypond[relative=2,fragment,verbatim,ragged-right] -< - c - \tweak #'color #red d - g - \tweak #'duration-log #1 a ->4-\tweak #'padding #10 -. -@end lilypond +Which of these are conventions and which are rules? +Which are rules of the underlying language, and which are +LP-specific? -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 @internalsref{Event} from the input, for example +@node Modifying properties +@section Modifying properties -@itemize -@item note heads, caused by chord-pitch (i.e., notes inside a chord) -@item articulation signs, caused by articulation instructions -@end itemize +@menu +* Overview of modifying properties:: +* The \set command:: +* The \override command:: +* \set versus \override:: +* Objects connected to the input:: +@end menu -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 +@node Overview of modifying properties +@subsection Overview of modifying properties + +Each context is responsible for creating certain types of graphical +objects. The settings used for printing these objects are also stored by +context. By changing these settings, the appearance of objects can be +altered. + +The syntax for this is @example -\tweak #'color #red c4 +\override @var{context}.@var{name} #'@var{property} = #@var{value} @end example +Here @var{name} is the name of a graphical object, like +@code{Stem} or @code{NoteHead}, and @var{property} is an internal +variable of the formatting system (@q{grob property} or @q{layout +property}). The latter is a symbol, so it must be quoted. The +subsection @ref{Modifying properties}, explains what to fill in +for @var{name}, @var{property}, and @var{value}. Here we only +discuss the functionality of this command. + +The command + +@verbatim +\override Staff.Stem #'thickness = #4.0 +@end verbatim + @noindent -does not change color. See @ref{Displaying music expressions}, for -details. +makes stems thicker (the default is 1.3, with staff line thickness as a +unit). Since the command specifies @code{Staff} as context, it only +applies to the current staff. Other staves will keep their normal +appearance. Here we see the command in action: +@lilypond[quote,verbatim,relative=2,fragment] +c4 +\override Staff.Stem #'thickness = #4.0 +c4 +c4 +c4 +@end lilypond -@node Using Scheme code instead of \tweak -@subsection Using Scheme code instead of @code{\tweak} +The @code{\override} command changes the definition of the @code{Stem} +within the current @code{Staff}. After the command is interpreted +all stems are thickened. -The main disadvantage of @code{\tweak} is its syntactical -inflexibility. For example, the following produces a syntax error. +Analogous to @code{\set}, the @var{context} argument may be left out, +causing the default context @code{Voice} to be used. Adding +@code{\once} applies the change during one timestep only. -@example -F = \tweak #'font-size #-3 -\flageolet +@lilypond[quote,fragment,verbatim,relative=2] +c4 +\once \override Stem #'thickness = #4.0 +c4 +c4 +@end lilypond -\relative c'' @{ - c4^\F c4_\F -@} -@end example +The @code{\override} must be done before the object is +started. Therefore, when altering @emph{Spanner} objects such as slurs +or beams, the @code{\override} command must be executed at the moment +when the object is created. In this example, + +@lilypond[quote,fragment,verbatim,relative=2] +\override Slur #'thickness = #3.0 +c8[( c +\override Beam #'thickness = #0.6 +c8 c]) +@end lilypond @noindent -With other words, @code{\tweak} doesn't behave like an articulation -regarding the syntax; in particular, it can't be attached with -@samp{^} and @samp{_}. +the slur is fatter but the beam is not. This is because the command for +@code{Beam} comes after the Beam is started, so it has no effect. -Using Scheme, this problem can be circumvented. The route to the -result is given in @ref{Adding articulation to notes (example)}, -especially how to use @code{\displayMusic} as a helping guide. +Analogous to @code{\unset}, the @code{\revert} command for a context +undoes an @code{\override} command; like with @code{\unset}, it only +affects settings that were made in the same context. In other words, the +@code{\revert} in the next example does not do anything. @example -F = #(let ((m (make-music 'ArticulationEvent - 'articulation-type "flageolet"))) - (set! (ly:music-property m 'tweaks) - (acons 'font-size -3 - (ly:music-property m 'tweaks))) - m) - -\relative c'' @{ - c4^\F c4_\F -@} +\override Voice.Stem #'thickness = #4.0 +\revert Staff.Stem #'thickness @end example -@noindent -Here, the @code{tweaks} properties of the flageolet object -@samp{m} (created with @code{make-music}) are extracted with -@code{ly:music-property}, a new key-value pair to change the -font size is prepended to the property list with the -@code{acons} Scheme function, and the result is finally -written back with @code{set!}. The last element of the -@code{let} block is the return value, @samp{m} itself. +Some tweakable options are called @q{subproperties} and reside inside +properties. To tweak those, use commands of the form +@c leave this as a long long +@example +\override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value} +@end example -@node \set versus \override -@subsection @code{\set} vs. @code{\override} +@noindent +such as + +@example +\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}. + + +@knownissues + +The back-end is not very strict in type-checking object properties. +Cyclic references in Scheme values for properties can cause hangs +or crashes, or both. + + + +@node The \set command +@subsection The @code{\set} command + +@cindex properties +@funindex \set +@cindex changing properties + +Each context can have different @emph{properties}, variables contained +in that context. They can be changed during the interpretation step. +This is achieved by inserting the @code{\set} command in the music, + +@example +\set @var{context}.@var{prop} = #@var{value} +@end example + +For example, +@lilypond[quote,verbatim,relative=2,fragment] +R1*2 +\set Score.skipBars = ##t +R1*2 +@end lilypond + +This command skips measures that have no notes. The result is that +multi-rests are condensed. The value assigned is a Scheme object. In +this case, it is @code{#t}, the boolean True value. + +If the @var{context} argument is left out, then the current bottom-most +context (typically @code{ChordNames}, @code{Voice}, or +@code{Lyrics}) is used. In this example, + +@lilypond[quote,verbatim,relative=2,fragment] +c8 c c c +\set autoBeaming = ##f +c8 c c c +@end lilypond + +@noindent +the @var{context} argument to @code{\set} is left out, so automatic +beaming is switched off in the current @rinternals{Voice}. Note that +the bottom-most context does not always contain the property that you +wish to change -- for example, attempting to set the @code{skipBars} +property (of the bottom-most context, in this case @code{Voice}) will +have no effect. + +@lilypond[quote,verbatim,relative=2,fragment] +R1*2 +\set skipBars = ##t +R1*2 +@end lilypond + +Contexts are hierarchical, so if a bigger context was specified, for +example @code{Staff}, then the change would also apply to all +@code{Voice}s in the current stave. The change is applied +@q{on-the-fly}, during the music, so that the setting only affects the +second group of eighth notes. + +@funindex \unset + +There is also an @code{\unset} command, +@example +\unset @var{context}.@var{prop} +@end example + +@noindent +which removes the definition of @var{prop}. This command removes +the definition only if it is set in @var{context}, so + +@example +\set Staff.autoBeaming = ##f +@end example + +@noindent +introduces a property setting at @code{Staff} level. The setting also +applies to the current @code{Voice}. However, + +@example +\unset Voice.autoBeaming +@end example + +@noindent +does not have any effect. To cancel this setting, the @code{\unset} +must be specified on the same level as the original @code{\set}. In +other words, undoing the effect of @code{Staff.autoBeaming = ##f} +requires +@example +\unset Staff.autoBeaming +@end example + +Like @code{\set}, the @var{context} argument does not have to be +specified for a bottom context, so the two statements + +@example +\set Voice.autoBeaming = ##t +\set autoBeaming = ##t +@end example + +@noindent +are equivalent. + + +@cindex \once +Settings that should only apply to a single time-step can be entered +with @code{\once}, for example in + +@lilypond[quote,verbatim,relative=2,fragment] +c4 +\once \set fontSize = #4.7 +c4 +c4 +@end lilypond + +the property @code{fontSize} is unset automatically after the second +note. + +A full description of all available context properties is in the +program reference, see +@ifhtml +@rinternals{Tunable context properties}. +@end ifhtml +@ifnothtml +Translation @expansion{} Tunable context properties. +@end ifnothtml + + + +@node The \override command +@subsection The @code{\override} command + +Commands which change output generally look like + +@example +\override Voice.Stem #'thickness = #3.0 +@end example + +@noindent +To construct this tweak we must determine these bits of information: + +@itemize +@item the context: here @code{Voice}. +@item the layout object: here @code{Stem}. +@item the layout property: here @code{thickness}. +@item a sensible value: here @code{3.0}. +@end itemize + +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) +@end example + +@cindex internal documentation +@cindex finding graphical objects +@cindex graphical object descriptions +@cindex tweaking +@funindex \override +@cindex internal documentation + +For many properties, regardless of the data type of the property, setting the +property to false ( @code{##f} ) will result in turning it off, causing +LilyPond to ignore that property entirely. This is particularly useful for +turning off grob properties which may otherwise be causing problems. + +We demonstrate how to glean this information from the notation manual +and the program reference. + + +@node \set versus \override +@subsection @code{\set} vs. @code{\override} We have seen two methods of changing properties: @code{\set} and @code{\override}. There are actually two different kinds of @@ -1357,9 +1366,9 @@ properties. Contexts can have properties, which are usually named in @code{studlyCaps}. They mostly control the translation from -music to notatino, eg. @code{localKeySignature} (for determining +music to notation, eg. @code{localKeySignature} (for determining whether to print accidentals), @code{measurePosition} (for -determining when to print a barline). Context properties can +determining when to print a bar line). Context properties can change value over time while interpreting a piece of music; @code{measurePosition} is an obvious example of this. Context properties are modified with @code{\set}. @@ -1386,7 +1395,7 @@ is more or less equivalent to \set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) 4-\tweak #'padding #10 -. +@end lilypond -In other words, an @code{\override} always affects all pieces of a -broken spanner. To change only one part of a spanner at a line break, -it is necessary to hook into the formatting process. The -@code{after-line-breaking} callback contains the Scheme procedure that -is called after the line breaks have been determined, and layout -objects have been split over different systems. +As you can see, properties are set in the objects directly, +without mentioning the grob name or context where this should be +applied. -In the following example, we define a procedure -@code{my-callback}. This procedure +This technique only works for objects that are directly connected to +an @rinternals{Event} from the input, for example @itemize -@item -determines if we have been split across line breaks -@item -if yes, retrieves all the split objects -@item -checks if we are the last of the split objects -@item -if yes, it sets @code{extra-offset}. +@item note heads, caused by chord-pitch (i.e., notes inside a chord) +@item articulation signs, caused by articulation instructions @end itemize -This procedure is installed into @internalsref{Tie}, so the last part -of the broken tie is translated up. +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 -@lilypond[quote,verbatim,ragged-right] -#(define (my-callback grob) - (let* ( - ; have we been split? - (orig (ly:grob-original grob)) +@example +\tweak #'color #red c4 +@end example + +@noindent +does not change color. See @ref{Displaying music expressions}, for +details. - ; if yes, get the split pieces (our siblings) - (siblings (if (ly:grob? orig) - (ly:spanner-broken-into orig) '() ))) - (if (and (>= (length siblings) 2) - (eq? (car (last-pair siblings)) grob)) - (ly:grob-set-property! grob 'extra-offset '(-2 . 5))))) +@node Useful concepts and properties +@section Useful concepts and properties -\relative c'' { - \override Tie #'after-line-breaking = - #my-callback - c1 ~ \break c2 ~ c + +@menu +* Input modes:: +* Direction and placement:: +* Distances and measurements:: +* Spanners:: +@end menu + +@node Input modes +@subsection Input modes + +The way in which the notation contained within an input file is +interpreted is determined by the current input mode. + +@strong{Chord mode} + +This is activated with the @code{\chordmode} command, and causes +input to be interpreted with the syntax of chord notation, see +@ref{Chord notation}. Chords are rendered as notes on a staff. + +Chord mode is also activated with the @code{\chords} command. +This also creates a new @code{ChordNames} context and +causes the following input to be interpreted with the syntax of +chord notation and rendered as chord names in the @code{ChordNames} +context, see @ref{Printing chord names}. + +@strong{Drum mode} + +This is activated with the @code{\drummode} command, and causes +input to be interpreted with the syntax of drum notation, see +@ref{Basic percussion notation}. + +Drum mode is also activated with the @code{\drums} command. +This also creates a new @code{DrumStaff} context and causes the +following input to be interpreted with the syntax of drum notation +and rendered as drum symbols on a drum staff, see @ref{Basic +percussion notation}. + +@strong{Figure mode} + +This is activated with the @code{\figuremode} command, and causes +input to be interpreted with the syntax of figured bass, see +@ref{Entering figured bass}. + +Figure mode is also activated with the @code{\figures} command. +This also creates a new @code{FiguredBass} context and causes the +following input to be interpreted with the figured bass syntax +and rendered as figured bass symbols in the @code{FiguredBass} +context, see @ref{Introduction to figured bass}. + +@strong{Fret and tab modes} + +There are no special input modes for entering fret and tab symbols. + +To create tab diagrams, enter notes or chords in note mode and +render them in a @code{TabStaff} context, see +@ref{Default tablatures}. + +To create fret diagrams above a staff, enter them as markup +above the notes using the @code{\fret-diagram} command, see +@ref{Fret diagrams}. + +@strong{Lyrics mode} + +This is activated with the @code{\lyricmode} command, and causes +input to be interpreted as lyric syllables with optional durations +and associated lyric modifiers, see @ref{Vocal music}. + +Lyric mode is also activated with the @code{\addlyrics} command. +This also creates a new @code{Lyrics} context and an implicit +@code{\lyricsto} command which associates the following lyrics +with the preceding music. + +@strong{Markup mode} + +This is activated with the @code{\markup} command, and causes +input to be interpreted with the syntax of markup, see +@ref{Text markup commands}. + +@c silly work-around for texinfo broken-ness +@c (@strong{Note...} causes a spurious cross-reference in Info) +@b{Note mode} + +This is the default mode or it may be activated with the +@code{\notemode} command. Input is interpreted as pitches, +durations, markup, etc and typeset as musical notation on a staff. + +It is not normally necessary to specify note mode explicitly, but +it may be useful to do so in certain situations, for example if you +are in lyric mode, chord mode or any other mode and want to insert +something that only can be done with note mode syntax. + +For example, to indicate dynamic markings for the verses of a +choral pieces it is necessary to enter note mode to interpret +the markings: + +@lilypond[verbatim,relative=2,quote] +{ c4 c4 c4 c4 } +\addlyrics { + \notemode{\set stanza = \markup{ \dynamic f 1. } } + To be sung loudly +} +\addlyrics { + \notemode{\set stanza = \markup{ \dynamic p 2. } } + To be sung quietly } @end lilypond + + +@node Direction and placement +@subsection Direction and placement + +In typesetting music the direction and placement of many items is +a matter of choice. For example, the stems of notes can +be directed up or down; lyrics, dynamics, and other expressive +marks may be placed above or below the staff; text may be aligned +left, right or center; etc. Most of these choices may be left to +be determined automatically by LilyPond, but in some cases it may +be desirable to force a particular direction or placement. + +@strong{Default actions} + +By default some directions are always up or always down (e.g. +dynamics or fermata), while other things can alternate between +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. + +@c TODO Add example ? + +The default order in which contexts are laid out can be changed, +see @ref{Aligning contexts} + +@strong{Articulation direction indicators} + +When adding articulations to notes the direction indicator, +@code{^} (meaning @qq{up}), @code{_} (meaning @qq{down}) or +@code{-} (meaning @qq{use default direction}), can usually be +omitted, in which case @code{-} is assumed. But a direction +indicator is @strong{always} required before + +@itemize +@item @code{\tweak} commands +@item @code{\markup} commands +@item @code{\tag} commands +@item string markups, e.g. -"string" +@item fingering instructions, e.g. @code{-1} +@item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--} +@end itemize + +@strong{The direction property} + +The position or direction of many layout objects is controlled +by the @code{direction} property. + +The value of the @code{direction} property may be +set to @code{1}, meaning @qq{up} or @qq{above}, or to @code{-1}, +meaning @qq{down} or @qq{below}. The symbols @code{UP} and +@code{DOWN} may be used instead of @code{1} and @code{-1} +respectively. The default direction may be specified by setting +@code{direction} to @code{0} or @code{CENTER}. Alternatively, +in many cases predefined commands +exist to specify the direction. These are all of the form + @noindent -When applying this trick, the new @code{after-line-breaking} callback -should also call the old one @code{after-line-breaking}, if there is -one. For example, if using this with @code{Hairpin}, -@code{ly:hairpin::after-line-breaking} should also be called. +@code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral} + +@noindent +where @code{xxxNeutral} means @qq{use the default direction}. +See @rlearning{Within-staff objects}. + +In a few cases, arpeggio being the only common example, the value +of the @code{direction} property specifies whether the object +is to be placed to the right or left of the parent object. In +this case @code{-1} or @code{LEFT} means @qq{to the left} and +@code{1} or @code{RIGHT} means @qq{to the right}. @code{0} +or @code{CENTER} means @qq{use the default} direction, as before. + +@ignore +These all have side-axis set to #X +AmbitusAccidental - direction has no effect +Arpeggio - works +StanzaNumber - not tried +TrillPitchAccidental - not tried +TrillPitchGroup - not tried +@end ignore + + + +@node Distances and measurements +@subsection Distances and measurements + +DISCUSS after working on other sections. + +TODO: staff spaces. Maybe move into tweaks? + + +@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. + + +@node Common properties +@section Common properties + +@menu +* Controlling visibility of objects:: +* Line styles:: +* Rotating objects:: +* Aligning objects:: +@end menu + +@node Controlling visibility of objects +@subsection Controlling visibility of objects + + +@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. + +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. + +Here is an example of 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 information that determines the end-points is computed +on-the-fly for every graphic object, but it is possible to +override these. + +@lilypond[relative=2,ragged-right,verbatim,fragment] +e2 \glissando f +\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}. + +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 + +FIXME: should this be in NR 3? + +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 \!. -@item Some objects cannot be changed with @code{\override} for -technical reasons. Examples of those are @code{NonMusicalPaperColumn} -and @code{PaperColumn}. They can be changed with the -@code{\overrideProperty} function, which works similar to @code{\once -\override}, but uses a different syntax. + + +@seealso + +Internals Reference: @rinternals{TextSpanner}, +@rinternals{Glissando}, @rinternals{VoiceFollower}, +@rinternals{TrillSpanner}, +@rinternals{line-spanner-interface}. + + +@node Rotating objects +@subsection Rotating objects + +@node Aligning objects +@subsection Aligning objects + + +@node Advanced tweaks +@section Advanced tweaks + +@menu +* Vertical grouping of grobs:: +* Modifying ends of spanners:: +* Modifying stencils:: +@end menu + + + + +@node Vertical grouping of grobs +@subsection Vertical grouping of grobs + +The VerticalAlignment and VerticalAxisGroup grobs work together. +VerticalAxisGroup groups together different grobs like Staff, Lyrics, +etc. VerticalAlignment then vertically aligns the different grobs +grouped together by VerticalAxisGroup. There is usually only one +VerticalAlignment per score but every Staff, Lyrics, etc. has its own +VerticalAxisGroup. + + +@node Modifying ends of spanners +@subsection Modifying ends of spanners + + +@node Modifying stencils +@subsection Modifying stencils + + + +@node old The \override command +@section old The @code{\override} command + +In the previous section, we have already touched on a command that +changes layout details: the @code{\override} command. In this section, +we will look in more detail at how to use the command in practice. The +general syntax of this command is: @example -\overrideProperty -#"Score.NonMusicalPaperColumn" % Grob name -#'line-break-system-details % Property name -#'((next-padding . 20)) % Value +\override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value} @end example -Note, however, that @code{\override}, applied to -@code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as -expected within @code{\context} blocks. +This will set the @var{layout_property} of the specified @var{layout_object}, +which is a member of the @var{context}, to the @var{value}. + + + + + +@node Discussion of specific tweaks +@section Discussion of specific tweaks + +@menu +* old Contexts explained:: +@end menu + + +@node old Contexts explained +@subsection old Contexts explained + +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: + +@lilypond[quote,verbatim,relative=2,fragment] +cis4 cis2. g4 +@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 + +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 + +@c [TODO: describe propagation] + + -@end itemize