From: Carl Sorensen <c_sorensen@byu.edu>
Date: Thu, 17 Dec 2009 06:07:14 +0000 (-0700)
Subject: Doc -- move simple substition functions to NR5
X-Git-Tag: release/2.13.10-1~150
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=a50623bd6f5ff0ecc55aa9fe6a4b2699d47fafb0;p=lilypond.git

Doc -- move simple substition functions to NR5
---

diff --git a/Documentation/extending/programming-interface.itely b/Documentation/extending/programming-interface.itely
index cfde6b712c..b5b1c196b0 100644
--- a/Documentation/extending/programming-interface.itely
+++ b/Documentation/extending/programming-interface.itely
@@ -31,45 +31,47 @@ not familiar with Scheme, you may wish to read our
 @node Music functions
 @section Music functions
 
-This section discusses how to create music functions within LilyPond.
+Music functions are scheme functions that are used to
+automatically create music expressions.  They can be used to
+greatly simplify the input file.
 
 @menu
-* Overview of music functions::
+* Music function syntax::
 * Simple substitution functions::
-* Paired substitution functions::
+* Intermediate substitution functions::
 * Mathematics in functions::
 * Void functions::
 * Functions without arguments::
 @end menu
 
-@node Overview of music functions
-@subsection Overview of music functions
+@node Music function syntax
+@subsection Music function syntax
 
-Making a function that substitutes a variable into LilyPond
-code is easy.  The general form of these functions is
+The general syntax of a music function is:
 
 @example
-function =
-#(define-music-function (parser location @var{var1} @var{var2}...@var{vari}... )
-                        (@var{var1-type?} @var{var2-type?}...@var{vari-type?}...)
-  #@{
-    @emph{...music...}
-  #@})
+myFunction =
+#(define-music-function (parser location @var{var_1} @var{var_2}...@var{var_n})
+                        (@var{var_1-type?} @var{var_2-type?}...@var{var_n-type?})
+    @var{...valid music expression...})
 @end example
 
 @noindent
 where
 
 @multitable @columnfractions .33 .66
