Guide, node Updating translation committishes..
@end ignore
-@c \version "2.19.22"
+@c \version "2.19.24"
@node Interfaces for programmers
@chapter Interfaces for programmers
@subsection Scheme function usage
Scheme functions can be called pretty much anywhere where a Scheme
-expression starting with @code{#} can be written. You call a scheme
-function by writing its name preceded by @code{\}, followed by its
-arguments. Once an optional argument predicate does not match an
-argument, LilyPond skips this and all following optional arguments,
-replacing them with their specified default, and @q{backs up} the
-argument that did not match to the place of the next mandatory argument.
-Since the backed up argument needs to go somewhere, optional arguments
-are not actually considered optional unless followed by a mandatory
+expression starting with @code{#} can be written. You call a
+scheme function from LilyPond by writing its name preceded by
+@code{\}, followed by its arguments. Once an optional argument
+predicate does not match an argument, LilyPond skips this and all
+following optional arguments, replacing them with their specified
+default, and @q{backs up} the argument that did not match to the
+place of the next mandatory argument. Since the backed up
+argument needs to go somewhere, optional arguments are not
+actually considered optional unless followed by a mandatory
argument.
There is one exception: if you write @code{\default} in the place of an
cases where you always return a useful value, and use void scheme
functions (@pxref{Void scheme functions}) otherwise.
+For convenience, scheme functions may also be called directly from
+Scheme bypassing the LilyPond parser. Their name can be used like
+the name of an ordinary function. Typechecking of the arguments
+and skipping optional arguments will happen in the same manner as
+when called from within LilyPond, with the Scheme value
+@code{*unspecified*} taking the role of the @code{\default}
+reserved word for explicitly skipping optional arguments.
+
@node Void scheme functions
@subsection Void scheme functions
@funindex define-void-function
The most versatile way of tuning an object is @code{\applyOutput} which
works by inserting an event into the specified context
-(@rinternals{ApplyOutputEvent}). Its syntax is
+(@rinternals{ApplyOutputEvent}). Its syntax is either
@example
\applyOutput @var{Context} @var{proc}
@end example
+or
+@example
+\applyOutput @var{Context}.@var{Grob} @var{proc}
+@end example
@noindent
where @code{@var{proc}} is a Scheme function, taking three arguments.
When interpreted, the function @code{@var{proc}} is called for
-every layout object found in the context @code{@var{Context}} at
-the current time step, with the following arguments:
+every layout object (with grob name @var{Grob} if specified) found
+in the context @code{@var{Context}} at the current time step, with
+the following arguments:
@itemize
@item the layout object itself,
@item the context where the layout object was created, and
@lilypond[quote,verbatim,ragged-right]
#(define (blanker grob grob-origin context)
- (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
- (< (abs (ly:grob-property grob 'staff-position)) 2))
+ (if (< (abs (ly:grob-property grob 'staff-position)) 2)
(set! (ly:grob-property grob 'transparent) #t)))
\relative {
- a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
+ a'4 e8 <<\applyOutput Voice.NoteHead #blanker a c d>> b2
}
@end lilypond
level use these forms
@example
-\applyOutput #'Score #@var{function}
-\applyOutput #'Staff #@var{function}
+\applyOutput Score@dots{}
+\applyOutput Staff@dots{}
@end example
\override Stem.thickness = #2.0
@end example
-Properties can also be set to a Scheme procedure,
+Properties can also be set to a Scheme procedure:
-@lilypond[fragment,verbatim,quote,relative=2]
+@lilypond[fragment,verbatim,quote]
\override Stem.thickness = #(lambda (grob)
(if (= UP (ly:grob-property grob 'direction))
2.0
7.0))
-c b a g b a g b
+\relative { c'' b a g b a g b }
@end lilypond
@noindent