Add dynamic script fffff; update docs.

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

diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely
index 9263b951dcee9368c5f13ece3a1e72f102ce37f8..2d28412eabf138715b88cfcdfe1d2fec21d176e7 100644 (file)
--- a/Documentation/user/programming-interface.itely
+++ b/Documentation/user/programming-interface.itely
@@ -7,7 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

-@c \version "2.11.51"
+@c \version "2.12.0"

 
 @node Interfaces for programmers
 @chapter Interfaces for programmers
 
 @node Interfaces for programmers
 @chapter Interfaces for programmers


@@ -17,13 +17,14 @@ not familiar with Scheme, you may wish to read our
 @rlearning{Scheme tutorial}.
 
 @menu
 @rlearning{Scheme tutorial}.
 
 @menu

-* Music functions::             
-* Programmer interfaces::       
-* Building complicated functions::  
-* Markup programmer interface::  
-* Contexts for programmers::    
-* Scheme procedures as properties::  
-* TODO moved into scheme::      
+* Music functions::
+* Programmer interfaces::
+* Building complicated functions::
+* Markup programmer interface::
+* Contexts for programmers::
+* Scheme procedures as properties::
+* Using Scheme code instead of \tweak::
+* Difficult tweaks::

 @end menu
 
 
 @end menu
 
 


@@ -33,13 +34,13 @@ not familiar with Scheme, you may wish to read our
 This section discusses how to create music functions within LilyPond.
 
 @menu
 This section discusses how to create music functions within LilyPond.
 
 @menu

-* Overview of music functions::  
-* Simple substitution functions::  
-* Paired substitution functions::  
-* Mathematics in functions::    
-* Void functions::              
-* Functions without arguments::  
-* Overview of available music functions::  
+* Overview of music functions::
+* Simple substitution functions::
+* Paired substitution functions::
+* Mathematics in functions::
+* Void functions::
+* Functions without arguments::
+* Overview of available music functions::

 @end menu
 
 @node Overview of music functions
 @end menu
 
 @node Overview of music functions


@@ -50,8 +51,8 @@ code is easy.  The general form of these functions is
 
 @example
 function =
 
 @example
 function =

-#(define-music-function (parser location @var{var1} @var{var2}... )
-                        (@var{var1-type?} @var{var2-type?}...)
+#(define-music-function (parser location @var{var1} @var{var2}...@var{vari}... )
+                        (@var{var1-type?} @var{var2-type?}...@var{vari-type?}...)

   #@{
     @emph{...music...}
   #@})
   #@{
     @emph{...music...}
   #@})


@@ -61,10 +62,10 @@ function =
 where
 
 @multitable @columnfractions .33 .66
 where
 
 @multitable @columnfractions .33 .66

-@item @var{argi}         @tab @var{i}th variable
-@item @var{argi-type?}   @tab type of variable
+@item @var{vari}         @tab @var{i}th variable
+@item @var{vari-type?}   @tab type of @var{i}th variable

 @item @var{...music...}  @tab normal LilyPond input, using
 @item @var{...music...}  @tab normal LilyPond input, using

