From 6061d1c04417e9b669455116756159fdf81a32c1 Mon Sep 17 00:00:00 2001 From: David Kastrup Date: Sun, 28 Aug 2011 17:49:40 +0200 Subject: [PATCH] programming-interface.itely: Integrate new behavior of #{ ... #} into docs --- .../extending/programming-interface.itely | 86 +++++++++++++------ 1 file changed, 61 insertions(+), 25 deletions(-) diff --git a/Documentation/extending/programming-interface.itely b/Documentation/extending/programming-interface.itely index 71865e7788..130ea01ab7 100644 --- a/Documentation/extending/programming-interface.itely +++ b/Documentation/extending/programming-interface.itely @@ -76,7 +76,11 @@ LilyPond code enclosed in hashed braces (@tie{}@w{@code{#@{@dots{}#@}}}@tie{}). Within LilyPond code blocks, use @code{$} to reference function arguments (eg., @samp{$arg1}) or to start an inline scheme expression containing -function arguments (eg., @w{@samp{$(cons arg1 arg2)}}). +function arguments (eg., @w{@samp{$(cons arg1 arg2)}}). A LilyPond code +block may contain anything that you can use on the right side of an +assignment. In addition, an empty LilyPond block corresponds to a void +music expression, and a LilyPond block containing multiple music events +gets turned into a sequential music expression. @end multitable @@ -117,9 +121,7 @@ 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. +on the argument list. @item As a post-event. All trailing arguments of the music function with the @@ -295,12 +297,9 @@ may want to have a function that does not involve music (such as turning off Point and Click). To do this, we return a @code{void} music expression. -That is why the form that is returned is the -@w{@code{(make-music @dots{})}}. With the @code{'void} property -set to @code{#t}, the parser is told to actually disregard this -returned music expression. Thus the important part of the void -music function is the processing done by the function, not the -music expression that is returned. +Using the form @code{#@{ #@}} will actually achieve that. If you for +some reason really need an empty sequential music expression, you would +have to write @code{#@{ @{ @} #@}} instead. @example noPointAndClick = @@ -308,7 +307,7 @@ noPointAndClick = (parser location) () (ly:set-option 'point-and-click #f) - (make-music 'SequentialMusic 'void #t)) + #@{ #@}) ... \noPointAndClick % disable point and click @end example @@ -343,13 +342,16 @@ providing a LilyPond-like syntax. For example, @noindent is equivalent to: @example -\markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @} - \larger \line @{ foo bar baz @} @} +#@{ \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @} + \larger \line @{ foo bar baz @} @} #@} @end example @noindent This example demonstrates the main translation rules between regular -LilyPond markup syntax and Scheme markup syntax. +LilyPond markup syntax and Scheme markup syntax. Using @code{#@{ +@dots{} #@}} for entering in Lilypond syntax will often be most +convenient, but we explain how to use the @code{markup} macro to get a +Scheme-only solution. @quotation @multitable @columnfractions .3 .3 @@ -560,6 +562,16 @@ command is needed. Thus, we write a @code{double-box} markup command, taking one argument (the text). This draws the two boxes, with some padding. +@lisp +#(define-markup-command (double-box layout props text) (markup?) + "Draw a double box around text." + (interpret-markup layout props + #@{\markup \override #'(box-padding . 0.4) \box + \override #'(box-padding . 0.6) \box @{ $text @}#@})) +@end lisp + +or, equivalently + @lisp #(define-markup-command (double-box layout props text) (markup?) "Draw a double box around text." @@ -571,10 +583,10 @@ padding. @code{text} is the name of the command argument, and @code{markup?} its type: it identifies it as a markup. The @code{interpret-markup} function is used in most of markup commands: it builds a stencil, using -@code{layout}, @code{props}, and a markup. Here, this markup is built -using the @code{markup} scheme macro, see @ref{Markup construction in Scheme}. -The transformation from @code{\markup} expression to scheme -markup expression is straight-forward. +@code{layout}, @code{props}, and a markup. In the second case, this +markup is built using the @code{markup} scheme macro, see @ref{Markup +construction in Scheme}. The transformation from @code{\markup} +expression to scheme markup expression is straight-forward. The new command can be used as follow: @@ -591,6 +603,19 @@ and the text. So we will introduce a new property, @code{box-padding} will be used for the inner padding. The new code is now as follows: +@lisp +#(define-markup-command (double-box layout props text) (markup?) + #:properties ((inter-box-padding 0.4) + (box-padding 0.6)) + "Draw a double box around text." + (interpret-markup layout props + #@{\markup \override #`(box-padding . ,$inter-box-padding) \box + \override #`(box-padding . ,$box-padding) \box + @{ $text @} #@})) +@end lisp + +Again, the equivalent version using the markup macro would be: + @lisp #(define-markup-command (double-box layout props text) (markup?) #:properties ((inter-box-padding 0.4) @@ -620,8 +645,9 @@ customized: (box-padding 0.6)) "Draw a double box around text." (interpret-markup layout props - (markup #:override `(box-padding . ,inter-box-padding) #:box - #:override `(box-padding . ,box-padding) #:box text))) + #{\markup \override #`(box-padding . ,$inter-box-padding) \box + \override #`(box-padding . ,$box-padding) \box + { $text } #})) \markup \double-box A \markup \override #'(inter-box-padding . 0.8) \double-box A @@ -722,6 +748,16 @@ a single stencil, the former returns a list of stencils. In the following example, a @code{\paragraph} markup list command is defined, which returns a list of justified lines, the first one being indented. The indent width is taken from the @code{props} argument. + +@example +#(define-markup-list-command (paragraph layout props args) (markup-list?) + #:properties ((par-indent 2)) + (interpret-markup-list layout props + #@{\markuplines \justified-lines @{ \hspace #$par-indent $args @} #@})) +@end example + + +The version using just Scheme is more complex: @example #(define-markup-list-command (paragraph layout props args) (markup-list?) #:properties ((par-indent 2)) @@ -737,11 +773,11 @@ Besides the usual @code{layout} and @code{props} arguments, the First, the function gets the indent width, a property here named @code{par-indent}, from the property list @code{props}. If the property 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. A -horizontal space is added at the beginning using the -@code{make-hspace-markup} function. Finally, the markup list is +list of justified lines is made using the built-in markup list command +@code{\justified-lines}, which is related to the +@code{make-justified-lines-markup-list} function. A +horizontal space is added at the beginning using @code{\hspace} (or the +@code{make-hspace-markup} function). Finally, the markup list is interpreted using the @code{interpret-markup-list} function. This new markup list command can be used as follows: -- 2.39.2