Merge branch 'lilypond/translation'

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

diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
index e8a5ad20f167e203831f85dff8abf56d48d82b50..6c4e96aadfd36c427bee129ab8b35be4bc8fc48f 100644 (file)
--- a/Documentation/notation/changing-defaults.itely
+++ b/Documentation/notation/changing-defaults.itely
@@ -4,7 +4,8 @@
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the
     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"
 @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
 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.}
 
 
 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::
 * Modifying properties::
 * Useful concepts and properties::
 * Advanced tweaks::

+* Using music functions::

 @end menu
 
 
 @end menu
 
 


@@ -121,8 +123,8 @@ Contexts are arranged hierarchically:
 @node Score - the master of all contexts
 @unnumberedsubsubsec Score - the master of all contexts
 
 @node Score - the master of all contexts
 @unnumberedsubsubsec Score - the master of all contexts
 

-This is the top level notation context. No other context can
-contain a Score context. By default the Score context handles
+This is the top level notation context.  No other context can
+contain a Score context.  By default the Score context handles

 the administration of time signatures and makes sure that items
 such as clefs, time signatures, and key-signatures are aligned
 across staves.
 the administration of time signatures and makes sure that items
 such as clefs, time signatures, and key-signatures are aligned
 across staves.


@@ -138,7 +140,7 @@ executed.
 @strong{@emph{StaffGroup}}
 
 Groups staves while adding a bracket on the left side, grouping
 @strong{@emph{StaffGroup}}
 
 Groups staves while adding a bracket on the left side, grouping

-the staves together. The bar lines of the contained staves are
+the staves together.  The bar lines of the contained staves are

 connected vertically.  @code{StaffGroup} only consists of a collection
 of staves, with a bracket in front and spanning bar lines.
 
 connected vertically.  @code{StaffGroup} only consists of a collection
 of staves, with a bracket in front and spanning bar lines.
 


@@ -233,6 +235,12 @@ input entered in @code{\figuremode} mode.
 The voice context used within a @code{TabStaff} context.  Usually
 left to be created implicitly.
 
 The voice context used within a @code{TabStaff} context.  Usually
 left to be created implicitly.
 

+@strong{@emph{CueVoice}}
+
+A voice context used to render notes of a reduced size, intended
+primarily for adding cue notes to a staff, see @ref{Formatting
+cue notes}.  Usually left to be created implicitly.
+

 @strong{@emph{ChordNames}}
 
 Typesets chord names.
 @strong{@emph{ChordNames}}
 
 Typesets chord names.


@@ -253,7 +261,6 @@ documented.
 
     * NoteNames
 
 
     * NoteNames
 

-    * CueVoice Not documented

     * Global
         Hard coded entry point for LilyPond. Cannot be tuned.
     * Devnull
     * Global
         Hard coded entry point for LilyPond. Cannot be tuned.
     * Devnull


@@ -386,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
 
 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
 @code{\context}, it is usually applied to @code{Voice}
 
 @example


@@ -739,6 +746,22 @@ after calling @code{\RemoveEmptyStaffContext}, ie
 @node Defining new contexts
 @subsection Defining new contexts
 
 @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.
 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.


@@ -1277,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:
 
 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)
 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
 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
 CamelCase

-    context properties: lowercaseFollowedByCamelCase
-    engravers:
+@item context properties: lowercaseFollowedByCamelCase
+@item engravers:

 Capitalized_followed_by_lowercase_and_with_underscores
 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?
 LP-specific?

-
+@end itemize

 
 @node Modifying properties
 @section Modifying properties
 
 @node Modifying properties
 @section Modifying properties


@@ -1320,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.
 
 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
 The syntax for this is
 
 @example


@@ -1410,11 +1448,15 @@ such as
 \override Stem #'(details beamed-lengths) = #'(4 4 3)
 @end example
 
 \override Stem #'(details beamed-lengths) = #'(4 4 3)
 @end example
 

+@end ignore

 
 @seealso
 
 @seealso

