From 1117e3e62b740f513a8372a10a6fec32dbf012be Mon Sep 17 00:00:00 2001
From: Mark Polesky <address@hidden>
Date: Sun, 25 Apr 2010 17:33:58 -0700
Subject: [PATCH] Doc: Reorganize music functions material.

* Remove nodes from Extending that are covered in
  Notation:
    2.1.1 Music function syntax
    2.1.2 Simple substitution functions

* In Extending 2.1, move `Void functions' to end
  of section, so `Functions without arguments'
  comes first.

* Use a consistent indentation format for music
  functions.

* Make some minor formatting/wording changes.

* Create type-predicates-doc-string to document
  type-p-name-alist automatically.

* Add notation appendix
  `Music function type predicates' to include
  type-predicates-doc-string.
---
 .../extending/programming-interface.itely          |  259 ++++++-------------
 Documentation/notation/changing-defaults.itely     |  113 +++++----
 Documentation/notation/notation-appendices.itely   |    7 +
 scm/c++.scm                                        |    2 +-
 scm/documentation-generate.scm                     |    9 +-
 5 files changed, 156 insertions(+), 234 deletions(-)

diff --git a/Documentation/extending/programming-interface.itely b/Documentation/extending/programming-interface.itely
index 7045b49..e8e44cf 100644
--- a/Documentation/extending/programming-interface.itely
+++ b/Documentation/extending/programming-interface.itely
@@ -30,137 +30,25 @@ not familiar with Scheme, you may wish to read our
 @node Music functions
 @section Music functions
 
-Music functions are scheme functions that are used to
-automatically create music expressions.  They can be used to
-greatly simplify the input file.
address@hidden functions} are scheme procedures that can create music
+expressions automatically.  They can be used to greatly simplify
+the input file.  This section assumes that you are already
+familiar with simple substitution functions, which are described
+in @ruser{Using music functions}.
 
 @menu
-* Music function syntax::
-* Simple substitution functions::
 * Intermediate substitution functions::
 * Mathematics in functions::
-* Void functions::
 * Functions without arguments::
+* Void functions::
 @end menu
 
address@hidden Music function syntax
address@hidden Music function syntax
-
-The general syntax of a music function is:
-
address@hidden
-myFunction =
-#(define-music-function (parser location @var{var_1} @address@hidden)
-                        (@var{var_1-type?} @address@hidden)
-    @var{...valid music expression...})
address@hidden example
-
address@hidden
-where
-
address@hidden @columnfractions .33 .66
address@hidden @var{var_i}         @tab @var{i}th variable
address@hidden @var{var_i-type?}   @tab type of @var{i}th variable
address@hidden @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.
address@hidden multitable
-
-The variable type checkers are scheme procedures that will return
address@hidden 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
address@hidden/music-scheme.cc} and @file{scm/c++.scm}.  The complete
-list of named type checkers for LilyPond is found in the
address@hidden of @file{scm/lily.scm}.
-
address@hidden TODO -- automatically document type-p-name-alist
-
address@hidden @columnfractions .33 .66
address@hidden Input type          @tab @var{vari-type?} notation
address@hidden Integer                 @tab @code{integer?}
address@hidden Float (decimal number)  @tab @code{number?}
address@hidden Text string             @tab @code{string?}
address@hidden Markup                  @tab @code{markup?}
address@hidden Music expression        @tab @code{ly:music?}
address@hidden A pair of variables     @tab @code{pair?}
address@hidden multitable
-
-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.
-
address@hidden Simple substitution functions
address@hidden Simple substitution functions
-
-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
-
address@hidden
-myFunction =
-#(define-music-function (parser location @var{var1})
-                        (@var{var1-type?})
-  address@hidden
-    @emph{... LilyPond input code with} @code{#$var1} @emph{for substition ...}
-  address@hidden)
address@hidden example
-
-Note that the special characters @address@hidden and @address@hidden surround the
-LilyPond music.
-
address@hidden @columnfractions .33 .66
address@hidden @var{vari}         @tab @var{i}th variable
address@hidden @var{vari-type?}   @tab type of @var{i}th variable
address@hidden @var{...music...}  @tab normal LilyPond input, using
- variables as @code{#$var1}, etc.
address@hidden multitable
-
-For example, a function can be defined that simplifies
-setting the padding of a TextScript:
-
address@hidden,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
-}
address@hidden lilypond
-
-In addition to numbers, we can use music expressions such
-as notes for arguments to music functions:
-
address@hidden,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
-  #})
address@hidden 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.
+Intermediate substitution functions involve a mix of Scheme code
+and LilyPond code in the music expression to be returned.
 
 Some @code{\override} commands require an argument consisting of
 a pair of numbers (called a @code{cons cell} in Scheme).
@@ -168,20 +56,19 @@ a pair of numbers (called a @code{cons cell} in Scheme).
 The pair can be directly passed into the music function,
 using a @code{pair?} variable:
 
address@hidden
 @example
 manualBeam =
-#(define-music-function (parser location beg-end)
-                        (pair?)
address@hidden
-  \once \override Beam #'positions = #$beg-end
address@hidden)
+#(define-music-function
+  (parser location beg-end)
+  (pair?)
+  address@hidden
+    \once \override Beam #'positions = #$beg-end
+  address@hidden)
 
 \relative c' @{
   \manualBeam #'(3 . 6) c8 d e f
 @}
 @end example
address@hidden quotation
 
 Alternatively, the numbers making up the pair can be
 passed as separate arguments, and the Scheme code
@@ -190,11 +77,12 @@ music expression:
 
 @lilypond[quote,verbatim,ragged-right]
 manualBeam =
-#(define-music-function (parser location beg end)
-                        (number? number?)
-#{
-  \once \override Beam #'positions = #(cons $beg $end)
-#})
+#(define-music-function
+  (parser location beg end)
+  (number? number?)
+  #{
+    \once \override Beam #'positions = #(cons $beg $end)
+  #})
 
 \relative c' {
   \manualBeam #3 #6 c8 d e f
@@ -209,60 +97,49 @@ Music functions can involve Scheme programming in
 addition to simple substitution,
 
 @lilypond[quote,verbatim,ragged-right]
-AltOn = #(define-music-function (parser location mag) (number?)
-  #{ \override Stem #'length = #$(* 7.0 mag)
-     \override NoteHead #'font-size =
-       #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #})
+AltOn =
+#(define-music-function
+  (parser location mag)
+  (number?)
+  #{
+    \override Stem #'length = #$(* 7.0 mag)
+    \override NoteHead #'font-size =
+      #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
+  #})
 
 AltOff = {
   \revert Stem #'length
   \revert NoteHead #'font-size
 }
 
-{ c'2 \AltOn #0.5 c'4 c'
-  \AltOn #1.5 c' c' \AltOff c'2 }
+\relative c' {
+  c2 \AltOn #0.5 c4 c
+  \AltOn #1.5 c c \AltOff c2
+}
 @end lilypond
 
 @noindent
 This example may be rewritten to pass in music expressions,
 
 @lilypond[quote,verbatim,ragged-right]
-withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
-  #{ \override Stem #'length = #$(* 7.0 mag)
-     \override NoteHead #'font-size =
-       #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
-     $music
-     \revert Stem #'length
-     \revert NoteHead #'font-size #})
-
-{ c'2 \withAlt #0.5 {c'4 c'}
-  \withAlt #1.5 {c' c'} c'2 }
address@hidden lilypond
-
address@hidden Void functions
address@hidden Void functions
-
-A music function must return a music expression, but sometimes we
-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 @code{(make-music ...)}.  With the
address@hidden'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.
+withAlt =
+#(define-music-function
+  (parser location mag music)
+  (number? ly:music?)
+  #{
+    \override Stem #'length = #$(* 7.0 mag)
+    \override NoteHead #'font-size =
+      #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
+    $music
+    \revert Stem #'length
+    \revert NoteHead #'font-size
+  #})
 
address@hidden
-noPointAndClick =
-#(define-music-function (parser location) ()
-   (ly:set-option 'point-and-click #f)
-   (make-music 'SequentialMusic 'void #t))
-...
-\noPointAndClick   % disable point and click
address@hidden example
+\relative c' {
+  c2 \withAlt #0.5 { c4 c }
+  \withAlt #1.5 { c c } c2
+}
address@hidden lilypond
 
 
 @node Functions without arguments
@@ -280,10 +157,12 @@ without arguments,
 
 @example
 displayBarNum =
-#(define-music-function (parser location) ()
-   (if (eq? #t (ly:get-option 'display-bar-numbers))
-       address@hidden \once \override Score.BarNumber #'break-visibility = ##f address@hidden
-       address@hidden@}))
+#(define-music-function
+  (parser location)
+  ()
+  (if (eq? #t (ly:get-option 'display-bar-numbers))
+      address@hidden \once \override Score.BarNumber #'break-visibility = ##f address@hidden
+      address@hidden@}))
 @end example
 
 To actually display bar numbers where this function is called,
@@ -294,6 +173,32 @@ lilypond -d display-bar-numbers FILENAME.ly
 @end example
 
 
address@hidden Void functions
address@hidden Void functions
+
+A music function must return a music expression, but sometimes we
+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
address@hidden@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.
+
address@hidden
+noPointAndClick =
+#(define-music-function
+  (parser location)
+  ()
+  (ly:set-option 'point-and-click #f)
+  (make-music 'SequentialMusic 'void #t))
+...
+\noPointAndClick   % disable point and click
address@hidden example
+
 
 @node Markup functions
 @section Markup functions
diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
index e743ac1..091e2d2 100644
--- a/Documentation/notation/changing-defaults.itely
+++ b/Documentation/notation/changing-defaults.itely
@@ -3572,16 +3572,15 @@ of ties as required.
 
 @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
address@hidden functions}.
+Where tweaks need to be reused with different music expressions,
+it is often convenient to make the tweak part of a @emph{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
 
@@ -3593,10 +3592,11 @@ code is easy.  The general form of these functions is
 
 @example
 function =
-#(define-music-function (parser location @var{var1} @address@hidden )
-                        (@var{var1-type?} @address@hidden)
+#(define-music-function
+  (parser location @var{arg1} @var{arg2} @dots{})
+  (@var{type1?} @var{type2?} @dots{})
   address@hidden
-    @emph{...music...}
+    @address@hidden@dots{}}
   address@hidden)
 @end example
 
@@ -3604,63 +3604,60 @@ function =
 where
 
 @multitable @columnfractions .33 .66
address@hidden @var{vari}         @tab @var{i}th variable
address@hidden @var{vari-type?}   @tab type of @var{i}th variable
address@hidden @var{...music...}  @tab normal LilyPond input, using
- variables as @code{#$var1}, etc.
address@hidden multitable
address@hidden @address@hidden
address@hidden @var{n}th argument
 
-Common variable types are described in @ref{Common argument types}.
-A more complete description of variable types is found in
address@hidden function syntax}.  The complete list of defined variable
-types is found in the @var{type-p-name-alist} entry of
address@hidden/lily.scm}.
address@hidden @address@hidden
address@hidden a scheme @emph{type predicate} for which @address@hidden
+must return @code{#t}.
 
address@hidden TODO -- find an automatic way of documenting the type-p-name-alist
address@hidden @address@hidden@address@hidden
address@hidden normal LilyPond input, with arguments referenced as
address@hidden or @samp{#$arg1}, depending on context.
address@hidden multitable
 
-The @code{parser} and @code{location} arguments are mandatory,
-and are used in some advanced situations as described in
address@hidden function syntax}.  For substitution functions, just be sure
-to include them.
 
address@hidden
+The @code{parser} and @code{location} arguments are mandatory, and
+are used in some advanced situations as described in
address@hidden function syntax}.  For substitution functions, just
+be sure to include them.
 
-Notation Reference:
address@hidden argument types}.
+The list of type predicates is also required.  Some of the most
+common type predicates used in music functions are:
 
-Extending LilyPond:
address@hidden function syntax}.
address@hidden
+boolean?
+list?
+ly:music?
+markup?
+number?
+pair?
+string?
+symbol?
address@hidden example
 
address@hidden Common argument types
address@hidden Common argument types
address@hidden
+For the complete list of available type predicates, see
address@hidden function type predicates}.
 
-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}.
+TODO: Explain @address@hidden vs. @code{$}} once and for all.
 
address@hidden @columnfractions .33 .66
address@hidden Input type          @tab @var{vari-type?} notation
address@hidden Integer                 @tab @code{integer?}
address@hidden Float (decimal number)  @tab @code{number?}
address@hidden Text string             @tab @code{string?}
address@hidden Markup                  @tab @code{markup?}
address@hidden Music expression        @tab @code{ly:music?}
address@hidden A Scheme pair           @tab @code{pair?}
address@hidden multitable
+Properly referencing arguments inside the music block may be
+confusing at first. ...
 
 @seealso
 
+Notation Reference:
address@hidden function type predicates}.
+
 Extending LilyPond:
address@hidden {Music function syntax}.
address@hidden function syntax}.
 
 Installed Files:
 @file{lily/music-scheme.cc},
address@hidden/c++.scm}.
address@hidden/c++.scm},
address@hidden/lily.scm}.
 
 
 @node Substitution function examples
@@ -3674,7 +3671,10 @@ 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?)
+padText =
+#(define-music-function
+  (parser location padding)
+  (number?)
   #{
     \once \override TextScript #'padding = #$padding
   #})
@@ -3692,8 +3692,10 @@ 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?)
+custosNote =
+#(define-music-function
+  (parser location note)
+  (ly:music?)
   #{
     \once \override Voice.NoteHead #'stencil =
       #ly:text-interface::print
@@ -3709,7 +3711,9 @@ custosNote = #(define-music-function (parser location note)
 Substitution functions with multiple arguments can be defined:
 
 @lilypond[quote,verbatim,ragged-right]
-tempoPadded = #(define-music-function (parser location padding tempotext)
+tempoPadded =
+#(define-music-function
+  (parser location padding tempotext)
   (number? string?)
 #{
   \once \override Score.MetronomeMark #'padding = $padding
@@ -3726,3 +3730,4 @@ tempoPadded = #(define-music-function (parser location padding tempotext)
 
 @seealso
 
+TODO: add missing @@ref's here.
diff --git a/Documentation/notation/notation-appendices.itely b/Documentation/notation/notation-appendices.itely
index b18810e..e46f990 100644
--- a/Documentation/notation/notation-appendices.itely
+++ b/Documentation/notation/notation-appendices.itely
@@ -47,6 +47,7 @@ and just before
 * All context properties::
 * Layout properties::
 * Available music functions::
+* Music function type predicates::
 * Scheme functions::
 @end menu
 
@@ -1343,6 +1344,12 @@ Internals Reference:
 @include identifiers.tely
 
 
address@hidden Music function type predicates
address@hidden Music function type predicates
+
address@hidden type-predicates.tely
+
+
 @node Scheme functions
 @appendixsec Scheme functions
 
diff --git a/scm/c++.scm b/scm/c++.scm
index 362e358..78e0a2c 100644
--- a/scm/c++.scm
+++ b/scm/c++.scm
@@ -58,7 +58,7 @@
 
 ;; moved list to end of lily.scm: then all type-predicates are
 ;; defined.
-(define type-p-name-alist '())
+(define-public type-p-name-alist '())
 
 (define (match-predicate obj alist)
   (if (null? alist)
diff --git a/scm/documentation-generate.scm b/scm/documentation-generate.scm
index c64fb3a..0e6cfe3 100644
--- a/scm/documentation-generate.scm
+++ b/scm/documentation-generate.scm
@@ -32,6 +32,7 @@
 	       "document-functions.scm"
 	       "document-translation.scm"
 	       "document-music.scm"
+	       "document-type-predicates.scm"
 	       "document-identifiers.scm"
 	       "document-backend.scm"
 	       "document-markup.scm"))
@@ -42,7 +43,7 @@
  (slot-ref (all-scheme-functions-doc) 'text)
  (open-output-file "scheme-functions.tely"))
 
-;;(display 
+;;(display
 ;; (markup-doc-string)
 ;; (open-output-file "markup-commands.tely"))
 
@@ -54,7 +55,11 @@
   (lambda (port)
     (dump-node (markup-list-doc-node) port 2)))
 
-(display 
+(display
+ type-predicates-doc-string
+ (open-output-file "type-predicates.tely"))
+
+(display
  (identifiers-doc-string)
  (open-output-file "identifiers.tely"))
 
-- 
1.6.3.3