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"
@node The set command
-@subsection The @code{\set} command
+@subsection The @code{@bs{}set} command
@cindex properties
@funindex \set
@qq{accepts} list can be changed, see @ref{Aligning contexts}.
@seealso
-Learning Manual:
+Usage Manual:
@rprogram{An extra staff appears}.
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
Notation Reference:
@ref{Explaining the Internals Reference},
-@ref{Modifying properties},
+@ref{Modifying properties}.
Installed Files:
@file{scm/@/define@/-grobs@/.scm}.
marks on such objects.
@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}
@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
@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}
@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
@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,
@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
@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
+@item @code{@var{argN}}
+@tab @var{n}th argument
-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{typeN?}}
+@tab a scheme @emph{type predicate} for which @code{@var{argN}}
+must return @code{#t}.
-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.
-
-@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
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" }
@seealso
+TODO: add missing @@ref's here.