-Internals: @rinternals{OverrideProperty}, @rinternals{RevertProperty},
-@rinternals{PropertySet}, @rinternals{Backend}, and
-@rinternals{All layout objects}.
+Internals:
+@rinternals{Backend},
+@rinternals{All layout objects},
+@rinternals{OverrideProperty},
+@rinternals{RevertProperty},
+@rinternals{PropertySet}.

 
 
 @knownissues
 
 
 @knownissues


@@ -1426,48 +1468,66 @@ or crashes, or both.
 
 
 @node The set command
 
 
 @node The set command

-@subsection The @code{\set} command
+@subsection The @code{@bs{}set} command

 
 @cindex properties
 @funindex \set
 @cindex changing properties
 
 
 @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
 
 @example

-\set @var{context}.@var{prop} = #@var{value}
+\set @var{context}.@var{property} = #@var{value}

 @end example
 
 @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
 
 @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]
 
 @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
 
 @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
 
 @lilypond[quote,verbatim,relative=2,fragment]
 R1*2


@@ -1475,43 +1535,38 @@ R1*2
 R1*2
 @end lilypond
 
 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
 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
 
 
 @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
 
 @example

-\set Staff.autoBeaming = ##f
+\unset @var{context}.@var{property}

 @end example
 
 @noindent
 @end example
 
 @noindent

-introduces a property setting at @code{Staff} level.  The setting also
-applies to the current @code{Voice}.  However,
+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:

 
 

-@example
-\unset Voice.autoBeaming
-@end example
-
-@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
 
 Like @code{\set}, the @var{context} argument does not have to be
 specified for a bottom context, so the two statements


@@ -1522,12 +1577,12 @@ specified for a bottom context, so the two statements
 @end example
 
 @noindent
 @end example
 
 @noindent

-are equivalent.
+are equivalent if the current bottom context is @code{Voice}.

 
 
 @cindex \once
 
 
 @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
 
 @lilypond[quote,verbatim,relative=2,fragment]
 c4


@@ -1536,11 +1591,8 @@ c4
 c4
 @end lilypond
 
 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
 A full description of all available context properties is in the

-program reference, see
+internals reference, see

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


@@ -1548,11 +1600,135 @@ program reference, see
 Translation @expansion{} Tunable context properties.
 @end ifnothtml
 
 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
 
 
 
 @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
 Commands which change output generally look like
 
 @example


@@ -1590,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.
 
 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
 
 @node The tweak command
 @subsection The @code{\tweak} command


@@ -1598,12 +1779,28 @@ and the program reference.
 @funindex \tweak
 @cindex tweaking
 
 @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:
 
 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
 < c
   \tweak #'color #red
   d


@@ -1615,16 +1812,13 @@ For example:
 -^
 @end lilypond
 
 -^
 @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.
 
 
 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}
 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}


@@ -1652,6 +1846,11 @@ but this does not:
 \tweak #'color #red c4
 @end lilypond
 
 \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.
 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.


@@ -1668,29 +1867,53 @@ include the following:
 
 @c TODO add examples of these
 
 
 @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
 
 
 @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]
 notational element -- all affect it:
 
 @lilypond[verbatim,quote,relative=1]


@@ -1705,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,
 
 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}.
 
 
 
 @seealso
 Learning Manual:
 @rlearning{Tweaking methods}.
 

-Notation Reference:
-@ref{Displaying music expressions}.
+Extending:
+@rextend{Displaying music expressions}.

 
 
 @knownissues
 
 
 @knownissues


@@ -1728,60 +1953,25 @@ 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 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}
 
 
 @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.
 
 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.
 
 @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
 
 @node Useful concepts and properties
 @section Useful concepts and properties


@@ -1790,6 +1980,7 @@ property (modified with @code{\set}) was created.
 @menu
 * Input modes::
 * Direction and placement::
 @menu
 * Input modes::
 * Direction and placement::

+* Context layout order::

 * Distances and measurements::
 * Staff symbol properties::
 * Spanners::
 * Distances and measurements::
 * Staff symbol properties::
 * Spanners::


