documentation for #{ ... #} : rfc

[Nicolas Sceaux]

Hello,

Here is a draft doc for the #{ ... #} syntax. As I'm not exactly easy with
English, may someone read it and comment?

nicolas

--- programming-interface.itely.~1.9.~  2004-05-13 10:36:54.000000000 +0200
+++ programming-interface.itely 2004-05-30 14:19:06.000000000 +0200
@@ -18,6 +18,7 @@
 * Internal music representation::  
 * Extending music syntax::      
 * Manipulating music expressions::  
+* Using LilyPond syntax inside Scheme::  
 @end menu
 
 @node Input variables and Scheme
@@ -189,14 +190,24 @@
 @code{\applymusic} is selected by defining
 
 @example
-  apply = #(ly:make-music-function
-   (list procedure? ly:music?)
-   (lambda (where func music)
-     (func music)))
+  applymusic = #(ly:make-music-function
+                  (list procedure? ly:music?)
+                  (lambda (location func music)
+                    (func music)))
address@hidden example
+
+A @code{def-music-function} macro is introduced on top of
address@hidden:make-music-function} as a syntactic suggar:
+
address@hidden
+  applymusic = #(def-music-function (location func music) (procedure? 
ly:music?)
+                  (func music))
 @end example
 
 Examples of the use of @code{\applymusic} are in the next section.
 
address@hidden
address@hidden/music-functions-init.ly}.
 
 @node Manipulating music expressions
 @appendixsubsec Manipulating music expressions
@@ -289,7 +300,113 @@
 @inputfileref{input/test,unfold-all-repeats.ly}, and
 @inputfileref{input/test,music-box.ly}.
 
address@hidden Using LilyPond syntax inside Scheme
address@hidden Using LilyPond syntax inside Scheme
+
+Creating music expressions in scheme requires the knowledge of a
+little API (@code{make-music}, @code{ly:music-property}, etc), music
+expressions interfaces, how music objects are nested in order to
+build a whole music expression, and is usually verbose. For some
+simple tasks, this can be avoided, using LilyPond usual syntax inside
+scheme, thanks to the dedicated @address@hidden ... address@hidden syntax.
+
+The following two expressions give equivalent music expressions:
address@hidden
+  mynotes = @{ \override Stem #'thickness = #4
+              \notes @{ c'8 d' @} @}
+  
+  #(define mynotes address@hidden \override Stem #'thickness = #4
+                      \notes @{ c'8 d' @} address@hidden)
address@hidden example
+
+The content of @address@hidden ... address@hidden is enclosed in an implicit 
@address@hidden
+... @}} block, which is parsed. The resulting music expression, a
+SequentialMusic music object, is then returned and usable in scheme.
+
+Variables and scheme forms can be introduced in @address@hidden ... 
address@hidden
+expressions thanks to the @code{$} character. This makes the creation
+of simple functions straightforward. In the following example, a
+function setting the TextScript's padding is defined:
+
address@hidden,raggedright]
+  #(use-modules (ice-9 optargs))
+  #(define* (textpad padding #:optional once?)
+    (ly:export   ; this is necessary for using the expression
+                 ; directly inside a \notes block
+      (if once?
+          #{ \once \override TextScript #'padding = #$padding #}
+          #{ \override TextScript #'padding = #$padding #})))
+  
+  \score {
+      \notes {
+          c'^"1"
+          #(textpad 3.0 #t) % only once
+          c'^"2"
+          c'^"3"
+          #(textpad 5.0)
+          c'^"4"
+          c'^"5"
+          
+      }
+  }
address@hidden lilypond
 
+Here, the variable @code{padding} is a number; music expression
+variables may also be used in a similar fashion, as in the following
+example:
+
address@hidden,raggedright]
+  #(define (with-padding padding)
+     (lambda (music)
+       #{ \override TextScript #'padding = #$padding
+          $music
+          \revert TextScript #'padding #}))
+  
+  \score {
+      \notes {
+          c'^"1"
+          \applymusic #(with-padding 3)
+            { c'^"2" c'^"3"}
+          c'^"4"
+      }
+  }
address@hidden lilypond
+
+The function created by @code{(with-padding 3)} adds @code{\override} and
address@hidden statements around the music given as an argument, and returns
+this new expression. Thus, this example is equivalent to:
+
address@hidden
+  \score @{
+      \notes @{
+          c'^"1"
+          @{ \override TextScript #'padding = #3
+            @{ c'^"2" c'^"3"@}
+            \revert TextScript #'padding
+          @}
+          c'^"4"
+      @}
+  @}
address@hidden example
+
+Note: we could also have defined @code{with-padding} as a
+music function.
+
address@hidden,raggedright]
+  withPadding = #(def-music-function (location padding music) (number? 
ly:music?)
+                   #{ \override TextScript #'padding = #$padding
+                      $music 
+                      \revert TextScript #'padding #})
+  
+  \score {
+      \notes {
+          c'^"1"
+          \withPadding #3
+            { c'^"2" c'^"3"}
+          c'^"4"
+      }
+  }
address@hidden lilypond
 
 @node Markup programmer interface
 @appendixsec Markup programmer interface