X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fchanging-defaults.itely;h=6c4e96aadfd36c427bee129ab8b35be4bc8fc48f;hb=4ecef06e22df3293a2bf246e1ebccb300ce90b3e;hp=9c5da9d02a3f7fa634e7af915aa2860f8d718a46;hpb=0767b19c9139922e6d4f7fc569e1f5ffa016b7ac;p=lilypond.git diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely index 9c5da9d02a..6c4e96aadf 100644 --- a/Documentation/notation/changing-defaults.itely +++ b/Documentation/notation/changing-defaults.itely @@ -123,8 +123,8 @@ Contexts are arranged hierarchically: @node Score - the master of all contexts @unnumberedsubsubsec Score - the master of all contexts -This is the top level notation context. No other context can -contain a Score context. By default the Score context handles +This is the top level notation context. No other context can +contain a Score context. By default the Score context handles the administration of time signatures and makes sure that items such as clefs, time signatures, and key-signatures are aligned across staves. @@ -140,7 +140,7 @@ executed. @strong{@emph{StaffGroup}} Groups staves while adding a bracket on the left side, grouping -the staves together. The bar lines of the contained staves are +the staves together. The bar lines of the contained staves are connected vertically. @code{StaffGroup} only consists of a collection of staves, with a bracket in front and spanning bar lines. @@ -2320,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}. @@ -2401,7 +2401,7 @@ a For some layout objects, the @code{minimum-length} property becomes effective only if the @code{set-spacing-rods} procedure is called explicitly. To do this, the @code{springs-and-rods} property should -be set to @code{ly:spanner::set-spacing-rods}. For example, +be set to @code{ly:spanner::set-spacing-rods}. For example, the minimum length of a glissando has no effect unless the @code{springs-and-rods} property is set: @@ -2448,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. @@ -3097,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} @@ -3164,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 @@ -3205,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} @@ -3306,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 @@ -3322,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 @@ -3348,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 @@ -3369,42 +3385,42 @@ 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 @@ -3572,16 +3588,15 @@ of ties as required. @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 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}. +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:: -* Common argument types:: * Substitution function examples:: @end menu @@ -3593,87 +3608,88 @@ code is easy. The general form of these functions is @example function = -#(define-music-function (parser location @var{var1} @var{var2}...@var{vari}... ) - (@var{var1-type?} @var{var2-type?}...@var{vari-type?}...) - #@{ - @emph{...music...} - #@}) +#(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 @var{vari} @tab @var{i}th variable -@item @var{vari-type?} @tab type of @var{i}th variable -@item @var{...music...} @tab normal LilyPond input, using - variables as @code{#$var1}, etc. -@end multitable - -Common variable types are described in @ref{Common argument types}. -A more complete description of variable types is found in -@rextend{Music function syntax}. +@item @code{@var{argN}} +@tab @var{n}th argument -The @code{parser} and @code{location} arguments are mandatory, -and are used in some advanced situations as described in -@rextend{Music function syntax}. For substitution functions, just be sure -to include them. +@item @code{@var{typeN?}} +@tab a scheme @emph{type predicate} for which @code{@var{argN}} +must return @code{#t}. -@seealso +@item @code{@var{@dots{}music@dots{}}} +@tab normal LilyPond input, using @code{$} to reference arguments +(eg. @samp{$arg1}). +@end multitable -Notation Reference: -@ref{Common argument types}. -Extending LilyPond: -@rextend{Music function syntax}. +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. -@node Common argument types -@subsection Common argument types +The list of type predicates is also required. Some of the most +common type predicates used in music functions are: -In order to allow for error checking, the type of each argument -that is passed to a music function must be defined. Some of the -common types of variables are shown in the table below. +@example +boolean? +cheap-list? @emph{(use instead of }@q{list?}@emph{ for faster processing)} +ly:music? +markup? +number? +pair? +string? +symbol? +@end example -The following input types may be used as variables in a music -function. This list is not exhaustive; -more information about possible variable types -can be found in @rextend{Music function syntax}. +@noindent +For a list of available type predicates, see +@ref{Predefined type predicates}. User-defined type predicates +are also allowed. -@multitable @columnfractions .33 .66 -@headitem Input type @tab @var{vari-type?} notation -@item Integer @tab @code{integer?} -@item Float (decimal number) @tab @code{number?} -@item Text string @tab @code{string?} -@item Markup @tab @code{markup?} -@item Music expression @tab @code{ly:music?} -@item A Scheme pair @tab @code{pair?} -@end multitable @seealso -Extending LilyPond: -@rextend {Music function syntax}. +Notation Reference: +@ref{Predefined type predicates}. + +Extending: +@rextend{Music functions}. Installed Files: @file{lily/music-scheme.cc}, -@file{scm/c++.scm}. +@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. +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 - #}) +padText = +#(define-music-function + (parser location padding) + (number?) + #{ + \once \override TextScript #'padding = $padding + #}) \relative c''' { c4^"piu mosso" b a b @@ -3687,30 +3703,36 @@ padText = #(define-music-function (parser location padding) (number?) In addition to numbers, we can use music expressions such as notes for arguments to music functions: -@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 - #}) +@c TODO: use a better example (the music argument is redundant). -{ c' d' e' f' \custosNote g' } +@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 } -#}) +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" } @@ -3722,3 +3744,4 @@ tempoPadded = #(define-music-function (parser location padding tempotext) @seealso +TODO: add missing @@ref's here.