@@ -1913,7 +2104,7 @@ left, right or center; etc.  Most of these choices may be left to
 be determined automatically by LilyPond, but in some cases it may
 be desirable to force a particular direction or placement.
 
 be determined automatically by LilyPond, but in some cases it may
 be desirable to force a particular direction or placement.
 

-@strong{Default actions}
+@strong{Articulation direction indicators}

 
 By default some directions are always up or always down (e.g.
 dynamics or fermata), while other things can alternate between
 
 By default some directions are always up or always down (e.g.
 dynamics or fermata), while other things can alternate between


@@ -1921,26 +2112,12 @@ up or down based on the stem direction (like slurs or accents).
 
 @c TODO Add table showing these
 
 
 @c TODO Add table showing these
 

-@strong{Context layout order}
-
-Contexts are normally positioned in a system from top to bottom
-in the order in which they are encountered.  Note, however, that
-a context will be created implicitly if a command is encountered
-when there is no suitable context available to contain it.  When
-contexts are nested, the outer context will exclude inner contexts
-which are not included in its @qq{accepts} list; excluded contexts
-will be repositioned below the outer context.
-
-The default order in which contexts are laid out and the
-@qq{accepts} list can be changed, see @ref{Aligning contexts}.
-
-@strong{Articulation direction indicators}
-
-When adding articulations to notes the direction indicator,
-@code{^} (meaning @qq{up}), @code{_} (meaning @qq{down}) or
-@code{-} (meaning @qq{use default direction}), can usually be
-omitted, in which case @code{-} is assumed.  But a direction
-indicator is @strong{always} required before
+The default action may be overridden by prefixing the articulation
+by a @emph{direction indicator}.  Three direction indicators are
+available: @code{^} (meaning @qq{up}), @code{_} (meaning @qq{down})
+and @code{-} (meaning @qq{use default direction}).  The direction
+indicator can usually be omitted, in which case @code{-} is assumed,
+but a direction indicator is @strong{always} required before

 
 @itemize
 @item @code{\tweak} commands
 
 @itemize
 @item @code{\tweak} commands


@@ -1951,7 +2128,7 @@ indicator is @strong{always} required before
 @item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
 @end itemize
 
 @item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
 @end itemize
 

-These indications affect only the next note.
+Direction indicators affect only the next note:

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


@@ -2009,6 +2186,31 @@ c2( c)
 @end lilypond
 
 
 @end lilypond
 
 

+@node Context layout order
+@subsection Context layout order
+
+@cindex contexts, layout order
+
+Contexts are normally positioned in a system from top to bottom
+in the order in which they are encountered in the input file.  When
+contexts are nested, the outer context will include inner nested
+contexts as specified in the input file, provided the inner contexts
+are included in the outer context's @qq{accepts} list.  Nested
+contexts which are not included in the outer context's @qq{accepts}
+list will be repositioned below the outer context rather than nested
+within it.
+
+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.
+
+The default order in which contexts are laid out and the
+@qq{accepts} list can be changed, see @ref{Aligning contexts}.
+
+@seealso
+Usage Manual:
+@rprogram{An extra staff appears}.
+

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


@@ -2118,7 +2320,7 @@ are collectively called @qq{spanners}, and have special properties to control
 their appearance and behaviour.  Some of these properties are common
 to all spanners; others are restricted to a sub-set of the spanners.
 
 their appearance and behaviour.  Some of these properties are common
 to all spanners; others are restricted to a sub-set of the spanners.
 

-All spanners support the @code{spanner-interface}.  A few, esentially
+All spanners support the @code{spanner-interface}.  A few, essentially

 those that draw a straight line between the two objects, support in
 addition the @code{line-spanner-interface}.
 
 those that draw a straight line between the two objects, support in
 addition the @code{line-spanner-interface}.
 


@@ -2199,7 +2401,7 @@ a
 For some layout objects, the @code{minimum-length} property becomes
 effective only if the @code{set-spacing-rods} procedure is called
 explicitly.  To do this, the @code{springs-and-rods} property should
 For some layout objects, the @code{minimum-length} property becomes
 effective only if the @code{set-spacing-rods} procedure is called
 explicitly.  To do this, the @code{springs-and-rods} property should

