Doc: standardise level 5 headings (2730)

[lilypond.git] / Documentation / notation / changing-defaults.itely

diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
index 68aa8b8c4943a78b3d9a247d26679f991cc8d8b1..edf8a3f262cd312cecf1279a9ca03df4d2df5292 100644 (file)
--- a/Documentation/notation/changing-defaults.itely
+++ b/Documentation/notation/changing-defaults.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     Guide, node Updating translation committishes..
 @end ignore
 

-@c \version "2.15.20"
+@c \version "2.15.39"

 
 @node Changing defaults
 @chapter Changing defaults
 
 @node Changing defaults
 @chapter Changing defaults


@@ -30,7 +30,7 @@ Reference}.  That manual lists all the variables, functions and
 options available in LilyPond.  It is written as a HTML document,
 which is available
 @c leave the @uref as one long line.
 options available in LilyPond.  It is written as a HTML document,
 which is available
 @c leave the @uref as one long line.

-@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
+@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/internals/,on@/-line},

 and is also included with the LilyPond documentation package.
 
 Internally, LilyPond uses Scheme (a LISP dialect) to provide
 and is also included with the LilyPond documentation package.
 
 Internally, LilyPond uses Scheme (a LISP dialect) to provide


@@ -67,7 +67,6 @@ This section describes what contexts are, and how to modify them.
 * Context layout order::
 @end menu
 
 * Context layout order::
 @end menu
 

-

 @seealso
 Learning Manual:
 @rlearning{Contexts and engravers}.
 @seealso
 Learning Manual:
 @rlearning{Contexts and engravers}.


@@ -565,12 +564,11 @@ words = \lyricmode { These words fol -- low the mel -- o -- dy }
 
 @c TODO Should this be Modifying engravers or Modifying contexts?
 
 
 @c TODO Should this be Modifying engravers or Modifying contexts?
 

-Notation contexts (like @code{Score} and @code{Staff}) not only
-store properties,
-they also contain plug-ins called @q{engravers} that create notation
-elements.  For example, the @code{Voice} context contains a
+Notation contexts (like @code{Score} and @code{Staff}) not only store
+properties, they also contain plug-ins called @q{engravers} that create
+notation elements.  For example, the @code{Voice} context contains a

 @code{Note_heads_engraver} and the @code{Staff} context contains a
 @code{Note_heads_engraver} and the @code{Staff} context contains a

-@code{Key_signature_engraver}.
+@code{Key_engraver}.

 
 For a full a description of each plug-in, see
 @ifhtml
 
 For a full a description of each plug-in, see
 @ifhtml


@@ -674,98 +672,335 @@ time signature.
 
 @knownissues
 
 
 @knownissues
 

-Usually the order in which the engravers are specified
-does not matter, but in a few special cases the order
-is important, for example where one engraver writes
-a property and another reads it, or where one engraver
-creates a grob and another must process it.  The order in
-which the engravers are specified is the order in which
-they are called to carry out their processing.
+The order in which the engravers are specified is the order in
+which they are called to carry out their processing.  Usually the
+order in which the engravers are specified does not matter, but in
+a few special cases the order is important, for example where one
+engraver writes a property and another reads it, or where one
+engraver creates a grob and another must process it.
+
+The following orderings are important:
+
+@itemize
+@item
+the @code{Bar_engraver} must normally be first,
+
+@item
+the @code{New_fingering_engraver} must come before the
+@code{Script_column_engraver},
+
+@item
+the @code{Timing_translator} must come before the
+@code{Bar_number_engraver}.
+
+@end itemize
+
+@seealso
+Installed Files:
+@file{ly/engraver-init.ly}.

 
 

-The following orderings are important: the
-@code{Bar_engraver} must normally be first, and
-the @code{New_fingering_engraver} must come before
-the @code{Script_column_engraver}.  There may be others
-with ordering dependencies.

 
 @node Changing context default settings
 @subsection Changing context default settings
 
 
 @node Changing context default settings
 @subsection Changing context default settings
 

