X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fchanging-defaults.itely;h=551c56d91ae0a9424e8e8e5b8e98010b60b95d11;hb=da12a3eb8e07ec4e910ead9f39f477920251190a;hp=9aece758792f30d04b6dea406db6d39a2020490f;hpb=88da77553a3b898874f578810b1bc451382aceff;p=lilypond.git diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely index 9aece75879..551c56d91a 100644 --- a/Documentation/user/changing-defaults.itely +++ b/Documentation/user/changing-defaults.itely @@ -7,6 +7,8 @@ version that you are working on. See TRANSLATION for details. @end ignore +@c \version "2.11.38" + @node Changing defaults @chapter Changing defaults @@ -20,15 +22,15 @@ are available and explains how to lookup which knob to use for a particular effect. -@cindex Program reference +@cindex Internals Reference The controls available for tuning are described in a separate document, the @iftex -Program reference manual. +Internals Reference manual. @end iftex @ifnottex -@ref{Top,Program reference,,lilypond-internals}. +@ref{Top,Internals Reference,,lilypond-internals}. @end ifnottex That manual lists all different variables, functions and options available in @@ -56,7 +58,7 @@ notation. For example, giving each staff a separate time signature. @item Page layout: changing the appearance of the spacing, line breaks, and page dimensions. These modifications are discussed -in @ref{Non-musical notation}, and @ref{Spacing issues}. +@c in @ref{notation}, and @ref{Spacing issues}. @end itemize Internally, LilyPond uses Scheme (a LISP dialect) to provide @@ -68,578 +70,16 @@ on entering numbers, lists, strings, and symbols in Scheme.} @menu -* Automatic notation:: -* Interpretation contexts:: -* The \override command:: -@end menu - - -@node Automatic notation -@section Automatic notation - -This section describes how to change the way that accidentals and -beams are automatically displayed. - -@menu -* Automatic accidentals:: -* Setting automatic beam behavior:: +* Interpretation contexts:: +* Explaining the Internals Reference:: +* Modifying properties:: +* Useful concepts and properties:: +* Common properties:: +* Advanced tweaks:: +* old The \override command:: +* Discussion of specific tweaks:: @end menu -@node Automatic accidentals -@subsection Automatic accidentals -@cindex Automatic accidentals - -Common rules for typesetting accidentals have been placed in a -function. This function is called as follows - -@funindex set-accidental-style -@example -#(set-accidental-style 'STYLE) -@end example - -@c TODO: check the context stuff below -@c -does it *really* work? -@c -the default contexts as specified in -@c scm/music-function.scm seem to be different -vv - -Optionally, the function can take two arguments: the name of the -accidental style, and an optional argument that denotes the context that -should be changed: - -@example -#(set-accidental-style 'STYLE #('CONTEXT#)) -@end example - -If no context name is supplied, @code{Staff} is the default, -but you may wish to apply the accidental style to a single @code{Voice} -instead. - -The following accidental styles are supported: - -@table @code -@item default -This is the default typesetting behavior. It corresponds -to 18th century common practice: Accidentals are -remembered to the end of the measure in which they occur and -only on their own octave. - -@lilypond[quote,ragged-right] -musicA = { << \relative { cis'8 fis, d'4 8 f bis4 | cis2. 4 | } \\ - \relative { ais'2 cis, | fis8 b a4 cis2 | } >> } - -musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4 - \change Staff = up cis' \change Staff = down - \change Staff = up dis' | \change Staff = down 4 gis - 2 | } }} - -\score { - \new PianoStaff { - << \context Staff = "up" { - %#(set-accidental-style 'default) - \musicA } - \context Staff = "down"{ - %#(set-accidental-style 'default) - \musicB } >> } - \header { piece = \markup {\fill-line { \fontsize #3 "'default" }}} -} -@end lilypond - -@item voice -The normal behavior is to remember the accidentals on -Staff-level. This variable, however, typesets accidentals -individually for each voice. Apart from that, the rule is similar to -@code{default}. - -@example - \new Staff << - #(set-accidental-style 'voice) - @{ @dots{} @} - >> -@end example - -As a result, accidentals from one voice do not get canceled in other -voices, which is often an unwanted result: in the following example, it -is hard to determine whether the second @samp{a} should be played -natural or sharp. - -@lilypond[quote,ragged-right] -musicA = { << \relative { cis'8 fis, d'4 8 f bis4 | cis2. 4 | } \\ - \relative { ais'2 cis, | fis8 b a4 cis2 | } >> } - -musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4 - \change Staff = up cis' \change Staff = down - \change Staff = up dis' | \change Staff = down 4 gis - 2 | } }} - -\score { - \new PianoStaff { - << \context Staff = "up" { - #(set-accidental-style 'voice) - \musicA } - \context Staff = "down"{ - #(set-accidental-style 'voice) - \musicB } >> } - \header { piece = \markup {\fill-line { \fontsize #3 "'voice" }}} -} -@end lilypond - -The @code{voice} option should be used if the voices -are to be read solely by individual musicians. If the staff is to be -used by one musician (e.g., a conductor) then -@code{modern} or @code{modern-cautionary} -should be used instead. - -@item modern -@funindex modern style accidentals -This rule corresponds to the common practice in the 20th century. This rule -prints the same accidentals as @code{default}, but temporary -accidentals also are canceled in other octaves. Furthermore, -in the same octave, they also get canceled in the following -measure: in the following example, notice the two natural signs which appear -in the second bar of the upper staff. - -@lilypond[quote,ragged-right] -musicA = { << \relative { cis'8 fis, d'4 8 f bis4 | cis2. 4 | } \\ - \relative { ais'2 cis, | fis8 b a4 cis2 | } >> } - -musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4 - \change Staff = up cis' \change Staff = down - \change Staff = up dis' | \change Staff = down 4 gis - 2 | } }} - -\score { - \new PianoStaff { - << \context Staff = "up" { - #(set-accidental-style 'modern) - \musicA } - \context Staff = "down"{ - #(set-accidental-style 'modern) - \musicB } >> } - \header { piece = \markup {\fill-line { \fontsize #3 "'modern" }}} -} -@end lilypond - -@item @code{modern-cautionary} -@funindex modern-cautionary -This rule is similar to @code{modern}, but the @q{extra} accidentals -(the ones not typeset by @code{default}) are typeset as cautionary -accidentals. They are printed in reduced size or (by default) -with parentheses -- this can be set by definig the @code{cautionary-style} -property of the @internalsref{AccidentalSuggestion} object. - -@lilypond[quote,ragged-right] -musicA = { << \relative { cis'8 fis, d'4 8 f bis4 | cis2. 4 | } \\ - \relative { ais'2 cis, | fis8 b a4 cis2 | } >> } - -musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4 - \change Staff = up cis' \change Staff = down - \change Staff = up dis' | \change Staff = down 4 gis - 2 | } }} - -\score { - \new PianoStaff { - << \context Staff = "up" { - #(set-accidental-style 'modern-cautionary) - \musicA } - \context Staff = "down"{ - #(set-accidental-style 'modern-cautionary) - \musicB } >> } - \header { piece = \markup {\fill-line { \fontsize #3 "'modern-cautionary" }}} -} -@end lilypond - -@funindex modern-voice -@item modern-voice -This rule is used for multivoice accidentals to be read both by musicians -playing one voice and musicians playing all voices. Accidentals are -typeset for each voice, but they @emph{are} canceled across voices in -the same @internalsref{Staff}. - -@lilypond[quote,ragged-right] -musicA = { << \relative { cis'8 fis, d'4 8 f bis4 | cis2. 4 | } \\ - \relative { ais'2 cis, | fis8 b a4 cis2 | } >> } - -musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4 - \change Staff = up cis' \change Staff = down - \change Staff = up dis' | \change Staff = down 4 gis - 2 | } }} - -\score { - \new PianoStaff { - << \context Staff = "up" { - #(set-accidental-style 'modern-voice) - \musicA } - \context Staff = "down"{ - #(set-accidental-style 'modern-voice) - \musicB } >> } - \header { piece = \markup {\fill-line { \fontsize #3 "'modern-voice" }}} -} -@end lilypond - -@funindex modern-voice-cautionary -@item modern-voice-cautionary -This rule is the same as @code{modern-voice}, but with the extra -accidentals (the ones not typeset by @code{voice}) typeset -as cautionaries. Even though all accidentals typeset by -@code{default} @emph{are} typeset by this variable, -some of them are typeset as cautionaries. - -@lilypond[quote,ragged-right] -musicA = { << \relative { cis'8 fis, d'4 8 f bis4 | cis2. 4 | } \\ - \relative { ais'2 cis, | fis8 b a4 cis2 | } >> } - -musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4 - \change Staff = up cis' \change Staff = down - \change Staff = up dis' | \change Staff = down 4 gis - 2 | } }} - -\score { - \new PianoStaff { - << \context Staff = "up" { - #(set-accidental-style 'modern-voice-cautionary) - \musicA } - \context Staff = "down"{ - #(set-accidental-style 'modern-voice-cautionary) - \musicB } >> } - \header { piece = \markup {\fill-line { \fontsize #3 "'modern-voice-cautionary" }}} -} -@end lilypond - -@item piano -@funindex piano accidentals -This accidental style takes place in a GrandStaff context. However, you have to -explicitly set it for @emph{each} individual Staff of the GrandStaff: - -@example -\new GrandStaff @{ << - \new Staff = "up" @{ << - #(set-accidental-style 'piano) - @{ @dots{} @} - >> @} - \new Staff = "down"@{ << - #(set-accidental-style 'piano) - @{ @dots{} @} - >> @} ->> @} -@end example - -This rule reflects 20th century practice for piano notation. Its behavior is very -similar to @code{modern} style, but here accidentals also get canceled -across the staves in the same @internalsref{GrandStaff} or -@internalsref{PianoStaff}. - -@lilypond[quote,ragged-right] -musicA = { << \relative { cis'8 fis, d'4 8 f bis4 | cis2. 4 | } \\ - \relative { ais'2 cis, | fis8 b a4 cis2 | } >> } - -musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4 - \change Staff = up cis' \change Staff = down - \change Staff = up dis' | \change Staff = down 4 gis - 2 | } }} - -\score { - \new PianoStaff { - << \context Staff = "up" { - #(set-accidental-style 'piano) - \musicA } - \context Staff = "down"{ - #(set-accidental-style 'piano) - \musicB } >> } - \header { piece = \markup {\fill-line { \fontsize #3 "'piano" }}} -} -@end lilypond - -@item piano-cautionary -@funindex #(set-accidental-style 'piano-cautionary) -Same as @code{#(set-accidental-style 'piano)} but with the extra -accidentals typeset as cautionaries. - -@lilypond[quote,ragged-right] -musicA = { << \relative { cis'8 fis, d'4 8 f bis4 | cis2. 4 | } \\ - \relative { ais'2 cis, | fis8 b a4 cis2 | } >> } - -musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4 - \change Staff = up cis' \change Staff = down - \change Staff = up dis' | \change Staff = down 4 gis - 2 | } }} - -\score { - \new PianoStaff { - << \context Staff = "up" { - #(set-accidental-style 'piano-cautionary) - \musicA } - \context Staff = "down"{ - #(set-accidental-style 'piano-cautionary) - \musicB } >> } - \header { piece = \markup {\fill-line { \fontsize #3 "'piano-cautionary" }}} -} -@end lilypond - -@item no-reset -@funindex no-reset accidental style -This is the same as @code{default} but with accidentals lasting -@q{forever} and not only until the next measure: -@lilypond[quote,ragged-right] -musicA = { << \relative { cis'8 fis, d'4 8 f bis4 | cis2. 4 | } \\ - \relative { ais'2 cis, | fis8 b a4 cis2 | } >> } - -musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4 - \change Staff = up cis' \change Staff = down - \change Staff = up dis' | \change Staff = down 4 gis - 2 | } }} - -\score { - \new PianoStaff { - << \context Staff = "up" { - #(set-accidental-style 'no-reset) - \musicA } - \context Staff = "down"{ - #(set-accidental-style 'no-reset) - \musicB } >> } - \header { piece = \markup {\fill-line { \fontsize #3 "'no-reset" }}} -} -@end lilypond - -@item forget -This is sort of the opposite of @code{no-reset}: Accidentals -are not remembered at all -- and hence all accidentals are -typeset relative to the key signature, regardless of what was -before in the music - -@lilypond[quote,ragged-right] -musicA = { << \relative { cis'8 fis, d'4 8 f bis4 | cis2. 4 | } \\ - \relative { ais'2 cis, | fis8 b a4 cis2 | } >> } - -musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4 - \change Staff = up cis' \change Staff = down - \change Staff = up dis' | \change Staff = down 4 gis - 2 | } }} - -\score { - \new PianoStaff { - << \context Staff = "up" { - #(set-accidental-style 'forget) - \musicA } - \context Staff = "down"{ - #(set-accidental-style 'forget) - \musicB } >> } - \header { piece = \markup {\fill-line { \fontsize #3 "'forget" }}} -} -@end lilypond -@end table - - -@seealso - -Program reference: @internalsref{Accidental_engraver}, -@internalsref{Accidental}, @internalsref{AccidentalSuggestion} and @internalsref{AccidentalPlacement}. - - -@refbugs - -Simultaneous notes are considered to be entered in sequential -mode. This means that in a chord the accidentals are typeset as if the -notes in the chord happen one at a time, in the order in which -they appear in the input file. This is a problem when accidentals -in a chord depend on each other, -which does not happen for the default accidental style. The problem -can be solved by manually inserting @code{!} and @code{?} for the -problematic notes. - - -@node Setting automatic beam behavior -@subsection Setting automatic beam behavior - -@funindex autoBeamSettings -@funindex (end * * * *) -@funindex (begin * * * *) -@cindex automatic beams, tuning -@cindex tuning automatic beaming - -@c [TODO: use \applyContext] - -In normal time signatures, automatic beams can start on any note but can -only end in a few positions within the measure: beams can end on a beat, -or at durations specified by the properties in -@code{autoBeamSettings}. The properties in @code{autoBeamSettings} -consist of a list of rules for where beams can begin and end. The -default @code{autoBeamSettings} rules are defined in -@file{scm/@/auto@/-beam@/.scm}. - -In order to add a rule to the list, use -@example -#(override-auto-beam-setting '(be p q n m) a b [context]) -@end example - -@itemize - -@item @code{be} is either "begin" or "end". - -@item @code{p/q} is the duration of the note for which you want -to add a rule. A beam is considered to have the duration of its -shortest note. Set @code{p} and @code{q} to @code{'*'} to -have this apply to any beam. - -@item @code{n/m} is the time signature to which -this rule should apply. Set @code{n} and @code{m} to @code{'*'} -to have this apply in any time signature. - -@item @code{a/b} is the position in the bar at which the beam should -begin/end. - -@item @code{context} is optional, and it specifies the context at which -the change should be made. The default is @code{'Voice}. -@code{#(score-override-auto-beam-setting '(A B C D) E F)} is equivalent to -@code{#(override-auto-beam-setting '(A B C D) E F 'Score)}. - -@end itemize - -For example, if automatic beams should always end on the first quarter -note, use - -@example -#(override-auto-beam-setting '(end * * * *) 1 4) -@end example - -You can force the beam settings to only take effect on beams whose shortest -note is a certain duration - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\time 2/4 -#(override-auto-beam-setting '(end 1 16 * *) 1 16) -a16 a a a a a a a | -a32 a a a a16 a a a a a | -#(override-auto-beam-setting '(end 1 32 * *) 1 16) -a32 a a a a16 a a a a a | -@end lilypond - -You can force the beam settings to only take effect in certain time -signatures - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\time 5/8 -#(override-auto-beam-setting '(end * * 5 8) 2 8) -c8 c d d d -\time 4/4 -e8 e f f e e d d -\time 5/8 -c8 c d d d -@end lilypond - -You can also remove a previously set beam-ending rule by using - -@example -#(revert-auto-beam-setting '(be p q n m) a b [context]) -@end example - -@noindent -be, p, q, n, m, a, b and context are the same as above. Note that the -default rules are specified in @file{scm/@/auto@/-beam@/.scm}, -so you can revert rules that you did not explicitly create. - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\time 4/4 -a16 a a a a a a a a a a a a a a a -#(revert-auto-beam-setting '(end 1 16 4 4) 1 4) -a16 a a a a a a a a a a a a a a a -@end lilypond - -The rule in a revert-auto-beam-setting statement must exactly match the -original rule. That is, no wildcard expansion is taken into account. - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\time 1/4 -#(override-auto-beam-setting '(end 1 16 1 4) 1 8) -a16 a a a -#(revert-auto-beam-setting '(end 1 16 * *) 1 8) % this won't revert it! -a a a a -#(revert-auto-beam-setting '(end 1 16 1 4) 1 8) % this will -a a a a -@end lilypond - - - -@c TODO: old material -- not covered by above stuff, I think. -If automatic beams should end on every quarter in 5/4 time, specify -all endings -@example -#(override-auto-beam-setting '(end * * * *) 1 4 'Staff) -#(override-auto-beam-setting '(end * * * *) 1 2 'Staff) -#(override-auto-beam-setting '(end * * * *) 3 4 'Staff) -#(override-auto-beam-setting '(end * * * *) 5 4 'Staff) -@dots{} -@end example - -The same syntax can be used to specify beam starting points. In this -example, automatic beams can only end on a dotted quarter note -@example -#(override-auto-beam-setting '(end * * * *) 3 8) -#(override-auto-beam-setting '(end * * * *) 1 2) -#(override-auto-beam-setting '(end * * * *) 7 8) -@end example -In 4/4 time signature, this means that automatic beams could end only on -3/8 and on the fourth beat of the measure (after 3/4, that is 2 times -3/8, has passed within the measure). - -If any unexpected beam behaviour occurs, check the default automatic beam -settings in @file{scm/@/auto@/-beam@/.scm} -for possible interference, because the beam -endings defined there will still apply on top of your own overrides. Any -unwanted endings in the default vales must be reverted for your time -signature(s). - -For example, to typeset @code{(3 4 3 2)}-beam endings in 12/8, begin -with - -@example -%%% revert default values in scm/auto-beam.scm regarding 12/8 time -#(revert-auto-beam-setting '(end * * 12 8) 3 8) -#(revert-auto-beam-setting '(end * * 12 8) 3 4) -#(revert-auto-beam-setting '(end * * 12 8) 9 8) - -%%% your new values -#(override-auto-beam-setting '(end 1 8 12 8) 3 8) -#(override-auto-beam-setting '(end 1 8 12 8) 7 8) -#(override-auto-beam-setting '(end 1 8 12 8) 10 8) -@end example - -@cindex automatic beam generation -@cindex autobeam -@funindex autoBeaming -@cindex lyrics - -If beams are used to indicate melismata in songs, then automatic -beaming should be switched off with @code{\autoBeamOff}. - - -@refcommands - -@funindex \autoBeamOff -@code{\autoBeamOff}, -@funindex \autoBeamOn -@code{\autoBeamOn}. - -@commonprop - -Beaming patterns may be altered with the @code{beatGrouping} property, - -@lilypond[quote,verbatim,relative=2,fragment,ragged-right] -\time 5/16 -\set beatGrouping = #'(2 3) -c8[^"(2+3)" c16 c8] -\set beatGrouping = #'(3 2) -c8[^"(3+2)" c16 c8] -@end lilypond - - -@refbugs - -If a score ends while an automatic beam has not been ended and is -still accepting notes, this last beam will not be typeset at all. The -same holds polyphonic voices, entered with @code{<< @dots{} \\ @dots{} ->>}. If a polyphonic voice ends while an automatic beam is still -accepting notes, it is not typeset. - @node Interpretation contexts @section Interpretation contexts @@ -647,79 +87,159 @@ accepting notes, it is not typeset. This section describes what contexts are, and how to modify them. @menu -* Contexts explained:: -* Creating contexts:: -* Changing context properties on the fly:: -* Modifying context plug-ins:: -* Layout tunings within contexts:: -* Changing context default settings:: -* Defining new contexts:: -* Aligning contexts:: -* Vertical grouping of grobs:: +* Contexts explained:: +* Creating contexts:: +* Modifying context plug-ins:: +* Changing context default settings:: +* Defining new contexts:: +* Aligning contexts:: @end menu @node Contexts explained @subsection Contexts explained -When music is printed, a lot of notational elements must be added to the -output. For example, compare the input and output of the following example: - -@lilypond[quote,verbatim,relative=2,fragment] -cis4 cis2. g4 -@end lilypond - -The input is rather sparse, but in the output, bar lines, accidentals, -clef, and time signature are added. LilyPond @emph{interprets} the -input. During this step, the musical information is inspected in time -order, similar to reading a score from left to right. While reading -the input, the program remembers where measure boundaries are, and which -pitches require explicit accidentals. This information can be presented on -several levels. For example, the effect of an accidental is limited -to a single staff, while a bar line must be synchronized across the -entire score. - -Within LilyPond, these rules and bits of information are grouped in -@emph{Contexts}. Some examples of contexts are @context{Voice}, -@context{Staff}, and @context{Score}. They are hierarchical, for -example: a @context{Staff} can contain many @context{Voice}s, and a -@context{Score} can contain many @context{Staff} contexts. - -@quotation -@image{context-example,5cm,,} -@end quotation - -Each context has the responsibility for enforcing some notation rules, -creating some notation objects and maintaining the associated -properties. For example, the @context{Voice} context may introduce an -accidental and then the @context{Staff} context maintains the rule to -show or suppress the accidental for the remainder of the measure. The -synchronization of bar lines is handled at @context{Score} context. - -However, in some music we may not want the bar lines to be -synchronized -- consider a polymetric score in 4/4 and 3/4 time. In -such cases, we must modify the default settings of the @context{Score} -and @context{Staff} contexts. - -For very simple scores, contexts are created implicitly, and you need -not be aware of them. For larger pieces, such as anything with more -than one staff, they must be -created explicitly to make sure that you get as many staves as you -need, and that they are in the correct order. For typesetting pieces -with specialized notation, it can be useful to modify existing or -to define new contexts. - - -A complete description of all available contexts is in the program -reference, see -@ifhtml -@internalsref{Contexts}. -@end ifhtml -@ifnothtml -Translation @expansion{} Context. -@end ifnothtml +>> > > - list of contexts: my *danger unmaintainable* +>> > > alarm just went off. I'm + +I knew it would... And leaving out some of them is perfectly fine +with me. +I do think that a list like this, with the main contexts and a +brief +description of what they do (perhaps also with a note about what +default +behavior is associated with each of them, but this may be +unmanageable), +should be there, and then we could simply list the remaining ones +without +further explanation and with links to the IR. + + +The Master Of All Contexts +========================== + + * Score + This is the top level notation context. No other context +can + contain a Score context. This context handles the + administration of time signatures. It also makes sure that + items such as clefs, time signatures, and key-signatures +are + aligned across staves. + You cannot explicitly instantiate a Score context (since +it is + not contained in any other context). It is instantiated + automatically when an output definition (a \score or +\layout + block) is processed. + (it should also be made clear somewhere what the +difference is between + \score and \Score). + +Top-level contexts: Staff containers +==================================== + * StaffGroup + Groups staves while adding a bracket on the left side, + grouping the staves together. The bar lines of the +contained + staves are connected vertically. StaffGroup only consists +of a + collection of staves, with a bracket in front and spanning +bar + lines. + * ChoirStaff + Identical to StaffGroup except that the contained staves +are + not connected vertically. + * GrandStaff + A group of staves, with a brace on the left side, grouping +the + staves together. The bar lines of the contained staves are + connected vertically. + * PianoStaff + Just like GrandStaff but with a forced distance between +the + staves, so cross staff beaming and slurring can be used. + * DrumStaff + Handles typesetting for percussion. Can contain DrumVoice + * InnerStaffGroup + * InnerChoirStaff + +Staff-level contexts +==================== + * Staff + Handles clefs, bar lines, keys, accidentals. It can +contain + Voice contexts. + * RhythmicStaff + Like Staff but for printing rhythms. Pitches are + ignored; the notes are printed on one line. + * TabStaff + Context for generating tablature. By default lays the +music + expression out as a guitar tablature, printed on six +lines. + * VaticanaStaff + Same as Staff, except that it is accommodated for + typesetting a piece in gregorian style. + * MensuralStaff + Same as Staff, except that it is accommodated for + typesetting a piece in mensural style. + +Voice-level (bottom) contexts +============================= +What is generated by default here? The voice-level contexts +initiate +certain properties and start engravers. + + * Voice + Corresponds to a voice on a staff. This context handles +the + conversion of dynamic signs, stems, beams, super- and + subscripts, slurs, ties, and rests. + You have to instantiate this explicitly if you want to +have + multiple voices on the same staff. + Bottom context. + * VaticanaVoice + Same as Voice, except that it is accommodated for + typesetting a piece in gregorian style. + * MensuralVoice + Same as Voice, except that it is accommodated for + typesetting a piece in mensural style. + * Lyrics + Corresponds to a voice with lyrics. Handles the printing +of a + single line of lyrics. + Bottom context. + * DrumVoice + A voice on a percussion staff. + * FiguredBass + + * ChordNames + Typesets chord names. This context is a `bottom' context; +it + cannot contain other contexts. + +------------------------------ +Then the following, which I don't know what to do with: + + * TabVoice + * GregorianTranscriptionVoice + * GregorianTranscriptionStaff + + * FretBoards + Engraves fretboards from chords. Not easy... Not +documented. + * NoteNames + + * CueVoice Not documented + * Global + Hard coded entry point for LilyPond. Cannot be tuned. + * Devnull + Silently discards all musical information given to this +context. -@c [TODO: describe propagation] @node Creating contexts @@ -807,7 +327,7 @@ music = @{ c4 c4 @} arts = @{ s4-. s4-> @} @end example -They are combined by sending both to the same @context{Voice} context, +They are combined by sending both to the same @code{Voice} context, @example << @@ -844,13 +364,13 @@ any context of type @var{type}, regardless of its given name. This variant is used with music expressions that can be interpreted at several levels. For example, the @code{\applyOutput} command (see @ref{Running a function on all layout objects}). Without an explicit -@code{\context}, it is usually applied to @context{Voice} +@code{\context}, it is usually applied to @code{Voice} @example \applyOutput #'@var{context} #@var{function} % apply to Voice @end example -To have it interpreted at the @context{Score} or @context{Staff} level use +To have it interpreted at the @code{Score} or @code{Staff} level use these forms @example @@ -861,175 +381,51 @@ these forms @end itemize -@node Changing context properties on the fly -@subsection Changing context properties on the fly - -@cindex properties -@funindex \set -@cindex changing properties +@node Modifying context plug-ins +@subsection Modifying context plug-ins -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, +Notation contexts (like @code{Score} and @code{Staff}) not only +store properties, +they also contain plug-ins called @q{engravers} that create notation +elements. For example, the @code{Voice} context contains a +@code{Note_head_engraver} and the @code{Staff} context contains a +@code{Key_signature_engraver}. -@example -\set @var{context}.@var{prop} = #@var{value} -@end example +For a full a description of each plug-in, see +@ifhtml +@rinternals{Engravers and Performers}. +@end ifhtml +@ifnothtml +Internals Reference @expansion{} Translation @expansion{} Engravers. +@end ifnothtml +Every context described in +@ifhtml +@rinternals{Contexts} +@end ifhtml +@ifnothtml +Internals Reference @expansion{} Translation @expansion{} Context. +@end ifnothtml +lists the engravers used for that context. -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. +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, -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, +@funindex \with -@lilypond[quote,verbatim,relative=2,fragment] -c8 c c c -\set autoBeaming = ##f -c8 c c c -@end lilypond - -@noindent -the @var{context} argument to @code{\set} is left out, so automatic -beaming is switched off in the current @internalsref{Voice}. Note that -the bottom-most context does not always contain the property that you -wish to change -- for example, attempting to set the @code{skipBars} -property (of the bottom-most context, in this case @code{Voice}) will -have no effect. - -@lilypond[quote,verbatim,relative=2,fragment] -R1*2 -\set skipBars = ##t -R1*2 -@end lilypond - -Contexts are hierarchical, so if a bigger context was specified, for -example @context{Staff}, then the change would also apply to all -@context{Voice}s in the current stave. The change is applied -@q{on-the-fly}, during the music, so that the setting only affects the -second group of eighth notes. - -@funindex \unset - -There is also an @code{\unset} command, -@example -\unset @var{context}.@var{prop} -@end example - -@noindent -which removes the definition of @var{prop}. This command removes -the definition only if it is set in @var{context}, so - -@example -\set Staff.autoBeaming = ##f -@end example - -@noindent -introduces a property setting at @code{Staff} level. The setting also -applies to the current @code{Voice}. However, - -@example -\unset Voice.autoBeaming -@end example - -@noindent -does not have any effect. To cancel this setting, the @code{\unset} -must be specified on the same level as the original @code{\set}. In -other words, undoing the effect of @code{Staff.autoBeaming = ##f} -requires -@example -\unset Staff.autoBeaming -@end example - -Like @code{\set}, the @var{context} argument does not have to be -specified for a bottom context, so the two statements - -@example -\set Voice.autoBeaming = ##t -\set autoBeaming = ##t -@end example - -@noindent -are equivalent. - - -@cindex \once -Settings that should only apply to a single time-step can be entered -with @code{\once}, for example in - -@lilypond[quote,verbatim,relative=2,fragment] -c4 -\once \set fontSize = #4.7 -c4 -c4 -@end lilypond - -the property @code{fontSize} is unset automatically after the second -note. - -A full description of all available context properties is in the -program reference, see -@ifhtml -@internalsref{Tunable context properties}. -@end ifhtml -@ifnothtml -Translation @expansion{} Tunable context properties. -@end ifnothtml - - -@node Modifying context plug-ins -@subsection Modifying context plug-ins - -Notation contexts (like @code{Score} and @code{Staff}) not only -store properties, -they also contain plug-ins called @q{engravers} that create notation -elements. For example, the @code{Voice} context contains a -@code{Note_head_engraver} and the @code{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 @expansion{} Translation @expansion{} Engravers. -@end ifnothtml -Every context described in -@ifhtml -@internalsref{Contexts} -@end ifhtml -@ifnothtml -Program reference @expansion{} Translation @expansion{} 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, - -@funindex \with - -@example -\new @var{context} \with @{ - \consists @dots{} - \consists @dots{} - \remove @dots{} - \remove @dots{} - @emph{etc.} -@} -@{ - @emph{..music..} -@} -@end example +@example +\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 @@ -1053,14 +449,14 @@ example which removes @code{Time_signature_engraver} and In the second staff there are no time signature or clef symbols. This is a rather crude method of making objects disappear since it will affect the entire staff. This method also influences the spacing, which may or -may not be desirable. A more -sophisticated method of blanking objects is shown in @rlearning{Common tweaks}. +may not be desirable. More sophisticated methods of blanking objects +are shown in @rlearning{Visibility and color of objects}. The next example shows a practical application. Bar lines and time signatures are normally synchronized across the score. This is done by the @code{Timing_translator} and @code{Default_bar_line_engraver}. This plug-in keeps an administration of time signature, location -within the measure, etc. By moving thes engraver from @code{Score} to +within the measure, etc. By moving these engraver from @code{Score} to @code{Staff} context, we can have a score where each staff has its own time signature. @@ -1090,125 +486,13 @@ time signature. @end lilypond -@node Layout tunings within contexts -@subsection Layout tunings within contexts - -Each context is responsible for creating certain types of graphical -objects. The settings used for printing these objects are also stored by -context. By changing these settings, the appearance of objects can be -altered. - -The syntax for this is - -@example -\override @var{context}.@var{name} #'@var{property} = #@var{value} -@end example - -Here @var{name} is the name of a graphical object, like @code{Stem} or -@code{NoteHead}, and @var{property} is an internal variable of the -formatting system (@q{grob property} or @q{layout property}). The latter is a -symbol, so it must be quoted. The subsection @ref{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. - -The command - -@verbatim -\override Staff.Stem #'thickness = #4.0 -@end verbatim - -@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. - -Analogous to @code{\set}, the @var{context} argument may be left out, -causing the default context @context{Voice} to be used. Adding -@code{\once} applies the change during one timestep only. - -@lilypond[quote,fragment,verbatim,relative=2] -c4 -\once \override Stem #'thickness = #4.0 -c4 -c4 -@end lilypond - -The @code{\override} must be done before the object is -started. Therefore, when altering @emph{Spanner} objects such as slurs -or beams, the @code{\override} command must be executed at the moment -when the object is created. In this example, - -@lilypond[quote,fragment,verbatim,relative=2] -\override Slur #'thickness = #3.0 -c8[( c -\override Beam #'thickness = #0.6 -c8 c]) -@end lilypond - -@noindent -the slur is fatter but the beam is not. This is because the command for -@code{Beam} comes after the Beam is started, so it has no effect. - -Analogous to @code{\unset}, the @code{\revert} command for a context -undoes an @code{\override} command; like with @code{\unset}, it only -affects settings that were made in the same context. In other words, the -@code{\revert} in the next example does not do anything. - -@example -\override Voice.Stem #'thickness = #4.0 -\revert Staff.Stem #'thickness -@end example - -Some tweakable options are called @q{subproperties} and reside inside -properties. To tweak those, use commands of the form - -@c leave this as a long long -@example -\override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value} -@end example - -@noindent -such as - -@example -\override Stem #'details #'beamed-lengths = #'(4 4 3) -@end example - - -@seealso - -Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty}, -@internalsref{PropertySet}, @internalsref{Backend}, and -@internalsref{All layout objects}. - - -@refbugs - -The back-end is not very strict in type-checking object properties. -Cyclic references in Scheme values for properties can cause hangs -or crashes, or both. - - @node Changing context default settings @subsection Changing context default settings -The adjustments of the previous subsections (@ref{Changing context -properties on the fly}, @ref{Modifying context plug-ins}, and -@ref{Layout tunings within contexts}) can also be entered separately -from the music in the @code{\layout} block, +The adjustments of the previous subsections ( +@ref{The \set command}, @ref{Modifying context plug-ins}, and +@ref{Overview of modifying properties}) can also be entered +separately from the music in the @code{\layout} block, @example \layout @{ @@ -1251,7 +535,7 @@ will also work. -@refbugs +@knownissues It is not possible to collect context changes in a variable and apply them to a @code{\context} definition by referring to that variable. @@ -1271,17 +555,20 @@ after calling @code{\RemoveEmptyStaffContext}, ie @} @end example +TODO: add \with in here. + + @node Defining new contexts @subsection Defining new contexts -Specific contexts, like @context{Staff} and @code{Voice}, are made of +Specific contexts, like @code{Staff} and @code{Voice}, are made of simple building blocks. It is possible to create new types of contexts with different combinations of engraver plug-ins. The next example shows how to build a different type of -@context{Voice} context from scratch. It will be similar to -@code{Voice}, but only prints centered slash noteheads. It can be used +@code{Voice} context from scratch. It will be similar to +@code{Voice}, but only prints centered slash note heads. It can be used to indicate improvisation in jazz pieces, @lilypond[quote,ragged-right] @@ -1328,9 +615,9 @@ First it is necessary to define a name for the new context: \name ImproVoice @end example -Since it is similar to the @context{Voice}, we want commands that work -on (existing) @context{Voice}s to remain working. This is achieved by -giving the new context an alias @context{Voice}, +Since it is similar to the @code{Voice}, we want commands that work +on (existing) @code{Voice}s to remain working. This is achieved by +giving the new context an alias @code{Voice}, @example \alias Voice @@ -1351,8 +638,8 @@ but we only need this on the center line, squashedPosition = #0 @end example -The @internalsref{Pitch_squash_engraver} modifies note heads (created -by @internalsref{Note_heads_engraver}) and sets their vertical +The @rinternals{Pitch_squash_engraver} modifies note heads (created +by @rinternals{Note_heads_engraver}) and sets their vertical position to the value of @code{squashedPosition}, in this case@tie{}@code{0}, the center line. @@ -1365,7 +652,7 @@ The notes look like a slash, and have no stem, All these plug-ins have to cooperate, and this is achieved with a special plug-in, which must be marked with the keyword @code{\type}. -This should always be @internalsref{Engraver_group}, +This should always be @rinternals{Engraver_group}, @example \type "Engraver_group" @@ -1388,8 +675,8 @@ Put together, we get @end example @funindex \accepts -Contexts form hierarchies. We want to hang the @context{ImproVoice} -under @context{Staff}, just like normal @code{Voice}s. Therefore, we +Contexts form hierarchies. We want to hang the @code{ImproVoice} +under @code{Staff}, just like normal @code{Voice}s. Therefore, we modify the @code{Staff} definition with the @code{\accepts} command, @@ -1437,10 +724,12 @@ Then the output at the start of this subsection can be entered as @node Aligning contexts @subsection Aligning contexts -New contexts may be aligned above or below exisiting contexts. This +New contexts may be aligned above or below existing contexts. This could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and in ossia, +FIXME: this section doesn't work in pdf. (?) + @cindex ossia @findex alignAboveContext @findex alignBelowContext @@ -1459,94 +748,22 @@ ossia = { f4 f f f } @end lilypond -@node Vertical grouping of grobs -@subsection Vertical grouping of grobs - -The VerticalAlignment and VerticalAxisGroup grobs work together. -VerticalAxisGroup groups together different grobs like Staff, Lyrics, -etc. VerticalAlignment then vertically aligns the different grobs -grouped together by VerticalAxisGroup. There is usually only one -VerticalAlignment per score but every Staff, Lyrics, etc. has its own -VerticalAxisGroup. - - -@node The \override command -@section The @code{\override} command - -In the previous section, we have already touched on a command that -changes layout details: the @code{\override} command. In this section, -we will look in more detail at how to use the command in practice. The -general syntax of this command is: - -@example -\override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value} -@end example +@node Explaining the Internals Reference +@section Explaining the Internals Reference -This will set the @var{layout_property} of the specified @var{layout_object}, -which is a member of the @var{context}, to the @var{value}. @menu -* Constructing a tweak:: * Navigating the program reference:: * Layout interfaces:: * Determining the grob property:: -* Objects connected to the input:: -* Using Scheme code instead of \tweak:: -* \set versus \override:: -* Difficult tweaks:: +* Naming conventions:: @end menu +@node Navigating the program reference +@subsection Navigating the program reference - -@node Constructing a tweak -@subsection Constructing a tweak - -Commands which change output generally look like - -@example -\override Voice.Stem #'thickness = #3.0 -@end example - -@noindent -To construct this tweak we must determine these bits of information: - -@itemize -@item the context: here @context{Voice}. -@item the layout object: here @code{Stem}. -@item the layout property: here @code{thickness}. -@item a sensible value: here @code{3.0}. -@end itemize - -Some tweakable options are called @q{subproperties} and reside inside -properties. To tweak those, use commands in the form - -@example -\override Stem #'details #'beamed-lengths = #'(4 4 3) -@end example - -@cindex internal documentation -@cindex finding graphical objects -@cindex graphical object descriptions -@cindex tweaking -@funindex \override -@cindex internal documentation - -For many properties, regardless of the data type of the property, setting the -property to false ( @code{##f} ) will result in turning it off, causing -Lilypond to ignore that property entirely. This is particularly useful for -turning off grob properties which may otherwise be causing problems. - -We demonstrate how to glean this information from the notation manual -and the program reference. - - - - -@node Navigating the program reference -@subsection Navigating the program reference - -Suppose we want to move the fingering indication in the fragment -below: +Suppose we want to move the fingering indication in the fragment +below: @lilypond[quote,fragment,relative=2,verbatim] c-2 @@ -1558,9 +775,9 @@ If you visit the documentation on fingering instructions (in @ref{Fingering instructions}), you will notice: @quotation -@seealso +@strong{See also} -Program reference: @internalsref{Fingering}. +Internals Reference: @rinternals{Fingering}. @end quotation @@ -1575,7 +792,7 @@ expression for the input @code{-2}. The page contains many links forward. For example, it says @quotation -Accepted by: @internalsref{Fingering_engraver}, +Accepted by: @rinternals{Fingering_engraver}, @end quotation @noindent @@ -1583,7 +800,7 @@ That link brings us to the documentation for the Engraver, the plug-in, which says @quotation -This engraver creates the following layout objects: @internalsref{Fingering}. +This engraver creates the following layout objects: @rinternals{Fingering}. @end quotation In other words, once the @code{FingerEvent}s are interpreted, the @@ -1594,7 +811,7 @@ In other words, once the @code{FingerEvent}s are interpreted, the @c I can't figure out what this is supposed to mean. -gp The @code{Fingering_engraver} is also listed to create -@internalsref{Fingering} objects, +@rinternals{Fingering} objects, @c old info? it doesn't make any sense to me with our current docs. This is also the @@ -1610,12 +827,12 @@ difficult to understand if you are using the PDF manual. @end ifnothtml -Follow the link to @internalsref{Fingering}. At the top of the +Follow the link to @rinternals{Fingering}. At the top of the page, you will see @quotation -Fingering objects are created by: @internalsref{Fingering_engraver} and -@internalsref{New_fingering_engraver}. +Fingering objects are created by: @rinternals{Fingering_engraver} and +@rinternals{New_fingering_engraver}. @end quotation By following related links inside the program reference, we can follow the @@ -1623,16 +840,16 @@ flow of information within the program: @itemize -@item @internalsref{Fingering}: -@internalsref{Fingering} objects are created by: -@internalsref{Fingering_engraver} +@item @rinternals{Fingering}: +@rinternals{Fingering} objects are created by: +@rinternals{Fingering_engraver} -@item @internalsref{Fingering_engraver}: -Music types accepted: @internalsref{fingering-event} +@item @rinternals{Fingering_engraver}: +Music types accepted: @rinternals{fingering-event} -@item @internalsref{fingering-event}: +@item @rinternals{fingering-event}: Music event type @code{fingering-event} is in Music expressions named -@internalsref{FingerEvent} +@rinternals{FingerEvent} @end itemize This path goes against the flow of information in the program: it @@ -1643,12 +860,12 @@ information, eventually ending up at the output object(s). The program reference can also be browsed like a normal document. It contains chapters on @ifhtml -@internalsref{Music definitions}, +@rinternals{Music definitions}, @end ifhtml @ifnothtml @code{Music definitions} @end ifnothtml -on @internalsref{Translation}, and the @internalsref{Backend}. Every +on @rinternals{Translation}, and the @rinternals{Backend}. Every chapter lists all the definitions used and all properties that may be tuned. @@ -1661,11 +878,11 @@ tuned. @cindex grob The HTML page that we found in the previous section describes the -layout object called @internalsref{Fingering}. Such an object is a +layout object called @rinternals{Fingering}. Such an object is a symbol within the score. It has properties that store numbers (like thicknesses and directions), but also pointers to related objects. A layout object is also called a @emph{Grob}, which is short for Graphical -Object. For more details about Grobs, see @internalsref{grob-interface}. +Object. For more details about Grobs, see @rinternals{grob-interface}. The page for @code{Fingering} lists the definitions for the @code{Fingering} object. For example, the page says @@ -1697,7 +914,7 @@ That piece of text is typeset with a font, unlike slurs or beams. @item Horizontally, the center of the symbol should be aligned to the -center of the notehead. +center of the note head. @item Vertically, the symbol is placed next to the note and the staff. @@ -1708,15 +925,15 @@ and subscript symbols. @end itemize Each of these aspects is captured in so-called @emph{interface}s, -which are listed on the @internalsref{Fingering} page at the bottom +which are listed on the @rinternals{Fingering} page at the bottom @quotation This object supports the following interfaces: -@internalsref{item-interface}, -@internalsref{self-alignment-interface}, -@internalsref{side-position-interface}, @internalsref{text-interface}, -@internalsref{text-script-interface}, @internalsref{font-interface}, -@internalsref{finger-interface}, and @internalsref{grob-interface}. +@rinternals{item-interface}, +@rinternals{self-alignment-interface}, +@rinternals{side-position-interface}, @rinternals{text-interface}, +@rinternals{text-script-interface}, @rinternals{font-interface}, +@rinternals{finger-interface}, and @rinternals{grob-interface}. @end quotation Clicking any of the links will take you to the page of the respective @@ -1726,7 +943,7 @@ can be modified. We have been talking of @emph{the} @code{Fingering} object, but actually it does not amount to much. The initialization file (see -@rlearning{Default files}) +@rlearning{Other sources of information}) @file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object}, @example @@ -1754,7 +971,7 @@ does not amount to much. The initialization file (see @noindent As you can see, the @code{Fingering} object is nothing more than a -bunch of variable settings, and the webpage in the Program Reference +bunch of variable settings, and the webpage in the Internals Reference is directly generated from this definition. @@ -1796,7 +1013,7 @@ Add this much extra space between objects that are next to each other. @end quotation By increasing the value of @code{padding}, we can move the -fingering away from the notehead. The following command inserts +fingering away from the note head. The following command inserts 3 staff spaces of white between the note and the fingering: @example @@ -1814,244 +1031,950 @@ f @end lilypond -In this case, the context for this tweak is @context{Voice}. This +In this case, the context for this tweak is @code{Voice}. This fact can also be deduced from the program reference, for the page for -the @internalsref{Fingering_engraver} plug-in says +the @rinternals{Fingering_engraver} plug-in says @quotation -Fingering_engraver is part of contexts: @dots{} @internalsref{Voice} +Fingering_engraver is part of contexts: @dots{} @rinternals{Voice} @end quotation -@node Objects connected to the input -@subsection Objects connected to the input - -@funindex \tweak +@node Naming conventions +@subsection Naming conventions -In some cases, it is possible to take a short-cut for tuning graphical -objects. For objects that result directly from a piece of the input, -you can use the @code{\tweak} function, for example +Another thing that is needed, is an overview of the various naming +conventions: -@lilypond[relative=2,fragment,verbatim,ragged-right] -< - c - \tweak #'color #red d - g - \tweak #'duration-log #1 a ->4-\tweak #'padding #10 -. -@end lilypond + scheme functions: lowercase-with-hyphens (incl. one-word +names) + scheme functions: ly:plus-scheme-style + music events, music classes and music properties: +as-scheme-functions + Grob interfaces: scheme-style + backend properties: scheme-style (but X and Y!) + contexts (and MusicExpressions and grobs): Capitalized or +CamelCase + context properties: lowercaseFollowedByCamelCase + engravers: +Capitalized_followed_by_lowercase_and_with_underscores -As you can see, properties are set in the objects directly, -without mentioning the grob name or context where this should be -applied. +Which of these are conventions and which are rules? +Which are rules of the underlying language, and which are +LP-specific? -This technique only works for objects that are directly connected to -an @internalsref{Event} from the input, for example -@itemize -@item note heads, caused by chord-pitch (i.e., notes inside a chord) -@item articulation signs, caused by articulation instructions -@end itemize +@node Modifying properties +@section Modifying properties -It notably does not work for stems and accidentals (these are caused -by note heads, not by music events) or clefs (these are not caused by -music inputs, but rather by the change of a property value). +@menu +* Overview of modifying properties:: +* The \set command:: +* The \override command:: +* \set versus \override:: +* Objects connected to the input:: +@end menu -There are very few objects which are @emph{directly} connected to -output. A normal note (like @code{c4}) is not directly connected -to output, so -@example -\tweak #'color #red c4 -@end example +@node Overview of modifying properties +@subsection Overview of modifying properties -@noindent -does not change color. See @ref{Displaying music expressions}, for -details. +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 -@node Using Scheme code instead of \tweak -@subsection Using Scheme code instead of @code{\tweak} +@example +\override @var{context}.@var{name} #'@var{property} = #@var{value} +@end example -The main disadvantage of @code{\tweak} is its syntactical -inflexibility. For example, the following produces a syntax error. +Here @var{name} is the name of a graphical object, like +@code{Stem} or @code{NoteHead}, and @var{property} is an internal +variable of the formatting system (@q{grob property} or @q{layout +property}). The latter is a symbol, so it must be quoted. The +subsection @ref{Modifying properties}, explains what to fill in +for @var{name}, @var{property}, and @var{value}. Here we only +discuss the functionality of this command. -@example -F = \tweak #'font-size #-3 -\flageolet +The command -\relative c'' @{ - c4^\F c4_\F -@} -@end example +@verbatim +\override Staff.Stem #'thickness = #4.0 +@end verbatim @noindent -With other words, @code{\tweak} doesn't behave like an articulation -regarding the syntax; in particular, it can't be attached with -@samp{^} and @samp{_}. +makes stems thicker (the default is 1.3, with staff line thickness as a +unit). Since the command specifies @code{Staff} as context, it only +applies to the current staff. Other staves will keep their normal +appearance. Here we see the command in action: -Using Scheme, this problem can be circumvented. The route to the -result is given in @ref{Adding articulation to notes (example)}, -especially how to use @code{\displayMusic} as a helping guide. +@lilypond[quote,verbatim,relative=2,fragment] +c4 +\override Staff.Stem #'thickness = #4.0 +c4 +c4 +c4 +@end lilypond -@example -F = #(let ((m (make-music 'ArticulationEvent - 'articulation-type "flageolet"))) - (set! (ly:music-property m 'tweaks) - (acons 'font-size -3 - (ly:music-property m 'tweaks))) - m) - -\relative c'' @{ - c4^\F c4_\F -@} -@end example +The @code{\override} command changes the definition of the @code{Stem} +within the current @code{Staff}. After the command is interpreted +all stems are thickened. -@noindent -Here, the @code{tweaks} properties of the flageolet object -@samp{m} (created with @code{make-music}) are extracted with -@code{ly:music-property}, a new key-value pair to change the -font size is prepended to the property list with the -@code{acons} Scheme function, and the result is finally -written back with @code{set!}. The last element of the -@code{let} block is the return value, @samp{m} itself. +Analogous to @code{\set}, the @var{context} argument may be left out, +causing the default context @code{Voice} to be used. Adding +@code{\once} applies the change during one timestep only. +@lilypond[quote,fragment,verbatim,relative=2] +c4 +\once \override Stem #'thickness = #4.0 +c4 +c4 +@end lilypond -@node \set versus \override -@subsection @code{\set} vs. @code{\override} +The @code{\override} must be done before the object is +started. Therefore, when altering @emph{Spanner} objects such as slurs +or beams, the @code{\override} command must be executed at the moment +when the object is created. In this example, -We have seen two methods of changing properties: @code{\set} and -@code{\override}. There are actually two different kinds of -properties. +@lilypond[quote,fragment,verbatim,relative=2] +\override Slur #'thickness = #3.0 +c8[( c +\override Beam #'thickness = #0.6 +c8 c]) +@end lilypond -Contexts can have properties, which are usually named in -@code{studlyCaps}. They mostly control the translation from -music to notatino, eg. @code{localKeySignature} (for determining -whether to print accidentals), @code{measurePosition} (for -determining when to print a barline). Context properties can -change value over time while interpreting a piece of music; -@code{measurePosition} is an obvious example of -this. Context properties are modified with @code{\set}. +@noindent +the slur is fatter but the beam is not. This is because the command for +@code{Beam} comes after the Beam is started, so it has no effect. -There is a special type of context property: the element -description. These properties are named in @code{StudlyCaps} -(starting with capital letters). They contain the -@q{default settings} for said graphical object as an -association list. See @file{scm/@/define@/-grobs@/.scm} -to see what kind of settings there are. Element descriptions -may be modified with @code{\override}. +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. -@code{\override} is actually a shorthand; +@example +\override Voice.Stem #'thickness = #4.0 +\revert Staff.Stem #'thickness +@end example +Some tweakable options are called @q{subproperties} and reside inside +properties. To tweak those, use commands of the form + +@c leave this as a long long @example -\override @var{context}.@var{name} #'@var{property} = #@var{value} +\override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value} @end example @noindent -is more or less equivalent to +such as -@c leave this long line -gp @example -\set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) = (length siblings) 2) - (eq? (car (last-pair siblings)) grob)) - (ly:grob-set-property! grob 'extra-offset '(-2 . 5))))) +If the @var{context} argument is left out, then the current bottom-most +context (typically @code{ChordNames}, @code{Voice}, or +@code{Lyrics}) is used. In this example, -\relative c'' { - \override Tie #'after-line-breaking = - #my-callback - c1 ~ \break c2 ~ c -} +@lilypond[quote,verbatim,relative=2,fragment] +c8 c c c +\set autoBeaming = ##f +c8 c c c @end lilypond @noindent -When applying this trick, the new @code{after-line-breaking} callback -should also call the old one @code{after-line-breaking}, if there is -one. For example, if using this with @code{Hairpin}, -@code{ly:hairpin::after-line-breaking} should also be called. +the @var{context} argument to @code{\set} is left out, so automatic +beaming is switched off in the current @rinternals{Voice}. Note that +the bottom-most context does not always contain the property that you +wish to change -- for example, attempting to set the @code{skipBars} +property (of the bottom-most context, in this case @code{Voice}) will +have no effect. + +@lilypond[quote,verbatim,relative=2,fragment] +R1*2 +\set skipBars = ##t +R1*2 +@end lilypond + +Contexts are hierarchical, so if a bigger context was specified, for +example @code{Staff}, then the change would also apply to all +@code{Voice}s in the current stave. The change is applied +@q{on-the-fly}, during the music, so that the setting only affects the +second group of eighth notes. + +@funindex \unset +There is also an @code{\unset} command, +@example +\unset @var{context}.@var{prop} +@end example -@item Some objects cannot be changed with @code{\override} for -technical reasons. Examples of those are @code{NonMusicalPaperColumn} -and @code{PaperColumn}. They can be changed with the -@code{\overrideProperty} function, which works similar to @code{\once -\override}, but uses a different syntax. +@noindent +which removes the definition of @var{prop}. This command removes +the definition only if it is set in @var{context}, so @example -\overrideProperty -#"Score.NonMusicalPaperColumn" % Grob name -#'line-break-system-details % Property name -#'((next-padding . 20)) % Value +\set Staff.autoBeaming = ##f @end example -Note, however, that @code{\override}, applied to -@code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as -expected within @code{\context} blocks. +@noindent +introduces a property setting at @code{Staff} level. The setting also +applies to the current @code{Voice}. However, + +@example +\unset Voice.autoBeaming +@end example + +@noindent +does not have any effect. To cancel this setting, the @code{\unset} +must be specified on the same level as the original @code{\set}. In +other words, undoing the effect of @code{Staff.autoBeaming = ##f} +requires +@example +\unset Staff.autoBeaming +@end example + +Like @code{\set}, the @var{context} argument does not have to be +specified for a bottom context, so the two statements + +@example +\set Voice.autoBeaming = ##t +\set autoBeaming = ##t +@end example + +@noindent +are equivalent. + + +@cindex \once +Settings that should only apply to a single time-step can be entered +with @code{\once}, for example in + +@lilypond[quote,verbatim,relative=2,fragment] +c4 +\once \set fontSize = #4.7 +c4 +c4 +@end lilypond + +the property @code{fontSize} is unset automatically after the second +note. + +A full description of all available context properties is in the +program reference, see +@ifhtml +@rinternals{Tunable context properties}. +@end ifhtml +@ifnothtml +Translation @expansion{} Tunable context properties. +@end ifnothtml + + + +@node The \override command +@subsection The @code{\override} command + +Commands which change output generally look like + +@example +\override Voice.Stem #'thickness = #3.0 +@end example + +@noindent +To construct this tweak we must determine these bits of information: + +@itemize +@item the context: here @code{Voice}. +@item the layout object: here @code{Stem}. +@item the layout property: here @code{thickness}. +@item a sensible value: here @code{3.0}. +@end itemize + +Some tweakable options are called @q{subproperties} and reside inside +properties. To tweak those, use commands in the form + +@example +\override Stem #'details #'beamed-lengths = #'(4 4 3) +@end example + +@cindex internal documentation +@cindex finding graphical objects +@cindex graphical object descriptions +@cindex tweaking +@funindex \override +@cindex internal documentation + +For many properties, regardless of the data type of the property, setting the +property to false ( @code{##f} ) will result in turning it off, causing +LilyPond to ignore that property entirely. This is particularly useful for +turning off grob properties which may otherwise be causing problems. + +We demonstrate how to glean this information from the notation manual +and the program reference. + + +@node \set versus \override +@subsection @code{\set} vs. @code{\override} + +We have seen two methods of changing properties: @code{\set} and +@code{\override}. There are actually two different kinds of +properties. + +Contexts can have properties, which are usually named in +@code{studlyCaps}. They mostly control the translation from +music to notation, eg. @code{localKeySignature} (for determining +whether to print accidentals), @code{measurePosition} (for +determining when to print a bar line). Context properties can +change value over time while interpreting a piece of music; +@code{measurePosition} is an obvious example of +this. Context properties are modified with @code{\set}. + +There is a special type of context property: the element +description. These properties are named in @code{StudlyCaps} +(starting with capital letters). They contain the +@q{default settings} for said graphical object as an +association list. See @file{scm/@/define@/-grobs@/.scm} +to see what kind of settings there are. Element descriptions +may be modified with @code{\override}. + +@code{\override} is actually a shorthand; + +@example +\override @var{context}.@var{name} #'@var{property} = #@var{value} +@end example + +@noindent +is more or less equivalent to + +@c leave this long line -gp +@example +\set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) 4-\tweak #'padding #10 -. +@end lilypond + +As you can see, properties are set in the objects directly, +without mentioning the grob name or context where this should be +applied. + +This technique only works for objects that are directly connected to +an @rinternals{Event} from the input, for example + +@itemize +@item note heads, caused by chord-pitch (i.e., notes inside a chord) +@item articulation signs, caused by articulation instructions +@end itemize + +It notably does not work for stems and accidentals (these are caused +by note heads, not by music events) or clefs (these are not caused by +music inputs, but rather by the change of a property value). + +There are very few objects which are @emph{directly} connected to +output. A normal note (like @code{c4}) is not directly connected +to output, so + +@example +\tweak #'color #red c4 +@end example + +@noindent +does not change color. See @ref{Displaying music expressions}, for +details. + + +@node Useful concepts and properties +@section Useful concepts and properties + + +@menu +* Input modes:: +* Direction and placement:: +* Distances and measurements:: +* Spanners:: +@end menu + +@node Input modes +@subsection Input modes + +The way in which the notation contained within an input file is +interpreted is determined by the current input mode. + +@strong{Chord mode} + +This is activated with the @code{\chordmode} command, and causes +input to be interpreted with the syntax of chord notation, see +@ref{Chord notation}. Chords are rendered as notes on a staff. + +Chord mode is also activated with the @code{\chords} command. +This also creates a new @code{ChordNames} context and +causes the following input to be interpreted with the syntax of +chord notation and rendered as chord names in the @code{ChordNames} +context, see @ref{Printing chord names}. + +@strong{Drum mode} + +This is activated with the @code{\drummode} command, and causes +input to be interpreted with the syntax of drum notation, see +@ref{Basic percussion notation}. + +Drum mode is also activated with the @code{\drums} command. +This also creates a new @code{DrumStaff} context and causes the +following input to be interpreted with the syntax of drum notation +and rendered as drum symbols on a drum staff, see @ref{Basic +percussion notation}. + +@strong{Figure mode} + +This is activated with the @code{\figuremode} command, and causes +input to be interpreted with the syntax of figured bass, see +@ref{Entering figured bass}. + +Figure mode is also activated with the @code{\figures} command. +This also creates a new @code{FiguredBass} context and causes the +following input to be interpreted with the figured bass syntax +and rendered as figured bass symbols in the @code{FiguredBass} +context, see @ref{Introduction to figured bass}. + +@strong{Fret and tab modes} + +There are no special input modes for entering fret and tab symbols. + +To create tab diagrams, enter notes or chords in note mode and +render them in a @code{TabStaff} context, see +@ref{Default tablatures}. + +To create fret diagrams above a staff, enter them as markup +above the notes using the @code{\fret-diagram} command, see +@ref{Fret diagrams}. + +@strong{Lyrics mode} + +This is activated with the @code{\lyricmode} command, and causes +input to be interpreted as lyric syllables with optional durations +and associated lyric modifiers, see @ref{Vocal music}. + +Lyric mode is also activated with the @code{\addlyrics} command. +This also creates a new @code{Lyrics} context and an implicit +@code{\lyricsto} command which associates the following lyrics +with the preceding music. + +@strong{Markup mode} + +This is activated with the @code{\markup} command, and causes +input to be interpreted with the syntax of markup, see +@ref{Text markup commands}. + +@c silly work-around for texinfo broken-ness +@c (@strong{Note...} causes a spurious cross-reference in Info) +@b{Note mode} + +This is the default mode or it may be activated with the +@code{\notemode} command. Input is interpreted as pitches, +durations, markup, etc and typeset as musical notation on a staff. + +It is not normally necessary to specify note mode explicitly, but +it may be useful to do so in certain situations, for example if you +are in lyric mode, chord mode or any other mode and want to insert +something that only can be done with note mode syntax. + +For example, to indicate dynamic markings for the verses of a +choral pieces it is necessary to enter note mode to interpret +the markings: + +@lilypond[verbatim,relative=2,quote] +{ c4 c4 c4 c4 } +\addlyrics { + \notemode{\set stanza = \markup{ \dynamic f 1. } } + To be sung loudly +} +\addlyrics { + \notemode{\set stanza = \markup{ \dynamic p 2. } } + To be sung quietly +} +@end lilypond + + + +@node Direction and placement +@subsection Direction and placement + +In typesetting music the direction and placement of many items is +a matter of choice. For example, the stems of notes can +be directed up or down; lyrics, dynamics, and other expressive +marks may be placed above or below the staff; text may be aligned +left, right or center; etc. Most of these choices may be left to +be determined automatically by LilyPond, but in some cases it may +be desirable to force a particular direction or placement. + +@strong{Default actions} + +By default some directions are always up or always down (e.g. +dynamics or fermata), while other things can alternate between +up or down based on the stem direction (like slurs or accents). + +@c TODO Add table showing these + +@strong{Context layout} + +Contexts are positioned in a system from top to bottom in the +order in which they are encountered. Note, however, that a +context will be created implicitly if a command is encountered +when there is no suitable context available to contain it. + +@c TODO Add example ? + +The default order in which contexts are laid out can be changed, +see @ref{Aligning contexts} + +@strong{Articulation direction indicators} + +When adding articulations to notes the direction indicator, +@code{^} (meaning @qq{up}), @code{_} (meaning @qq{down}) or +@code{-} (meaning @qq{use default direction}), can usually be +omitted, in which case @code{-} is assumed. But a direction +indicator is @strong{always} required before + +@itemize +@item @code{\tweak} commands +@item @code{\markup} commands +@item @code{\tag} commands +@item string markups, e.g. -"string" +@item fingering instructions, e.g. @code{-1} +@item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--} +@end itemize + +@strong{The direction property} + +The position or direction of many layout objects is controlled +by the @code{direction} property. + +The value of the @code{direction} property may be +set to @code{1}, meaning @qq{up} or @qq{above}, or to @code{-1}, +meaning @qq{down} or @qq{below}. The symbols @code{UP} and +@code{DOWN} may be used instead of @code{1} and @code{-1} +respectively. The default direction may be specified by setting +@code{direction} to @code{0} or @code{CENTER}. Alternatively, +in many cases predefined commands +exist to specify the direction. These are all of the form + +@noindent +@code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral} + +@noindent +where @code{xxxNeutral} means @qq{use the default direction}. +See @rlearning{Within-staff objects}. + +In a few cases, arpeggio being the only common example, the value +of the @code{direction} property specifies whether the object +is to be placed to the right or left of the parent object. In +this case @code{-1} or @code{LEFT} means @qq{to the left} and +@code{1} or @code{RIGHT} means @qq{to the right}. @code{0} +or @code{CENTER} means @qq{use the default} direction, as before. + +@ignore +These all have side-axis set to #X +AmbitusAccidental - direction has no effect +Arpeggio - works +StanzaNumber - not tried +TrillPitchAccidental - not tried +TrillPitchGroup - not tried +@end ignore + + + +@node Distances and measurements +@subsection Distances and measurements + +DISCUSS after working on other sections. + +TODO: staff spaces. Maybe move into tweaks? + + +@node Spanners +@subsection Spanners + +Many objects of musical notation extend over several notes or even +several bars. Examples are crescendi, trills, tuplet brackets, and +volta repeat brackets. Such objects are called @qq{spanners}, and +have special properties to control their appearance and behaviour. +Some of these properties are common to all spanners; others are +restricted to a sub-set of the spanners. + + +@node Common properties +@section Common properties + +@menu +* Controlling visibility of objects:: +* Line styles:: +* Rotating objects:: +* Aligning objects:: +@end menu + +@node Controlling visibility of objects +@subsection Controlling visibility of objects + + +@node Line styles +@subsection Line styles + +@c TODO: split the following explanations between expressive marks and +@c text-related stuff. Perhaps create a new subsection named +@c "Spanner limits", "Spanner boundaries"? -vv + +Some performance indications, e.g., @i{rallentando} and +@i{accelerando} and @i{trills} are written as text and are +extended over many measures with lines, sometimes dotted or wavy. + +These all use the same routines as the glissando for drawing the +texts and the lines, and tuning their behavior is therefore also +done in the same way. It is done with a spanner, and the routine +responsible for drawing the spanners is +@code{ly:line-interface::print}. This routine determines the +exact location of the two @i{span points} and draws a line in +between, in the style requested. + +Here is an example of the different line styles available, and how +to tune them. + +@lilypond[relative=2,ragged-right,verbatim,fragment] +d2 \glissando d'2 +\once \override Glissando #'style = #'dashed-line +d,2 \glissando d'2 +\override Glissando #'style = #'dotted-line +d,2 \glissando d'2 +\override Glissando #'style = #'zigzag +d,2 \glissando d'2 +\override Glissando #'style = #'trill +d,2 \glissando d'2 +@end lilypond + +The information that determines the end-points is computed +on-the-fly for every graphic object, but it is possible to +override these. + +@lilypond[relative=2,ragged-right,verbatim,fragment] +e2 \glissando f +\once \override Glissando #'bound-details #'right #'Y = #-2 +e2 \glissando f +@end lilypond + +The @code{Glissando} object, like any other using the +@code{ly:line-interface::print} routine, carries a nested +association list. In the above statement, the value for @code{Y} +is set to @code{-2} for the association list corresponding to the +right end point. Of course, it is also possible to adjust the +left side with @code{left} instead of @code{right}. + +If @code{Y} is not set, the value is computed from the vertical +position of right attachment point of the spanner. + +In case of a line break, the values for the span-points are +extended with contents of the @code{left-broken} and +@code{right-broken} sublists, for example + +@lilypond[relative=2,ragged-right,verbatim,fragment] +\override Glissando #'breakable = ##T +\override Glissando #'bound-details #'right-broken #'Y = #-3 +c1 \glissando \break +f1 +@end lilypond + +The following properties can be used for the + +@table @code +@item Y +This sets the Y-coordinate of the end point, in staff space. By +default, it is the center of the bound object, so for a glissando +it points to the vertical center of the note head. + +For horizontal spanners, such as text spanner and trill spanners, +it is hardcoded to 0. + +@item attach-dir +This determines where the line starts and ends in X-direction, +relative to the bound object. So, a value of @code{-1} (or +@code{LEFT}) makes the line start/end at the left side of the note +head it is attached to. + +@item X +This is the absolute coordinate of the end point. It is usually +computed on the fly, and there is little use in overriding it. + +@item stencil +Line spanners may have symbols at the beginning or end, which is +contained in this sub-property. This is for internal use, it is +recommended to use @code{text}. + +@item text +This is a markup that is evaluated to yield stencil. It is used +to put @i{cresc.} and @i{tr} on horizontal spanners. + +@lilypond[quote,ragged-right,fragment,relative=2,verbatim] +\override TextSpanner #'bound-details #'left #'text + = \markup { \small \bold Slower } +c2\startTextSpan b c a\stopTextSpan +@end lilypond + +@item stencil-align-dir-y +@item stencil-offset +Without setting this, the stencil is simply put there at the +end-point, as defined by the @code{X} and @code{Y} sub properties. +Setting either @code{stencil-align-dir-y} or @code{stencil-offset} +will move the symbol at the edge relative to the end point of the +line + +@lilypond[relative=1,fragment,verbatim] +\override TextSpanner #'bound-details + #'left #'stencil-align-dir-y = #DOWN +\override TextSpanner #'bound-details + #'right #'stencil-align-dir-y = #UP + +\override TextSpanner #'bound-details + #'left #'text = #"gggg" +\override TextSpanner #'bound-details + #'right #'text = #"hhhh" +c4^\startTextSpan c c c \stopTextSpan +@end lilypond + +@item arrow +Setting this sub property to @code{#t} produce an arrowhead at the +end of the line. + +@item padding +This sub property controls the space between the specified +end-point of the line and the actual end. Without padding, a +glissando would start and end in the center of each note head. + +@end table + +FIXME: should this be in NR 3? + +The music function \endSpanners terminates spanners and hairpins +after exactly one note. + +@lilypond[verbatim,quote,ragged-right,relative=2,fragment] +\endSpanners +c2 \startTextSpan c2 +c2 \< c2 +@end lilypond + +When using \endSpanners it is not necessary to close +\startTextSpan with \stopTextSpan, nor is it necessary to close +hairpins with \!. + + + +@seealso + +Internals Reference: @rinternals{TextSpanner}, +@rinternals{Glissando}, @rinternals{VoiceFollower}, +@rinternals{TrillSpanner}, +@rinternals{line-spanner-interface}. + + +@node Rotating objects +@subsection Rotating objects + +@node Aligning objects +@subsection Aligning objects + + +@node Advanced tweaks +@section Advanced tweaks + +@menu +* Vertical grouping of grobs:: +* Modifying ends of spanners:: +* Modifying stencils:: +@end menu + + + + +@node Vertical grouping of grobs +@subsection Vertical grouping of grobs + +The VerticalAlignment and VerticalAxisGroup grobs work together. +VerticalAxisGroup groups together different grobs like Staff, Lyrics, +etc. VerticalAlignment then vertically aligns the different grobs +grouped together by VerticalAxisGroup. There is usually only one +VerticalAlignment per score but every Staff, Lyrics, etc. has its own +VerticalAxisGroup. + + +@node Modifying ends of spanners +@subsection Modifying ends of spanners + + +@node Modifying stencils +@subsection Modifying stencils + + + +@node old The \override command +@section old The @code{\override} command + +In the previous section, we have already touched on a command that +changes layout details: the @code{\override} command. In this section, +we will look in more detail at how to use the command in practice. The +general syntax of this command is: + +@example +\override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value} +@end example + +This will set the @var{layout_property} of the specified @var{layout_object}, +which is a member of the @var{context}, to the @var{value}. + + + + + +@node Discussion of specific tweaks +@section Discussion of specific tweaks + +@menu +* old Contexts explained:: +@end menu + + +@node old Contexts explained +@subsection old Contexts explained + +When music is printed, a lot of notational elements must be added to the +output. For example, compare the input and output of the following example: + +@lilypond[quote,verbatim,relative=2,fragment] +cis4 cis2. g4 +@end lilypond + +The input is rather sparse, but in the output, bar lines, accidentals, +clef, and time signature are added. LilyPond @emph{interprets} the +input. During this step, the musical information is inspected in time +order, similar to reading a score from left to right. While reading +the input, the program remembers where measure boundaries are, and which +pitches require explicit accidentals. This information can be presented on +several levels. For example, the effect of an accidental is limited +to a single staff, while a bar line must be synchronized across the +entire score. + +Within LilyPond, these rules and bits of information are grouped in +@emph{Contexts}. Some examples of contexts are @code{Voice}, +@code{Staff}, and @code{Score}. They are hierarchical, for +example: a @code{Staff} can contain many @code{Voice}s, and a +@code{Score} can contain many @code{Staff} contexts. + +@quotation +@sourceimage{context-example,5cm,,} +@end quotation + +Each context has the responsibility for enforcing some notation rules, +creating some notation objects and maintaining the associated +properties. For example, the @code{Voice} context may introduce an +accidental and then the @code{Staff} context maintains the rule to +show or suppress the accidental for the remainder of the measure. The +synchronization of bar lines is handled at @code{Score} context. + +However, in some music we may not want the bar lines to be +synchronized -- consider a polymetric score in 4/4 and 3/4 time. In +such cases, we must modify the default settings of the @code{Score} +and @code{Staff} contexts. + +For very simple scores, contexts are created implicitly, and you need +not be aware of them. For larger pieces, such as anything with more +than one staff, they must be +created explicitly to make sure that you get as many staves as you +need, and that they are in the correct order. For typesetting pieces +with specialized notation, it can be useful to modify existing or +to define new contexts. + + +A complete description of all available contexts is in the program +reference, see +@ifhtml +@rinternals{Contexts}. +@end ifhtml +@ifnothtml +Translation @expansion{} Context. +@end ifnothtml + +@c [TODO: describe propagation] + + -@end itemize