Issue 4421/7: Documentation and Changes entry

[lilypond.git] / Documentation / extending / programming-interface.itely

diff --git a/Documentation/extending/programming-interface.itely b/Documentation/extending/programming-interface.itely
index e8f41a9338bd33442c6f978fc74c1b564742e3cc..f572fc9d83f6a5c4cb3539d6f120ab936dda3e0c 100644 (file)
--- a/Documentation/extending/programming-interface.itely
+++ b/Documentation/extending/programming-interface.itely
@@ -197,14 +197,15 @@ Installed Files:
 @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
@@ -224,6 +225,14 @@ some context, you should use normal scheme functions only for those
 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