]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/notation/changing-defaults.itely
Doc: Clarify \relative inside \repeat issue.
[lilypond.git] / Documentation / notation / changing-defaults.itely
index 8cb0e90ae7a74dd7aa0b51f65b7682ad462468f5..e743ac1683e5f20269f6f0eaf084c9a7d1c9c8ab 100644 (file)
@@ -4,7 +4,8 @@
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the
-    version that you are working on.  See TRANSLATION for details.
+    version that you are working on.  For details, see the Contributors'
+    Guide, node Updating translation committishes..
 @end ignore
 
 @c \version "2.12.0"
@@ -36,7 +37,7 @@ Internally, LilyPond uses Scheme (a LISP dialect) to provide
 infrastructure.  Overriding layout decisions in effect accesses the
 program internals, which requires Scheme input.  Scheme elements are
 introduced in a @code{.ly} file with the hash mark
-@code{#}.@footnote{@rlearning{Scheme tutorial}, contains a short tutorial
+@code{#}.@footnote{@rextend{Scheme tutorial}, contains a short tutorial
 on entering numbers, lists, strings, and symbols in Scheme.}
 
 
@@ -46,6 +47,7 @@ on entering numbers, lists, strings, and symbols in Scheme.}
 * Modifying properties::
 * Useful concepts and properties::
 * Advanced tweaks::
+* Using music functions::
 @end menu
 
 
@@ -391,7 +393,7 @@ any context of type @var{type}, regardless of its given name.
 
 This variant is used with music expressions that can be interpreted at
 several levels.  For example, the @code{\applyOutput} command (see
-@ref{Running a function on all layout objects}).  Without an explicit
+@rextend{Running a function on all layout objects}).  Without an explicit
 @code{\context}, it is usually applied to @code{Voice}
 
 @example
@@ -744,6 +746,22 @@ after calling @code{\RemoveEmptyStaffContext}, ie
 @node Defining new contexts
 @subsection Defining new contexts
 
+@cindex contexts, defining new
+@cindex engravers, including in contexts
+
+@funindex \alias
+@funindex alias
+@funindex \name
+@funindex name
+@funindex \type
+@funindex type
+@funindex \consists
+@funindex consists
+@funindex \accepts
+@funindex accepts
+@funindex \denies
+@funindex denies
+
 Specific contexts, like @code{Staff} and @code{Voice}, are made of
 simple building blocks.  It is possible to create new types of
 contexts with different combinations of engraver plug-ins.
@@ -1282,23 +1300,27 @@ Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
 Another thing that is needed, is an overview of the various naming
 conventions:
 
