X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fchanging-defaults.itely;h=336b4c9d23c290adbcc1e470932124012644df26;hb=150ff905539154877da98ae5d59fcf8938dcda97;hp=7d5fd57dcbafe1d12eb08622833ecf61b85b000e;hpb=c53d0cabdf9361e448cdd02a338aa5d696f4f466;p=lilypond.git diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely index 7d5fd57dcb..b0497e7d0d 100644 --- a/Documentation/user/changing-defaults.itely +++ b/Documentation/user/changing-defaults.itely @@ -1,1626 +1,1659 @@ -@c -*-texinfo-*- +@c -*- coding: utf-8; mode: texinfo; -*- @node Changing defaults @chapter Changing defaults -TODO: reorganise. + +The purpose of LilyPond's design is to provide the finest output +quality as a default. Nevertheless, it may happen that you need to +change this default layout. The layout is controlled through a large +number of proverbial ``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. + + +@cindex Program reference + +The controls available for tuning are described in a separate +document, the @internalsref{Program reference} manual. That manual +lists all different variables, functions and options available in +LilyPond. It is written as a HTML document, which is available +@uref{http://@/lilypond@/.org/@/doc/@/Documentation/@/user/@/out@/-www/@/lilypond@/-internals/,on@/-line}, +but is also included with the LilyPond documentation package. + +There are three areas where the default settings may be changed: + +@itemize @bullet +@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 +Global layout: changing the appearance of the spacing, line +breaks, and page dimensions. +@end itemize + +Then there are separate systems for typesetting text (like +@emph{ritardando}) and selecting different fonts. This chapter also +discusses these. + +Internally, LilyPond uses Scheme (a LISP dialect) to provide +infrastructure. Overriding layout decisions in effect accesses the +program internals, which requires Scheme input. Scheme elements are +introduced in a @code{.ly} file with the hash mark +@code{#}.@footnote{@ref{Scheme tutorial} contains a short tutorial +on entering numbers, lists, strings, and symbols in Scheme.} + @menu -* Scheme integration:: -* Setting variables:: -* Fine tuning layout:: -* Tuning output:: +* Interpretation contexts:: +* The \override command:: +* Fonts:: * Text markup:: -* Global layout:: -* Interpretation context:: -* Output details:: @end menu + +@node Interpretation contexts +@section Interpretation contexts +When music is printed, a lot of notational elements must be added to the +input, which is often bare bones. For example, compare the input and +output of the following example: -@node Scheme integration -@section Scheme integration - -@cindex Scheme -@cindex GUILE -@cindex Scheme, in-line code -@cindex accessing Scheme -@cindex evaluating Scheme -@cindex LISP +@lilypond[quote,verbatim,relative=2,fragment] +cis4 cis2. g4 +@end lilypond -LilyPond internally uses GUILE, a Scheme-interpreter, to represent -data throughout the whole program, and glue together different program -modules. For advanced usage, it is sometimes necessary to access and -program the Scheme interpreter. +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 what +pitches need 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 +so-called Contexts. Examples of context 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. + +Each context has the responsibility for enforcing some notation rules, +creating some notation objects and maintaining the associated +properties. So, the synchronization of bar lines is handled at +@context{Score} context. The @context{Voice} 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. + +For simple scores, contexts are created implicitly, and you need not +be aware of them. For larger pieces, such as piano music, 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 @arrow{} Context. +@end ifnothtml -Scheme is a full-blown programming language, from the LISP -family. and a full discussion is outside the scope of this document. -Interested readers are referred to the website -@uref{http://www.schemers.org/} for more information on Scheme. +@c [TODO: describe propagation] -The GUILE library for extension is documented at -@uref{http://www.gnu.org/software/guile}. -@ifinfo -When it is installed, the following link should take you to its manual -@ref{(guile.info)guile} -@end ifinfo @menu -* Inline Scheme:: +* Creating contexts:: +* Changing context properties on the fly:: +* Modifying context plug-ins:: +* Layout tunings within contexts:: +* Changing context default settings:: +* Defining new contexts:: @end menu -@node Inline Scheme -@subsection Inline Scheme +@node Creating contexts +@subsection Creating contexts -Scheme expressions can be entered in the input file by entering a -hash-sign (@code{#}). The expression following the hash-sign is -evaluated as Scheme. For example, the boolean value @var{true} is -@code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t}, -and can be used in property assignments: -@example - \set Staff.autoBeaming = ##f -@end example +For scores with only one voice and one staff, correct contexts are +created automatically. For more complex scores, it is necessary to +create them by hand. There are three commands that do this. +The easiest command is @code{\new}, and it also the quickest to type. +It is prepended to a music expression, for example -@node Setting variables -@section Setting variables +@cindex @code{\new} +@cindex new contexts +@cindex Context, creating -When the music is converted from notes to print it is interpreted -in left-to-right order. This is similar to what happens when we read -music. During this step context-sensitive information such as the -accidentals to print, and where bar lines must be placed, are stored in -variables. These variables are called @emph{context properties}. -The properties can also be manipulated from input files. Consider this input: @example -\set Staff.autoBeaming = ##f -@end example +\new @var{type} @var{music expression} +@end example @noindent -It sets the property named @code{autoBeaming} in the current staff at -this point in the music to @code{##f}, which means `false'. This -property controls whether beams are printed automatically: -@c -@lilypond[relative=1,fragment,verbatim] - c8 c c c - \set Staff.autoBeaming = ##f - c8 c c c +where @var{type} is a context name (like @code{Staff} or +@code{Voice}). This command creates a new context, and starts +interpreting the @var{music expression} with that. + +A practical application of @code{\new} is a score with many +staves. Each part that should be on its own staff, is preceded with +@code{\new Staff}. + +@lilypond[quote,verbatim,relative=2,raggedright,fragment] +<< \new Staff { c4 c } + \new Staff { d4 d } +>> @end lilypond -@noindent -LilyPond includes a built-in programming language, namely, a dialect -of Scheme. The argument to @code{\set}, @code{##f}, is an -expression in that language. The first hash-mark signals that a piece -of Scheme code follows. The second hash character is part of the -boolean value true (@code{#t}). Values of other types may be -entered as follows: -@itemize @bullet -@item a string, enclosed in double quotes, for example, +@cindex @code{\context} + +Like @code{\new}, the @code{\context} command also directs a music +expression to a context object, but gives the context an extra name. The +syntax is + @example - \set Staff.instrument = #"French Horn" +\context @var{type} = @var{id} @var{music} @end example -@item a boolean: either @code{#t} or @code{#f}, for true and false -respectively, e.g. + +This form will search for an existing context of type @var{type} +called @var{id}. If that context does not exist yet, it is created. +This is useful if the context is referred to later on. For example, when +setting lyrics the melody is in a named context + @example - \set autoBeaming = ##f - \set Score.skipBars = ##t +\CONtext Voice = "@b{tenor}" @var{music} @end example -@item a number, such as +@noindent +so the texts can be properly aligned to its notes, + @example - \set Score.currentBarNumber = #20 +\new Lyrics \lyricsto "@b{tenor}" @var{lyrics} @end example -@item a symbol, which is introduced by a quote character, as in +@noindent + +Another possibility is funneling two different music expressions into +one context. In the following example, articulations and notes are +entered separately, + @example - \set Staff.crescendoSpanner = #'dashed-line +music = @{ c4 c4 @} +arts = @{ s4-. s4-> @} @end example -@item a pair, which is also introduced by a quote character, like in -the following statements, which set properties to the pairs (-7.5, 6) -and (3, 4) respectively: +They are combined by sending both to the same @context{Voice} context, @example - \set Staff.minimumVerticalExtent = #'(-7.5 . 6) - \set Staff.timeSignatureFraction = #'(3 . 4) +<< \new Staff \context Voice = "A" \music + \context Voice = "A" \arts +>> @end example +@lilypond[quote,raggedright] +music = { c4 c4 } +arts = { s4-. s4-> } +\relative c'' << + \new Staff \context Voice = "A" \music + \context Voice = "A" \arts +>> +@end lilypond -@item a list, which is also introduced by a quote character. In the -following example, the @code{breakAlignOrder} property is set to a -list of symbols: +With this mechanism, it is possible to define an Urtext (original +edition), with the option to put several distinct articulations on the +same notes. + +@cindex @code{\context} +@cindex creating contexts + +The third command for creating contexts is @example - \set Score.breakAlignOrder = - #'(left-edge time-signature key-signatures) +\context @var{type} @var{music} @end example -@end itemize +@noindent +This is similar to @code{\context} with @code{= @var{id}}, but matches +any context of type @var{type}, regardless of its given name. -There are many different properties. Not all of them are listed in -this manual. However, the program reference lists them all in the -section @internalsref{Context-properties}, and most properties are -demonstrated in one of the -@ifhtml -@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks} -@end ifhtml -@ifnothtml -tips-and-tricks -@end ifnothtml -examples. +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} + +@example +\applyoutput #@var{function} % apply to Voice +@end example +To have it interpreted at the @context{Score} or @context{Staff} level use +these forms -@node Fine tuning layout -@section Fine tuning layout +@example +\context Score \applyoutput #@var{function} +\context Staff \applyoutput #@var{function} +@end example -Sometimes it is necessary to change music layout by hand. When music -is formatted, layout objects are created for each symbol. For -example, every clef and every note head is represented by a layout -object. These layout objects also carry variables, which we call -@emph{layout properties}. By changing these variables from their -values, we can alter the look of a formatted score: -@lilypond[verbatim,relative] - c4 - \override Stem #'thickness = #3.0 - c4 c4 c4 -@end lilypond +@node Changing context properties on the fly +@subsection Changing context properties on the fly -@noindent -In the example shown here, the layout property @code{thickness} (a -symbol) is set to 3 in the @code{Stem} layout objects of the current -As a result, the notes following @code{\override} have thicker -stems. +@cindex properties +@cindex @code{\set} +@cindex changing properties -For the most part, a manual override is needed only on a case by -case basis and not for all subsequent instances of the altered -property. To accomplish this, simply prefix @code{\once} to the -@code{\override} statement and the override will apply only once, -immediately reverting to its default setting, i.e. +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 - \once \override Stem #'thickness = #3.0 +\set @var{context}.@var{prop} = #@var{value} @end example -@lilypond[relative] - c4 - \once \override Stem #'thickness = #3.0 - c4 c4 c4 +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 -Some overrides are so common that predefined commands are provided as -a short cut. For example, @code{\slurUp} and @code{\stemDown}. These -commands are described in -@ifhtml -the -@end ifhtml -@ref{Notation manual}, under the sections for slurs and stems -respectively. +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 -The exact tuning possibilities for each type of layout object are -documented in the program reference of the respective -object. However, many layout objects share properties, which can be -used to apply generic tweaks. We mention a couple of these: +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 +`on-the-fly', during the music, so that the setting only affects the +second group of eighth notes. -@itemize @bullet -@item The @code{extra-offset} property, which -@cindex @code{extra-offset} -has a pair of numbers as value, moves around objects in the printout. -The first number controls left-right movement; a positive number will -move the object to the right. The second number controls up-down -movement; a positive number will move it higher. The units of these -offsets are staff-spaces. The @code{extra-offset} property is a -low-level feature: the formatting engine is completely oblivious to -these offsets. +@cindex @code{\unset} -In the following example, the second fingering is moved a little to -the left, and 1.8 staff space downwards: +There is also an @code{\unset} command, +@example +\unset @var{context}.@var{prop} +@end example -@cindex setting object properties +@noindent +which removes the definition of @var{prop}. This command removes +the definition only if it is set in @var{context}, so -@lilypond[relative=1,verbatim] -\stemUp -f-5 -\once \override Fingering - #'extra-offset = #'(-0.3 . -1.8) -f-5 -@end lilypond +@example +\set Staff.autoBeaming = ##f +@end example -@item -Setting the @code{transparent} property will cause an object to be printed -in `invisible ink': the object is not printed, but all its other -behavior is retained. The object still takes up space, it takes part in -collisions, and slurs, and ties and beams can be attached to it. +@noindent +introduces a property setting at @code{Staff} level. The setting also +applies to the current @code{Voice}. However, -@cindex transparent objects -@cindex removing objects -@cindex invisible objects -The following example demonstrates how to connect different voices -using ties. Normally, ties only connect two notes in the same -voice. By introducing a tie in a different voice, and blanking a stem -in that voice, the tie appears to cross voices: - -@lilypond[fragment,relative=1,verbatim] - c4 << { - \once \override Stem #'transparent = ##t - b8~ b8 - } \\ { - b[ g8] - } >> -@end lilypond +@example +\unset Voice.autoBeaming +@end example -@item -The @code{padding} property for objects with -@cindex @code{padding} -@code{side-position-interface} can be set to increase distance between -symbols that are printed above or below notes. We only give an -example; a more elaborate explanation is in @ref{Constructing a -tweak}: +@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 -@lilypond[relative=1,verbatim] - c2\fermata - \override Script #'padding = #3 - b2\fermata -@end lilypond +Like @code{\set}, the @var{context} argument does not have to be +specified for a bottom context, so the two statements -@end itemize +@example +\set Voice.autoBeaming = ##t +\set autoBeaming = ##t +@end example -More specific overrides are also possible. The notation manual -discusses in depth how to figure out these statements for yourself, in -@ref{Tuning output}. +@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 -@node Tuning output -@section Tuning output +the property @code{fontSize} is unset automatically after the second +note. -There are situations where default layout decisions are not -sufficient. In this section we discuss ways to override these -defaults. +A full description of all available context properties is in the +program reference, see +@ifhtml +@internalsref{Tunable context properties}. +@end ifhtml +@ifnothtml +Translation @arrow{} Tunable context properties. +@end ifnothtml -Formatting is internally done by manipulating so called objects -(graphic objects). Each object carries with it a set of properties -(object or layout properties) specific to that object. For example, a -stem object has properties that specify its direction, length and -thickness. -The most direct way of tuning the output is by altering the values of -these properties. There are two ways of doing that: first, you can -temporarily change the definition of one type of object, thus -affecting a whole set of objects. Second, you can select one specific -object, and set a layout property in that object. +@node Modifying context plug-ins +@subsection Modifying context plug-ins -Do not confuse layout properties with translation -properties. Translation properties always use a mixed caps style -naming, and are manipulated using @code{\set} and @code{\unset}: -@example - \set Context.propertyName = @var{value} -@end example +Notation contexts (like Score and Staff) not only store properties, +they also contain plug-ins, called ``engravers'' that create notation +elements. For example, the Voice context contains a +@code{Note_head_engraver} and the Staff context contains a +@code{Key_signature_engraver}. + +For a full a description of each plug-in, see +@ifhtml +@internalsref{Engravers}. +@end ifhtml +@ifnothtml +Program reference @arrow Translation @arrow{} Engravers. +@end ifnothtml +Every context described in +@ifhtml +@internalsref{Contexts} +@end ifhtml +@ifnothtml +Program reference @arrow Translation @arrow{} Context. +@end ifnothtml +lists the engravers used for that context. + + +It can be useful to shuffle around these plug-ins. This is done by +starting a new context, with @code{\new} or @code{\context}, and +modifying it like this, -Layout properties are use Scheme style variable naming, i.e. lower -case words separated with dashes. They are symbols, and should always -be quoted using @code{#'}. For example, this could be an imaginary -layout property name: @example - #'layout-property-name +\new @var{context} \with @{ + \consists @dots{} + \consists @dots{} + \remove @dots{} + \remove @dots{} + @emph{etc.} +@} +@emph{..music..} @end example +@noindent +where the @dots{} should be the name of an engraver. Here is a simple +example which removes @code{Time_signature_engraver} and +@code{Clef_engraver} from a @code{Staff} context, -@menu -* Tuning objects:: -* Constructing a tweak:: -* Font selection:: -@end menu - +@lilypond[quote,relative=1,verbatim,fragment] +<< \new Staff { + f2 g + } + \new Staff \with { + \remove "Time_signature_engraver" + \remove "Clef_engraver" + } { + f2 g2 + } +>> +@end lilypond +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. The spacing is adversely influenced too. A more +sophisticated method of blanking objects is shown in @ref{Common tweaks}. + +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_engraver}. This plug-in keeps an administration of +time signature, location within the measure, etc. By moving the +@code{Timing_engraver} engraver from @code{Score} to @code{Staff} +context, we can have a score where each staff has its own time +signature. + +@cindex polymetric scores +@cindex Time signatures, multiple + +@lilypond[quote,relative=1,raggedright,verbatim,fragment] +\new Score \with { + \remove "Timing_engraver" +} << + \new Staff \with { + \consists "Timing_engraver" + } { + \time 3/4 + c4 c c c c c + } + \new Staff \with { + \consists "Timing_engraver" + } { + \time 2/4 + c4 c c c c c + } +>> +@end lilypond -@node Tuning objects -@subsection Tuning objects -@cindex object description +@node Layout tunings within contexts +@subsection Layout tunings within contexts -The definition of an object is a list of default object -properties. For example, the definition of the Stem object (available -in @file{scm/define-grobs.scm}), includes the following definitions -for @internalsref{Stem}: +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 - (thickness . 1.3) - (beamed-lengths . (3.5 3.5 3.5 4.5 5.0)) - (Y-extent-callback . ,Stem::height) - @var{...} +\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 (`grob property' or `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. -Adding variables on top of this existing definition overrides the -system default, and alters the resulting appearance of the layout -object. +The command + +@verbatim +\override Staff.Stem #'thickness = #4.0 +@end verbatim -@syntax +@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: + +@lilypond[quote,verbatim,relative=2,fragment] +c4 +\override Staff.Stem #'thickness = #4.0 +c4 +c4 +c4 +@end lilypond +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. -Changing a variable for only one object is commonly achieved with -@code{\once}: +Analogous to @code{\set}, the @var{context} argument may be left out, +causing it to default to @context{Voice}, and adding @code{\once} applies +the change during one timestep only -@example -\once \override @var{context}.@var{objectname} - @var{symbol} = @var{value} -@end example -Here @var{symbol} is a Scheme expression of symbol type, @var{context} -and @var{objectname} is a string and @var{value} is a Scheme expression. -This command applies a setting only during one moment in the score. - -In the following example, only one @internalsref{Stem} object is -changed from its original setting: - -@lilypond[verbatim,fragment,relative=1] - c4 - \once \override Voice.Stem #'thickness = #4 - c4 - c4 +@lilypond[quote,fragment,verbatim,relative=2] +c4 +\once \override Stem #'thickness = #4.0 +c4 +c4 @end lilypond -@cindex @code{\once} -For changing more objects, the same command, without @code{\once} can -be used: -@example -\override @var{context}.@var{objectname} @var{symbol} = @var{value} -@end example -This command adds @code{@var{symbol} = @var{value}} to the definition -of @var{objectname} in the context @var{context}, and this definition -stays in place until it is removed. +The @code{\override} must be done before the object is +started. Therefore, when altering @emph{Spanner} objects, like 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 +the slur is fatter but the beam is not. This is because the command for +@code{Beam} comes after the Beam is started. Therefore it has no effect. + +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. -An existing definition may be removed by the following command: -@c @example -\property @var{context}.@var{objectname} \revert @var{symbol} +\override Voice.Stem #'thickness = #4.0 +\revert Staff.Stem #'thickness @end example -@c - -Some examples: -@lilypond[verbatim] -c'4 \override Stem #'thickness = #4.0 -c'4 -c'4 \revert Stem #'thickness -c'4 -@end lilypond -The following example gives exactly the same result as the previous -one (assuming the system default for stem thickness is 1.3): -@c -@lilypond[verbatim] - c'4 \override Stem #'thickness = #4.0 - c'4 - c'4 \override Stem #'thickness = #1.3 - c'4 -@end lilypond -Reverting a setting which was not set in the first place has no -effect. @seealso Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty}, @internalsref{PropertySet}, @internalsref{All-backend-properties}, and -@internalsref{All-layout-objects}. +@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 -and/or crashes. +or crashes, or both. -@menu -* Constructing a tweak:: -* Applyoutput:: -* Font selection:: -* Text markup:: -@end menu -@node Constructing a tweak -@subsection Constructing a tweak +@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, -@cindex internal documentation -@cindex finding graphical objects -@cindex graphical object descriptions -@cindex tweaking -@cindex @code{\override} -@cindex @code{\set} -@cindex internal documentation +@example +\layout @{ + @dots{} + \context @{ + \Staff + + \set fontSize = #-2 + \override Stem #'thickness = #4.0 + \remove "Time_signature_engraver" + @} +@} +@end example +Here +@example +\Staff +@end example +@noindent +takes the existing definition for context @context{Staff} from the +identifier @code{\Staff}. -Three pieces of information are required to use @code{\override} and -@code{\set}: the name of the layout object, the context and the name -of the property. We demonstrate how to glean this information from -the notation manual and the generated documentation. +The statements +@example +\set fontSize = #-2 +\override Stem #'thickness = #4.0 +\remove "Time_signature_engraver" +@end example -The generated documentation is a set of HTML pages which should be -included if you installed a binary distribution, typically in -@file{/usr/share/doc/lilypond}. They are also available on the web: -go to the @uref{http://lilypond.org,LilyPond website}, click -``Documentation'', select the correct version, and click then -``Program reference.'' It is advisable to bookmark the local HTML -files. They will load faster than the ones on the web. If you use the -version from the web, you must check whether the documentation matches -the program version: it is generated from the definitions that the -program uses, and therefore it is strongly tied to the LilyPond -version. +@noindent +affect all staves in the score. +Other contexts can be modified analogously. -@c [TODO: revise for new site.] +The @code{\set} keyword is optional within the @code{\layout} block, so -Suppose we want to move the fingering indication in the fragment below: +@example +\context @{ + @dots{} + fontSize = #-2 +@} +@end example -@lilypond[relative=2,verbatim] -c-2 -\stemUp -f -@end lilypond +@noindent +will also work. -If you visit the documentation of @code{Fingering} (in @ref{Fingering -instructions}), you will notice that there is written: -@quotation -@seealso -Internals: @internalsref{FingerEvent} and @internalsref{Fingering}. +@refbugs -@end quotation +It is not possible to collect context changes in a variable, and apply +them to one @code{\context} definition by referring to that variable. -@separate +The @code{\RemoveEmptyStaffContext} will override your current +@code{\Staff} variable. If you wish to change the defaults for a +staff that uses @code{\RemoveEmptyStaffContext}, you must do so +after calling @code{\RemoveemptyStaffContext}, ie -@noindent -In other words, the fingerings once entered, are internally stored as -@code{FingerEvent} music objects. When printed, a @code{Fingering} -layout object is created for every @code{FingerEvent}. +@example +\layout @{ + \context @{ + \RemoveEmptyStaffContext -The Fingering object has a number of different functions, and each of -those is captured in an interface. The interfaces are listed under -@internalsref{Fingering} in the program reference. + \override Stem #'thickness = #4.0 + @} +@} +@end example +@node Defining new contexts +@subsection Defining new contexts -The @code{Fingering} object has a fixed size -(@internalsref{item-interface}), the symbol is a piece of text -(@internalsref{text-interface}), whose font can be set -(@internalsref{font-interface}). It is centered horizontally -(@internalsref{self-alignment-interface}), it is placed next to other -objects (@internalsref{side-position-interface}) vertically, and its -placement is coordinated with other scripts -(@internalsref{text-script-interface}). It also has the standard -@internalsref{grob-interface} (grob stands for Graphical object) -@cindex grob -@cindex graphical object -@cindex layout object -@cindex object, layout -with all the variables that come with -it. Finally, it denotes a fingering instruction, so it has -@internalsref{finger-interface}. - -For the vertical placement, we have to look under -@code{side-position-interface}: -@quotation -@code{side-position-interface} +Specific contexts, like @context{Staff} and @code{Voice}, are made of +simple building blocks, and it is possible to compose engraver +plug-ins in different combinations, thereby creating new types of +contexts. - Position a victim object (this one) next to other objects (the - support). In this case, the property @code{direction} signifies where to put the - victim object relative to the support (left or right, up or down?) -@end quotation +The next example shows how to build a different type of +@context{Voice} context from scratch. It will be similar to +@code{Voice}, but prints centered slash noteheads only. It can be used +to indicate improvisation in Jazz pieces, -@cindex padding -@noindent -below this description, the variable @code{padding} is described as -@quotation -@table @code -@item padding - (dimension, in staff space) +@lilypond[quote,raggedright] +\layout { \context { + \name ImproVoice + \type "Engraver_group_engraver" + \consists "Note_heads_engraver" + \consists "Text_engraver" + \consists Pitch_squash_engraver + squashedPosition = #0 + \override NoteHead #'style = #'slash + \override Stem #'transparent = ##t + \alias Voice +} +\context { \Staff + \accepts "ImproVoice" +}} + +\relative c'' { + a4 d8 bes8 \new ImproVoice { c4^"ad lib" c + c4 c^"undress" c_"while playing :)" c } + a1 +} +@end lilypond - add this much extra space between objects that are next to each -other. Default value: @code{0.6} -@end table -@end quotation -By increasing the value of @code{padding}, we can move away the -fingering. The following command inserts 3 staff spaces of white -between the note and the fingering: +These settings are again done within a @code{\context} block inside a +@code{\layout} block, + @example -\once \override Fingering #'padding = #3 +\layout @{ + \context @{ + @dots{} + @} +@} @end example -Inserting this command before the Fingering object is created, -i.e. before @code{c2}, yields the following result: - -@lilypond[relative=2,fragment,verbatim] -\once \override Fingering - #'padding = #3 -c-2 -\stemUp -f -@end lilypond +In the following discussion, the example input shown should go on the +@dots{} in the previous fragment. -The context name @code{Voice} in the example above can be determined -as follows. In the documentation for @internalsref{Fingering}, it says -@quotation -Fingering grobs are created by: @internalsref{Fingering_engraver} @c -@end quotation +First, the context gets a name. Instead of @context{Voice} it +will be called @context{ImproVoice}, -Clicking @code{Fingering_engraver} shows the documentation of -the module responsible for interpreting the fingering instructions and -translating them to a @code{Fingering} object. Such a module is called -an @emph{engraver}. The documentation of the @code{Fingering_engraver} -says @example -Fingering_engraver is part of contexts: Voice +\name ImproVoice @end example -so tuning the settings for Fingering should be done with + +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}, + @example - \override Fingering @dots{} +\alias Voice @end example -Of course, the tweak may also done in a larger context than -@code{Voice}, for example, @internalsref{Staff} or -@internalsref{Score}. +The context will print notes, and instructive texts -@seealso +@example +\consists Note_heads_engraver +\consists Text_engraver +@end example -Internals: the program reference also contains alphabetical lists of -@internalsref{Contexts}, @internalsref{All-layout-objects} and -@internalsref{Music-expressions}, so you can also find which objects -to tweak by browsing the internals document. +but only on the center line, +@example +\consists Pitch_squash_engraver +squashedPosition = #0 +@end example +The @internalsref{Pitch_squash_engraver} modifies note heads (created +by @internalsref{Note_heads_engraver}) and sets their vertical +position to the value of @code{squashedPosition}, in this case@tie{}@code{0}, +the center line. +The notes look like a slash, without a stem, -@node Font selection -@subsection Font selection +@example +\override NoteHead #'style = #'slash +\override Stem #'transparent = ##t +@end example -The most common thing to change about the appearance of fonts is their -size. The font size of any context can be easily changed by setting -the @code{fontSize} property for that context. Its value is a number: -negative numbers make the font smaller, positive numbers larger. An -example is given below: -@c -@lilypond[fragment,relative=1,verbatim] - c4 c4 \set fontSize = #-1 - f4 g4 -@end lilypond -This command will set @code{font-size} (see below), and does -not change the size of variable symbols, such as beams or slurs. -One of the uses of @code{fontSize} is to get smaller symbols for cue -notes. An elaborate example of those is in -@inputfileref{input/test,cue-notes.ly}. +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_engraver}, -@cindex magnification -@cindex cue notes +@example +\type "Engraver_group_engraver" +@end example + +Put together, we get -The font used for printing a object can be selected by setting -@code{font-name}, e.g. @example - \override Staff.TimeSignature - #'font-name = #"cmr17" +\context @{ + \name ImproVoice + \type "Engraver_group_engraver" + \consists "Note_heads_engraver" + \consists "Text_engraver" + \consists Pitch_squash_engraver + squashedPosition = #0 + \override NoteHead #'style = #'slash + \override Stem #'transparent = ##t + \alias Voice +@} @end example -@noindent -Any font can be used, as long as it is available to @TeX{}. Possible -fonts include foreign fonts or fonts that do not belong to the -Computer Modern font family. The size of fonts selected in this way -can be changed with the @code{font-magnification} property. For -example, @code{2.0} blows up all letters by a factor 2 in both -directions. +Contexts form hierarchies. We want to hang the @context{ImproVoice} +under @context{Staff}, just like normal @code{Voice}s. Therefore, we +modify the @code{Staff} definition with the @code{\accepts} +command,@footnote{The opposite of @code{\accepts} is @code{\denies}, +which is sometimes needed when reusing existing context definitions.} -@cindex font size -@cindex font magnification -Font selection for the standard fonts, @TeX{}'s Computer Modern fonts, -can also be adjusted with a more fine-grained mechanism. By setting -the object properties described below, you can select a different font; -all three mechanisms work for every object that supports -@code{font-interface}: +@example +\context @{ + \Staff + \accepts ImproVoice +@} +@end example -@table @code -@item font-family - is a symbol indicating the general class of the typeface. Supported are -@code{roman} (Computer Modern), @code{braces} (for piano staff -braces), @code{music} (the standard music font, including ancient -glyphs), @code{dynamic} (for dynamic signs) and @code{typewriter}. - -@item font-shape - is a symbol indicating the shape of the font, there are typically several - font shapes available for each font family. Choices are @code{italic}, - @code{caps} and @code{upright}. +Putting both into a @code{\layout} block, like -@item font-series -is a symbol indicating the series of the font. There are typically several -font series for each font family and shape. Choices are @code{medium} -and @code{bold}. +@example +\layout @{ + \context @{ + \name ImproVoice + @dots{} + @} + \context @{ + \Staff + \accepts "ImproVoice" + @} +@} +@end example -@end table +Then the output at the start of this subsection can be entered as -For any of these properties, the value @code{*} (i.e. the symbol -@code{*}, entered as @code{#'*}), acts as a wildcard. This can be used -to override default setting, which are always present. For example: @example - \override Lyrics .LyricText #'font-series = #'bold - \override Lyrics .LyricText #'font-family = #'typewriter - \override Lyrics .LyricText #'font-shape = #'* +\relative c'' @{ + a4 d8 bes8 + \new ImproVoice @{ + c4^"ad lib" c + c4 c^"undress" + c c_"while playing :)" + @} + a1 +@} @end example + -@cindex @code{font-style} + -The font size is set by modifying the @code{font-size} property. Its -value is a number indicating the size relative to the standard size. -Each step up is an increase of approximately 12% of the font size. Six -steps is exactly a factor two. The Scheme function @code{magstep} -converts a @code{font-size} number to a scaling factor. +@node The \override command +@section The \override command -LilyPond has fonts in different design sizes: the music fonts for -smaller sizes are chubbier, while the text fonts are relatively wider. -Font size changes are achieved by scaling the design size that is -closest to the desired size. +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. +First, we will give a few versatile commands that are sufficient +for many situations. The next section will discuss the general use of +@code{\override}. -The @code{font-size} mechanism does not work for fonts selected -through @code{font-name}. These may be scaled with -@code{font-magnification}. -@refcommands +@menu +* Common tweaks:: +* Constructing a tweak:: +* Navigating the program reference:: +* Layout interfaces:: +* Determining the grob property:: +* Difficult tweaks:: +@end menu -The following commands set @code{fontSize} for the current voice. -@cindex @code{\tiny} -@code{\tiny}, -@cindex @code{\small} -@code{\small}, -@cindex @code{\normalsize} -@code{\normalsize}. -@seealso +@node Common tweaks +@subsection Common tweaks -Init files: @file{ly/declarations-init.ly} contains hints how new -fonts may be added to LilyPond. +@c Should we point at ly/property-init.ly ? -gp +Some overrides are so common that predefined commands are provided as +short-cuts, for example, @code{\slurUp} and @code{\stemDown}. These +commands are described in +@ifhtml +the +@end ifhtml +@c @ref{Notation manual}, +Notation manual +@c FIXME +under the sections for slurs and stems +respectively. -@refbugs +The exact tuning possibilities for each type of layout object are +documented in the program reference of the respective +object. However, many layout objects share properties, which can be +used to apply generic tweaks. We mention a few of these: -There is no style sheet provided for other fonts besides the @TeX{} -Computer Modern family. +@itemize @bullet +@item The @code{extra-offset} property, which +@cindex @code{extra-offset} +has a pair of numbers as value, moves objects around in the printout. +The first number controls left-right movement; a positive number will +move the object to the right. The second number controls up-down +movement; a positive number will move it higher. The units of these +offsets are staff-spaces. The @code{extra-offset} property is a +low-level feature: the formatting engine is completely oblivious to +these offsets. -@cindex font selection -@cindex font magnification -@cindex @code{font-interface} +In the following example, the second fingering is moved a little to +the left, and 1.8 staff space downwards: +@cindex setting object properties -@node Text markup -@section Text markup -@cindex text markup -@cindex markup text +@lilypond[quote,fragment,relative=1,verbatim] +\stemUp +f-5 +\once \override Fingering + #'extra-offset = #'(-0.3 . -1.8) +f-5 +@end lilypond +@item +Setting the @code{transparent} property will cause an object to be printed +in `invisible ink': the object is not printed, but all its other +behavior is retained. The object still takes up space, it takes part in +collisions, and slurs, ties, and beams can be attached to it. -@cindex typeset text +@cindex transparent objects +@cindex removing objects +@cindex hiding objects +@cindex invisible objects +The following example demonstrates how to connect different voices +using ties. Normally, ties only connect two notes in the same +voice. By introducing a tie in a different voice, + +@lilypond[quote,fragment,relative=2] +<< { + b8~ b8\noBeam +} \\ { + b[ g8] +} >> +@end lilypond -LilyPond has an internal mechanism to typeset texts. You can access it -with the keyword @code{\markup}. Within markup mode, you can enter texts -similar to lyrics: simply enter them, surrounded by spaces: -@cindex markup +@noindent +and blanking the first up-stem in that voice, the tie appears to cross +voices: + +@lilypond[quote,fragment,relative=2,verbatim] +<< { + \once \override Stem #'transparent = ##t + b8~ b8\noBeam +} \\ { + b[ g8] +} >> +@end lilypond + +@item +The @code{padding} property for objects with +@cindex @code{padding} +@code{side-position-interface} can be set to increase the distance between +symbols that are printed above or below notes. We only give an +example; a more elaborate explanation is in @ref{Constructing a +tweak}: -@lilypond[verbatim,fragment,relative=1] - c1^\markup { hello } - c1_\markup { hi there } - c1^\markup { hi \bold there, is \italic anyone home? } +@lilypond[quote,fragment,relative=1,verbatim] +c2\fermata +\override Script #'padding = #3 +b2\fermata @end lilypond -@cindex font switching +@end itemize -The markup in the example demonstrates font switching commands. The -command @code{\bold} and @code{\italic} only apply to the first -following word; enclose a set of texts with braces to apply a command -to more words: -@example - \markup @{ \bold @{ hi there @} @} -@end example +More specific overrides are also possible. The next section +discusses in depth how to figure out these statements for yourself. -@noindent -For clarity, you can also do this for single arguments, e.g. -@verbatim - \markup { is \italic { anyone } home } -@end verbatim +@node Constructing a tweak +@subsection Constructing a tweak + +The general procedure of changing output, that is, entering +a command like + +@example +\override Voice.Stem #'thickness = #3.0 +@end example -@cindex font size, texts +@noindent +means that we have to 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 -In markup mode you can compose expressions, similar to mathematical -expressions, XML documents and music expressions. The braces group -notes into horizontal lines. Other types of lists also exist: you can -stack expressions grouped with @code{<}, and @code{>} vertically with -the command @code{\column}. Similarly, @code{\center-align} aligns -texts by their center lines: - -@lilypond[verbatim,fragment,relative=1] - c1^\markup { \column < a bbbb c > } - c1^\markup { \center-align < a bbbb c > } - c1^\markup { \line < a b c > } -@end lilypond +@cindex internal documentation +@cindex finding graphical objects +@cindex graphical object descriptions +@cindex tweaking +@cindex @code{\override} +@cindex internal documentation -Markups can be stored in variables, and these variables -may be attached to notes, like -@verbatim -allegro = \markup { \bold \large { Allegro } } -\notes { a^\allegro b c d } -@end verbatim +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 -Some objects have alignment procedures of their own, which cancel out -any effects of alignments applied to their markup arguments as a -whole. For example, the @internalsref{RehearsalMark} is horizontally -centered, so using @code{\mark \markup @{ \left-align .. @}} has no -effect. Similarly, whole texts over notes cannot be moved vertically -with @code{\raise}. For moving and aligning complete objects, grob -properties should be used. +Suppose we want to move the fingering indication in the fragment +below: +@lilypond[quote,fragment,relative=2,verbatim] +c-2 +\stemUp +f +@end lilypond +If you visit the documentation on fingering instructions (in +@ref{Fingering instructions}), you will notice that there is written: +@quotation @seealso -Init files: @file{scm/new-markup.scm}. +Program reference: @internalsref{FingerEvent} and @internalsref{Fingering}. +@end quotation -@refbugs -Text layout is ultimately done by @TeX{}, which does kerning of -letters. LilyPond does not account for kerning, so texts will be -spaced slightly too wide. -Syntax errors for markup mode are confusing. +This fragment points to two parts of the program reference: a page +on @code{FingerEvent} and one on @code{Fingering}. -Markup texts cannot be used in the titling of the @code{\header} -field. Titles are made by La@TeX{}, so La@TeX{} commands should be used -for formatting. +The page on @code{FingerEvent} describes the properties of the music +expression for the input @code{-2}. The page contains many links +forward. For example, it says +@quotation +Accepted by: @internalsref{Fingering_engraver}, +@end quotation +@noindent +That link brings us to the documentation for the Engraver, the +plug-in, which says -@menu -* Overview of text markup commands:: -@end menu +@quotation +This engraver creates the following layout objects: @internalsref{Fingering}. +@end quotation -@node Overview of text markup commands -@subsection Overview of text markup commands +In other words, once the @code{FingerEvent}s are interpreted, the +@code{Fingering_engraver} plug-in will process them. +The @code{Fingering_engraver} is also listed to create +@internalsref{Fingering} objects, -@include markup-commands.tely +Lo and behold, that is also the +second bit of information listed under @b{See also} in the Notation +manual. By clicking around in the program reference, we can follow the +flow of information within the program, either forward (like we did +here), or backwards, following links like this: -@node Global layout -@section Global layout +@itemize @bullet -The global layout determined by three factors: the page layout, the -line breaks and the spacing. These all influence each other. The -choice of spacing determines how densely each system of music is set, -which influences where line breaks breaks are chosen, and thus -ultimately how many pages a piece of music takes. This section -explains how to tune the algorithm for spacing. +@item @internalsref{Fingering}: +@internalsref{Fingering} objects are created by: +@b{@internalsref{Fingering_engraver}} -Globally spoken, this procedure happens in three steps: first, -flexible distances (``springs'') are chosen, based on durations. All -possible line breaking combination are tried, and the one with the -best results---a layout that has uniform density and requires as -little stretching or cramping as possible---is chosen. When the score -is processed by @TeX{}, each page is filled with systems, and page breaks -are chosen whenever the page gets full. +@item @internalsref{Fingering_engraver}: +Music types accepted: @b{@internalsref{fingering-event}} +@item @internalsref{fingering-event}: +Music event type @code{fingering-event} is in Music expressions named +@b{@internalsref{FingerEvent}} +@end itemize +This path goes against the flow of information in the program: it +starts from the output, and ends at the input event. -@menu -* Vertical spacing:: -* Horizontal spacing:: -* Font Size:: -* Line breaking:: -* Page layout:: -@end menu +The program reference can also be browsed like a normal document. It +contains a chapter on +@ifhtml +@internalsref{Music definitions}, +@end ifhtml +@ifnothtml +@code{Music definitions} +@end ifnothtml +on @internalsref{Translation}, and the @internalsref{Backend}. Every +chapter lists all the definitions used, and all properties that may be +tuned. + + +@node Layout interfaces +@subsection Layout interfaces + +@cindex interface, layout +@cindex layout interface + +The HTML page that we found in the previous section, describes the +layout object called @internalsref{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 @emph{grob}, +@cindex grob +which is short for Graphical Object. -@node Vertical spacing -@subsection Vertical spacing +The page for @code{Fingering} lists the definitions for the +@code{Fingering} object. For example, the page says -@cindex vertical spacing -@cindex distance between staves -@cindex staff distance -@cindex between staves, distance -@cindex staffs per page -@cindex space between staves +@quotation +@code{padding} (dimension, in staff space): + +@code{0.6} +@end quotation -The height of each system is determined automatically by LilyPond, to -keep systems from bumping into each other, some minimum distances are -set. By changing these, you can put staves closer together, and thus -put more systems onto one page. +@noindent +which means that the number will be kept at a distance of at least 0.6 +of the note head. -Normally staves are stacked vertically. To make -staves maintain a distance, their vertical size is padded. This is -done with the property @code{minimumVerticalExtent}. It takes a pair -of numbers, so if you want to make it smaller from its, then you could -set -@example - \set Staff.minimumVerticalExtent = #'(-4 . 4) -@end example -This sets the vertical size of the current staff to 4 staff spaces on -either side of the center staff line. The argument of -@code{minimumVerticalExtent} is interpreted as an interval, where the -center line is the 0, so the first number is generally negative. The -staff can be made larger at the bottom by setting it to @code{(-6 -. 4)}. - -The piano staves are handled a little differently: to make cross-staff -beaming work correctly, it is necessary that the distance between staves -is fixed beforehand. This is also done with a -@internalsref{VerticalAlignment} object, created in -@internalsref{PianoStaff}. In this object the distance between the -staves is fixed by setting @code{forced-distance}. If you want to -override this, use a @code{\translator} block as follows: -@example - \paper @{ - \translator @{ - \PianoStaffContext - \override VerticalAlignment #'forced-distance = #9 - @} - @dots{} - @} -@end example -This would bring the staves together at a distance of 9 staff spaces, -measured from the center line of each staff. -@seealso +Each layout object may have several functions as a notational or +typographical element. For example, the Fingering object +has the following aspects -Internals: Vertical alignment of staves is handled by the -@internalsref{VerticalAlignment} object. +@itemize @bullet +@item +Its size is independent of the horizontal spacing, unlike slurs or beams. +@item +It is a piece of text. Granted, it is usually a very short text. +@item +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. -@node Horizontal spacing -@subsection Horizontal Spacing +@item +Vertically, the symbol is placed next to the note and the staff. -The spacing engine translates differences in durations into -stretchable distances (``springs'') of differing lengths. Longer -durations get more space, shorter durations get less. The shortest -durations get a fixed amount of space (which is controlled by -@code{shortest-duration-space} in the @internalsref{SpacingSpanner} object). -The longer the duration, the more space it gets: doubling a -duration adds a fixed amount (this amount is controlled by -@code{spacing-increment}) of space to the note. +@item +The vertical position is also coordinated with other super- and subscript +symbols. +@end itemize -For example, the following piece contains lots of half, quarter and -8th notes, the eighth note is followed by 1 note head width (NHW). -The quarter note is followed by 2 NHW, the half by 3 NHW, etc. -@lilypond[fragment,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8 -c8 c4 c4 c4 -@end lilypond +Each of these aspects is captured in so-called @emph{interface}s, +which are listed on the @internalsref{Fingering} page at the bottom -Normally, @code{shortest-duration-space} is set to 1.2, which is the -width of a note head, and @code{shortest-duration-space} is set to -2.0, meaning that the shortest note gets 2 NHW (i.e. 2 times -@code{shortest-duration-space}) of space. For normal notes, this space -is always counted from the left edge of the symbol, so the shortest -notes are generally followed by one NHW of space. - -If one would follow the above procedure exactly, then adding a single -32th note to a score that uses 8th and 16th notes, would widen up the -entire score a lot. The shortest note is no longer a 16th, but a 32nd, -thus adding 1 NHW to every note. To prevent this, the -shortest duration for spacing is not the shortest note in the score, -but the most commonly found shortest note. Notes that are even -shorter this are followed by a space that is proportional to their -duration relative to the common shortest note. So if we were to add -only a few 16th notes to the example above, they would be followed by -half a NHW: - -@lilypond[fragment,verbatim,relative=2] - c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4 -@end lilypond +@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}. +@end quotation -The most common shortest duration is determined as follows: in every -measure, the shortest duration is determined. The most common short -duration, is taken as the basis for the spacing, with the stipulation -that this shortest duration should always be equal to or shorter than -1/8th note. The shortest duration is printed when you run lilypond -with @code{--verbose}. These durations may also be customized. If you -set the @code{common-shortest-duration} in -@internalsref{SpacingSpanner}, then this sets the base duration for -spacing. The maximum duration for this base (normally 1/8th), is set -through @code{base-shortest-duration}. - -@cindex @code{common-shortest-duration} -@cindex @code{base-shortest-duration} -@cindex @code{stem-spacing-correction} -@cindex @code{spacing} - -In the introduction it was explained that stem directions influence -spacing. This is controlled with @code{stem-spacing-correction} -property in @internalsref{NoteSpacing}, which are generated for every -@internalsref{Voice} context. The @code{StaffSpacing} object -(generated at @internalsref{Staff} context) contains the same property -for controlling the stem/bar line spacing. The following example -shows these corrections, once with default settings, and once with -exaggerated corrections: - -@lilypond - \score { \notes { - c'4 e''4 e'4 b'4 | - b'4 e''4 b'4 e''4| - \override Staff.NoteSpacing #'stem-spacing-correction - = #1.5 - \override Staff.StaffSpacing #'stem-spacing-correction - = #1.5 - c'4 e''4 e'4 b'4 | - b'4 e''4 b'4 e''4| - } - \paper { raggedright = ##t } } -@end lilypond +Clicking any of the links will take you to the page of the respective +object interface. Each interface has a number of properties. Some of +them are not user-serviceable (``Internal properties''), but others +are. -@cindex SpacingSpanner, overriding properties +We have been talking of @emph{the} @code{Fingering} object, but actually it +does not amount to much. The initialization file +@file{scm/@/define@/-grobs@/.scm} shows the soul of the `object', -Properties of the @internalsref{SpacingSpanner} must be overridden -from the @code{\paper} block, since the @internalsref{SpacingSpanner} is -created before any property commands are interpreted. @example -\paper @{ \translator @{ - \ScoreContext - SpacingSpanner \override #'spacing-increment = #3.0 -@} @} +(Fingering + . ((print-function . ,Text_interface::print) + (padding . 0.6) + (staff-padding . 0.6) + (self-alignment-X . 0) + (self-alignment-Y . 0) + (script-priority . 100) + (font-size . -5) + (meta . ((interfaces . (finger-interface font-interface + text-script-interface text-interface + side-position-interface + self-alignment-interface + item-interface)))))) @end example +@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 +is directly generated from this definition. -@seealso - -Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing}, -@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and -@internalsref{SeparatingGroupSpanner}. +@node Determining the grob property +@subsection Determining the grob property -@refbugs -Spacing is determined on a score wide basis. If you have a score that -changes its character (measured in durations) halfway during the -score, the part containing the longer durations will be spaced too -widely. +Recall that we wanted to change the position of the @b{2} in -There is no convenient mechanism to manually override spacing. +@lilypond[quote,fragment,relative=2,verbatim] +c-2 +\stemUp +f +@end lilypond +Since the @b{2} is vertically positioned next to its note, we have to +meddle with the interface associated with this positioning. This is +done using @code{side-position-interface}. The page for this interface +says +@quotation +@code{side-position-interface} -@node Font Size -@subsection Font size -@cindex font size, setting -@cindex staff size, setting -@cindex @code{paper} file +Position a victim object (this one) next to other objects (the +support). The property @code{direction} signifies where to put the +victim object relative to the support (left or right, up or down?) +@end quotation -The Feta font provides musical symbols at eight seven different -sizes. Each font is tuned for a different staff size: at smaller sizes -the font gets heavier, to match the relatively heavier staff lines. -The recommended font sizes are listed in the following table: +@cindex padding +@noindent +below this description, the variable @code{padding} is described as -@multitable @columnfractions .25 .25 .25 .25 +@quotation +@table @code +@item padding +(dimension, in staff space) -@item @b{name} -@tab @b{staff height (pt)} -@tab @b{staff height (mm)} -@tab @b{use} +Add this much extra space between objects that are next to each other. +@end table +@end quotation -@item feta11 -@tab 11.22 -@tab 3.9 -@tab pocket scores +By increasing the value of @code{padding}, we can move away the +fingering. The following command inserts 3 staff spaces of white +between the note and the fingering: +@example +\once \override Voice.Fingering #'padding = #3 +@end example -@item feta13 -@tab 12.60pt -@tab 4.4mm -@tab +Inserting this command before the Fingering object is created, +i.e., before @code{c2}, yields the following result: -@item feta14 -@tab 14.14pt -@tab 5.0mm -@tab +@lilypond[quote,relative=2,fragment,verbatim] +\once \override Voice.Fingering #'padding = #3 +c-2 +\stemUp +f +@end lilypond -@item feta16 -@tab 15.87pt -@tab 5.6mm -@tab -@item feta18 -@tab 17.82pt -@tab 6.3mm -@tab song books +In this case, the context for this tweak is @context{Voice}. This +fact can also be deduced from the program reference, for the page for +the @internalsref{Fingering_engraver} plug-in says -@item feta20 -@tab 17.82pt -@tab 7.0mm -@tab standard parts +@quotation +Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}} +@end quotation -@item feta23 -@tab 22.45 pt -@tab 7.9mm -@tab +@node Difficult tweaks +@subsection Difficult tweaks + +There are two classes of difficult adjustments. First, when there are +several of the same objects at one point, and you want to adjust only +one. For example, if you want to change only one note head in a chord. + +In this case, the @code{\applyoutput} function must be used. The +next example defines a Scheme function @code{set-position-font-size} +that sets the @code{font-size} property, but only +on objects that have @internalsref{note-head-interface} and are at the +right Y-position. + +@lilypond[quote,verbatim] +#(define ((set-position-font-size pos size) grob origin current) + (let* + ((interfaces (ly:grob-property grob 'interfaces)) + (position (ly:grob-property grob 'staff-position))) + (if (and + ; is this a note head? + (memq 'note-head-interface interfaces) + + ; is the Y coordinate right? + (= pos position)) + + ; then do it. + (set! (ly:grob-property grob 'font-size) size)))) + +\relative { + c + \applyoutput #(set-position-font-size -2 4) + +} +@end lilypond -@item feta20 -@tab 25.2 pt -@tab 8.9mm -@tab -@c modern rental material ? +@noindent +A similar technique can be used for accidentals. In that case, the +function should check for @code{accidental-interface}. + +Another difficult adjustment is the appearance of spanner objects, +such as slur and tie. Initially, only one of these objects is created, +and they can be adjusted with the normal mechanism. However, in some +cases the spanners cross line breaks. If this happens, these objects +are cloned. A separate object is created for every system that it is +in. These are clones of the original object and inherit all +properties, including @code{\override}s. + +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} property contains the Scheme procedure +that is called after the line breaks have been determined, and layout +objects have been split over different systems. + +In the following example, we define a procedure +@code{my-callback}. This procedure + +@itemize @bullet +@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}. +@end itemize -@end multitable +This procedure is installed into @internalsref{Tie}, so the last part +of the broken tie is translated up. -These fonts are available in any sizes. The context property -@code{fontSize} and the layout property @code{staff-space} (in -@internalsref{StaffSymbol}) can be used to tune size for individual -staffs. The size of individual staffs are relative to the global size, -which can be set in the following manner: -@example - #(set-global-staff-size 14) -@end example +@lilypond[quote,verbatim,raggedright] +#(define (my-callback grob) + (let* ( + ; have we been split? + (orig (ly:grob-original grob)) -This sets the global default size to 14pt staff height, and scales all -fonts accordingly. + ; 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))))) +\relative c'' { + \override Tie #'after-line-breaking-callback = + #my-callback + c1 ~ \break c2 ~ c +} +@end lilypond -@node Line breaking -@subsection Line breaking +@noindent +When applying this trick, the new @code{after-line-breaking-callback} +should also call the old @code{after-line-breaking-callback}, if there +is one. For example, if using this with @code{Slur}, +@code{Slur::after_line_breaking} should also be called. -@cindex line breaks -@cindex breaking lines +@node Fonts +@section Fonts -Line breaks are normally computed automatically. They are chosen such -that lines look neither cramped nor loose, and that consecutive lines -have similar density. +This section details the ways that the font can be changed. -Occasionally you might want to override the automatic breaks; you can -do this by specifying @code{\break}. This will force a line break at -this point. Line breaks can only occur at places where there are bar -lines. If you want to have a line break where there is no bar line, -you can force an invisible bar line by entering @code{\bar -""}. Similarly, @code{\noBreak} forbids a line break at a -point. +@menu +* Selecting font sizes:: +* Font selection:: +@end menu -@cindex regular line breaks -@cindex four bar music. -For line breaks at regular intervals use @code{\break} separated by -skips and repeated with @code{\repeat}: -@example -<< \repeat unfold 7 @{ - s1 \noBreak s1 \noBreak - s1 \noBreak s1 \break @} - @emph{the real music} ->> -@end example +@node Selecting font sizes +@subsection Selecting font sizes -@noindent -This makes the following 28 measures (assuming 4/4 time) be broken every -4 measures, and only there. -@refcommands +The easiest method of setting the font size of any context, is by +setting the @code{fontSize} property. -@code{\break}, @code{\noBreak} -@cindex @code{\break} -@cindex @code{\noBreak} +@lilypond[quote,fragment,relative=1,verbatim] +c8 +\set fontSize = #-4 +c f +\set fontSize = #3 +g +@end lilypond -@seealso +@noindent +It does not change the size of variable symbols, such as beams or +slurs. + +Internally, the @code{fontSize} context property will cause the +@code{font-size} property to be set in all layout objects. The value +of @code{font-size} is a number indicating the size relative to the +standard size for the current staff height. Each step up is an +increase of approximately 12% of the font size. Six steps is exactly a +factor two. The Scheme function @code{magstep} converts a +@code{font-size} number to a scaling factor. + +@lilypond[quote,fragment,relative=1,verbatim] +c8 +\override NoteHead #'font-size = #-4 +c f +\override NoteHead #'font-size = #3 +g +@end lilypond -Internals: @internalsref{BreakEvent}. - - -@node Page layout -@subsection Page layout - -@cindex page breaks -@cindex breaking pages - -@cindex @code{indent} -@cindex @code{linewidth} - -The most basic settings influencing the spacing are @code{indent} and -@code{linewidth}. They are set in the @code{\paper} block. They -control the indentation of the first line of music, and the lengths of -the lines. - -If @code{raggedright} is set to true in the @code{\paper} -block, then the lines are justified at their natural length. This -useful for short fragments, and for checking how tight the natural -spacing is. - -@cindex page layout -@cindex vertical spacing - -The page layout process happens outside the LilyPond formatting -engine: variables controlling page layout are passed to the output, -and are further interpreted by @code{lilypond} wrapper program. It -responds to the following variables in the @code{\paper} block. The -variable @code{textheight} sets the total height of the music on each -page. The spacing between systems is controlled with -@code{interscoreline}, its default is 16pt. The distance between the -score lines will stretch in order to fill the full page -@code{interscorelinefill} is set to a positive number. In that case -@code{interscoreline} specifies the minimum spacing. - -@cindex @code{textheight} -@cindex @code{interscoreline} -@cindex @code{interscorelinefill} - -If the variable @code{lastpagefill} is defined, -@c fixme: this should only be done if lastpagefill= #t -systems are evenly distributed vertically on the last page. This -might produce ugly results in case there are not enough systems on the -last page. The @command{lilypond-book} command ignores -@code{lastpagefill}. See @ref{lilypond-book manual} for more -information. - -@cindex @code{lastpagefill} - -Page breaks are normally computed by @TeX{}, so they are not under -direct control of LilyPond. However, you can insert a commands into -the @file{.tex} output to instruct @TeX{} where to break pages. This -is done by setting the @code{between-systems-strings} on the -@internalsref{NonMusicalPaperColumn} where the system is broken. -An example is shown in @inputfileref{input/regression,between-systems.ly}. -The predefined command @code{\newpage} also does this. - -@cindex paper size -@cindex page size -@cindex @code{papersize} - -To change the paper size, use the following Scheme code: -@example - \paper@{ - #(set-paper-size "a4") - @} -@end example +LilyPond has fonts in different design sizes. The music fonts for +smaller sizes are chubbier, while the text fonts are relatively wider. +Font size changes are achieved by scaling the design size that is +closest to the desired size. The standard font size (for +@code{font-size} equals 0), depends on the standard staff height. For +a 20pt staff, a 10pt font is selected. +The @code{font-size} mechanism does not work for fonts selected +through @code{font-name}. These may be scaled with +@code{font-magnification}. The @code{font-size} property can only be +set on layout objects that use fonts; these are the ones supporting +the @internalsref{font-interface} layout interface. @refcommands -@cindex @code{\newpage} -@code{\newpage}. +The following commands set @code{fontSize} for the current voice: +@cindex @code{\tiny} +@code{\tiny}, +@cindex @code{\small} +@code{\small}, +@cindex @code{\normalsize} +@code{\normalsize}. -@seealso -In this manual: @ref{Invoking lilypond}. -Examples: @inputfileref{input/regression,between-systems.ly}. +@cindex magnification +@cindex cue notes -Internals: @internalsref{NonMusicalPaperColumn}. -@refbugs +@node Font selection +@subsection Font selection -LilyPond has no concept of page layout, which makes it difficult to -reliably choose page breaks in longer pieces. -@node Interpretation context -@section Interpretation context +@cindex font selection +@cindex font magnification +@cindex @code{font-interface} -@menu -* Creating contexts:: -* Default contexts:: -* Context properties:: -* Defining contexts:: -* Changing contexts locally:: -* Engravers and performers:: -* Defining new contexts:: -@end menu +By setting the object properties described below, you can select a +font from the preconfigured font families. LilyPond has default +support for the feta music fonts and @TeX{}'s Computer Modern text +fonts. -Interpretation contexts are objects that only exist during program -run. During the interpretation phase (when @code{interpreting music} -is printed on the standard output), the music expression in a -@code{\score} block is interpreted in time order, the same order in -which we hear and play the music. During this phase, the interpretation -context holds the state for the current point within the music, for -example: @itemize @bullet -@item What notes are playing at this point? - -@item What symbols will be printed at this point? +@item @code{font-encoding} +is a symbol that sets layout of the glyphs. This should only be set to +select different types of non-text fonts, eg. -@item What is the current key signature, time signature, point within -the measure, etc.? -@end itemize - -Contexts are grouped hierarchically: A @internalsref{Voice} context is -contained in a @internalsref{Staff} context (because a staff can contain -multiple voices at any point), a @internalsref{Staff} context is contained in -@internalsref{Score}, @internalsref{StaffGroup}, or -@internalsref{ChoirStaff} context. +@code{fetaBraces} for piano staff braces, @code{fetaMusic} the +standard music font, including ancient glyphs, @code{fetaDynamic} for +dynamic signs and @code{fetaNumber} for the number font. -Contexts associated with sheet music output are called @emph{notation -contexts}, those for sound output are called @emph{performance -contexts}. The default definitions of the standard notation and -performance contexts can be found in @file{ly/engraver-init.ly} and -@file{ly/performer-init.ly}, respectively. +@item @code{font-family} +is a symbol indicating the general class of the typeface. Supported are +@code{roman} (Computer Modern), @code{sans}, and @code{typewriter}. + +@item @code{font-shape} +is a symbol indicating the shape of the font. There are typically +several font shapes available for each font family. Choices are +@code{italic}, @code{caps}, and @code{upright}. +@item @code{font-series} +is a symbol indicating the series of the font. There are typically +several font series for each font family and shape. Choices are +@code{medium} and @code{bold}. -@node Creating contexts -@subsection Creating contexts -@cindex @code{\context} -@cindex context selection +@end itemize -Contexts for a music expression can be selected manually, using one of -the following music expressions: +Fonts selected in the way sketched above come from a predefined style +sheet. +The font used for printing a object can be selected by setting +@code{font-name}, e.g., @example -\new @var{contexttype} @var{musicexpr} -\context @var{contexttype} [= @var{contextname}] @var{musicexpr} +\override Staff.TimeSignature + #'font-name = #"cmr17" @end example @noindent -This means that @var{musicexpr} should be interpreted within a context -of type @var{contexttype} (with name @var{contextname} if specified). -If no such context exists, it will be created: - -@lilypond[verbatim,raggedright] -\score { - \notes \relative c'' { - c4 <> f - } -} -@end lilypond +Any font can be used, as long as it is available to @TeX{}. Possible +fonts include foreign fonts or fonts that do not belong to the +Computer Modern font family. The size of fonts selected in this way +can be changed with the @code{font-magnification} property. For +example, @code{2.0} blows up all letters by a factor 2 in both +directions. -@noindent -In this example, the @code{c} and @code{d} are printed on the default -staff. For the @code{e}, a context @code{Staff} called @code{another} -is specified; since that does not exist, a new context is created. -Within @code{another}, a (default) Voice context is created for the -@code{e4}. A context is ended when when all music referring it has -finished, so after the third quarter, @code{another} is removed. +@cindex font size +@cindex font magnification -The @code{\new} construction creates a context with a -generated, unique @var{contextname}. An expression with -@code{\new} always leads to a new context. This is convenient -for creating multiple staffs, multiple lyric lines, etc. -When using automatic staff changes, automatic phrasing, etc., the -context names have special meanings, so @code{\new} cannot be -used. +@seealso -@node Default contexts -@subsection Default contexts +Init files: @file{ly/@/declarations@/-init@/.ly} contains hints how new +fonts may be added to LilyPond. -Every top level music is interpreted by the @code{Score} context; in -other words, you may think of @code{\score} working like -@example -\score @{ - \context Score @var{music} -@} -@end example -Music expressions inherit their context from the enclosing music -expression. Hence, it is not necessary to explicitly specify -@code{\context} for most expressions. In -the following example, only the sequential expression has an explicit -context. The notes contained therein inherit the @code{goUp} context -from the enclosing music expression. +@node Text markup +@section Text markup +@cindex text markup +@cindex markup text -@lilypond[verbatim,raggedright] - \notes \context Voice = goUp { c'4 d' e' } -@end lilypond +@cindex typeset text -Second, contexts are created automatically to be able to interpret the -music expressions. Consider the following example: +The internal mechanism to typeset texts is accessed with the keyword +@code{\markup}. Within markup mode, you can enter texts similar to +lyrics. They are simply entered, while commands use the backslash @code{\}. +@cindex markup -@lilypond[verbatim,raggedright] - \score { \notes { c'4-( d' e'-) } } +@lilypond[quote,verbatim,fragment,relative=1] +c1^\markup { hello } +c1_\markup { hi there } +c1^\markup { hi \bold there, is \italic anyone home? } @end lilypond -@noindent -The sequential music is interpreted by the Score context initially, -but when a note is encountered, contexts are setup to accept that -note. In this case, a @code{Voice}, and @code{Staff} -context are created. The rest of the sequential music is also -interpreted with the same @code{Voice}, and -@code{Staff} context, putting the notes on the same staff, in the same -voice. - -@node Context properties -@subsection Context properties - -Contexts have properties. These properties are set from the @file{.ly} -file using the following expression: -@cindex context properties -@cindex properties, context +@cindex font switching +The markup in the example demonstrates font switching commands. The +command @code{\bold} and @code{\italic} apply to the first following +word only; enclose a set of texts with braces to apply a command +to more words: @example -\set @var{contextname}.@var{propname} = @var{value} +\markup @{ \bold @{ hi there @} @} @end example @noindent -Sets the @var{propname} property of the context @var{contextname} to -the specified Scheme expression @var{value}. Both @var{propname} and -@var{contextname} are strings, which can often be written unquoted. - -@cindex inheriting -Properties that are set in one context are inherited by all of the -contained contexts. This means that a property valid for the -@internalsref{Voice} context can be set in the @internalsref{Score} context -(for example) and thus take effect in all @internalsref{Voice} contexts. +For clarity, you can also do this for single arguments, e.g., -Properties can be unset using the following statement. @example -\unset @var{contextname}.@var{propname} +\markup @{ is \italic @{ anyone @} home @} @end example -@cindex properties, unsetting -@cindex @code{\unset} - -@noindent -This removes the definition of @var{propname} in @var{contextname}. If -@var{propname} was not defined in @var{contextname} (but was inherited -from a higher context), then this has no effect. - -If @var{contextname} is left out, then it defaults to the current -``bottom'' context: this is a context like @internalsref{Voice} that -cannot contain any other contexts. - - -@node Defining contexts -@subsection Defining contexts - -@cindex context definition -@cindex translator definition +@cindex font size, texts -The most common way to create a new context definition is by extending -an existing one. An existing context from the paper block is copied -by referencing a context identifier: -@example -\paper @{ - \translator @{ - @var{context-identifier} - @} -@} -@end example +In markup mode you can compose expressions, similar to mathematical +expressions, XML documents, and music expressions. You can stack +expressions grouped vertically with the command @code{\column}. +Similarly, @code{\center-align} aligns texts by their center lines: + +@lilypond[quote,verbatim,fragment,relative=1] +c1^\markup { \column { a bbbb \line { c d } } } +c1^\markup { \center-align { a bbbb c } } +c1^\markup { \line { a b c } } +@end lilypond -@noindent -Every predefined context has a standard identifier. For example, the -@code{Staff} context can be referred to as @code{\StaffContext}. -The context can then be modified by setting or changing properties, -e.g. +Markups can be stored in variables and these variables +may be attached to notes, like @example -\translator @{ - \StaffContext - Stem \set #'thickness = #2.0 - defaultBarType = #"||" -@} +allegro = \markup @{ \bold \large @{ Allegro @} @} + @{ a^\allegro b c d @} @end example -These assignments happen before interpretation starts, so a property -command will override any predefined settings. -@cindex engraver -@refbugs +Some objects have alignment procedures of their own, which cancel out +any effects of alignments applied to their markup arguments as a +whole. For example, the @internalsref{RehearsalMark} is horizontally +centered, so using @code{\mark \markup @{ \left-align .. @}} has no +effect. -It is not possible to collect multiple property assignments in a -variable, and apply to one @code{\translator} definition by -referencing that variable. +Similarly, for moving whole texts over notes with +@code{\raise}, use the following trick: +@lilypond[quote,verbatim] +{ + c'^\markup { \raise #0.5 not-raised } + c'^\markup { "" \raise #0.5 raised } +} +@end lilypond -@node Changing contexts locally -@subsection Changing contexts locally +On the second note, the text @code{raised} is moved relative to the +empty string @code{""} which is not visible. Alternatively, complete +objects can be moved with layout properties such as @code{padding} and +@code{extra-offset}. -Extending an existing context can also be done locally. A piece of -music can be interpreted in a changed context by using the following syntax -@example - \with @{ - @var{context modifications} - @} -@end example -These statements comes between @code{\new} or @code{\context} and the -music to be interpreted. The @var{context modifications} property -settings and @code{\remove}, @code{\consists} and @code{\consistsend} -commands. The syntax is similar to the @code{\translator} block. +@seealso -The following example shows how a staff is created with bigger spaces, -and without a @code{Clef_engraver}. +Init files: @file{scm/@/new@/-markup@/.scm}. -@lilypond[relative=1,fragment,verbatim] -<< - \new Staff { c4 es4 g2 } - \new Staff \with { - \override StaffSymbol #'staff-space = #(magstep 1.5) - fontSize = #1.5 - \remove "Clef_engraver" - } { - c4 es4 g2 - } >> -@end lilypond @refbugs -The command @code{\with} has no effect on contexts that already -exist. - - -@node Engravers and performers -@subsection Engravers and performers +Kerning or generation of ligatures is only done when the @TeX{} +backend is used. In this case, LilyPond does not account for them so +texts will be spaced slightly too wide. +Syntax errors for markup mode are confusing. -Each context is composed of a number of building blocks, or plug-ins -called engravers. An engraver is a specialized C++ class that is -compiled into the executable. Typically, an engraver is responsible -for one function: the @code{Slur_engraver} creates only @code{Slur} -objects, and the @code{Skip_event_swallow_translator} only swallows -(silently gobbles) @code{SkipEvent}s. +@menu +* Text encoding:: +* Nested scores:: +* Overview of text markup commands:: +* New dynamic marks:: +@end menu +@node Text encoding +@subsection Text encoding -@cindex engraver -@cindex plug-in +LilyPond uses the Pango library to format multi-lingual texts, and +does not perform any input-encoding conversions. This means that any +text, be it title, lyric text, or musical instruction containing +non-ASCII characters, must be utf-8. Easiest to enter such texts is +by using a Unicode-aware editor, and save using utf-8 encoding. Most +popular modern editors have utf-8 support, for example, vim, Emacs, +jEdit, and GEdit do. -An existing context definition can be changed by adding or removing an -engraver. The syntax for these operations is -@example -\consists @var{engravername} -\remove @var{engravername} -@end example +Depending on the fonts installed, the following fragment shows Hebrew +and Cyrillic lyrics, -@cindex @code{\consists} -@cindex @code{\remove} +@cindex Cyrillic +@cindex Hebrew +@cindex ASCII, non -@noindent -Here @var{engravername} is a string, the name of an engraver in the -system. In the following example, the @code{Clef_engraver} is removed -from the Staff context. The result is a staff without a clef, where -the middle C is at its default position, the center line: - -@lilypond[verbatim,raggedright] -\score { - \notes { - c'4 f'4 - } - \paper { - \translator { - \StaffContext - \remove Clef_engraver - } - } -} -@end lilypond +@lilypondfile[fontload]{utf8.ly} -A list of all engravers is in the internal documentation, -see @internalsref{Engravers}. -@node Defining new contexts -@subsection Defining new contexts +The @TeX{} backend does not handle encoding specially at all. Strings +in the input are put in the output as-is. Extents of text items in the +@TeX{} backend, are determined by reading a file created via the +@file{texstr} backend, +@example +lilypond -b texstr input/les-nereides.ly +latex les-nereides.texstr +@end example -It is also possible to define new contexts from scratch. To do this, -you must define give the new context a name. In the following -example, a very simple Staff context is created: one that will put -note heads on a staff symbol. +The last command produces @file{les-nereides.textmetrics}, which is +read when you execute @example -\translator @{ - \type "Engraver_group_engraver" - \name "SimpleStaff" - \alias "Staff" - \consists "Staff_symbol_engraver" - \consists "Note_head_engraver" - \consistsend "Axis_group_engraver" -@} +lilypond -b tex input/les-nereides.ly @end example -@noindent -The argument of @code{\type} is the name for a special engraver that -handles cooperation between simple engravers such as -@code{Note_head_engraver} and @code{Staff_symbol_engraver}. This -should always be @code{Engraver_group_engraver} (unless you are -defining a Score context from scratch, in which case -@code{Score_engraver} must be used). - -The complete list of context modifiers is the following: -@itemize @bullet -@item @code{\alias} @var{alternate-name}: -This specifies a different name. In the above example, -@code{\set Staff.X = Y} will also work on @code{SimpleStaff}s. - -@item @code{\consistsend} @var{engravername}: -Analogous to @code{\consists}, but makes sure that -@var{engravername} is always added to the end of the list of -engravers. - -Engravers that group context objects into axis groups or alignments -need to be at the end of the list. @code{\consistsend} insures that -engravers stay at the end even if a user adds or removes engravers. - -@item @code{\accepts} @var{contextname}: -This context can contains @var{contextname} contexts. The first -@code{\accepts} is created as a default context when events (e.g. notes -or rests) are encountered. - -@item @code{\denies}: -The opposite of @code{\accepts}. - -@item @code{\name} @var{contextname}: -This sets the type name of the context, e.g. @code{Staff}, -@code{Voice}. If the name is not specified, the translator will not -do anything. -@end itemize +Both @file{les-nereides.texstr} and @file{les-nereides.tex} need +suitable LaTeX wrappers to load appropriate La@TeX{} packages for +interpreting non-ASCII strings. + +@seealso -@c EOF +@inputfileref{input/regression,utf8.ly} +@node Nested scores +@subsection Nested scores +It is possible to nest music inside markups, by adding a @code{\score} +block to a markup expression. Such a score must contain a @code{\layout} +block. -@node Output details -@section Output details +@lilypond[quote,verbatim,raggedright] +\relative { + c4 d^\markup { + \score { + \relative { c4 d e f } + \layout { } + } + } + e f +} +@end lilypond + -The default output format is La@TeX{}, which should be run -through La@TeX{}. Using the option @option{-f} -(or @option{--format}) other output formats can be selected also, but -currently none of them work reliably. -At the beginning of the output file, various global parameters are -defined. Then the file @file{lilyponddefs.tex} is loaded to define -the macros used in the code which follows. @file{lilyponddefs.tex} -includes various other files, partially depending on the global -parameters. +@node Overview of text markup commands +@subsection Overview of text markup commands -Now the music is output system by system (a `system' consists of all -staves belonging together). From @TeX{}'s point of view, a system is an -@code{\hbox} which contains a lowered @code{\vbox} so that it is centered -vertically on the baseline of the text. Between systems, -@code{\interscoreline} is inserted vertically to have stretchable space. -The horizontal dimension of the @code{\hbox} is given by the -@code{linewidth} parameter from LilyPond's @code{\paper} block. +The following commands can all be used inside @code{\markup @{ @}}. -After the last system LilyPond emits a stronger variant of -@code{\interscoreline} only if the macro -@code{\lilypondpaperlastpagefill} is not defined (flushing the systems -to the top of the page). You can avoid that by setting the variable -@code{lastpagefill} in LilyPond's @code{\paper} block. +@include markup-commands.tely -It is possible to fine-tune the vertical offset further by defining the -macro @code{\lilypondscoreshift}: -@example -\def\lilypondscoreshift@{0.25\baselineskip@} -@end example +@node New dynamic marks +@subsection New dynamic marks -@noindent -where @code{\baselineskip} is the distance from one text line to the next. +It is possible to print new dynamic marks or text that should be aligned +with dynamics. Use @code{make-dynamic-script} to create these marks. -Here an example how to embed a small LilyPond file @code{foo.ly} into -running La@TeX{} text without using the @code{lilypond-book} script -(@pxref{lilypond-book manual}): +@cindex make-dynamic-script -@example -\documentclass@{article@} +@lilypond[quote,verbatim,raggedright] +sfzp = #(make-dynamic-script "sfzp") +\relative c' { + c4 c c\sfzp c +} +@end lilypond -\def\lilypondpaperlastpagefill@{@} -\lineskip 5pt -\def\lilypondscoreshift@{0.25\baselineskip@} +@cindex Dynamics, editorial +@cindex Dynamics, parenthesis -\begin@{document@} -This is running text which includes an example music file -\input@{foo.tex@} -right here. -\end@{document@} -@end example +It is also possible to print dynamics in round parenthesis or square +brackets. These are often used for adding editorial dynamics. -The file @file{foo.tex} has been simply produced with +@lilypond[quote,verbatim,raggedright] +\version "2.4.2" +rndf = \markup{ \center-align {\line { \bold{\italic (} + \dynamic f \bold{\italic )} }} } +boxf = \markup{ \bracket { \dynamic f } } +{ c'1_\rndf c'1_\boxf } +@end lilypond -@example - lilypond-bin foo.ly -@end example -The call to @code{\lineskip} assures that there is enough vertical space -between the LilyPond box and the surrounding text lines.