(Scheme

procedures as properties): more doco on simple-closure and scheme
callbacks.
(Input variables and Scheme): use lilypond[verbatim], document
dummy statement.

diff --git a/ChangeLog b/ChangeLog
index 6ca0e40326626c021823ad0495c2751614fcfdee..078395566f4f0be0ee6289dac3b3e41b3723f82b 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2006-10-20  Han-Wen Nienhuys  <hanwen@lilypond.org>
 
+       * Documentation/user/programming-interface.itely (Scheme
+       procedures as properties): more doco on simple-closure and scheme
+       callbacks.
+       (Input variables and Scheme): use lilypond[verbatim], document
+       dummy statement.
+
        * Documentation/user/page.itely (Displaying spacing): use \book
        explicitly, so arrows show .
        (Line breaking): add note about Forbid_line_break_engraver

diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely
index 38dbbc0ae5e2e47795a5504d70c5d2dcba5c96ae..e8eade873c07f4da080fae954103c99ba27cf10b 100644 (file)
--- a/Documentation/user/programming-interface.itely
+++ b/Documentation/user/programming-interface.itely
@@ -292,23 +292,35 @@ mixed.  In the following example, a music fragment is stored in the
 variable @code{traLaLa}, and duplicated using Scheme.  The result is
 imported in a @code{\score} block by means of a second variable
 @code{twice}:
-@example
+
+@lilypond[verbatim]
 traLaLa = @{ c'4 d'4 @}
 
+%% deal with parser lookahead
+#(display "this needs to be here, sorry!")
+
 #(define newLa (map ly:music-deep-copy
   (list traLaLa traLaLa)))
 #(define twice
   (make-sequential-music newLa))
 
 @{ \twice @}
-@end example
+@end lilypond
 
-In the above example, music expressions can be `exported' from the
+Due to parser lookahead
+
+In this example, the assignment happens after parser has verified that
+nothing interesting happens after @code{traLaLa = @{ ... @}}. Without
+the dummy statement in the above example, the @code{newLa} definition
+is executed before @code{traLaLa} is defined, leading to a syntax
+error.
+
+The above example shows how to `export' music expressions from the
 input to the Scheme interpreter.  The opposite is also possible.  By
 wrapping a Scheme value in the function @code{ly:export}, a Scheme
-value is interpreted as if it were entered in LilyPond syntax.  Instead
-of defining @code{\twice}, the example above could also have been
-written as
+value is interpreted as if it were entered in LilyPond syntax.
+Instead of defining @code{\twice}, the example above could also have
+been written as
 @example
 @dots{}
 @{ #(ly:export (make-sequential-music (list newLa))) @}
@@ -1152,8 +1164,26 @@ Properties can also be set to a Scheme procedure,
 c b a g b a g b
 @end lilypond
 
-Procedures may also be combined like that with
-"grob closure".  Here is a setting from
+@noindent
+In this case, the procedure is executed as soon as the value of the
+property is requested during the formatting process.
+
+Most of the typesetting engine is driven by such callbacks.
+Properties that typically use callbacks include  
+
+@table @code
+@item stencil
+  The printing routine, that constructs a drawing for the symbol
+@item X-offset
+  The routine that sets the horizontal position
+@item X-extent
+  The routine that computes the width of an object
+@end table
+
+The procedure always takes a single argument, being the grob.
+
+If routines with multiple arguments must be called, the current grob
+can be inserted with a grob closure.  Here is a setting from
 @code{AccidentalSuggestion},
 
 @example
@@ -1166,4 +1196,20 @@ Procedures may also be combined like that with
            (list ly:self-alignment-interface::x-aligned-on-self)))))
 @end example
 
+@noindent
+In this example, both @code{ly:self-alignment-interface::x-aligned-on-self} and
+@code{ly:self-alignment-interface::centered-on-x-parent} are called
+with the grob as argument. The results are added with the @code{+}
+function. To ensure that this addition is properly executed, the whole
+thing is enclosed in @code{ly:make-simple-closure}.
+
+In fact, using a single procedure as property value is equivalent to
 
+@example
+(ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
+@end example
+
+@noindent
+The inner @code{ly:make-simple-closure} supplies the grob as argument
+to @var{proc}, the outer ensures that result of the function is
+returned, rather than the @code{simple-closure} object.