X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fchanging-defaults.itely;h=b4618ea1a024478e543cc94e471723a823118cf2;hb=17098f34eace028d047ee7f9cd6f81a84e0e7537;hp=257c915e5763bdf4aeba0acadc843cf467ede1b5;hpb=83670be1cca069bfcd19abe4dc2abbeb2d3bba06;p=lilypond.git diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely index 257c915e57..b4618ea1a0 100644 --- a/Documentation/user/changing-defaults.itely +++ b/Documentation/user/changing-defaults.itely @@ -33,8 +33,8 @@ 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/@/v2.8/@/Documentation/@/user/@/ -lilypond@/-internals/,on@/-line}, +@c leave the @uref as one long line. +@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line}, but is also included with the LilyPond documentation package. There are four areas where the default settings may be changed: @@ -56,14 +56,14 @@ 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}. +in @ref{Non-musical notation}, and @ref{Spacing issues}. @end itemize 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 +@code{#}.@footnote{@ref{Scheme tutorial}, contains a short tutorial on entering numbers, lists, strings, and symbols in Scheme.} @@ -93,21 +93,29 @@ 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 -The function can take two arguments: the name of the accidental style, -and an optional argument that denotes the context that should be -changed. If no context name is supplied, @code{Staff} is the default, +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. -@c TODO: we should create a very clear example, and show every -@c accidental style on that example (with the example specially -@c constructed so that it illustrates all the differences). -gp +The following accidental styles are supported: -The following accidental styles are supported @table @code @item default This is the default typesetting behavior. It corresponds @@ -115,22 +123,64 @@ 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 - -@lilypond[quote,ragged-right,relative=1,fragment,verbatim] -\new Staff << - #(set-accidental-style 'voice) - << - { es g } \\ - { c, e } ->> >> +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 @@ -145,21 +195,57 @@ 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 +measure: in the following example, notice the two natural signs which appear +in the second bar of the upper staff. -@lilypond[quote,ragged-right,fragment,verbatim] -#(set-accidental-style 'modern) -cis' c'' cis'2 | c'' c' +@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 with parentheses -@lilypond[quote,ragged-right,fragment,verbatim] -#(set-accidental-style 'modern-cautionary) -cis' c'' cis'2 | c'' c' +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 @@ -169,6 +255,27 @@ 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 @@ -177,25 +284,120 @@ 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 rule reflects 20th century practice for piano notation. Very similar to -@code{modern} but accidentals also get canceled +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,fragment,verbatim,relative=1] -#(set-accidental-style 'no-reset) -c1 cis cis c +@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 @@ -204,9 +406,25 @@ 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,fragment,verbatim,relative=1] -#(set-accidental-style 'forget) -\key d\major c4 c cis cis d d dis dis +@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 @@ -214,7 +432,7 @@ before in the music @seealso Program reference: @internalsref{Accidental_engraver}, -@internalsref{Accidental}, and @internalsref{AccidentalPlacement}. +@internalsref{Accidental}, @internalsref{AccidentalSuggestion} and @internalsref{AccidentalPlacement}. @refbugs @@ -437,6 +655,7 @@ This section describes what contexts are, and how to modify them. * Changing context default settings:: * Defining new contexts:: * Aligning contexts:: +* Vertical grouping of grobs:: @end menu @@ -444,7 +663,7 @@ This section describes what contexts are, and how to modify them. @subsection Contexts explained When music is printed, a lot of notational elements must be added to the -input. For example, compare the input and output of the following example: +output. For example, compare the input and output of the following example: @lilypond[quote,verbatim,relative=2,fragment] cis4 cis2. g4 @@ -889,7 +1108,7 @@ 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 +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 @@ -917,8 +1136,8 @@ 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 it to default to @context{Voice}, and adding @code{\once} applies -the change during one timestep only +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 @@ -1004,8 +1223,8 @@ from the music in the @code{\layout} block, @} @end example -Here @code{\Staff} takes the existing definition for context @context{Staff} from the -identifier @code{\Staff}. +The @code{\Staff} command brings in the existing definition of the +staff context so that it can be modified. The statements @example @@ -1100,11 +1319,10 @@ These settings are defined within a @code{\context} block inside a @} @end example -In the following discussion, the example input shown should go on the -@dots{} in the previous fragment. +In the following discussion, the example input shown should go in place +of the @dots{} in the previous fragment. -First the context's name is defined. Instead of @context{Voice} it -will be called @context{ImproVoice}, +First it is necessary to define a name for the new context: @example \name ImproVoice @@ -1118,14 +1336,15 @@ giving the new context an alias @context{Voice}, \alias Voice @end example -The context will print notes, and instructive texts +The context will print notes and instructive texts, so we need to add +the engravers which provide this functionality, @example \consists Note_heads_engraver \consists Text_engraver @end example -but only on the center line, +but we only need this on the center line, @example \consists Pitch_squash_engraver @@ -1240,14 +1459,31 @@ 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 \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. +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}. @menu * Constructing a tweak:: @@ -1255,7 +1491,8 @@ we will look in more detail at how to use the command in practice. * Layout interfaces:: * Determining the grob property:: * Objects connected to the input:: -* \set vs. \override:: +* Using Scheme code instead of \tweak:: +* \set versus \override:: * Difficult tweaks:: @end menu @@ -1271,7 +1508,7 @@ Commands which change output generally look like @end example @noindent -This means that we must determine these bits of information: +To construct this tweak we must determine these bits of information: @itemize @item the context: here @context{Voice}. @@ -1294,10 +1531,17 @@ properties. To tweak those, use commands in the form @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 @@ -1358,6 +1602,14 @@ second bit of information listed under @b{See also} in the Notation manual. @end ignore +@ifnothtml +The programmer's reference is available as an HTML document. It is +highly recommended that you read it in HTML form, either online or +by downloading the HTML documentation. This section will be much more +difficult to understand if you are using the +PDF manual. +@end ifnothtml + Follow the link to @internalsref{Fingering}. At the top of the page, you will see @@ -1366,8 +1618,8 @@ Fingering objects are created by: @internalsref{Fingering_engraver} and @internalsref{New_fingering_engraver}. @end quotation -By clicking around in the program reference, we can follow the -flow of information within the program, following links like this: +By following related links inside the program reference, we can follow the +flow of information within the program: @itemize @bullet @@ -1425,7 +1677,7 @@ The page for @code{Fingering} lists the definitions for the @end quotation @noindent -which means that the number will be kept at a distance of at least 0.6 +which means that the number will be kept at a distance of at least 0.5 of the note head. @@ -1577,7 +1829,7 @@ Fingering_engraver is part of contexts: @dots{} @internalsref{Voice} @funindex \tweak In some cases, it is possible to take a short-cut for tuning graphical -objects. For objects that result directly from a piece of the input, +objects. For objects that result directly from a piece of the input, you can use the @code{\tweak} function, for example @lilypond[relative=2,fragment,verbatim,ragged-right] @@ -1589,7 +1841,7 @@ you can use the @code{\tweak} function, for example >4-\tweak #'padding #10 -. @end lilypond -As you can see, properties are set directly in the objects directly, +As you can see, properties are set in the objects directly, without mentioning the grob name or context where this should be applied. @@ -1597,8 +1849,8 @@ This technique only works for objects that are directly connected to an @internalsref{event} from the input, for example @itemize @bullet -@item note heads, caused by chord-pitch (i.e., notes inside a chord). -@item articulation signs, caused by articulation instructions. +@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 @@ -1614,12 +1866,58 @@ to output, so @end example @noindent -will not change color. See @ref{Displaying music expressions} for +does not change color. See @ref{Displaying music expressions}, for details. -@node \set vs. \override -@subsection \set vs. \override +@node Using Scheme code instead of \tweak +@subsection Using Scheme code instead of @code{\tweak} + +The main disadvantage of @code{\tweak} is its syntactical +inflexibility. For example, the following produces a syntax error. + +@example +F = \tweak #'font-size #-3 -\flageolet + +\relative c'' @{ + c4^\F c4_\F +@} +@end example + +@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{_}. + +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. + +@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 + +@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. + + +@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 @@ -1740,16 +2038,20 @@ one. For example, if using this with @code{Hairpin}, @item Some objects cannot be changed with @code{\override} for -technical reasons. Examples of those are @code{NonMusicalPaperColumn} +technical reasons. Examples of those are @code{NonMusicalPaperColumn} and @code{PaperColumn}. They can be changed with the -@code{\outputProperty} function, which works similar to @code{\once -\override}, but uses a different syntax, +@code{\overrideProperty} function, which works similar to @code{\once +\override}, but uses a different syntax. @example -\outputProperty +\overrideProperty #"Score.NonMusicalPaperColumn" % Grob name #'line-break-system-details % Property name #'((next-padding . 20)) % Value @end example +Note, however, that @code{\override}, applied to +@code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as +expected within @code{\context} blocks. + @end itemize