Merge branch 'master' of git://git.sv.gnu.org/lilypond.git into td-lily

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

diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely
index ac5e5ea0a4e5a99475688dd6b5dd70458490df26..26d5842d87d41ef1da83389664e4e5be802d8f5b 100644 (file)
--- a/Documentation/user/programming-interface.itely
+++ b/Documentation/user/programming-interface.itely
@@ -7,6 +7,8 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
+@c \version "2.11.38"
+
 @node Interfaces for programmers
 @chapter Interfaces for programmers
 
@@ -269,7 +271,7 @@ displayBarNum =
 @end example
 
 To actually display bar numbers where this function is called,
-invoke lilypond with
+invoke @command{lilypond} with
 
 @example
 lilypond -d display-bar-numbers FILENAME.ly
@@ -389,7 +391,7 @@ define some Scheme code in a macro (to be called later), use
 @end example
 
 
-@refbugs
+@knownissues
 
 Mixing Scheme and LilyPond variables is not possible with the
 @code{--safe} option.
@@ -895,7 +897,7 @@ useful when defining new markup commands (see
 @ref{New markup command definition}).
 
 
-@refbugs
+@knownissues
 
 The markup-list argument of commands such as @code{#:line},
 @code{#:center}, and @code{#:column} cannot be a variable or
@@ -1112,7 +1114,53 @@ to the @code{interpret-markup} function, with the @code{layout} and
 
 Note: there is now an internal command @code{\smallCaps} which can
 be used to set text in small caps.  See
-@ref{Overview of text markup commands}, for details.
+@ref{Text markup commands}, for details.
+
+@knownissues
+
+Currently, the available combinations of arguments (after the standard
+@var{layout} and @var{props} arguments) to a markup command defined with
+@code{define-markup-command} are limited as follows.
+
+@table @asis
+@item (no argument)
+@itemx @var{list}
+@itemx @var{markup}
+@itemx @var{markup markup}
+@itemx @var{scm}
+@itemx @var{scm markup}
+@itemx @var{scm scm}
+@itemx @var{scm scm markup}
+@itemx @var{scm markup markup}
+@itemx @var{scm scm scm}
+@end table
+
+@noindent
+In the above table, @var{scm} represents native Scheme data types like
+@q{number} oder @q{string}.
+
+As an example, it is not possible to use a markup command @code{foo} with
+four arguments defined as
+
+@example
+#(define-markup-command (foo layout props
+                         num1    str1    num2    str2)
+                        (number? string? number? string?)
+  ...)
+@end example
+
+@noindent
+If you apply it as, say,
+
+@example
+\markup \foo #1 #"bar" #2 #"baz"
+@end example
+
+@cindex Scheme signature
+@cindex signature, Scheme
+@noindent
+@command{lilypond} complains that it cannot parse @code{foo} due to its
+unknown Scheme signature.
 
 
 @node New markup list command definition
@@ -1120,7 +1168,7 @@ be used to set text in small caps.  See
 Markup list commands are defined with the
 @code{define-markup-list-command} Scheme macro, which is similar to the
 @code{define-markup-command} macro described in
-@ref{New markup command definition}, except that where the later returns
+@ref{New markup command definition}, except that where the latter returns
 a single stencil, the former returns a list stencils.
 
 In the following example, a @code{\paragraph} markup list command is
@@ -1144,7 +1192,7 @@ is not found, the default value is @code{2}.  Then, a list of justified
 lines is made using the @code{make-justified-lines-markup-list}
 function, which is related to the @code{\justified-lines}
 built-in markup list command.  An horizontal space is added at the
-begining using the @code{make-hspace-markup} function.  Finally, the
+beginning using the @code{make-hspace-markup} function.  Finally, the
 markup list is interpreted using the @code{interpret-markup-list}
 function.