Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.14.0"
@node Interfaces for programmers
@chapter Interfaces for programmers
input file.
@menu
-* Music function syntax::
+* Music function definitions::
+* Music function usage::
* Simple substitution functions::
* Intermediate substitution functions::
* Mathematics in functions::
@end menu
-@node Music function syntax
-@subsection Music function syntax
+@node Music function definitions
+@subsection Music function definitions
-The general form for music functions is:
+The general form for defining music functions is:
@example
function =
@item @code{@var{typeN?}}
@tab a scheme @emph{type predicate} for which @code{@var{argN}}
-must return @code{#t}.
+must return @code{#t}. Some of these predicates are specially
+recognized by the parser, see below.
@item @code{@var{music}}
@tab A music expression, optionally written in scheme, with any
@end multitable
@noindent
-For a list of available type predicates, see
-@ruser{Predefined type predicates}. User-defined type predicates
-are also allowed.
+Some type predicates are specially recognized by the parser and will
+make the parser look for the respective arguments in Lilypond syntax
+rather than in Scheme syntax. Currently these are @code{ly:music?},
+@code{markup?}, @code{ly:pitch?}, and @code{ly:duration?}.
+
+If you really want to input one of those items as a Scheme rather than a
+Lilypond expression, you may write them as a Scheme expression that
+calls @code{ly:export} at its outermost level.
+
+Other type predicates, including user-defined ones, will make the
+respective argument only be accepted as a Scheme expression.
+For a list of available type predicates, see
+@ruser{Predefined type predicates}.
@seealso
@file{scm/lily.scm}.
+@node Music function usage
+@subsection Music function usage
+Music functions may currently be used in three places. Depending on
+where they are used, restrictions apply in order to be able to parse
+them unambiguously. The result a music function returns must be
+compatible with the context in which it is called.
+
+@itemize
+@item
+At top level in a music expression. There are no special restrictions
+on the argument list. Using the @code{#@{}@dots{}@code{#@}} construct
+produces a sequential music expression and consequently can only applied
+in this context.
+
+@item
+As a post-event. All trailing arguments of the music function with the
+predicate @code{ly:music?} will get parsed also as post-events. Note
+that returning post-events will also be acceptable for music functions
+called at top level, leading to a result roughly equivalent to
+@example
+s 1*0-\fun
+@end example
+
+@item
+As a chord constituent. All trailing arguments of the music function
+with the predicate @code{ly:music?} will get parsed also as chord
+constituents.
+@end itemize
+
+@noindent
+The special rules for trailing arguments make it possible to write
+polymorphic functions like @code{\tweak} that can be applied to
+different constructs.
+
+There is another somewhat special rule: if you have a predicate
+@code{ly:music?} directly before a @code{ly:duration?} predicate, then
+the corresponding music expression must be either a music identifier, or
+literal sequential or parallel music enclosed in
+@code{@{}@dots{}@code{@}} or @code{<<}@dots{}@code{>>} explicitly.
+Otherwise, Lilypond could get confused about where the music ends and
+the duration starts.
+
@node Simple substitution functions
@subsection Simple substitution functions
and LilyPond code in the music expression to be returned.
Some @code{\override} commands require an argument consisting of
-a pair of numbers (called a @code{cons cell} in Scheme).
+a pair of numbers (called a @emph{cons cell} in Scheme).
The pair can be directly passed into the music function,
using a @code{pair?} variable:
@code{text example} string, and then it raises that Stencil by 0.5
staff space. This is a rather simple example; more complex examples
are in the rest
-of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
+of this section, and in @file{scm/define-markup-commands.scm}.
@node New markup command definition
The arguments are
-@table @var
-@item command-name
+@table @code
+@item @var{command-name}
the markup command name
@item layout
the @q{layout} definition.
@item props
a list of associative lists, containing all active properties.
-@item argi
+@item @var{argi}
@var{i}th command argument
-@item argi-type?
+@item @var{argi-type?}
a type predicate for the i@var{th} argument
@end table
-If the command uses properties from the @var{props} arguments, the
-@code{#:properties} keyword can be used to specify which properties are
-used along with their default values.
+If the command uses properties from the @code{props} arguments,
+the @code{#:properties} keyword can be used to specify which
+properties are used along with their default values.
Arguments are distinguished according to their type:
@itemize
@code{list?}, @code{number?}, @code{boolean?}, etc.
@end itemize
-There is no limitation on the order of arguments (after the standard
-@var{layout} and @var{props} arguments). However, markup functions
-taking a markup as their last argument are somewhat special as you can
-apply them to a markup list, and the result is a markup list where the
-markup function (with the specified leading arguments) has been applied
-to every element of the original markup list.
+There is no limitation on the order of arguments (after the
+standard @code{layout} and @code{props} arguments). However,
+markup functions taking a markup as their last argument are
+somewhat special as you can apply them to a markup list, and the
+result is a markup list where the markup function (with the
+specified leading arguments) has been applied to every element of
+the original markup list.
-Since replicating the leading arguments for applying a markup function
-to a markup list is cheap mostly for Scheme arguments, you avoid
-performance pitfalls by just using Scheme arguments for the leading
-arguments of markup functions that take a markup as their last argument.
+Since replicating the leading arguments for applying a markup
+function to a markup list is cheap mostly for Scheme arguments,
+you avoid performance pitfalls by just using Scheme arguments for
+the leading arguments of markup functions that take a markup as
+their last argument.
@node On properties
@unnumberedsubsubsec On properties
A good way to start writing a new markup command, is to take example on
a builtin one. Most of the markup commands provided with LilyPond can be
-found in file @file{scm/@/define@/-markup@/-commands@/.scm}.
+found in file @file{scm/define-markup-commands.scm}.
For instance, we would like to adapt the @code{\draw-line} command, to
draw a double line instead. The @code{\draw-line} command is defined as
\applyContext @var{function}
@end example
-@var{function} should be a Scheme function that takes a single
-argument: the context in which the @code{\applyContext} command is
-being called. The following code will print the current bar
-number on the standard output during the compile:
+@code{@var{function}} should be a Scheme function that takes a
+single argument: the context in which the @code{\applyContext}
+command is being called. The following code will print the
+current bar number on the standard output during the compile:
@example
\applyContext
@end example
@noindent
-where @var{proc} is a Scheme function, taking three arguments.
+where @code{@var{proc}} is a Scheme function, taking three arguments.
-When interpreted, the function @var{proc} is called for every layout
-object found in the context @var{context} at the current time step, with
-the following 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:
@itemize
@item the layout object itself,
@item the context where the layout object was created, and