+@cindex default context properties, changing
+@cindex context properties, changing defaults
+
+Context and grob properties can be changed with @code{\set}
+and @code{\override} commands, as described in
+@ref{Modifying properties}.  These commands create music events,
+making the changes take effect at the point in time the music
+is being processed.
+
+In contrast, this section explains how to change the @emph{default}
+values of context and grob properties at the time the context is
+created.  There are two ways of doing this.  One modifies the default
+values in all contexts of a particular type, the other modifies the
+default values in just one particular instance of a context.
+
+@menu
+* Changing all contexts of the same type::
+* Changing just one specific context::
+* Order of precedence::
+@end menu
+
+@node Changing all contexts of the same type
+@unnumberedsubsubsec Changing all contexts of the same type
+
+@cindex \context in \layout block
+@funindex \context
+@funindex \layout
+

 The context settings which are to be used by default in
 The context settings which are to be used by default in

-@code{Score}, @code{Staff} and @code{Voice} contexts may be specified
-in a @code{\layout} block, as illustrated in the following example.
+@code{Score}, @code{Staff}, @code{Voice} and other contexts may be
+specified in a @code{\context} block within any @code{\layout} block.

 The @code{\layout} block should be placed within the @code{\score}
 The @code{\layout} block should be placed within the @code{\score}

-block to which it is to apply, but outside any music.
+block to which it is to apply, after the music.

 
 

-Note that the @code{\set} command itself and the context must be
-omitted when the context default values are specified in this way:
+@example
+\layout @{
+  \context @{
+    \Voice
+    [context settings for all Voice contexts]
+  @}
+  \context @{
+    \Staff
+    [context settings for all Staff contexts]
+  @}
+@}
+@end example
+
+The following types of settings may be specified:
+
+@itemize
+@item
+An @code{\override} command, but with the context name omitted

 
 @lilypond[quote,verbatim]
 \score {
   \relative c'' {
 
 @lilypond[quote,verbatim]
 \score {
   \relative c'' {

-    a4^"Really small, thicker stems, no time signature" a a a
-    a a a a
+    a4^"Thicker stems" a a a
+    a4 a a\ff a

   }
   \layout {
     \context {
       \Staff
   }
   \layout {
     \context {
       \Staff

-      fontSize = #-4

       \override Stem #'thickness = #4.0
       \override Stem #'thickness = #4.0

-      \remove "Time_signature_engraver"

     }
   }
 }
 @end lilypond
 
     }
   }
 }
 @end lilypond
 

-In this example, the @code{\Staff} command specifies that the
-subsequent specifications are to be applied to all staves within
-this score block.
-
-Modifications can be made to the @code{Score} context or all
-@code{Voice} contexts in a similar way.
+@item
+Directly setting a context property

 
 

-Context changes can be placed in a variable and applied to a
-@code{\context} definition by prepending the modification with
-@code{\with}:

 @lilypond[quote,verbatim]
 @lilypond[quote,verbatim]

-blubb = \with {
-  fontSize = #-4
-  \override Stem #'thickness = #4.0
-  \remove "Time_signature_engraver"
+\score {
+  \relative c'' {
+    a4^"Smaller font" a a a
+    a4 a a\ff a
+  }
+  \layout {
+    \context {
+      \Staff
+      fontSize = #-4
+    }
+  }

 }
 }

+@end lilypond
+
+@item
+A predefined command such as @code{\dynamicUp} or a music
+expression like @code{\accidentalStyle "dodecaphonic"}

 
 

-bla = \with {
-  fontSize = #3
-  \override Stem #'thickness = #-2.0
+@lilypond[quote,verbatim]
+\score {
+  \relative c'' {
+    a4^"Dynamics above" a a a
+    a4 a a\ff a
+  }
+  \layout {
+    \context {
+      \Voice
+      \dynamicUp
+    }
+    \context {
+      \Staff
+      \accidentalStyle "dodecaphonic"
+    }
+  }

 }
 }

+@end lilypond

 
 