-be set to @code{ly:spanner::set-spacing-rods}.   For example,
+be set to @code{ly:spanner::set-spacing-rods}.  For example,

 the minimum length of a glissando has no effect unless the
 @code{springs-and-rods} property is set:
 
 the minimum length of a glissando has no effect unless the
 @code{springs-and-rods} property is set:
 


@@ -2246,7 +2448,7 @@ a \< a a a a \! a a a
 @end lilypond
 
 This property is not effective for all spanners.  For example,
 @end lilypond
 
 This property is not effective for all spanners.  For example,

-seting it to @code{#t} has no effect on slurs or phrasing slurs
+setting it to @code{#t} has no effect on slurs or phrasing slurs

 or on other spanners for which terminating on the bar line would
 not be meaningful.
 
 or on other spanners for which terminating on the bar line would
 not be meaningful.
 


@@ -2396,8 +2598,10 @@ hairpins with @code{\!}.
 
 
 @seealso
 
 
 @seealso

-Internals Reference: @rinternals{TextSpanner},
-@rinternals{Glissando}, @rinternals{VoiceFollower},
+Internals Reference:
+@rinternals{TextSpanner},
+@rinternals{Glissando},
+@rinternals{VoiceFollower},

 @rinternals{TrillSpanner},
 @rinternals{line-spanner-interface}.
 
 @rinternals{TrillSpanner},
 @rinternals{line-spanner-interface}.
 


@@ -2545,7 +2749,7 @@ beginning of a line.  Or to be more precise, before a line break,
 where there is no line break, or after a line break.
 
 Alternatively, these eight combinations may be specified
 where there is no line break, or after a line break.
 
 Alternatively, these eight combinations may be specified

-by pre-defined functions, defined in @file{scm/output-lib.scm},
+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:
 


@@ -2775,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:
 
 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
 @lilypond[relative=2,ragged-right,verbatim,fragment]
 e2 \glissando f
 \once \override Glissando #'(bound-details right Y) = #-2


@@ -2875,8 +3079,7 @@ Learning Manual:
 
 Notation Reference:
 @ref{Explaining the Internals Reference},
 
 Notation Reference:
 @ref{Explaining the Internals Reference},

-@ref{Modifying properties},
-@ref{Interfaces for programmers}.
+@ref{Modifying properties}.

 
 Installed Files:
 @file{scm/@/define@/-grobs@/.scm}.
 
 Installed Files:
 @file{scm/@/define@/-grobs@/.scm}.


@@ -2884,6 +3087,9 @@ Installed Files:
 Snippets:
 @rlsr{Tweaks and overrides}.
 
 Snippets:
 @rlsr{Tweaks and overrides}.
 

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

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


@@ -2891,52 +3097,54 @@ Internals Reference:
 @node Aligning objects
 @subsection Aligning objects
 
 @node Aligning objects
 @subsection Aligning objects
 

-Graphical objects which support the @code{self-alignment-interface} and/or
-the @code{side-position-interface} can be
-aligned to a previously placed object in a variety of ways.  For a list of these objects, see
+Graphical objects which support the @code{self-alignment-interface}
+and/or the @code{side-position-interface} can be aligned to a previously
+placed object in a variety of ways.  For a list of these objects, see

 @rinternals{self-alignment-interface} and @rinternals{side-position-interface}.
 
 All graphical objects have a reference point, a horizontal extent and a
 vertical extent.  The horizontal extent is a pair of numbers
 giving the displacements from the reference point of the left and
 @rinternals{self-alignment-interface} and @rinternals{side-position-interface}.
 
 All graphical objects have a reference point, a horizontal extent and a
 vertical extent.  The horizontal extent is a pair of numbers
 giving the displacements from the reference point of the left and

-right edges, displacements to the left being negative.  The
-vertical extent is a pair of numbers giving the displacement from
-the reference point to the bottom and top edges, displacements down
-being negative.
+right edges, displacements to the left being negative.  The vertical
+extent is a pair of numbers giving the displacement from the reference
+point to the bottom and top edges, displacements down being negative.

 
 An object's position on a staff is given by the values of the
 @code{X-offset} and @code{Y-offset} properties.  The value of
 
 An object's position on a staff is given by the values of the
 @code{X-offset} and @code{Y-offset} properties.  The value of

-@code{X-offset} gives the displacement from the x coordinate of
+@code{X-offset} gives the displacement from the X coordinate of

 the reference point of the parent object, and the value of
 @code{Y-offset} gives the displacement from the center line of the
 the reference point of the parent object, and the value of
 @code{Y-offset} gives the displacement from the center line of the

-staff.   The values of @code{X-offset} and
-@code{Y-offset} may be set directly or may be set to be calculated
-by procedures in order to achieve alignment with the parent object
-in several ways.
+staff.  The values of @code{X-offset} and @code{Y-offset} may
+be set directly or may be set to be calculated by procedures in order
+to achieve alignment with the parent object.

 
 @warning{Many objects have special positioning considerations which
 cause any setting of @code{X-offset} or @code{Y-offset} to be
 ignored or modified, even though the object supports the
 
 @warning{Many objects have special positioning considerations which
 cause any setting of @code{X-offset} or @code{Y-offset} to be
 ignored or modified, even though the object supports the

-@code{self-alignment-interface}.}
+@code{self-alignment-interface}.  Overriding the @code{X-offset}
+or @code{Y-offset} properties to a fixed value causes the respective
+@code{self-alignment} property to be disregarded.}
+
+For example, an accidental can be repositioned vertically by setting
+@code{Y-offset} but any changes to @code{X-offset} have no effect.

 
 

-For example, an accidental can be repositioned
-vertically by setting @code{Y-offset} but any changes to
-@code{X-offset} have no effect.
+Rehearsal marks may be aligned with breakable objects such as bar
+lines, clef symbols, time signature symbols and key signatures.  There
+are special properties to be found in the @code{break-aligned-interface}
+for positioning rehearsal marks on such objects.

 
 

-Rehearsal marks may be aligned with
-breakable objects such as bar lines, clef symbols, time signature
-symbols and key signatures.  There are special properties to be
-found in the @code{break-aligned-interface} for positioning rehearsal
-marks on such objects.
+@seealso
+@ref{Using the break-alignable-interface},
+@rextend{Callback functions}.

 
 @menu
 
 @menu

-* Setting @code{X-offset} and @code{Y-offset} directly::
-* Using the @code{side-position-interface}::
-* Using the @code{self-alignment-interface}::
-* Using the @code{break-alignable-interface}::
+* Setting X-offset and Y-offset directly::
+* Using the side-position-interface::
+* Using the self-alignment-interface::
+* Using the break-alignable-interface::

 @end menu
 
 @end menu
 

-@node Setting @code{X-offset} and @code{Y-offset} directly
+@node Setting X-offset and Y-offset directly

 @unnumberedsubsubsec Setting @code{X-offset} and @code{Y-offset} directly
 
 Numerical values may be given to the @code{X-offset} and @code{Y-offset}
 @unnumberedsubsubsec Setting @code{X-offset} and @code{Y-offset} directly
 
 Numerical values may be given to the @code{X-offset} and @code{Y-offset}


@@ -2958,7 +3166,7 @@ a
 
 @c TODO write more
 
 
 @c TODO write more
 

-@node Using the @code{side-position-interface}
+@node Using the side-position-interface

 @unnumberedsubsubsec Using the @code{side-position-interface}
 
 An object which supports the @code{side-position-interface} can be
 @unnumberedsubsubsec Using the @code{side-position-interface}
 
 An object which supports the @code{side-position-interface} can be


@@ -2999,7 +3207,7 @@ to value of @code{direction}.
 
 @c TODO Add examples
 
 
 @c TODO Add examples
 

-@node Using the @code{self-alignment-interface}
+@node Using the self-alignment-interface

 @unnumberedsubsubsec Using the @code{self-alignment-interface}
 
 @emph{Self-aligning objects horizontally}
 @unnumberedsubsubsec Using the @code{self-alignment-interface}
 
 @emph{Self-aligning objects horizontally}


@@ -3100,7 +3308,7 @@ example shows the difference:
 
 @c TODO The align-interface, BassFigureAlignment and VerticalAlignment
 
 
 @c TODO The align-interface, BassFigureAlignment and VerticalAlignment
 

-@node Using the @code{break-alignable-interface}
+@node Using the break-alignable-interface

 @unnumberedsubsubsec Using the @code{break-alignable-interface}
 
 @cindex align to objects
 @unnumberedsubsubsec Using the @code{break-alignable-interface}
 
 @cindex align to objects


@@ -3116,20 +3324,27 @@ By default, rehearsal marks and bar numbers will be horizontally
 centered above the object:
 
 @lilypond[verbatim,quote,relative=1]
 centered above the object:
 
 @lilypond[verbatim,quote,relative=1]

-e1
-% the RehearsalMark will be centered above the Clef
+% The rehearsal mark will be centered above the Clef

 \override Score.RehearsalMark #'break-align-symbols = #'(clef)
 \key a \major
 \clef treble
 \mark "↓"
 \override Score.RehearsalMark #'break-align-symbols = #'(clef)
 \key a \major
 \clef treble
 \mark "↓"

-e
-% the RehearsalMark will be centered above the TimeSignature
+e1
+% The rehearsal mark will be centered above the Time Signature

 \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
 \key a \major
 \clef treble
 \time 3/4
 \mark "↓"
 e2.
 \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
 \key a \major
 \clef treble
 \time 3/4
 \mark "↓"
 e2.

+% The rehearsal mark will be centered above the Breath Mark
+\override Score.RehearsalMark #'break-align-symbols = #'(breathing-sign)
+\key a \major
+\clef treble
+\time 4/4
+e1
+\breathe
+\mark "↓"

 @end lilypond
 
 A list of possible target alignment objects may be specified.  If
 @end lilypond
 
 A list of possible target alignment objects may be specified.  If


@@ -3142,20 +3357,27 @@ line is invisible the object is aligned to the place where the bar
 line would be.
 
 @lilypond[verbatim,quote,relative=1]
 line would be.
 
 @lilypond[verbatim,quote,relative=1]

-e1
-% the RehearsalMark will be centered above the Key Signature
+% The rehearsal mark will be centered above the Key Signature

 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
 \key a \major
 \clef treble
 \mark "↓"
 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
 \key a \major
 \clef treble
 \mark "↓"

-e
-% the RehearsalMark will be centered above the Clef
+e1
+% The rehearsal mark will be centered above the Clef

 \set Staff.explicitKeySignatureVisibility = #all-invisible
 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
 \set Staff.explicitKeySignatureVisibility = #all-invisible
 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)

-\key a \minor
+\key a \major

 \clef bass
 \mark "↓"
 \clef bass
 \mark "↓"

-e,
+gis,,1
+% The rehearsal mark will be centered above the Bar Line
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\set Staff.explicitClefVisibility = #all-invisible
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\key a \major
+\clef treble
+\mark "↓"
+e''1

 @end lilypond
 
 The alignment of the rehearsal mark relative to the notation object
 @end lilypond
 
 The alignment of the rehearsal mark relative to the notation object


@@ -3163,49 +3385,49 @@ can be changed, as shown in the following example.  In a score with
 multiple staves, this setting should be done for all the staves.
 
 @lilypond[verbatim,quote,relative=1]
 multiple staves, this setting should be done for all the staves.
 
 @lilypond[verbatim,quote,relative=1]

-% The RehearsalMark will be centered above the KeySignature
+% The RehearsalMark will be centered above the Key Signature

 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
 \key a \major
 \clef treble
 \time 4/4
 \mark "↓"
 e1
 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
 \key a \major
 \clef treble
 \time 4/4
 \mark "↓"
 e1

-% The RehearsalMark will be aligned with the left edge of the KeySignature
+% The RehearsalMark will be aligned with the left edge of the Key Signature

 \once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
 \mark "↓"
 \key a \major
 \once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
 \mark "↓"
 \key a \major

-e
-% The RehearsalMark will be aligned with the right edge of the KeySignature
+e1
+% The RehearsalMark will be aligned with the right edge of the Key Signature

 \once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
 \key a \major
 \mark "↓"
 \once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
 \key a \major
 \mark "↓"

-e
+e1

 @end lilypond
 
 @end lilypond
 

-The rehearsal mark can also be offset to the right or left of the left edge
-by an arbitrary amount.  The units are staff-spaces:
+The rehearsal mark can also be offset to the right or left of the left
+edge by an arbitrary amount.  The units are staff-spaces:

 
 @lilypond[verbatim,quote,relative=1]
 
 @lilypond[verbatim,quote,relative=1]

-% The RehearsalMark will be aligned with the left edge of the KeySignature
+% The RehearsalMark will be aligned with the left edge of the Key Signature

 % and then shifted right by 3.5 staff-spaces
 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
 \once \override Score.KeySignature #'break-align-anchor = #3.5
 \key a \major
 \mark "↓"
 % and then shifted right by 3.5 staff-spaces
 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
 \once \override Score.KeySignature #'break-align-anchor = #3.5
 \key a \major
 \mark "↓"

-e
-% The RehearsalMark will be aligned with the left edge of the KeySignature
+e1
+% The RehearsalMark will be aligned with the left edge of the Key Signature

 % and then shifted left by 2 staff-spaces
 \once \override Score.KeySignature #'break-align-anchor = #-2
 \key a \major
 \mark "↓"
 % and then shifted left by 2 staff-spaces
 \once \override Score.KeySignature #'break-align-anchor = #-2
 \key a \major
 \mark "↓"

-e
+e1

 @end lilypond
 
 
 @node Vertical grouping of grobs
 @subsection Vertical grouping of grobs
 
 @end lilypond
 
 
 @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,
 
 The VerticalAlignment and VerticalAxisGroup grobs work together.
 VerticalAxisGroup groups together different grobs like Staff, Lyrics,


@@ -3354,8 +3576,172 @@ 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}
 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 @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::
