Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.36"
+@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
@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
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