-melody = \relative c'' {
-  a4 a a a |
-  a4 a a a |
+@item
+A user-defined variable containing a @code{\with} block; for details
+of the @code{\with} block see
+@ref{Changing just one specific context}.
+
+@lilypond[quote,verbatim]
+StaffDefaults = \with {
+  fontSize = #-4

 }
 
 \score {
 }
 
 \score {

-  <<
-    \new Staff <<
-      \melody
-      s1*0^"Small, thicker stems, no time signature"
-    >>
-    \new Staff \bla <<
-      \melody
-      s1*0^"Different"
-    >>
-  >>
+  \new Staff {
+    \relative c'' {
+      a4^"Smaller font" a a a
+      a4 a a a
+    }
+  }

   \layout {
     \context {
       \Staff
   \layout {
     \context {
       \Staff

-      \blubb
+      \StaffDefaults
+    }
+  }
+}
+@end lilypond
+
+@end itemize
+
+Property-setting commands can be placed in a @code{\layout} block
+without being enclosed in a @code{\context} block.  Such settings
+are equivalent to including the same property-setting commands at
+the start of every context of the type specified.  If no context
+is specified @emph{every} bottom-level context is affected, see
+@ref{Bottom-level contexts - voices}.  The syntax of a
+property-setting command in a @code{\layout} block is the same as
+the same command written in the music stream.
+
+@lilypond[quote,verbatim]
+\score {
+  \new Staff {
+    \relative c'' {
+      a4^"Smaller font" a a a
+      a4 a a a
+    }
+  }
+  \layout {
+    \accidentalStyle "dodecaphonic"
+    \set fontSize = #-4
+    \override Voice.Stem #'thickness = #4.0
+  }
+}
+@end lilypond
+
+
+@node Changing just one specific context
+@unnumberedsubsubsec Changing just one specific context
+
+@cindex \with
+@funindex \with
+
+The context properties of just one specific context instance can be
+changed in a @code{\with} block.  All other context instances of the
+same type retain the default settings built into LilyPond and modified
+by any @code{\layout} block within scope.  The @code{\with} block
+must be placed immediately after the @code{\new} @var{context-type}
+command:
+
+@example
+\new Staff
+\with @{
+  [context settings for this context instance only]
+@} @{
+...
+@}
+@end example
+
+The following types of settings may be specified:
+
+@itemize
+@item
+An @code{\override} command, but with the context name omitted
+
+@lilypond[quote,verbatim]
+\score {
+  \new Staff {
+    \new Voice
+    \with {
+      \override Stem #'thickness = #4.0
+    }
+    {
+      \relative c'' {
+        a4^"Thick stems" a a a
+        a4 a a a
+      }

     }
   }
 }
 @end lilypond
 
     }
   }
 }
 @end lilypond
 

-@c TODO: add \with in here.
+@item
+Directly setting a context property

 
 

+@lilypond[quote,verbatim]
+\score {
+  <<
+    \new Staff {
+      \relative c'' {
+        a4^"Default font" a a a
+        a4 a a a
+      }
+    }
+    \new Staff
+    \with {
+      fontSize = #-4
+    } {
+      \relative c'' {
+        a4^"Smaller font" a a a
+        a4 a a a
+      }
+    }
+  >>
+}
+@end lilypond
+
+@item
+A predefined command such as @code{\dynamicUp}
+
+@lilypond[quote,verbatim]
+\score {
+  <<
+    \new Staff {
+      \new Voice {
+        \relative c'' {
+          a4^"Dynamics below" a a a
+          a4 a a\ff a
+        }
+      }
+    }
+    \new Staff
+    \with { \accidentalStyle "dodecaphonic" }
+    {
+      \new Voice
+      \with { \dynamicUp }
+      {
+        \relative c'' {
+          a4^"Dynamics above" a a a
+          a4 a a\ff a
+        }
+      }
+    }
+  >>
+}
+@end lilypond
+
+@end itemize
+
+@node Order of precedence
+@unnumberedsubsubsec Order of precedence
+
+The value of a property which applies at a particular time is
+determined as follows:
+
+@itemize
+@item
+if an @code{\override} or @code{\set} command in the input stream is
+in effect that value is used,
+
+@item
+otherwise the default value taken from a @code{\with} statement
+on the context initiation statement is used,
+
+@item
+otherwise the default value taken from the most recent appropriate
+@code{\context} block in the @code{\layout} blocks is used,
+
+@item
+otherwise the LilyPond built-in default is used.
+@end itemize
+
+@seealso
+Learning Manual:
+@rlearning{Modifying context properties}.
+
+Notation Reference:
+@ref{Contexts explained},
+@ref{Bottom-level contexts - voices},
+@ref{The set command},
+@ref{The override command},
+@ref{The \layout block}.

 
 
 @node Defining new contexts
 
 
 @node Defining new contexts