+* 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{arg1} @var{arg2} @dots{})
+     (@var{type1?} @var{type2?} @dots{})
+   #@{
+     @var{@dots{}music@dots{}}
+   #@})
+@end example
+
+@noindent
+where
+
+@multitable @columnfractions .33 .66
+@item @code{@var{argN}}
+@tab @var{n}th argument
+
+@item @code{@var{typeN?}}
+@tab a scheme @emph{type predicate} for which @code{@var{argN}}
+must return @code{#t}.
+
+@item @code{@var{@dots{}music@dots{}}}
+@tab normal LilyPond input, using @code{$} to reference arguments
+(eg. @samp{$arg1}).
+@end multitable
+
+
+The @code{parser} and @code{location} arguments are mandatory, and
+are used in some advanced situations as described in the
+@q{Extending} manual (see @rextend{Music functions}).  For
+substitution functions, just be sure to include them.

 
 

+The list of type predicates is also required.  Some of the most
+common type predicates used in music functions are:

 
 

+@example
+boolean?
+cheap-list?  @emph{(use instead of }@q{list?}@emph{ for faster processing)}
+ly:music?
+markup?
+number?
+pair?
+string?
+symbol?
+@end example
+
+@noindent
+For a list of available type predicates, see
+@ref{Predefined type predicates}.  User-defined type predicates
+are also allowed.
+
+
+@seealso
+
+Notation Reference:
+@ref{Predefined type predicates}.

 
 

+Extending:
+@rextend{Music functions}.
+
+Installed Files:
+@file{lily/music-scheme.cc},
+@file{scm/c++.scm},
+@file{scm/lily.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:
+
+@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?)
+   #{
+     \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
+   #})
+
+\relative c' { c4 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

 
 

+TODO: add missing @@ref's here.