-  variables as @code{#$var1}.
+ variables as @code{#$var1}, etc.

 @end multitable
 
 There following input types may be used as variables
 @end multitable
 
 There following input types may be used as variables


@@ -73,7 +74,7 @@ other documentation specifically about Scheme for more
 variable types.
 
 @multitable @columnfractions .33 .66
 variable types.
 
 @multitable @columnfractions .33 .66

-@headitem Input type          @tab @var{argi-type?} notation
+@headitem Input type          @tab @var{vari-type?} notation

 @item Integer                 @tab @code{integer?}
 @item Float (decimal number)  @tab @code{number?}
 @item Text string             @tab @code{string?}
 @item Integer                 @tab @code{integer?}
 @item Float (decimal number)  @tab @code{number?}
 @item Text string             @tab @code{string?}


@@ -82,9 +83,9 @@ variable types.
 @item A pair of variables     @tab @code{pair?}
 @end multitable
 
 @item A pair of variables     @tab @code{pair?}
 @end multitable
 

-The @code{parser} and @code{location} argument are mandatory,
+The @code{parser} and @code{location} arguments are mandatory,

 and are used in some advanced situations.  The @code{parser}
 and are used in some advanced situations.  The @code{parser}

-argument is used to access to the value of another LilyPond
+argument is used to gain access to the value of another LilyPond

 variable.  The @code{location} argument
 is used to set the @q{origin} of the music expression that is built
 by the music function, so that in case of a syntax error LilyPond
 variable.  The @code{location} argument
 is used to set the @q{origin} of the music expression that is built
 by the music function, so that in case of a syntax error LilyPond


@@ -131,18 +132,18 @@ custosNote = #(define-music-function (parser location note)
 Multiple variables may be used,
 
 @lilypond[quote,verbatim,ragged-right]
 Multiple variables may be used,
 
 @lilypond[quote,verbatim,ragged-right]

-tempoMark = #(define-music-function (parser location padding marktext)
-                                    (number? string?)
+tempoPadded = #(define-music-function (parser location padding tempotext)
+  (number? string?)

 #{
 #{

-  \once \override Score . RehearsalMark #'padding = $padding
-  \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
-  \mark \markup { \bold $marktext }
+  \once \override Score.MetronomeMark #'padding = $padding
+  \tempo \markup { \bold $tempotext }

 #})
 
 \relative c'' {
 #})
 
 \relative c'' {

-c2 e
-\tempoMark #3.0 #"Allegro"
-g c
+  \tempo \markup { "Low tempo" }
+  c4 d e f g1
+  \tempoPadded #4.0 #"High tempo"
+  g4 f e d c1

 }
 @end lilypond
 
 }
 @end lilypond
 


@@ -296,8 +297,8 @@ This section contains information about mixing LilyPond
 and Scheme.
 
 @menu
 and Scheme.
 
 @menu

-* Input variables and Scheme::  
-* Internal music representation::  
+* Input variables and Scheme::
+* Internal music representation::

 @end menu
 
 
 @end menu
 
 


@@ -359,7 +360,7 @@ traLaLa = { c'4 d'4 }
 { \twice }
 @end lilypond
 
 { \twice }
 @end lilypond
 

-Due to parser lookahead
+@c Due to parser lookahead

 
 In this example, the assignment happens after parser has verified that
 nothing interesting happens after @code{traLaLa = @{ ... @}}.  Without
 
 In this example, the assignment happens after parser has verified that
 nothing interesting happens after @code{traLaLa = @{ ... @}}.  Without


@@ -373,8 +374,9 @@ 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
 @example

-@dots{}
+...

 @{ #(ly:export (make-sequential-music (list newLa))) @}
 @end example
 
 @{ #(ly:export (make-sequential-music (list newLa))) @}
 @end example
 


@@ -437,7 +439,7 @@ under @rinternals{Music properties}.
 A compound music expression is a music object that contains other
 music objects in its properties.  A list of objects can be stored in
 the @code{elements} property of a music object, or a single @q{child}
 A compound music expression is a music object that contains other
 music objects in its properties.  A list of objects can be stored in
 the @code{elements} property of a music object, or a single @q{child}

-music object in the @code{element} object.  For example,
+music object in the @code{element} property.  For example,

 @rinternals{SequentialMusic} has its children in @code{elements},
 and @rinternals{GraceMusic} has its single argument in
 @code{element}.  The body of a repeat is stored in the @code{element}
 @rinternals{SequentialMusic} has its children in @code{elements},
 and @rinternals{GraceMusic} has its single argument in
 @code{element}.  The body of a repeat is stored in the @code{element}


@@ -453,10 +455,10 @@ This section explains how to gather the information necessary
 to create complicated music functions.
 
 @menu
 to create complicated music functions.
 
 @menu

-* Displaying music expressions::  
-* Music properties::            
-* Doubling a note with slurs (example)::  
-* Adding articulation to notes (example)::  
+* Displaying music expressions::
+* Music properties::
+* Doubling a note with slurs (example)::
+* Adding articulation to notes (example)::

 @end menu
 
 
 @end menu
 
 


@@ -464,8 +466,10 @@ to create complicated music functions.
 @subsection Displaying music expressions
 
 @cindex internal storage
 @subsection Displaying music expressions
 
 @cindex internal storage

+@cindex displaying music expressions
+@cindex internal representation, displaying
+@cindex displayMusic

 @funindex \displayMusic
 @funindex \displayMusic

-@funindex \displayLilyMusic

 
 When writing a music function it is often instructive to inspect how
 a music expression is stored internally.  This can be done with the
 
 When writing a music function it is often instructive to inspect how
 a music expression is stored internally.  This can be done with the


@@ -578,6 +582,8 @@ of the @code{NoteEvent} object,
 
 The note pitch can be changed by setting this 'pitch property,
 
 
 The note pitch can be changed by setting this 'pitch property,
 

+@funindex \displayLilyMusic
+

 @example
 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
                           'pitch)
 @example
 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
                           'pitch)


@@ -847,10 +853,10 @@ Markups are implemented as special Scheme functions which produce a
 Stencil object given a number of arguments.
 
 @menu
 Stencil object given a number of arguments.
 
 @menu

-* Markup construction in Scheme::  
-* How markups work internally::  
-* New markup command definition::  
-* New markup list command definition::  
+* Markup construction in Scheme::
+* How markups work internally::
+* New markup command definition::
+* New markup list command definition::

 @end menu
 
 
 @end menu
 
 


@@ -863,14 +869,14 @@ The @code{markup} macro builds markup expressions in Scheme while
 providing a LilyPond-like syntax.  For example,
 @example
 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
 providing a LilyPond-like syntax.  For example,
 @example
 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")

-                  #:bigger #:line ("foo" "bar" "baz")))
+                  #:larger #:line ("foo" "bar" "baz")))

 @end example
 
 @noindent
 is equivalent to:
 @example
 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
 @end example
 
 @noindent
 is equivalent to:
 @example
 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}

-                  \bigger \line @{ foo bar baz @} @}
+                  \larger \line @{ foo bar baz @} @}

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -885,7 +891,7 @@ LilyPond markup syntax and Scheme markup syntax.
         @code{(markup markup1 markup2 ... )}
 @item @code{\command} @tab @code{#:command}
 @item @code{\variable} @tab @code{variable}
         @code{(markup markup1 markup2 ... )}
 @item @code{\command} @tab @code{#:command}
 @item @code{\variable} @tab @code{variable}

-@item @code{\center-align @{ ... @}} @tab @code{#:center-align ( ... )}
+@item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}

 @item @code{string} @tab @code{"string"}
 @item @code{#scheme-arg} @tab @code{scheme-arg}
 @end multitable
 @item @code{string} @tab @code{"string"}
 @item @code{#scheme-arg} @tab @code{scheme-arg}
 @end multitable


@@ -1179,7 +1185,7 @@ indented.  The indent width is taken from the @code{props} argument.
 @example
 #(define-markup-list-command (paragraph layout props args) (markup-list?)
    (let ((indent (chain-assoc-get 'par-indent props 2)))
 @example
 #(define-markup-list-command (paragraph layout props args) (markup-list?)
    (let ((indent (chain-assoc-get 'par-indent props 2)))

-     (interpret-markup-list layout props 
+     (interpret-markup-list layout props

        (make-justified-lines-markup-list (cons (make-hspace-markup indent)
                                                args)))))
 @end example
        (make-justified-lines-markup-list (cons (make-hspace-markup indent)
                                                args)))))
 @end example


@@ -1220,8 +1226,8 @@ This new markup list command can be used as follows:
 @section Contexts for programmers
 
 @menu
 @section Contexts for programmers
 
 @menu

-* Context evaluation::          
-* Running a function on all layout objects::  
+* Context evaluation::
+* Running a function on all layout objects::

 @end menu
 
 @node Context evaluation
 @end menu
 
 @node Context evaluation


@@ -1285,13 +1291,16 @@ this is a @rinternals{NoteHead} object.
 Here is a function to use for @code{\applyOutput}; it blanks
 note-heads on the center-line:
 
 Here is a function to use for @code{\applyOutput}; it blanks
 note-heads on the center-line:
 

-@example
-(define (blanker grob grob-origin context)
- (if (and (memq (ly:grob-property grob 'interfaces)
-                note-head-interface)
-          (eq? (ly:grob-property grob 'staff-position) 0))
-     (set! (ly:grob-property grob 'transparent) #t)))
-@end example
+@lilypond[quote,verbatim,ragged-right]
+#(define (blanker grob grob-origin context)
+   (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
+            (eq? (ly:grob-property grob 'staff-position) 0))
+       (set! (ly:grob-property grob 'transparent) #t)))
+
+\relative {
+  e4 g8 \applyOutput #'Voice #blanker b d2
+}
+@end lilypond

 
 
 @node Scheme procedures as properties
 
 
 @node Scheme procedures as properties


@@ -1319,7 +1328,7 @@ 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.
 property is requested during the formatting process.
 
 Most of the typesetting engine is driven by such callbacks.

-Properties that typically use callbacks include  
+Properties that typically use callbacks include

 
 @table @code
 @item stencil
 
 @table @code
 @item stencil


@@ -1365,16 +1374,8 @@ to @var{proc}, the outer ensures that result of the function is
 returned, rather than the @code{simple-closure} object.
 
 
 returned, rather than the @code{simple-closure} object.
 
 

-@node TODO moved into scheme
-@section TODO moved into scheme
-
-@menu
-* Using Scheme code instead of \tweak::  
-* Difficult tweaks::            
-@end menu
-

 @node Using Scheme code instead of \tweak
 @node Using Scheme code instead of \tweak

-@subsection Using Scheme code instead of @code{\tweak}
+@section Using Scheme code instead of @code{\tweak}

 
 The main disadvantage of @code{\tweak} is its syntactical
 inflexibility.  For example, the following produces a syntax error.
 
 The main disadvantage of @code{\tweak} is its syntactical
 inflexibility.  For example, the following produces a syntax error.


@@ -1403,7 +1404,7 @@ F = #(let ((m (make-music 'ArticulationEvent
              (acons 'font-size -3
                     (ly:music-property m 'tweaks)))
        m)
              (acons 'font-size -3
                     (ly:music-property m 'tweaks)))
        m)

- 
+

 \relative c'' @{
   c4^\F c4_\F
 @}
 \relative c'' @{
   c4^\F c4_\F
 @}


@@ -1421,7 +1422,7 @@ written back with @code{set!}.  The last element of the
 
 
 @node Difficult tweaks
 
 
 @node Difficult tweaks

-@subsection Difficult tweaks
+@section Difficult tweaks

 
 There are a few classes of difficult adjustments.
 
 
 There are a few classes of difficult adjustments.
 


@@ -1504,7 +1505,7 @@ and @code{PaperColumn}.  They can be changed with the
 @end example
 
 Note, however, that @code{\override}, applied to
 @end example
 
 Note, however, that @code{\override}, applied to

-@code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as
+@code{NonMusicalPaperColumn} and @code{PaperColumn}, still works as

 expected within @code{\context} blocks.
 
 @end itemize
 expected within @code{\context} blocks.
 
 @end itemize