@@ -1009,19 +1244,53 @@ Note that a context will be silently created implicitly if a command
 is encountered when there is no suitable context available to
 contain it.  This can give rise to unexpected new staves or scores.
 
 is encountered when there is no suitable context available to
 contain it.  This can give rise to unexpected new staves or scores.
 

+@cindex alignAboveContext
+@cindex alignBelowContext
+@funindex alignAboveContext
+@funindex alignBelowContext
+
+Sometimes a context is required to exist for just a brief period, a
+good example being the staff context for an ossia.  This is usually
+achieved by introducing the context definition at the appropriate
+place in parallel with corresponding section of the main music.
+By default, the temporary context will be placed below all the
+existing contexts.  To reposition it above the context called
+@qq{main}, it should be defined like this:
+
+@example
+@code{\new Staff \with @{ alignAboveContext = #"main" @} }
+@end example
+
+A similar situation arises when positioning a temporary lyrics
+context within a multi-staved layout such as a @code{ChoirStaff},
+for example, when adding a second verse to a repeated section.
+By default the temporary lyrics context will be placed beneath the
+lower staves.  By defining the temporary lyrics context with
+@code{alignBelowContext} it can be positioned correctly beneath
+the (named) lyrics context containing the first verse.
+
+Examples showing this repositioning of temporary contexts can be
+found elsewhere --- see @rlearning{Nesting music expressions},
+@ref{Modifying single staves} and @ref{Techniques specific to lyrics}.
+

 @seealso
 @seealso

-Usage Manual:
+Learning Manual:
+@rlearning{Nesting music expressions}.
+
+Notation Reference:
+@ref{Modifying single staves},
+@ref{Techniques specific to lyrics}.
+
+Application Usage:

 @rprogram{An extra staff appears}.
 
 Installed Files:
 @file{ly/engraver-init.ly}.
 
 
 @rprogram{An extra staff appears}.
 
 Installed Files:
 @file{ly/engraver-init.ly}.
 
 

-

 @node Explaining the Internals Reference
 @section Explaining the Internals Reference
 
 @node Explaining the Internals Reference
 @section Explaining the Internals Reference
 

-

 @menu
 * Navigating the program reference::
 * Layout interfaces::
 @menu
 * Navigating the program reference::
 * Layout interfaces::


@@ -1474,22 +1743,19 @@ such as
 @end ignore
 
 @seealso
 @end ignore
 
 @seealso

-Internals:
+Internals Reference:

 @rinternals{Backend},
 @rinternals{All layout objects},
 @rinternals{OverrideProperty},
 @rinternals{RevertProperty},
 @rinternals{PropertySet}.
 
 @rinternals{Backend},
 @rinternals{All layout objects},
 @rinternals{OverrideProperty},
 @rinternals{RevertProperty},
 @rinternals{PropertySet}.
 

-

 @knownissues
 @knownissues

-

 The back-end is not very strict in type-checking object properties.
 Cyclic references in Scheme values for properties can cause hangs
 or crashes, or both.
 
 
 The back-end is not very strict in type-checking object properties.
 Cyclic references in Scheme values for properties can cause hangs
 or crashes, or both.
 
 

-

 @node The set command
 @subsection The @code{@bs{}set} command
 
 @node The set command
 @subsection The @code{@bs{}set} command
 


@@ -1624,12 +1890,9 @@ Translation @expansion{} Tunable context properties.
 @end ifnothtml
 
 @seealso
 @end ifnothtml
 
 @seealso

-

 Internals Reference:
 Internals Reference:

-

 @rinternals{Tunable context properties}.
 
 @rinternals{Tunable context properties}.
 

-

 @cindex grob properties
 @cindex properties, grob
 @funindex \override
 @cindex grob properties
 @cindex properties, grob
 @funindex \override


@@ -1792,10 +2055,10 @@ and the program reference.
 @end ignore
 
 @seealso
 @end ignore
 
 @seealso

-

 Internals Reference:
 @rinternals{Backend}
 
 Internals Reference:
 @rinternals{Backend}
 

+

 @node The tweak command
 @subsection The @code{\tweak} command
 
 @node The tweak command
 @subsection The @code{\tweak} command
 


@@ -1811,11 +2074,12 @@ accomplished with the @code{\tweak} command, which has the following
 syntax:
 
 @example
 syntax:
 
 @example

-\tweak #'@code{grob-property} #@code{value}
+\tweak @var{layout-object} #'@var{grob-property} @var{value}

 @end example
 
 @end example
 

-The @code{\tweak} command applies to the object that immediately
-follows @code{value} in the music stream.
+Specifying @var{layout-object} is optional.
+The @code{\tweak} command applies to the music object that immediately
+follows @var{value} in the music stream.

 
 @ignore
 In some cases, it is possible to take a short-cut for tuning
 
 @ignore
 In some cases, it is possible to take a short-cut for tuning


@@ -1915,23 +2179,33 @@ c-\tweak #'thickness #5 ( d e f)
 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.
 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:
+Tweaking a whole chord does not do anything since its music event
+only acts as a container, and all layout objects are created from events
+inside of the @code{EventChord}:

 
 @lilypond[relative=2,verbatim,quote]
 \tweak #'color #red c4
 
 @lilypond[relative=2,verbatim,quote]
 \tweak #'color #red c4

-<\tweak #'color #red c>4
+\tweak #'color #red <c e>4
+<\tweak #'color #red c e>4

 @end lilypond
 
 @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
+The simple @code{\tweak} command cannot be used to modify any object
+that is not directly created from the input.  In particular
+it will not affect stems, automatic
+beams or accidentals, since these are generated later by
+@code{NoteHead} layout objects rather than by music elements in the
+input stream.
+
+Such indirectly created layout objects can be tweaked using the explicit
+form of the @code{\tweak} command:
+
+@lilypond[relative=2,verbatim,quote]
+\tweak Stem #'color #red
+\tweak Beam #'color #green c8 e
+<c e \tweak Accidental #'font-size #-3 ges>4
+@end lilypond
+
+@code{\tweak} cannot 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.
 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.


@@ -1956,28 +2230,21 @@ determining what may be modified by a @code{\tweak} command, or
 in determining how to adjust the input to make a @code{\tweak}
 apply.
 
 in determining how to adjust the input to make a @code{\tweak}
 apply.
 

-

 @seealso
 Learning Manual:
 @rlearning{Tweaking methods}.
 
 @seealso
 Learning Manual:
 @rlearning{Tweaking methods}.
 

-Extending:
+Extending LilyPond:

 @rextend{Displaying music expressions}.
 
 @rextend{Displaying music expressions}.
 

-

 @knownissues
 
 @knownissues
 

-@cindex tweaks in a variable
-The @code{\tweak} command cannot be used inside a variable.
-
-@cindex tweaks in lyrics
-The @code{\tweak} commands cannot be used in @code{\lyricmode}.
-

 @cindex tweaking control points
 @cindex control points, tweaking
 
 @cindex tweaking control points
 @cindex control points, tweaking
 

-The @code{\tweak} command will apply to only the first of several
-generated ties in a chord.
+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.

 
 @node set versus override
 @subsection @code{\set} vs. @code{\override}
 
 @node set versus override
 @subsection @code{\set} vs. @code{\override}


@@ -2274,31 +2541,30 @@ c2^( c)
 
 @strong{The direction property}
 
 
 @strong{The direction property}
 

-The position or direction of many layout objects is controlled
-by the @code{direction} property.
+The position or direction of many layout objects is controlled by the
+@code{direction} property.

 
 

-The value of the @code{direction} property may be
-set to @code{1}, meaning @qq{up} or @qq{above}, or to @w{@code{-1}},
-meaning @qq{down} or @qq{below}.  The symbols @code{UP} and
-@code{DOWN} may be used instead of @code{1} and @w{@code{-1}}
-respectively.  The default direction may be specified by setting
-@code{direction} to @code{0} or @code{CENTER}.  Alternatively,
-in many cases predefined commands
-exist to specify the direction.  These are all of the form
+The value of the @code{direction} property may be set to @code{1},
+meaning @qq{up} or @qq{above}, or to @w{@code{-1}}, meaning @qq{down} or
+@qq{below}.  The symbols @code{UP} and @code{DOWN} may be used instead
+of @code{1} and @w{@code{-1}} respectively.  The default direction may
+be specified by setting @code{direction} to @code{0} or @code{CENTER}.
+Alternatively, in many cases predefined commands exist to specify the
+direction.  These are of the form

 
 

-@noindent
-@code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
+@example
+@code{\xxxUp}, @code{\xxxDown} or @code{\xxxNeutral}
+@end example

 
 @noindent
 
 @noindent

-where @code{xxxNeutral} means @qq{use the default direction}.
+where @code{\xxxNeutral} means @qq{use the default} direction.

 See @rlearning{Within-staff objects}.
 
 See @rlearning{Within-staff objects}.
 

-In a few cases, arpeggio being the only common example, the value
-of the @code{direction} property specifies whether the object
-is to be placed to the right or left of the parent object.  In
-this case @w{@code{-1}} or @code{LEFT} means @qq{to the left} and
-@code{1} or @code{RIGHT} means @qq{to the right}.  @code{0}
-or @code{CENTER} means @qq{use the default} direction, as before.
+In a few cases, arpeggio for example, the value of the @code{direction}
+property can specify whether the object is to be placed to the right or
+left of the parent.  In this case @w{@code{-1}} or @code{LEFT} means
+@qq{to the left} and @code{1} or @code{RIGHT} means @qq{to the right}.
+@code{0} or @code{CENTER} means @qq{use the default} direction.

 
 @ignore
 These all have side-axis set to #X
 
 @ignore
 These all have side-axis set to #X


@@ -2309,7 +2575,7 @@ TrillPitchAccidental - not tried
 TrillPitchGroup - not tried
 @end ignore
 
 TrillPitchGroup - not tried
 @end ignore
 

-These indications affect all notes until they are cancelled.
+These indications affect all notes until they are canceled.

 
 @lilypond[verbatim,quote,relative=2]
 c2( c)
 
 @lilypond[verbatim,quote,relative=2]
 c2( c)


@@ -2320,6 +2586,17 @@ c2( c)
 c2( c)
 @end lilypond
 
 c2( c)
 @end lilypond
 

+In polyphonic music, it is generally better to specify an explicit
+@code{voice} than change an object's direction.  For more information.
+See @ref{Multiple voices}.
+
+@seealso
+Learning Manual:
+@rlearning{Within-staff objects}.
+
+Notation Reference:
+@ref{Multiple voices}.
+

 
 @node Distances and measurements
 @subsection Distances and measurements
 
 @node Distances and measurements
 @subsection Distances and measurements


@@ -2369,7 +2646,6 @@ convert from a font size change to the equivalent change in
 @code{staff-space}.  For an explanation and an example of its use,
 see @rlearning{Length and thickness of objects}.
 
 @code{staff-space}.  For an explanation and an example of its use,
 see @rlearning{Length and thickness of objects}.
 

-

 @seealso
 Learning Manual:
 @rlearning{Length and thickness of objects}.
 @seealso
 Learning Manual:
 @rlearning{Length and thickness of objects}.


@@ -2705,7 +2981,6 @@ When using @code{\endSpanners} it is not necessary to close
 \startTextSpan with \stopTextSpan, nor is it necessary to close
 hairpins with @code{\!}.
 
 \startTextSpan with \stopTextSpan, nor is it necessary to close
 hairpins with @code{\!}.
 

-

 @seealso
 Internals Reference:
 @rinternals{TextSpanner},
 @seealso
 Internals Reference:
 @rinternals{TextSpanner},


@@ -2862,7 +3137,7 @@ by pre-defined functions, defined in @file{scm/output-lib.scm},
 where the last three columns indicate whether the layout objects
 will be visible in the positions shown at the head of the columns:
 
 where the last three columns indicate whether the layout objects
 will be visible in the positions shown at the head of the columns:
 

-@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {yes} {yes} {yes}
+@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {Before} {At no} {After}

 @headitem Function                   @tab Vector                  @tab Before @tab At no    @tab After
 @headitem form                       @tab form                    @tab break  @tab break    @tab break
 
 @headitem Function                   @tab Vector                  @tab Before @tab At no    @tab After
 @headitem form                       @tab form                    @tab break  @tab break    @tab break
 


@@ -3047,10 +3322,9 @@ For explicit clef changes, the @code{explicitClefVisibility}
 property controls both the clef symbol and any octavation symbol
 associated with it.
 
 property controls both the clef symbol and any octavation symbol
 associated with it.
 

-

 @seealso
 Learning Manual:
 @seealso
 Learning Manual:

-@rlearning{Visibility and color of objects}
+@rlearning{Visibility and color of objects}.

 
 
 @node Line styles
 
 
 @node Line styles


@@ -3180,7 +3454,6 @@ appearance of the printed score.
 * Unpure-pure containers::
 @end menu
 
 * Unpure-pure containers::
 @end menu
 

-

 @seealso
 Learning Manual:
 @rlearning{Tweaking output},
 @seealso
 Learning Manual:
 @rlearning{Tweaking output},


@@ -3190,15 +3463,15 @@ Notation Reference:
 @ref{Explaining the Internals Reference},
 @ref{Modifying properties}.
 
 @ref{Explaining the Internals Reference},
 @ref{Modifying properties}.
 

+Extending LilyPond:
+@rextend{Interfaces for programmers}.
+

 Installed Files:
 @file{scm/define-grobs.scm}.
 
 Snippets:
 @rlsr{Tweaks and overrides}.
 
 Installed Files:
 @file{scm/define-grobs.scm}.
 
 Snippets:
 @rlsr{Tweaks and overrides}.
 

-Extending:
-@rextend{Interfaces for programmers}.
-

 Internals Reference:
 @rinternals{All layout objects}.
 
 Internals Reference:
 @rinternals{All layout objects}.
 


@@ -3243,7 +3516,10 @@ are special properties to be found in the @code{break-aligned-interface}
 for positioning rehearsal marks on such objects.
 
 @seealso
 for positioning rehearsal marks on such objects.
 
 @seealso

-@ref{Using the break-alignable-interface},
+Notation Reference:
+@ref{Using the break-alignable-interface}.
+
+Extending LilyPond:

 @rextend{Callback functions}.
 
 @menu
 @rextend{Callback functions}.
 
 @menu


@@ -3593,7 +3869,6 @@ Any of the glyphs in the feta Font can be supplied to the
 
 @c TODO Add inserting Postscript or ref to later
 
 
 @c TODO Add inserting Postscript or ref to later
 

-

 @seealso
 Notation Reference:
 @ref{Graphic notation inside markup},
 @seealso
 Notation Reference:
 @ref{Graphic notation inside markup},


@@ -3698,6 +3973,7 @@ Internals Reference:
 @cindex unpure containers, Scheme
 @cindex horizontal spacing, overriding
 
 @cindex unpure containers, Scheme
 @cindex horizontal spacing, overriding
 

+

 @node Unpure-pure containers
 @subsection Unpure-pure containers
 
 @node Unpure-pure containers
 @subsection Unpure-pure containers
 


@@ -3707,12 +3983,12 @@ Scheme function instead of a literal (i.e. a number or pair).
 
 For certain grobs, the @code{Y-extent} is based on the @code{stencil}
 property, overriding the stencil property of one of these will
 
 For certain grobs, the @code{Y-extent} is based on the @code{stencil}
 property, overriding the stencil property of one of these will

-require and additional @code{Y-extent} override with an unpure-pure
+require an additional @code{Y-extent} override with an unpure-pure

 container.  When a function overrides a @code{Y-offset} and/or
 @code{Y-extent} it is assumed that this will trigger line breaking
 calculations too early during compilation.  So the function is not
 container.  When a function overrides a @code{Y-offset} and/or
 @code{Y-extent} it is assumed that this will trigger line breaking
 calculations too early during compilation.  So the function is not

-evaluated at all (usually returning a value of @var{0} or
-@var{'(0 . 0)}) which can result in collisions.  A @q{pure} function
+evaluated at all (usually returning a value of @samp{0} or
+@samp{'(0 . 0)}) which can result in collisions.  A @q{pure} function

 will not affect properties, objects or grob suicides and therefore will
 always have its Y-axis-related evaluated correctly.
 
 will not affect properties, objects or grob suicides and therefore will
 always have its Y-axis-related evaluated correctly.
 


@@ -3733,7 +4009,7 @@ An unpure-pure container is constructed as follows;
 
 where @code{f0} is a function taking @var{n} arguments (@var{n >= 1})
 and the first argument must always be the grob.  This is the function
 
 where @code{f0} is a function taking @var{n} arguments (@var{n >= 1})
 and the first argument must always be the grob.  This is the function

-that gives the actual result.  @var{f1} is the function being labelled
+that gives the actual result.  @var{f1} is the function being labeled

 as @q{pure} that takes @var{n + 2} arguments.  Again, the first argument
 must always still be the grob but the second and third are @q{start}
 and @q{end} arguments.
 as @q{pure} that takes @var{n + 2} arguments.  Again, the first argument
 must always still be the grob but the second and third are @q{start}
 and @q{end} arguments.


@@ -3791,7 +4067,7 @@ Usually for simple calculations nearly-identical functions for both the
 @q{unpure} and @q{pure} parts can be used, by only changing the number
 of arguments passed to, and the scope of, the function.
 
 @q{unpure} and @q{pure} parts can be used, by only changing the number
 of arguments passed to, and the scope of, the function.
 

-@warning{If a function is labelled as @q{pure} and it turns out not to
+@warning{If a function is labeled as @q{pure} and it turns out not to

 be, the results can be unexpected.}
 
 
 be, the results can be unexpected.}
 
 


@@ -3842,7 +4118,8 @@ must return @code{#t}.
 @item @code{@var{@dots{}music@dots{}}}
 @tab normal LilyPond input, using @code{$} (in places where only
 Lilypond constructs are allowed) or @code{#} (to use it as a Scheme
 @item @code{@var{@dots{}music@dots{}}}
 @tab normal LilyPond input, using @code{$} (in places where only
 Lilypond constructs are allowed) or @code{#} (to use it as a Scheme

-value or music function argument) to reference arguments
+value or music function argument or music inside of music lists) to
+reference arguments

 (eg. @samp{#arg1}).
 @end multitable
 
 (eg. @samp{#arg1}).
 @end multitable
 


@@ -3872,13 +4149,11 @@ For a list of available type predicates, see
 @ref{Predefined type predicates}.  User-defined type predicates
 are also allowed.
 
 @ref{Predefined type predicates}.  User-defined type predicates
 are also allowed.
 

-

 @seealso
 @seealso

-

 Notation Reference:
 @ref{Predefined type predicates}.
 
 Notation Reference:
 @ref{Predefined type predicates}.
 

-Extending:
+Extending Lilypond:

 @rextend{Music functions}.
 
 Installed Files:
 @rextend{Music functions}.
 
 Installed Files:


@@ -3918,20 +4193,17 @@ padText =
 In addition to numbers, we can use music expressions such
 as notes for arguments to music functions:
 
 In addition to numbers, we can use music expressions such
 as notes for arguments to music functions:
 

-@c TODO: use a better example (the music argument is redundant).
-

 @lilypond[quote,verbatim,ragged-right]
 custosNote =
 #(define-music-function
      (parser location note)
      (ly:music?)
    #{
 @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
+     \tweak NoteHead #'stencil #ly:text-interface::print
+     \tweak NoteHead #'text
+        \markup \musicglyph #"custodes.mensural.u0"
+     \tweak Stem #'stencil ##f
+     #note

    #})
 
 \relative c' { c4 d e f \custosNote g }
    #})
 
 \relative c' { c4 d e f \custosNote g }


@@ -3943,7 +4215,7 @@ Substitution functions with multiple arguments can be defined:
 tempoPadded =
 #(define-music-function
      (parser location padding tempotext)
 tempoPadded =
 #(define-music-function
      (parser location padding tempotext)

-     (number? string?)
+     (number? markup?)

    #{
      \once \override Score.MetronomeMark #'padding = #padding
      \tempo \markup { \bold #tempotext }
    #{
      \once \override Score.MetronomeMark #'padding = #padding
      \tempo \markup { \bold #tempotext }


@@ -3952,7 +4224,7 @@ tempoPadded =
 \relative c'' {
   \tempo \markup { "Low tempo" }
   c4 d e f g1
 \relative c'' {
   \tempo \markup { "Low tempo" }
   c4 d e f g1

-  \tempoPadded #4.0 #"High tempo"
+  \tempoPadded #4.0 "High tempo"

   g4 f e d c1
 }
 @end lilypond
   g4 f e d c1
 }
 @end lilypond