-@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
- variables as @code{#$var1}, etc.
+@item @var{var_i}         @tab @var{i}th variable
+@item @var{var_i-type?}   @tab type of @var{i}th variable
+@item @var{...valid music expression...}  @tab expression that returns
+valid music, generally in the form of a Scheme expression.  There is
+also special syntax that allows LilyPond input code in this music
+expression.
 @end multitable
 
-The following input types may be used as variables in a music
-function.  This list is not exhaustive; see other documentation
-specifically about Scheme for more variable types.
+The variable type checkers are scheme procedures that will return
+@code{#t} if a variable is of a given type.  Some common types
+are shown in the table below.  Other types can be found in the files
+@file{lily/music-scheme.cc} and @file{scm/c++.scm}.
 
 @multitable @columnfractions .33 .66
 @headitem Input type          @tab @var{vari-type?} notation
@@ -81,19 +83,42 @@ specifically about Scheme for more variable types.
 @item A pair of variables     @tab @code{pair?}
 @end multitable
 
-The @code{parser} and @code{location} arguments are mandatory,
-and are used in some advanced situations.  The @code{parser}
-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
+The @code{parser} and @code{location} arguments are mandatory.
+The @code{parser} argument is used in the body of the function
+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
 can tell the user an appropriate place to look in the input file.
 
-
 @node Simple substitution functions
 @subsection Simple substitution functions
 
-Here is a simple example,
+A simple substitution function is a music function whose output music
+expression is written in LilyPond code, but with an input variable
+substituted into the LilyPond code.  The general form of these functions is
+
+@example
+myFunction =
+#(define-music-function (parser location @var{var1})
+                        (@var{var1-type?})
+  #@{
+    @emph{... LilyPond input code with} @code{#$var1} @emph{for substition ...}
+  #@})
+@end example
+
+Note that the special characters @code{#@{} and @code{#@}} surround the
+LilyPond music.
+
+@multitable @columnfractions .33 .66
+@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
+ variables as @code{#$var1}, etc.
+@end multitable
+
+For example, a function can be defined that simplifies
+setting the padding of a TextScript:
 
 @lilypond[quote,verbatim,ragged-right]
 padText = #(define-music-function (parser location padding) (number?)
@@ -110,7 +135,8 @@ padText = #(define-music-function (parser location padding) (number?)
 }
 @end lilypond
 
-Music expressions may be substituted as well,
+In addition to numbers, we can use music expressions such
+as notes for arguments to music functions:
 
 @lilypond[quote,verbatim,ragged-right]
 custosNote = #(define-music-function (parser location note)
@@ -123,36 +149,21 @@ custosNote = #(define-music-function (parser location note)
     \once \override Voice.Stem #'stencil = ##f
     $note
   #})
-
-{ c' d' e' f' \custosNote g' }
 @end lilypond
 
-Multiple variables may be used,
-
-@lilypond[quote,verbatim,ragged-right]
-tempoPadded = #(define-music-function (parser location padding tempotext)
-  (number? string?)
-#{
-  \once \override Score.MetronomeMark #'padding = $padding
-  \tempo \markup { \bold $tempotext }
-#})
-
-\relative c'' {
-  \tempo \markup { "Low tempo" }
-  c4 d e f g1
-  \tempoPadded #4.0 #"High tempo"
-  g4 f e d c1
-}
-@end lilypond
+@node Intermediate substitution functions
+@subsection Intermediate substitution functions
 
+Slightly more complicated than simple substitution function,
+intermediate substitution functions involve a mix of Scheme code and
+LilyPond code in the music expression to be
+returned.
 
-@node Paired substitution functions
-@subsection Paired substitution functions
+Some @code{\override} commands require an argument consisting of
+a pair of numbers (called a @code{cons cell} in Scheme).
 
-Some @code{\override} commands require a pair of numbers
-(called a @code{cons cell} in Scheme).  To pass these numbers
-into a function, either use a @code{pair?} variable, or
-insert the @code{cons} into the music function.
+The pair can be directly passed into the music function,
+using a @code{pair?} variable:
 
 @quotation
 @example
@@ -169,8 +180,10 @@ manualBeam =
 @end example
 @end quotation
 
-@noindent
-or
+Alternatively, the numbers making up the pair can be
+passed as separate arguments, and the Scheme code
+used to create the pair can be included in the
+music expression:
 
 @lilypond[quote,verbatim,ragged-right]
 manualBeam =
@@ -1185,7 +1198,7 @@ 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 
+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
@@ -1424,7 +1437,7 @@ spanner objects, such as slurs and ties.  Usually, only one
 spanner object is created at a time, and it can be adjusted with
 the normal mechanism.  However, occasionally a spanner crosses a
 line break.  When this happens, the object is cloned.  A separate
-object is created for every system in which the spanner appears.  
+object is created for every system in which the spanner appears.
 The new objects are clones of the original object and inherit all
 properties, including @code{\override}s.
 
diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
index 5ee001c66e..70f46e0b36 100644
--- a/Documentation/notation/changing-defaults.itely
+++ b/Documentation/notation/changing-defaults.itely
@@ -46,6 +46,7 @@ on entering numbers, lists, strings, and symbols in Scheme.}
 * Modifying properties::
 * Useful concepts and properties::
 * Advanced tweaks::
+* Using music functions::
 @end menu
 
 
@@ -3563,3 +3564,158 @@ command.
 
 
 
+@node Using music functions
+@section Using music functions
+
+@c TODO -- add @seealso, etc. to these subsections
+
+Where tweaks need to be reused with different music expressions, it
+is often convenient to make the tweak part of a music function.
+In this section, we discuss only @emph{substitution} functions, where
+the object is to substitute a variable into a piece of LilyPond
+input code.  Other more complex functions are described in
+@rextend{Music functions}.
+
+@menu
+* Substitution function syntax::
+* Common argument types::
+* Substitution function examples::
+@end menu
+
+@node Substitution function syntax
+@subsection Substitution function syntax
+
+Making a function that substitutes a variable into LilyPond
+code is easy.  The general form of these functions is
+
+@example
+function =
+#(define-music-function (parser location @var{var1} @var{var2}...@var{vari}... )
+                        (@var{var1-type?} @var{var2-type?}...@var{vari-type?}...)
+  #@{
+    @emph{...music...}
+  #@})
+@end example
+
+@noindent
+where
+
+@multitable @columnfractions .33 .66
+@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
+ variables as @code{#$var1}, etc.
+@end multitable
+
+Common variable types are described in @ref{Common argument types}.
+A more complete description of variable types is found in
+@rextend{Music function syntax}.
+
+The @code{parser} and @code{location} arguments are mandatory,
+and are used in some advanced situations as described in
+@rextend{Music function syntax}.  For substitution functions, just be sure
+to include them.
+
+@seealso
+
+Notation Reference:
+@ref{Common argument types}.
+
+Extending LilyPond:
+@rextend{Music function syntax}.
+
+@node Common argument types
+@subsection Common argument types
+
+In order to allow for error checking, the type of each argument
+that is passed to a music function must be defined.  Some of the
+common types of variables are shown in the table below.
+
+The following input types may be used as variables in a music
+function.  This list is not exhaustive;
+more information about possible variable types
+can be found in @rextend{Music function syntax}.
+
+@multitable @columnfractions .33 .66
+@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 Markup                  @tab @code{markup?}
+@item Music expression        @tab @code{ly:music?}
+@item A Scheme pair           @tab @code{pair?}
+@end multitable
+
+@seealso
+
+Extending LilyPond:
+@rextend {Music function syntax}.
+
+Installed Files:
+@file{lily/music-scheme.cc},
+@file{scm/c++.scm}.
+
+
+@node Substitution function examples
+@subsection Substitution function examples
+
+This section introduces some substitution function examples.  These
+are not intended to be exhaustive, but rather to demonstrate some
+of the possibilities of simple substitution functions.
+
+In the first example, a function is defined that simplifies
+setting the padding of a TextScript:
+
+@lilypond[quote,verbatim,ragged-right]
+padText = #(define-music-function (parser location padding) (number?)
+  #{
+    \once \override TextScript #'padding = #$padding
+  #})
+
+\relative c''' {
+  c4^"piu mosso" b a b
+  \padText #1.8
+  c4^"piu mosso" d e f
+  \padText #2.6
+  c4^"piu mosso" fis a g
+}
+@end lilypond
+
+In addition to numbers, we can use music expressions such
+as notes for arguments to music functions:
+
+@lilypond[quote,verbatim,ragged-right]
+custosNote = #(define-music-function (parser location note)
+                                     (ly:music?)
+  #{
+    \once \override Voice.NoteHead #'stencil =
+      #ly:text-interface::print
+    \once \override Voice.NoteHead #'text =
+      \markup \musicglyph #"custodes.mensural.u0"
+    \once \override Voice.Stem #'stencil = ##f
+    $note
+  #})
+
+{ c' d' e' f' \custosNote g' }
+@end lilypond
+
+Substitution functions with multiple arguments can be defined:
+
+@lilypond[quote,verbatim,ragged-right]
+tempoPadded = #(define-music-function (parser location padding tempotext)
+  (number? string?)
+#{
+  \once \override Score.MetronomeMark #'padding = $padding
+  \tempo \markup { \bold $tempotext }
+#})
+
+\relative c'' {
+  \tempo \markup { "Low tempo" }
+  c4 d e f g1
+  \tempoPadded #4.0 #"High tempo"
+  g4 f e d c1
+}
+@end lilypond
+
+@seealso
+