-    scheme functions: lowercase-with-hyphens (incl. one-word
+@itemize
+@item scheme functions: lowercase-with-hyphens (incl. one-word
 names)
-    scheme functions: ly:plus-scheme-style
-    music events, music classes and music properties:
+@item scheme functions: ly:plus-scheme-style
+@item music events, music classes and music properties:
 as-scheme-functions
-    Grob interfaces: scheme-style
-    backend properties: scheme-style (but X and Y!)
-    contexts (and MusicExpressions and grobs): Capitalized or
+@item Grob interfaces: scheme-style
+@item backend properties: scheme-style (but X and Y!)
+@item contexts (and MusicExpressions and grobs): Capitalized or
 CamelCase
-    context properties: lowercaseFollowedByCamelCase
-    engravers:
+@item context properties: lowercaseFollowedByCamelCase
+@item engravers:
 Capitalized_followed_by_lowercase_and_with_underscores
+@end itemize
 
-Which of these are conventions and which are rules?
-Which are rules of the underlying language, and which are
+Questions to be answered:
+@itemize
+@item Which of these are conventions and which are rules?
+@item Which are rules of the underlying language, and which are
 LP-specific?
-
+@end itemize
 
 @node Modifying properties
 @section Modifying properties
@@ -1325,6 +1347,17 @@ objects.  The settings used for printing these objects are also stored by
 context.  By changing these settings, the appearance of objects can be
 altered.
 
+There are two different kinds of properties stored in contexts:
+context properties and grob properties.  Context properties are
+properties that apply to the context as a whole and control
+how the context itself is displayed.  In contrast, grob properties
+apply to specific grob types that will be displayed in the context.
+
+The @code{\set} and @code{\unset} commands are used to change values
+for context properties.  The @code{\override} and @code{\revert}
+commands are used to change values for grob properties.
+
+@ignore
 The syntax for this is
 
 @example
@@ -1415,14 +1448,15 @@ such as
 \override Stem #'(details beamed-lengths) = #'(4 4 3)
 @end example
 
+@end ignore
 
 @seealso
 Internals:
+@rinternals{Backend},
+@rinternals{All layout objects},
 @rinternals{OverrideProperty},
 @rinternals{RevertProperty},
-@rinternals{PropertySet},
-@rinternals{Backend},
-@rinternals{All layout objects}.
+@rinternals{PropertySet}.
 
 
 @knownissues
@@ -1434,48 +1468,66 @@ or crashes, or both.
 
 
 @node The set command
-@subsection The @code{\set} command
+@subsection The @code{@bs{}set} command
 
 @cindex properties
 @funindex \set
 @cindex changing properties
 
-Each context can have different @emph{properties}, variables contained
-in that context.  They can be changed during the interpretation step.
-This is achieved by inserting the @code{\set} command in the music,
+Each context has a set of @emph{properties}, variables contained
+in that context.  Context properties are changed with the @code{\set}
+command, which has the following syntax:
 
 @example
-\set @var{context}.@var{prop} = #@var{value}
+\set @var{context}.@var{property} = #@var{value}
 @end example
 
-For example,
+@var{value} is a Scheme object, which is why it must be preceded by
+the @code{#} character.
+
+Contexts properties are usually named in
+@code{studlyCaps}.  They mostly control the translation from
+music to notation, e.g. @code{localKeySignature} (for determining
+whether to print accidentals), or @code{measurePosition} (for
+determining when to print a bar line).  Context properties can
+change value over time while interpreting a piece of music;
+@code{measurePosition} is an obvious example of
+this.  Context properties are modified with @code{\set}.
+
+For example, multimeasure rests will be combined into a single bar
+if the context property @code{skipBars} is set to @code{#t}:
+
 @lilypond[quote,verbatim,relative=2,fragment]
 R1*2
 \set Score.skipBars = ##t
 R1*2
 @end lilypond
 
-This command skips measures that have no notes.  The result is that
-multi-rests are condensed.  The value assigned is a Scheme object.  In
-this case, it is @code{#t}, the boolean True value.
-
-If the @var{context} argument is left out, then the current bottom-most
-context (typically @code{ChordNames}, @code{Voice}, or
-@code{Lyrics}) is used.  In this example,
+If the @var{context} argument is left out, then the property will be
+set in the current bottom context (typically @code{ChordNames},
+@code{Voice}, @code{TabVoice}, or @code{Lyrics}).
 
 @lilypond[quote,verbatim,relative=2,fragment]
-c8 c c c
-\set autoBeaming = ##f
-c8 c c c
+\set Score.autoBeaming = ##f
+<<
+  {
+    e8 e e e
+    \set autoBeaming = ##t
+    e8 e e e
+  } \\ {
+    c8 c c c c8 c c c
+  }
+>>
 @end lilypond
 
-@noindent
-the @var{context} argument to @code{\set} is left out, so automatic
-beaming is switched off in the current @rinternals{Voice}.  Note that
-the bottom-most context does not always contain the property that you
-wish to change -- for example, attempting to set the @code{skipBars}
-property (of the bottom-most context, in this case @code{Voice}) will
-have no effect.
+The change is applied @q{on-the-fly}, during the music, so that the
+setting only affects the second group of eighth notes.
+
+Note that the bottom-most context does not always contain the property
+that you wish to change -- for example, attempting to set the
+@code{skipBars} property of the default bottom context, in this case
+@code{Voice}, will have no effect, because skipBars is a property of
+the @code{Score} context.
 
 @lilypond[quote,verbatim,relative=2,fragment]
 R1*2
@@ -1483,43 +1535,38 @@ R1*2
 R1*2
 @end lilypond
 
-Contexts are hierarchical, so if a bigger context was specified, for
+Contexts are hierarchical, so if an enclosing context was specified, for
 example @code{Staff}, then the change would also apply to all
-@code{Voice}s in the current stave.  The change is applied
-@q{on-the-fly}, during the music, so that the setting only affects the
-second group of eighth notes.
+@code{Voice}s in the current staff.
 
 @funindex \unset
 
-There is also an @code{\unset} command,
-@example
-\unset @var{context}.@var{prop}
-@end example
-
-@noindent
-which removes the definition of @var{prop}.  This command removes
-the definition only if it is set in @var{context}, so
+The @code{\unset} command:
 
 @example
-\set Staff.autoBeaming = ##f
+\unset @var{context}.@var{property}
 @end example
 
 @noindent
-introduces a property setting at @code{Staff} level.  The setting also
-applies to the current @code{Voice}.  However,
-
-@example
-\unset Voice.autoBeaming
-@end example
+is used to remove the definition of @var{property} from
+@var{context}.  This command removes
+the definition only if it is set in @var{context}.
+Properties that have been set in enclosing contexts will
+not be altered by an unset in an enclosed context:
 
-@noindent
-does not have any effect.  To cancel this setting, the @code{\unset}
-must be specified on the same level as the original @code{\set}.  In
-other words, undoing the effect of @code{Staff.autoBeaming = ##f}
-requires
-@example
-\unset Staff.autoBeaming
-@end example
+@lilypond[quote,verbatim,relative=2,fragment]
+\set Score.autoBeaming = ##t
+<<
+  {
+    \unset autoBeaming
+    e8 e e e
+    \unset Score.autoBeaming
+    e8 e e e
+  } \\ {
+    c8 c c c c8 c c c
+  }
+>>
+@end lilypond
 
 Like @code{\set}, the @var{context} argument does not have to be
 specified for a bottom context, so the two statements
@@ -1530,12 +1577,12 @@ specified for a bottom context, so the two statements
 @end example
 
 @noindent
-are equivalent.
+are equivalent if the current bottom context is @code{Voice}.
 
 
 @cindex \once
-Settings that should only apply to a single time-step can be entered
-with @code{\once}, for example in
+Preceding a @code{\set} command by @code{\once} makes the
+setting apply to only a single time-step:
 
 @lilypond[quote,verbatim,relative=2,fragment]
 c4
@@ -1544,11 +1591,8 @@ c4
 c4
 @end lilypond
 
-the property @code{fontSize} is unset automatically after the second
-note.
-
 A full description of all available context properties is in the
-program reference, see
+internals reference, see
 @ifhtml
 @rinternals{Tunable context properties}.
 @end ifhtml
@@ -1556,11 +1600,135 @@ program reference, see
 Translation @expansion{} Tunable context properties.
 @end ifnothtml
 
+@seealso
+
+Internals Reference:
+
+@rinternals{Tunable context properties}.
+
+
+@cindex grob properties
+@cindex properties, grob
+@funindex \override
 
 
 @node The override command
 @subsection The @code{\override} command
 
+There is a special type of context property: the grob
+description.  Grob descriptions are named in @code{StudlyCaps}
+(starting with capital letters).  They contain the
+@q{default settings} for a particular kind of grob as an
+association list.  See @file{scm/@/define@/-grobs@/.scm}
+to see the settings for each grob description.  Grob descriptions
+are modified with @code{\override}.
+
+@code{\override} is actually a shorthand;
+
+@example
+\override @var{context}.@var{GrobName} #'@var{property} = #@var{value}
+@end example
+
+@noindent
+is more or less equivalent to
+
+@c  leave this long line -gp
+@example
+\set @var{context}.@var{GrobName}  =
+  #(cons (cons '@var{property} @var{value})
+         <previous value of @var{context}.@var{GrobName}>)
+@end example
+
+The value of @code{context}.@code{GrobName} (the alist) is used to initialize
+the properties of individual grobs.  Grobs have
+properties, named in Scheme style, with
+@code{dashed-words}.  The values of grob properties change
+during the formatting process: formatting basically amounts
+to computing properties using callback functions.
+
+For example, we can increase the thickness of a note stem by
+overriding the @code{thickness} property of the @code{Stem}
+object:
+
+@lilypond[quote, verbatim, relative=2, fragment]
+c4 c
+\override Voice.Stem #'thickness = #3.0
+c4 c
+@end lilypond
+
+If no context is specified in an @code{\override}, the bottom
+context is used:
+
+@lilypond[quote, verbatim, relative=2, fragment]
+{ \override Staff.Stem #'thickness = #3.0
+  <<
+    {
+      e4 e
+      \override Stem #'thickness = #0.5
+      e4 e
+    } \\ {
+      c4 c c c
+    }
+  >>
+}
+@end lilypond
+
+@funindex \revert
+@cindex reverting overrides
+@cindex overrides, reverting
+
+The effects of @code{\override} can be undone by @code{\revert}:
+
+@lilypond[quote, verbatim, relative=2, fragment]
+c4
+\override Voice.Stem #'thickness = #3.0
+c4 c
+\revert Voice.Stem #'thickness
+c4
+@end lilypond
+
+The effects of @code{\override} and @code{\revert} apply to all
+grobs in the affected context from the current time forward:
+
+@lilypond[quote, verbatim, relative=2, fragment]
+{
+  <<
+    {
+      e4
+      \override Staff.Stem #'thickness = #3.0
+      e4 e e
+    } \\ {
+      c4 c c
+      \revert Staff.Stem #'thickness
+      c4
+    }
+  >>
+}
+@end lilypond
+
+@funindex \once
+@cindex overriding for only one moment
+
+@code{\once} can be used with @code{\override}
+to affect only the current time step:
+
+@lilypond[quote, verbatim, relative=2, fragment]
+{
+  <<
+    {
+      \override Stem #'thickness = #3.0
+      e4 e e e
+    } \\ {
+      c4
+      \once \override Stem #'thickness = #3.0
+      c4 c c
+    }
+  >>
+}
+@end lilypond
+
+
+@ignore
 Commands which change output generally look like
 
 @example
@@ -1598,7 +1766,12 @@ turning off grob properties which may otherwise be causing problems.
 
 We demonstrate how to glean this information from the notation manual
 and the program reference.
+@end ignore
+
+@seealso
 
+Internals Reference:
+@rinternals{Backend}
 
 @node The tweak command
 @subsection The @code{\tweak} command
@@ -1606,12 +1779,28 @@ and the program reference.
 @funindex \tweak
 @cindex tweaking
 
+Changing grob properties
+with @code{\override} causes the changes to apply to all of the
+given grobs in the context at the moment the change applies.
+Sometimes, however, it is desirable to have changes apply to just
+one grob, rather than to all grobs in the affected context.  This is
+accomplished with the @code{\tweak} command, which has the following
+syntax:
+
+@example
+\tweak #'@code{grob-property} #@code{value}
+@end example
+
+The @code{\tweak} command applies to the object that immediately
+follows @code{value} in the music stream.
+
+@ignore
 In some cases, it is possible to take a short-cut for tuning
 graphical objects.  For objects that are created directly from
 an item in the input file, you can use the @code{\tweak} command.
 For example:
 
-@lilypond[relative=2,verbatim]
+@lilypond[relative=2,verbatim,quote]
 < c
   \tweak #'color #red
   d
@@ -1623,16 +1812,13 @@ For example:
 -^
 @end lilypond
 
-@cindex chord, modifying one note in
+
 
 But the main use of the @code{\tweak} command is to modify just
 one of a number of notation elements which start at the same musical
 moment, like the notes of a chord, or tuplet brackets which start
 at the same time.
 
-For an introduction to the syntax and uses of the tweak command
-see @rlearning{Tweaking methods}.
-
 The @code{\tweak} command sets a property in the following object
 directly, without requiring the grob name or context to be
 specified.  For this to work, it is necessary for the @code{\tweak}
@@ -1660,6 +1846,11 @@ but this does not:
 \tweak #'color #red c4
 @end lilypond
 
+@end ignore
+
+For an introduction to the syntax and uses of the tweak command
+see @rlearning{Tweaking methods}.
+
 When several similar items are placed at the same musical moment,
 the @code{\override} command cannot be used to modify just one of
 them -- this is where the @code{\tweak} command must be used.
@@ -1676,29 +1867,53 @@ include the following:
 
 @c TODO add examples of these
 
-@noindent
-and @code{\tweak} may be used to modify any single occurrence of
-these items.
+@cindex chord, modifying one note in
 
-Notably the @code{\tweak} command cannot be used to modify stems,
-beams or accidentals directly, since these are generated later by
-note heads, rather than by music elements in the input stream.
-Nor can a @code{\tweak} command be used to modify clefs or time
-signatures, since these become separated from any preceding
-@code{\tweak} command in the input stream by the automatic
-insertion of extra elements required to specify the context.
+In this example, the color of one note head and the type of another
+note head are modified within a single chord:
 
-But the @code{\tweak} command can be used as an alternative to
-the @code{\override} command to modify those notational elements
-that do not cause any additional implicit elements to be added
-before them in the music stream.  For example, slurs may be
-modified in this way:
+@lilypond[relative=2,verbatim,quote]
+< c
+  \tweak #'color #red
+  d
+  g
+  \tweak #'duration-log #1
+  a
+> 4
+@end lilypond
+
+@code{\tweak} can be used to modify slurs:
 
 @lilypond[verbatim,quote,relative=1]
 c-\tweak #'thickness #5 ( d e f)
 @end lilypond
 
-Also several @code{\tweak} commands may be placed before a
+
+For the @code{\tweak} command to work, it must
+remain immediately adjacent to the object to which it is
+to apply after the input file has been converted to a music stream.
+At times, LilyPond may insert additional items into the music stream
+during the parsing process.  For example, when a note that is not
+explicitly part of a chord will be placed in a chord by LilyPond,
+so notes to be modified with @code{\tweak} must be placed inside
+a chord construct:
+
+@lilypond[relative=2,verbatim,quote]
+\tweak #'color #red c4
+<\tweak #'color #red c>4
+@end lilypond
+
+The @code{\tweak} command cannot be used to modify any item
+that does not appear explicitly in the input file.  In particular
+it cannot be used to modify stems,
+beams or accidentals directly, since these are generated later by
+note heads, rather than by music elements in the input stream.
+Nor can @code{\tweak} be used to modify clefs or time
+signatures, since these become separated from any preceding
+@code{\tweak} command in the input stream by the automatic
+insertion of extra elements required to specify the context.
+
+Several @code{\tweak} commands may be placed before a
 notational element -- all affect it:
 
 @lilypond[verbatim,quote,relative=1]
@@ -1713,16 +1928,18 @@ f'
 
 The music stream which is generated from a section of an input file,
 including any automatically inserted elements, may be examined,
-see @ref{Displaying music expressions}.  This may be helpful in
-determining what may be modified by a @code{\tweak} command.
+see @rextend{Displaying music expressions}.  This may be helpful in
+determining what may be modified by a @code{\tweak} command, or
+in determining how to adjust the input to make a @code{\tweak}
+apply.
 
 
 @seealso
 Learning Manual:
 @rlearning{Tweaking methods}.
 
-Notation Reference:
-@ref{Displaying music expressions}.
+Extending:
+@rextend{Displaying music expressions}.
 
 
 @knownissues
@@ -1736,60 +1953,25 @@ The @code{\tweak} commands cannot be used in @code{\lyricmode}.
 @cindex tweaking control points
 @cindex control points, tweaking
 
-The @code{\tweak} command cannot be used to modify the control
-points of just one of several ties in a chord, other than the first
-one encountered in the input file.
+The @code{\tweak} command will apply to only the first of several
+generated ties in a chord.
 
 @node set versus override
 @subsection @code{\set} vs. @code{\override}
 
+TODO -- This section is probably unnecessary now.
+
+@ignore
 We have seen two methods of changing properties: @code{\set} and
 @code{\override}.  There are actually two different kinds of
 properties.
 
-Contexts can have properties, which are usually named in
-@code{studlyCaps}.  They mostly control the translation from
-music to notation, eg. @code{localKeySignature} (for determining
-whether to print accidentals), @code{measurePosition} (for
-determining when to print a bar line).  Context properties can
-change value over time while interpreting a piece of music;
-@code{measurePosition} is an obvious example of
-this.  Context properties are modified with @code{\set}.
-
-There is a special type of context property: the element
-description.  These properties are named in @code{StudlyCaps}
-(starting with capital letters).  They contain the
-@q{default settings} for said graphical object as an
-association list.  See @file{scm/@/define@/-grobs@/.scm}
-to see what kind of settings there are.  Element descriptions
-may be modified with @code{\override}.
-
-@code{\override} is actually a shorthand;
-
-@example
-\override @var{context}.@var{name} #'@var{property} = #@var{value}
-@end example
-
-@noindent
-is more or less equivalent to
-
-@c  leave this long line -gp
-@example
-\set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
-@end example
-
-The value of @code{context} (the alist) is used to initialize
-the properties of individual grobs.  Grobs also have
-properties, named in Scheme style, with
-@code{dashed-words}.  The values of grob properties change
-during the formatting process: formatting basically amounts
-to computing properties using callback functions.
-
 @code{fontSize} is a special property: it is equivalent to
 entering @code{\override ... #'font-size} for all pertinent
 objects.  Since this is a common change, the special
 property (modified with @code{\set}) was created.
 
+@end ignore
 
 @node Useful concepts and properties
 @section Useful concepts and properties
@@ -2026,8 +2208,8 @@ The default order in which contexts are laid out and the
 @qq{accepts} list can be changed, see @ref{Aligning contexts}.
 
 @seealso
-Learning Manual:
-@rlearning{An extra staff appears}.
+Usage Manual:
+@rprogram{An extra staff appears}.
 
 
 @node Distances and measurements
@@ -2797,7 +2979,7 @@ The locations of the end-points of the spanner are computed
 on-the-fly for every graphic object, but it is possible to
 override these:
 
-@c FIXME Complete
+@c TODO Complete
 @lilypond[relative=2,ragged-right,verbatim,fragment]
 e2 \glissando f
 \once \override Glissando #'(bound-details right Y) = #-2
@@ -2897,8 +3079,7 @@ Learning Manual:
 
 Notation Reference:
 @ref{Explaining the Internals Reference},
-@ref{Modifying properties},
-@ref{Interfaces for programmers}.
+@ref{Modifying properties}.
 
 Installed Files:
 @file{scm/@/define@/-grobs@/.scm}.
@@ -2906,6 +3087,9 @@ Installed Files:
 Snippets:
 @rlsr{Tweaks and overrides}.
 
+Extending:
+@rextend{Interfaces for programmers}.
+
 Internals Reference:
 @rinternals{All layout objects}.
 
@@ -3227,7 +3411,7 @@ e
 @node Vertical grouping of grobs
 @subsection Vertical grouping of grobs
 
-@c FIXME Expand this section
+@c TODO Expand this section
 
 The VerticalAlignment and VerticalAxisGroup grobs work together.
 VerticalAxisGroup groups together different grobs like Staff, Lyrics,
@@ -3376,8 +3560,169 @@ to which the start of the tie (or slur) is attached.
 It is not possible to modify shapes of ties or slurs by changing
 the @code{control-points} property if there are more than one at
 the same musical moment, not even by using the @code{\tweak}
-command.
+command.  However, the @code{tie-configuration} property of
+@code{TieColumn} can be overridden to set start line and direction
+of ties as required.
+
+
+
+
+@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 complete list of defined variable
+types is found in the @var{type-p-name-alist} entry of
+@file{scm/lily.scm}.
 
+@c TODO -- find an automatic way of documenting the type-p-name-alist
 
+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