Issue 4421/7: Documentation and Changes entry

2 files changed, 29 insertions, 8 deletions

diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index 6735a03b08..f6137cf8f2 100644
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -62,6 +62,18 @@ which scares away people.
 @end ignore
 
 @item
+LilyPond functions defined with @code{define-music-function},
+@code{define-event-function}, @code{define-scheme-function} and
+@code{define-void-function} can now be directly called from Scheme
+as if they were genuine Scheme procedures.  Argument checking and
+matching will still be performed in the same manner as when
+calling the function through LilyPond input.  This includes the
+insertion of defaults for optional arguments not matching their
+predicates.  Instead of using @code{\default} in the actual
+argument list for explicitly skipping a sequence of optional
+arguments, @code{*unspecified*} can be employed.
+
+@item
 The definition of LilyPond functions with
 @code{define-music-function}, @code{define-event-function},
 @code{define-scheme-function} and @code{define-void-function} no
diff --git a/Documentation/extending/programming-interface.itely b/Documentation/extending/programming-interface.itely
index e8f41a9338..f572fc9d83 100644
--- 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