X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fchanging-defaults.itely;h=a0dfd6182f8347408f5c45ac5af65b50a4480c9a;hb=94408d4a2e538e8812561f29e09116ede58dd042;hp=5ee001c66e1ad84514cadac0146649ec8c466957;hpb=39a8eb7fc50acf368d70bdbf6d51fa26c28327d7;p=lilypond.git diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely index 5ee001c66e..a0dfd6182f 100644 --- a/Documentation/notation/changing-defaults.itely +++ b/Documentation/notation/changing-defaults.itely @@ -4,7 +4,8 @@ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH When revising a translation, copy the HEAD committish of the - version that you are working on. See TRANSLATION for details. + version that you are working on. For details, see the Contributors' + Guide, node Updating translation committishes.. @end ignore @c \version "2.12.0" @@ -46,6 +47,7 @@ on entering numbers, lists, strings, and symbols in Scheme.} * Modifying properties:: * Useful concepts and properties:: * Advanced tweaks:: +* Using music functions:: @end menu @@ -1466,7 +1468,7 @@ or crashes, or both. @node The set command -@subsection The @code{\set} command +@subsection The @code{@bs{}set} command @cindex properties @funindex \set @@ -2206,7 +2208,7 @@ The default order in which contexts are laid out and the @qq{accepts} list can be changed, see @ref{Aligning contexts}. @seealso -Learning Manual: +Usage Manual: @rprogram{An extra staff appears}. @@ -2318,7 +2320,7 @@ are collectively called @qq{spanners}, and have special properties to control their appearance and behaviour. Some of these properties are common to all spanners; others are restricted to a sub-set of the spanners. -All spanners support the @code{spanner-interface}. A few, esentially +All spanners support the @code{spanner-interface}. A few, essentially those that draw a straight line between the two objects, support in addition the @code{line-spanner-interface}. @@ -2446,7 +2448,7 @@ a \< a a a a \! a a a @end lilypond This property is not effective for all spanners. For example, -seting it to @code{#t} has no effect on slurs or phrasing slurs +setting it to @code{#t} has no effect on slurs or phrasing slurs or on other spanners for which terminating on the bar line would not be meaningful. @@ -2977,7 +2979,7 @@ The locations of the end-points of the spanner are computed on-the-fly for every graphic object, but it is possible to override these: -@c FIXME Complete +@c TODO Complete @lilypond[relative=2,ragged-right,verbatim,fragment] e2 \glissando f \once \override Glissando #'(bound-details right Y) = #-2 @@ -3077,7 +3079,7 @@ Learning Manual: Notation Reference: @ref{Explaining the Internals Reference}, -@ref{Modifying properties}, +@ref{Modifying properties}. Installed Files: @file{scm/@/define@/-grobs@/.scm}. @@ -3095,52 +3097,54 @@ Internals Reference: @node Aligning objects @subsection Aligning objects -Graphical objects which support the @code{self-alignment-interface} and/or -the @code{side-position-interface} can be -aligned to a previously placed object in a variety of ways. For a list of these objects, see +Graphical objects which support the @code{self-alignment-interface} +and/or the @code{side-position-interface} can be aligned to a previously +placed object in a variety of ways. For a list of these objects, see @rinternals{self-alignment-interface} and @rinternals{side-position-interface}. All graphical objects have a reference point, a horizontal extent and a vertical extent. The horizontal extent is a pair of numbers giving the displacements from the reference point of the left and -right edges, displacements to the left being negative. The -vertical extent is a pair of numbers giving the displacement from -the reference point to the bottom and top edges, displacements down -being negative. +right edges, displacements to the left being negative. The vertical +extent is a pair of numbers giving the displacement from the reference +point to the bottom and top edges, displacements down being negative. An object's position on a staff is given by the values of the @code{X-offset} and @code{Y-offset} properties. The value of -@code{X-offset} gives the displacement from the x coordinate of +@code{X-offset} gives the displacement from the X coordinate of the reference point of the parent object, and the value of @code{Y-offset} gives the displacement from the center line of the -staff. The values of @code{X-offset} and -@code{Y-offset} may be set directly or may be set to be calculated -by procedures in order to achieve alignment with the parent object -in several ways. +staff. The values of @code{X-offset} and @code{Y-offset} may +be set directly or may be set to be calculated by procedures in order +to achieve alignment with the parent object. @warning{Many objects have special positioning considerations which cause any setting of @code{X-offset} or @code{Y-offset} to be ignored or modified, even though the object supports the -@code{self-alignment-interface}.} +@code{self-alignment-interface}. Overriding the @code{X-offset} +or @code{Y-offset} properties to a fixed value causes the respective +@code{self-alignment} property to be disregarded.} + +For example, an accidental can be repositioned vertically by setting +@code{Y-offset} but any changes to @code{X-offset} have no effect. -For example, an accidental can be repositioned -vertically by setting @code{Y-offset} but any changes to -@code{X-offset} have no effect. +Rehearsal marks may be aligned with breakable objects such as bar +lines, clef symbols, time signature symbols and key signatures. There +are special properties to be found in the @code{break-aligned-interface} +for positioning rehearsal marks on such objects. -Rehearsal marks may be aligned with -breakable objects such as bar lines, clef symbols, time signature -symbols and key signatures. There are special properties to be -found in the @code{break-aligned-interface} for positioning rehearsal -marks on such objects. +@seealso +@ref{Using the break-alignable-interface}, +@rextend{Callback functions}. @menu -* Setting @code{X-offset} and @code{Y-offset} directly:: -* Using the @code{side-position-interface}:: -* Using the @code{self-alignment-interface}:: -* Using the @code{break-alignable-interface}:: +* Setting X-offset and Y-offset directly:: +* Using the side-position-interface:: +* Using the self-alignment-interface:: +* Using the break-alignable-interface:: @end menu -@node Setting @code{X-offset} and @code{Y-offset} directly +@node Setting X-offset and Y-offset directly @unnumberedsubsubsec Setting @code{X-offset} and @code{Y-offset} directly Numerical values may be given to the @code{X-offset} and @code{Y-offset} @@ -3162,7 +3166,7 @@ a @c TODO write more -@node Using the @code{side-position-interface} +@node Using the side-position-interface @unnumberedsubsubsec Using the @code{side-position-interface} An object which supports the @code{side-position-interface} can be @@ -3203,7 +3207,7 @@ to value of @code{direction}. @c TODO Add examples -@node Using the @code{self-alignment-interface} +@node Using the self-alignment-interface @unnumberedsubsubsec Using the @code{self-alignment-interface} @emph{Self-aligning objects horizontally} @@ -3304,7 +3308,7 @@ example shows the difference: @c TODO The align-interface, BassFigureAlignment and VerticalAlignment -@node Using the @code{break-alignable-interface} +@node Using the break-alignable-interface @unnumberedsubsubsec Using the @code{break-alignable-interface} @cindex align to objects @@ -3320,20 +3324,27 @@ By default, rehearsal marks and bar numbers will be horizontally centered above the object: @lilypond[verbatim,quote,relative=1] -e1 -% the RehearsalMark will be centered above the Clef +% The rehearsal mark will be centered above the Clef \override Score.RehearsalMark #'break-align-symbols = #'(clef) \key a \major \clef treble \mark "↓" -e -% the RehearsalMark will be centered above the TimeSignature +e1 +% The rehearsal mark will be centered above the Time Signature \override Score.RehearsalMark #'break-align-symbols = #'(time-signature) \key a \major \clef treble \time 3/4 \mark "↓" e2. +% The rehearsal mark will be centered above the Breath Mark +\override Score.RehearsalMark #'break-align-symbols = #'(breathing-sign) +\key a \major +\clef treble +\time 4/4 +e1 +\breathe +\mark "↓" @end lilypond A list of possible target alignment objects may be specified. If @@ -3346,20 +3357,27 @@ line is invisible the object is aligned to the place where the bar line would be. @lilypond[verbatim,quote,relative=1] -e1 -% the RehearsalMark will be centered above the Key Signature +% The rehearsal mark will be centered above the Key Signature \override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef) \key a \major \clef treble \mark "↓" -e -% the RehearsalMark will be centered above the Clef +e1 +% The rehearsal mark will be centered above the Clef \set Staff.explicitKeySignatureVisibility = #all-invisible \override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef) -\key a \minor +\key a \major \clef bass \mark "↓" -e, +gis,,1 +% The rehearsal mark will be centered above the Bar Line +\set Staff.explicitKeySignatureVisibility = #all-invisible +\set Staff.explicitClefVisibility = #all-invisible +\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef) +\key a \major +\clef treble +\mark "↓" +e''1 @end lilypond The alignment of the rehearsal mark relative to the notation object @@ -3367,49 +3385,49 @@ can be changed, as shown in the following example. In a score with multiple staves, this setting should be done for all the staves. @lilypond[verbatim,quote,relative=1] -% The RehearsalMark will be centered above the KeySignature +% The RehearsalMark will be centered above the Key Signature \override Score.RehearsalMark #'break-align-symbols = #'(key-signature) \key a \major \clef treble \time 4/4 \mark "↓" e1 -% The RehearsalMark will be aligned with the left edge of the KeySignature +% The RehearsalMark will be aligned with the left edge of the Key Signature \once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT \mark "↓" \key a \major -e -% The RehearsalMark will be aligned with the right edge of the KeySignature +e1 +% The RehearsalMark will be aligned with the right edge of the Key Signature \once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT \key a \major \mark "↓" -e +e1 @end lilypond -The rehearsal mark can also be offset to the right or left of the left edge -by an arbitrary amount. The units are staff-spaces: +The rehearsal mark can also be offset to the right or left of the left +edge by an arbitrary amount. The units are staff-spaces: @lilypond[verbatim,quote,relative=1] -% The RehearsalMark will be aligned with the left edge of the KeySignature +% The RehearsalMark will be aligned with the left edge of the Key Signature % and then shifted right by 3.5 staff-spaces \override Score.RehearsalMark #'break-align-symbols = #'(key-signature) \once \override Score.KeySignature #'break-align-anchor = #3.5 \key a \major \mark "↓" -e -% The RehearsalMark will be aligned with the left edge of the KeySignature +e1 +% The RehearsalMark will be aligned with the left edge of the Key Signature % and then shifted left by 2 staff-spaces \once \override Score.KeySignature #'break-align-anchor = #-2 \key a \major \mark "↓" -e +e1 @end lilypond @node Vertical grouping of grobs @subsection Vertical grouping of grobs -@c FIXME Expand this section +@c TODO Expand this section The VerticalAlignment and VerticalAxisGroup grobs work together. VerticalAxisGroup groups together different grobs like Staff, Lyrics, @@ -3558,8 +3576,172 @@ to which the start of the tie (or slur) is attached. It is not possible to modify shapes of ties or slurs by changing the @code{control-points} property if there are more than one at the same musical moment, not even by using the @code{\tweak} -command. +command. However, the @code{tie-configuration} property of +@code{TieColumn} can be overridden to set start line and direction +of ties as required. + + + + +@node Using music functions +@section Using music functions + +@c TODO -- add @seealso, etc. to these subsections +Where tweaks need to be reused with different music expressions, +it is often convenient to make the tweak part of a @emph{music +function}. In this section, we discuss only @emph{substitution} +functions, where the object is to substitute a variable into a +piece of LilyPond input code. Other more complex functions are +described in @rextend{Music functions}. +@menu +* Substitution function syntax:: +* Substitution function examples:: +@end menu + +@node Substitution function syntax +@subsection Substitution function syntax + +Making a function that substitutes a variable into LilyPond +code is easy. The general form of these functions is + +@example +function = +#(define-music-function + (parser location @var{arg1} @var{arg2} @dots{}) + (@var{type1?} @var{type2?} @dots{}) + #@{ + @var{@dots{}music@dots{}} + #@}) +@end example + +@noindent +where +@multitable @columnfractions .33 .66 +@item @code{@var{argN}} +@tab @var{n}th argument + +@item @code{@var{typeN?}} +@tab a scheme @emph{type predicate} for which @code{@var{argN}} +must return @code{#t}. + +@item @code{@var{@dots{}music@dots{}}} +@tab normal LilyPond input, using @code{$} to reference arguments +(eg. @samp{$arg1}). +@end multitable + + +The @code{parser} and @code{location} arguments are mandatory, and +are used in some advanced situations as described in the +@q{Extending} manual (see @rextend{Music functions}). For +substitution functions, just be sure to include them. + +The list of type predicates is also required. Some of the most +common type predicates used in music functions are: + +@example +boolean? +cheap-list? @emph{(use instead of }@q{list?}@emph{ for faster processing)} +ly:music? +markup? +number? +pair? +string? +symbol? +@end example + +@noindent +For a list of available type predicates, see +@ref{Predefined type predicates}. User-defined type predicates +are also allowed. + + +@seealso + +Notation Reference: +@ref{Predefined type predicates}. + +Extending: +@rextend{Music functions}. + +Installed Files: +@file{lily/music-scheme.cc}, +@file{scm/c++.scm}, +@file{scm/lily.scm}. + + +@node Substitution function examples +@subsection Substitution function examples + +This section introduces some substitution function examples. +These are not intended to be exhaustive, but rather to demonstrate +some of the possibilities of simple substitution functions. + +In the first example, a function is defined that simplifies +setting the padding of a TextScript: + +@lilypond[quote,verbatim,ragged-right] +padText = +#(define-music-function + (parser location padding) + (number?) + #{ + \once \override TextScript #'padding = $padding + #}) + +\relative c''' { + c4^"piu mosso" b a b + \padText #1.8 + c4^"piu mosso" d e f + \padText #2.6 + c4^"piu mosso" fis a g +} +@end lilypond + +In addition to numbers, we can use music expressions such +as notes for arguments to music functions: + +@c TODO: use a better example (the music argument is redundant). + +@lilypond[quote,verbatim,ragged-right] +custosNote = +#(define-music-function + (parser location note) + (ly:music?) + #{ + \once \override Voice.NoteHead #'stencil = + #ly:text-interface::print + \once \override Voice.NoteHead #'text = + \markup \musicglyph #"custodes.mensural.u0" + \once \override Voice.Stem #'stencil = ##f + $note + #}) + +\relative c' { c4 d e f \custosNote g } +@end lilypond + +Substitution functions with multiple arguments can be defined: + +@lilypond[quote,verbatim,ragged-right] +tempoPadded = +#(define-music-function + (parser location padding tempotext) + (number? string?) + #{ + \once \override Score.MetronomeMark #'padding = $padding + \tempo \markup { \bold $tempotext } + #}) + +\relative c'' { + \tempo \markup { "Low tempo" } + c4 d e f g1 + \tempoPadded #4.0 #"High tempo" + g4 f e d c1 +} +@end lilypond + +@seealso +TODO: add missing @@ref's here.