X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fexpressive.itely;h=1074130f2f2f8a5898b1c7ad98a48e2be529133e;hb=aa2564cc65be5886799542e28e1a60b7ecf453ce;hp=333c573fc7942ab4f3fa7fcd15f8027ffa81bd25;hpb=e0ab7a37fa31290d42c9e5534ac5480c7d9f4a8f;p=lilypond.git

diff --git a/Documentation/user/expressive.itely b/Documentation/user/expressive.itely
index 333c573fc7..1074130f2f 100644
--- a/Documentation/user/expressive.itely
+++ b/Documentation/user/expressive.itely
@@ -6,11 +6,12 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
+@c \version "2.11.38"
+
 @node Expressive marks
 @section Expressive marks
 
-@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
-{expressive-headword.ly}
+@lilypondfile[quote]{expressive-headword.ly}
 
 @menu
 * Attached to notes::           
@@ -22,59 +23,20 @@
 @node Attached to notes
 @subsection Attached to notes
 
-
 @menu
 * Articulations and ornamentations::  
 * Dynamics::                    
+* New dynamic marks::           
 @end menu
 
 @node Articulations and ornamentations
-@unnumberedsubsubsec Articulations and ornamentations
+@subsubsection Articulations and ornamentations
 
 @cindex articulations
 @cindex scripts
 @cindex ornaments
-
-A variety of symbols can appear above and below notes to indicate
-different characteristics of the performance.  All these symbols
-can be attached to a note using the syntax
-@var{note}@code{\}@var{name}.
-
-The possible values for @var{name} are listed in @ref{List of
-articulations}.
-
-Some of these articulations have shorthands for easier entry.  They
-are used by adding a dash and the character signifying
-the articulation to the note name.  The available shorthands and
-their output are:
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-c4-.  c--   c-+   c-|
-c->   c-^   c-_
-@end lilypond
-
-The marks are automatically placed, but the direction can be
-forced as well.  Like other pieces of LilyPond code,
-@code{_}@tie{}will place them below the staff, and@tie{}@code{^}
-will place them above.  This applies both to the shorthands and
-the fully named articulations.  For the shorthands, the dash
-itself should be omitted; the direction signs replace it:
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-c4^^ c4_^
-c\fermata c^\fermata c_\fermata
-@end lilypond
-
-
-@cindex accent
-@cindex marcato
-@cindex staccatissimo
 @cindex espressivo
 @cindex fermata
-@cindex stopped
-@cindex staccato
-@cindex portato
-@cindex tenuto
 @cindex upbow
 @cindex downbow
 @cindex foot marks
@@ -96,60 +58,95 @@ c\fermata c^\fermata c_\fermata
 @cindex coda
 @cindex varcoda
 
+A variety of symbols that denote articulations, ornamentations,
+and other performance indications can be attached to a note using
+this syntax:
 
-@commonprop
+@example
+@var{note}\@var{name}
+@end example
 
-The meanings of the shorthands can be changed.  They are defined
-in @file{ly/@/script@/-init@/.ly}, where the variables
-@code{dashDot}, @code{dashDash}, @code{dashPlus}, @code{dashBar},
-@code{dashLarger}, @code{dashHat}, and @code{dashUnderscore}
-are associated with the default articulation marks.  If you want,
-e.g., @code{-+} to produce a trill instead of a "+", you can
-redefine the variable in your document:
+The possible values for @var{name} are listed in @ref{List of
+articulations}.  For example:
 
-@lilypond[verbatim,quote,ragged-right]
-\relative c'' { c-+ }
-dashPlus = "trill"
-\relative c'' { c-+ }
+@lilypond[verbatim,quote,relative=2]
+c4\staccato c\mordent b2\turn
+c1\fermata
 @end lilypond
 
-The vertical ordering of scripts is controlled with the
-@code{script-priority} property.  The lower this number, the
-closer it will be put to the note.  In this example, the
-@code{TextScript} (the sharp symbol) first has the lowest
-priority, so it is put lowest in the first example.  In the
-second, the prall trill (the @code{Script}) has the
-lowest, so it is on the inside.  When two objects have the same
-priority, the order in which they are entered decides which one
-comes first.
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=3]
-\once \override TextScript #'script-priority = #-100
-a4^\prall^\markup { \sharp }
-
-\once \override Script #'script-priority = #-100
-a4^\prall^\markup { \sharp }
+@cindex marcato
+@cindex stopped
+@cindex tenuto
+@cindex staccatissimo
+@cindex accent
+@cindex staccato
+@cindex portato
+
+Some of these articulations have shorthands for easier entry.
+Shorthands are appended to the note name, and their syntax
+consists of a dash (@tie{}@code{-}) followed by a symbol
+signifying the articulation.  Predefined shorthands exist for
+@notation{marcato}, @notation{stopped}, @notation{tenuto},
+@notation{staccatissimo}, @notation{accent}, @notation{staccato},
+and @notation{portato}.  Their corresponding output appears as
+follows:
+
+@lilypond[verbatim,quote,relative=2]
+c4-^  c-+  c--  c-|
+c4->  c-.  c-_
 @end lilypond
 
+The rules for the default placement of articulations are defined
+in @file{scm/@/script@/.scm}.  Articulations and ornamentations
+may be manually placed above or below the staff, see
+@ref{Direction and placement}.
+
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{modifying-default-values-for-articulation-shorthand-notation.ly}
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{controlling-the-vertical-ordering-of-scripts.ly}
+
 
 @seealso
 
-Snippets: @lsrdir{expressive}
+Music Glossary:
+@rglos{tenuto},
+@rglos{accent},
+@rglos{staccato},
+@rglos{portato}.
+
+Notation Reference:
+@ref{Direction and placement},
+@ref{List of articulations}.
+
+Installed Files:
+@file{scm/@/script@/.scm}.
+
+Snippets:
+@rlsr{Expressive marks}.
 
-Internals Reference: @internalsref{Script},
-@internalsref{TextScript}.
+Internals Reference:
+@rinternals{Script},
+@rinternals{TextScript}.
 
 
-@refbugs
+@knownissues
 
 These signs appear in the printed output but have no effect on the
 MIDI rendering of the music.
 
 
 @node Dynamics
-@unnumberedsubsubsec Dynamics
+@subsubsection Dynamics
 
+@cindex absolute dynamics
 @cindex dynamics
+@cindex dynamics, absolute
+@funindex \ppppp
 @funindex \pppp
 @funindex \ppp
 @funindex \pp
@@ -169,125 +166,102 @@ MIDI rendering of the music.
 @funindex \rfz
 
 Absolute dynamic marks are specified using a command after a note,
-like @code{c4\ff}.  The available dynamic marks are @code{\ppppp},
-@code{\pppp}, @code{\ppp}, @code{\pp}, @code{\p}, @code{\mp},
-@code{\mf}, @code{\f}, @code{\ff}, @code{\fff}, @code{\ffff},
-@code{\fp}, @code{\sf}, @code{\sff}, @code{\sp}, @code{\spp},
-@code{\sfz}, and @code{\rfz}.  The dynamic marks can be placed
-above or below the staff with@tie{}@code{_} and@tie{}@code{^},
-just like articulation marks.
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+such as @code{c4\ff}.  The available dynamic marks are
+@code{\ppppp}, @code{\pppp}, @code{\ppp}, @code{\pp}, @code{\p},
+@code{\mp}, @code{\mf}, @code{\f}, @code{\ff}, @code{\fff},
+@code{\ffff}, @code{\fp}, @code{\sf}, @code{\sff}, @code{\sp},
+@code{\spp}, @code{\sfz}, and @code{\rfz}.  The dynamic marks may
+be manually placed above or below the staff, see 
+@ref{Direction and placement}.
+
+@lilypond[verbatim,quote,relative=2]
 c2\ppp c\mp
-c\rfz c^\mf
-c_\spp c_\staccato^\ff
+c2\rfz c^\mf
+c2_\spp c^\ff
 @end lilypond
 
+@cindex hairpin
 @funindex \<
 @funindex \>
 @funindex \!
-
-A crescendo mark is started with @code{\<} and terminated with
-@code{\!} or an absolute dynamic.  A decrescendo is started with
-@code{\>} and is also terminated with @code{\!} or an absolute
-dynamic.  @code{\cr} and @code{\decr} may be used instead of
-@code{\<} and @code{\>}.  They can be engraved either using a
-graphical sign (a @q{hairpin}), or with textual signs.
-
-Because these marks are bound to notes, you must use spacer notes
-if multiple marks are needed during one note.
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-c\< c\! d\> e\!
-<< f1 { s4 s4\< s4\! \> s4\! } >>
-@end lilypond
-
-This may give rise to very short hairpins.  To lengthen them, use
-for example @code{minimum-length} in
-@internalsref{Voice}.@internalsref{Hairpin}:
-
-@example
-\override Voice.Hairpin #'minimum-length = #5
-@end example
-
-@noindent
-A hairpin normally starts at the left edge of the beginning note
-and ends on the right edge of the ending note.  If the ending note
-falls on the downbeat, the hairpin ends on the immediately
-preceding bar line.  This may be modified by setting the
-@code{hairpinToBarline} property:
-@cindex hairpin
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-e4\< e2. e1\!
-\set hairpinToBarline = ##f
-e4\< e2. e1\!
+@funindex \cr
+@funindex \decr
+
+A @notation{crescendo} mark is started with @code{\<} and
+terminated with @code{\!}, an absolute dynamic, or an additional
+@notation{crescendo} or @notation{decrescendo} mark.  A
+@notation{decrescendo} mark is started with @code{\>} and is also
+terminated with @code{\!}, an absolute dynamic, or another
+@notation{crescendo} or @notation{decrescendo} mark.  @code{\cr}
+and @code{\decr} may be used instead of @code{\<} and @code{\>}.
+@notation{Hairpins} are engraved by default using this notation.
+
+@lilypond[verbatim,quote,relative=2]
+c2\< c\!
+d2\< d\f
+e2\< e\>
+f2\> f\!
+e2\> e\mp
+d2\> d\>
+c1\!
 @end lilypond
 
-@cindex espressivo, articulation
-In some situations the @code{\espressivo} articulation mark may be
-suitable to indicate a crescendo and decrescendo on the one note:
+Spacer notes are needed to engrave multiple marks on one note.
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-c2 b4 a g1\espressivo
+@lilypond[verbatim,quote,relative=2]
+c4\< c\! d\> e\!
+<< f1 { s4 s4\< s4\> s4\! } >>
 @end lilypond
 
-@cindex al niente
-@cindex niente, al
+@cindex espressivo articulation
 
-Hairpins may be printed with a circled tip (al niente notation) by
-setting the @code{circled-tip} property:
+In some situations the @code{\espressivo} articulation mark may be
+the appropriate choice to indicate a @notation{crescendo} and
+@notation{decrescendo} on one note:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-\override Hairpin #'circled-tip = ##t
-c2\< c\!
-c4\> c\< c2\!
+@lilypond[verbatim,quote,relative=2]
+c2 b4 a
+g1\espressivo
 @end lilypond
 
 @cindex crescendo
 @cindex decrescendo
 @cindex diminuendo
-
-You can use text saying @emph{cresc.}, @emph{decr.}, or
-@emph{dim.} instead of hairpins with the commands \setTextCresc,
-\setTextDim, and \setTextDecresc.  The corresponding
-\setHairpinCresc, \setHairpinDim, and \setHairpinDecresc will
+@funindex \setTextCresc
+@funindex \setTextDim
+@funindex \setTextDecr
+@funindex \setTextDecresc
+@funindex \setHairpinCresc
+@funindex \setHairpinDim
+@funindex \setHairpinDecresc
+
+@notation{Crescendos} and @notation{decrescendos} can be engraved
+as textual markings instead of hairpins.  The built-in commands
+that enable these text modes are @code{\setTextCresc},
+@code{\setTextDecresc}, @code{\setTextDecr}, and
+@code{\setTextDim}.  The corresponding @code{\setHairpinCresc},
+@code{\setHairpinDim}, and @code{\setHairpinDecresc} commands will
 revert to hairpins again:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
+c4\< d e f\!
+e4\> d c b\!
 \setTextCresc
-c\< d e f\!
-\setHairpinCresc
-e\> d c b\!
+c4\< d e f\!
 \setTextDecresc
-e\> d e f\!
-\setTextDecr
-c\> d e f\!
-\setTextDim
-e\> d c b\!
-@end lilypond
-
-You can also supply your own texts and change the style of the
-spanner line with the properties @code{\crescendoText},
-@code{\crescendoSpanner}, @code{\decrescendoText}, and
-@code{\decrescendoSpanner}.  Available values for the spanner
-properties are @code{hairpin}, @code{line}, @code{dashed-line},
-and @code{dotted-line}.  If unset, a hairpin crescendo is used:
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
-\set crescendoText = \markup { \italic "cresc. poco" }
-\set crescendoSpanner = #'dotted-line
-a'2\< a a a a a a a\!\mf
+e4\> d c b\!
+\setHairpinCresc
+c4\< d e f\!
 @end lilypond
 
-To create new dynamic marks or text that should be aligned with
-dynamics, see @ref{New dynamic marks}.
+To create new absolute dynamic marks or text that should be
+aligned with dynamics, see @ref{New dynamic marks}.
 
 Vertical positioning of dynamics is handled by
-@internalsref{DynamicLineSpanner}.
+@rinternals{DynamicLineSpanner}.
 
 
-@refcommands
+@predefined
 
 @funindex \dynamicUp
 @code{\dynamicUp},
@@ -297,51 +271,132 @@ Vertical positioning of dynamics is handled by
 @code{\dynamicNeutral}.
 
 
-@commonprop
+@snippets
 
-Dynamics that occur at, begin on, or end on the same note will be
-vertically aligned.  If you want to ensure that dynamics are
-aligned when they do not occur on the same note, you can increase
-the @code{staff-padding} property.
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{setting-hairpin-behavior-at-bar-lines.ly}
 
-@example
-\override DynamicLineSpanner #'staff-padding = #4
-@end example
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{setting-the-minimum-length-of-hairpins.ly}
 
-@noindent
-You may also use this property if the dynamics are colliding with
-other notation.
+@cindex al niente
+@cindex niente, al
 
-Crescendi and decrescendi that cross a line break will be
-continued on the second line.  If they end on the first note of a
-new line, nothing will be printed on that line.  To change this
-behavior, use
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{printing-hairpins-using-al-niente-notation.ly}
 
-@example
-\override Score.Hairpin #'after-line-breaking = ##t
-@end example
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{vertically-aligning-dynamics-across-multiple-notes.ly}
 
-Text style dynamic changes (such as @emph{cresc.} and @emph{dim.})
-are printed with a dashed line showing their extent.  To surpress
-printing this line, use
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{hiding-the-extender-line-for-text-dynamics.ly}
 
-@example
-\override DynamicTextSpanner #'dash-period = #-1.0
-@end example
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{changing-text-and-spanner-styles-for-text-dynamics.ly}
 
 
 @seealso
 
-Music Glossary: @rglos{hairpin}, @rglos{crescendo},
+@c TODO: Add hairpin to glossary.
+
+Music Glossary:
+@rglos{crescendo},
 @rglos{decrescendo}.
 
-Learning Manual: @rlearning{Articulation and dynamics}.
+Learning Manual:
+@rlearning{Articulation and dynamics}.
+
+Notation Reference:
+@ref{Direction and placement},
+@ref{New dynamic marks}.
+
+Snippets:
+@rlsr{Expressive marks}.
+
+Internals Reference:
+@rinternals{DynamicText},
+@rinternals{Hairpin},
+@rinternals{DynamicLineSpanner}.
+
 
-Snippets: @lsrdir{expressive}
+@node New dynamic marks
+@subsubsection New dynamic marks
 
-Internals Reference: @internalsref{DynamicText},
-@internalsref{Hairpin}.  Vertical positioning of these symbols is
-handled by @internalsref{DynamicLineSpanner}.
+@cindex new dynamic marks
+@cindex dynamic marks, new
+
+The easiest way to create dynamic indications is to use
+@code{\markup} objects.
+
+@lilypond[verbatim,quote]
+moltoF = \markup { molto \dynamic f }
+
+\relative c' {
+  <d e>16 <d e>
+  <d e>2.._\moltoF
+}
+@end lilypond
+
+@cindex dynamics, editorial
+@cindex dynamics, parenthesis
+
+Markup mode makes possible, for instance, to add
+editorial dynamics, printed in round parenthesis or square
+brackets.  Its syntax is described in @ref{Formatting text}.
+
+@lilypond[verbatim,quote]
+roundf = \markup { \center-align { \line { \bold { \italic ( }
+         \dynamic f \bold { \italic ) } } } }
+boxf = \markup { \bracket { \dynamic f } }
+\relative c' {
+  c1_\roundf
+  c1_\boxf
+}
+@end lilypond
+
+Markup objects are treated differently from authentic dynamic marks.
+Defining dynamic objects that will be entered and printed exactly like
+standard dynamic marks is also possible, using the following function:
+
+@cindex make-dynamic-script
+
+@lilypond[verbatim,quote]
+sfzp = #(make-dynamic-script "sfzp")
+\relative c' {
+  c4 c c\sfzp c
+}
+@end lilypond
+
+@noindent
+Note that the dynamic font only contains the characters 
+@code{f,m,p,r,s} and @code{z}.  To switch to other font families,
+it is necessary to use markup mode in its Scheme form, as
+explained in @ref{Markup construction in Scheme}.
+
+@lilypond[verbatim,quote]
+moltoF = #(make-dynamic-script (markup 
+                      #:normal-text "molto"
+                      #:dynamic "f"))
+\relative c' {
+  <d e>16 <d e>
+  <d e>2..\moltoF
+}
+@end lilypond
+
+@noindent
+Font settings in markup mode are described in
+@ref{Common markup commands}.
+
+
+@seealso
+
+Notation Reference:
+@ref{Formatting text},
+@ref{Common markup commands},
+@ref{Markup construction in Scheme}.
+
+Snippets:
+@rlsr{Expressive marks}.
 
 
 @node Curves
@@ -355,34 +410,50 @@ handled by @internalsref{DynamicLineSpanner}.
 @end menu
 
 @node Slurs
-@unnumberedsubsubsec Slurs
+@subsubsection Slurs
 
 @cindex slurs
 
-A slur indicates that notes are to be played bound or
-@emph{legato}.  They are entered using parentheses:
+@notation{Slurs} are entered using parentheses:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-f( g a) a8 b( a4 g2 f4)
+@lilypond[verbatim,quote,relative=2]
+f4( g a) a8 b(
+a4 g2 f4)
 <c e>2( <b d>2)
 @end lilypond
 
-Just as with ties, the direction of a slur can be specified with
-@code{\slur@emph{DIR}}, where @code{@emph{DIR}} is either
-@code{Up}, @code{Down}, or @code{Neutral} (automatically
-selected).  The shorthands are also available: by
-adding@tie{}@code{_} or@tie{}@code{^} before the opening
-parentheses, the direction is also set.
+@notation{Slurs} may be manually placed above or below the staff,
+see @ref{Direction and placement}.
+
+@lilypond[verbatim,quote,relative=2]
+c2( d)
+\slurDown
+c2( d)
+\slurNeutral
+c2( d)
+@end lilypond
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-c4_( c) c^( c)
+Different styles of @notation{slurs} may be created with the
+commands @code{\slurDashed} and @code{slurDotted};
+@code{\slurSolid} reverts back to the default @notation{slur}
+style:
+
+@lilypond[verbatim,quote,relative=1]
+c4( e g2)
+\slurDashed
+g4( e c2)
+\slurDotted
+c4( e g2)
+\slurSolid
+g4( e c2)
 @end lilypond
 
-Only one slur can be printed at once.  If you need to print a long
-slur over a few small slurs, please see @ref{Phrasing slurs}.
+Using this method, only one slur can be printed at once.
+@notation{Phrasing slurs} must be used to print a long slur over
+one or more small slurs.  For details, see @ref{Phrasing slurs}.
 
 
-@refcommands
+@predefined
 
 @funindex \slurUp
 @code{\slurUp},
@@ -398,49 +469,61 @@ slur over a few small slurs, please see @ref{Phrasing slurs}.
 @code{\slurSolid}.
 
 
-@commonprop
+@snippets
 
-Some composers write two slurs when they want legato chords.  This
-can be achieved in LilyPond by setting @code{doubleSlurs},
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
-\set doubleSlurs = ##t
-<c e>4 ( <d f> <c e> <d f> )
-@end lilypond
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{using-double-slurs-for-legato-chords.ly}
 
 
 @seealso
 
-Snippets: @lsrdir{expressive}
+Music Glossary:
+@rglos{slur}.
 
-Internals Reference: @internalsref{Slur}.
+Notation Reference:
+@ref{Direction and placement},
+@ref{Phrasing slurs}.
+
+Snippets:
+@rlsr{Expressive marks}.
+
+Internals Reference:
+@rinternals{Slur}.
 
 
 @node Phrasing slurs
-@unnumberedsubsubsec Phrasing slurs
+@subsubsection Phrasing slurs
 
 @cindex phrasing slurs
 @cindex phrasing marks
+@funindex \(
+@funindex \)
 
-A phrasing slur (or phrasing mark) connects notes and is used to
-indicate a musical sentence.  It is written using @code{\(} and
-@code{\)} respectively:
+@notation{Phrasing slurs} (or @notation{phrasing marks}) that
+indicate a musical sentence are written using the commands
+@code{\(} and @code{\)} respectively:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
-\time 6/4 c'\( d( e) f( e) d\)
+@lilypond[verbatim,quote,relative=2]
+c4\( d( e) f(
+e2) d\)
 @end lilypond
 
-Typographically, the phrasing slur behaves almost exactly like a
-normal slur.  However, they are treated as different objects.  A
-@code{\slurUp} will have no effect on a phrasing slur; instead,
-use @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and
-@code{\phrasingSlurNeutral}, or use the shorthands@tie{}@code{_}
-and@tie{}@code{^}.
+Typographically, a @notation{phrasing slur} behaves almost exactly
+like a normal @notation{slur}.  However, they are treated as
+different objects; a @code{\slurUp} will have no effect on a
+@notation{phrasing slur}.  Phrasing slurs may be manually placed
+above or below the staff, see @ref{Direction and placement}.
 
-You cannot have simultaneous phrasing slurs.
+@lilypond[verbatim,quote,relative=1]
+c4\( g' c,( b) | c1\)
+\phrasingSlurUp
+c4\( g' c,( b) | c1\)
+@end lilypond
 
+Simultaneous phrasing slurs are not permitted.
 
-@refcommands
+
+@predefined
 
 @funindex \phrasingSlurUp
 @code{\phrasingSlurUp},
@@ -452,54 +535,91 @@ You cannot have simultaneous phrasing slurs.
 
 @seealso
 
-Snippets: @lsrdir{expressive}
+Notation Reference:
+@ref{Direction and placement}.
+
+Snippets:
+@rlsr{Expressive marks}.
 
-Internals Reference: @internalsref{PhrasingSlur}.
+Internals Reference:
+@rinternals{PhrasingSlur}.
 
 
 @node Breath marks
-@unnumberedsubsubsec Breath marks
+@subsubsection Breath marks
+
+@cindex breath marks
+@funindex \breathe
 
 Breath marks are entered using @code{\breathe}:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
-c'4 \breathe d4
+@lilypond[verbatim,quote,relative=2]
+c2. \breathe d4
 @end lilypond
 
+Musical indicators for breath marks in ancient notation,
+@notation{divisiones}, are supported.  For details, see
+@ref{Divisiones}.
 
-@commonprop
 
-The glyph of the breath mark can be tuned by overriding the
-@code{text} property of the @code{BreathingSign} layout object
-with any markup text.  For example,
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{changing-the-breath-mark-symbol.ly}
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
-c'4
-\override BreathingSign #'text
-  = #(make-musicglyph-markup "scripts.rvarcomma")
-\breathe
-d4
-@end lilypond
 
 @seealso
 
-Snippets: @lsrdir{expressive}, @lsr{expressive,breathing-sign.ly}.
+Notation Reference:
+@ref{Divisiones}.
+
+Snippets:
+@rlsr{Expressive marks}.
+@c @lsr{expressive,breathing-sign.ly}.
 
-Internals Reference: @internalsref{BreathingSign}.
+Internals Reference:
+@rinternals{BreathingSign}.
 
 
 @node Falls and doits
-@unnumberedsubsubsec Falls and doits
+@subsubsection Falls and doits
 
-Falls and doits can be added to notes using the @code{\bendAfter}
-command,
+@cindex falls
+@cindex doits
+@funindex \bendAfter
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-\override Score.SpacingSpanner #'shortest-duration-space = #3.0
-c4-\bendAfter #+5
-c4-\bendAfter #-3
+@notation{Falls} and @notation{doits} can be added to notes using
+the @code{\bendAfter} command:
+
+@lilypond[verbatim,quote,relative=2]
+c2-\bendAfter #+4
+c2-\bendAfter #-4
+c2-\bendAfter #+8
+c2-\bendAfter #-8
 @end lilypond
 
+The dash (@tie{-}) immediately preceding the @code{\bendAfter}
+command is @emph{required} when writing @notation{falls} and
+@notation{doits}.
+
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{adjusting-the-shape-of-falls-and-doits.ly}
+
+
+@seealso
+
+@c TODO: add falls and doits to glossary.
+@c Music Glossary:
+@c @rglos{falls},
+@c @rglos{doits}.
+
+Snippets:
+@rlsr{Expressive marks}.
+
+
 @node Lines
 @subsection Lines
 
@@ -510,95 +630,117 @@ c4-\bendAfter #-3
 @end menu
 
 @node Glissando
-@unnumberedsubsubsec Glissando
+@subsubsection Glissando
 
 @cindex glissando
 @funindex \glissando
 
-A glissando is a smooth change in pitch.  It is denoted by a line
-or a wavy line between two notes.  It is requested by attaching
-@code{\glissando} to a note:
+A @notation{glissando} is created by attaching @code{\glissando}
+to a note:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-c2\glissando c'
-\override Glissando #'style = #'zigzag
+@lilypond[verbatim,quote,relative=2]
+g2\glissando g'
 c2\glissando c,
 @end lilypond
 
-@commonprop
-
+Different styles of @notation{glissandi} can be created.  For
+details, see @ref{Line styles}.
 
-@lilypond[verbatim,quote,ragged-right]
-I = \once \override NoteColumn #'ignore-collision = ##t
-
-\relative c' <<
-  { \oneVoice \stemDown f2 \glissando \stemNeutral a } \\
-  { \oneVoice \I c2 \glissando \I d, }
->>
-@end lilypond
+@snippets
 
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{contemporary-glissando.ly}
 
 
 @seealso
 
-Music Glossary: @rglos{falls}, @rglos{doits}.
+Music Glossary:
+@rglos{glissando}.
+
+Notation Reference:
+@ref{Line styles}.
 
-Snippets: @lsrdir{expressive}.
+Snippets:
+@rlsr{Expressive marks}.
 
 @c FIXME: I need to figure out what's up with these.  -gp
 @c @lsr{expressive,glissando.ly},
 @c @lsr{expressive,line-styles.ly}
 
-Internals Reference: @internalsref{Glissando}.
+Internals Reference:
+@rinternals{Glissando}.
 
 
-@refbugs
+@knownissues
 
 Printing text over the line (such as @emph{gliss.}) is not
 supported.
 
 
 @node Arpeggio
-@unnumberedsubsubsec Arpeggio
+@subsubsection Arpeggio
 
 @cindex arpeggio
 @cindex broken chord
-@funindex \arpeggio
+@cindex chord, broken
+
+An @notation{arpeggio} on a chord (also known as a
+@notation{broken chord}) is denoted by appending @code{\arpeggio}
+to the chord construct:
 
-You can specify an arpeggio sign (also known as broken chord) on a
-chord by attaching an @code{\arpeggio} to the chord:
+@lilypond[verbatim,quote,relative=1]
+<c e g c>1\arpeggio
+@end lilypond
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
-<c e g c>\arpeggio
+The direction of an @notation{arpeggio} is indicated by adding an
+arrowhead to the wiggly line.  The commands @code{\arpeggioUp} and
+@code{\arpeggioDown} are used for this task.
+@code{\arpeggioNeutral} reverts back to an arrow-less
+@notation{arpeggio}:
+
+@lilypond[verbatim,quote,relative=1]
+\arpeggioUp
+<c e g c>2\arpeggio
+\arpeggioDown
+<c e g c>2\arpeggio
+\arpeggioNeutral
+<c e g c>1\arpeggio
 @end lilypond
 
-A square bracket on the left is used to indicate that the chord
-should @emph{not} be arpeggiated:
+The command @code{\arpeggioBracket} can be used to create a square
+bracket on the left of a chord, indicating that the chord should
+@emph{not} be arpeggiated.  @code{\arpeggioNeutral} reverts back
+to a regular arpeggio:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
+@lilypond[verbatim,quote,relative=1]
+<c e g c>2
 \arpeggioBracket
-<c e g c>\arpeggio
+<c e g c>2\arpeggio
+\arpeggioNeutral
+<c e g c>1\arpeggio
 @end lilypond
 
-The direction of the arpeggio can be denoted by adding an
-arrowhead to the wiggly line.  This is done with the commands
-@code{arpeggioUp} and @code{arpeggioDown}.  @code{arpeggioNeutral}
-reverts to the arrow-less version:
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
-\new Voice {
-  \arpeggioUp
-  <c e g c>\arpeggio
-  \arpeggioDown
-  <c e g c>\arpeggio
-  \arpeggioNeutral
-  <c e g c>\arpeggio
-}
+A @emph{parenthesis} style bracket may be attached to an
+@notation{arpeggio} instead of a square bracket.
+
+@c Maybe create a new \arpeggioParen command, or something
+@c like that. -pm
+
+@lilypond[verbatim,quote,relative=1]
+<c e g c>2
+\override Arpeggio #'stencil = #ly:arpeggio::brew-chord-slur
+\override Arpeggio #'X-extent = #ly:grob::stencil-width
+<c e g c>2\arpeggio
+\arpeggioNeutral
+<c e g c>1\arpeggio
 @end lilypond
 
+@notation{Arpeggios} can be explicitly written out with
+@notation{ties}.  For more information, see @ref{Ties}.
 
-@refcommands
+@predefined
 
+@funindex \arpeggio
 @code{\arpeggio},
 @funindex \arpeggioUp
 @code{\arpeggioUp},
@@ -610,77 +752,37 @@ reverts to the arrow-less version:
 @code{\arpeggioBracket}.
 
 
-@commonprop
+@snippets
 
-In a @code{PianoStaff}, it is possible to let an arpeggio cross
-between the staves by setting the property
-@code{PianoStaff}.@code{connectArpeggios}.
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
-\new PianoStaff <<
-  \set PianoStaff.connectArpeggios = ##t
-  \new Staff { <c' e g c>\arpeggio }
-  \new Staff { \clef bass <c,, e g>\arpeggio }
->>
-@end lilypond
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{creating-cross-staff-arpeggios-in-a-piano-staff.ly}
 
-The same can be accomplished in contexts other than
-@code{PianoStaff} if the @code{Span_arpeggio_engraver} is included
-in the Score context.
-
-@lilypond[verbatim,quote,ragged-right]
-\score {
-  \new StaffGroup {
-    \set Score.connectArpeggios = ##t
-    <<
-      \new Voice \relative c' {
-        <e g>4\arpeggio
-      }
-      \new Voice  \relative c {
-        \clef bass
-        <c e>4\arpeggio
-      }
-    >>
-  }
-  \layout {
-    \context {
-      \Score
-      \consists "Span_arpeggio_engraver"
-    }
-  }
-}
-@end lilypond
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{creating-cross-staff-arpeggios-in-other-contexts.ly}
 
-Similarly, an arpeggio can be drawn across notes in different
-voices on the same staff if the @code{Span_arpeggio_engraver} is
-moved to the Staff context:
-
-@lilypond[verbatim,quote,ragged-right]
-\new Staff
-\with {
-  \consists "Span_arpeggio_engraver"
-} \relative c' {
-  \set Staff.connectArpeggios = ##t
-    <<
-    {<e' g>4\arpeggio <d f> <d f>2 }
-  \\
-  {<d, f>2\arpeggio  <g b>2  }
-  >>
-}
-@end lilypond
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{creating-arpeggios-across-notes-in-different-voices.ly}
 
 
 @seealso
 
-Notation Reference: @ref{Ties}, for writing out arpeggios.
+@c TODO: Add 'broken chord' to glossary.
+
+Music Glossary:
+@rglos{arpeggio}.
 
-Snippets: @lsrdir{expressive}
+Notation Reference:
+@ref{Ties}.
 
-Internals Reference: @internalsref{Arpeggio},
-@internalsref{PianoStaff}.
+Snippets:
+@rlsr{Expressive marks}.
 
+Internals Reference:
+@rinternals{Arpeggio},
+@rinternals{PianoStaff}.
 
-@refbugs
+
+@knownissues
 
 It is not possible to mix connected arpeggios and unconnected
 arpeggios in one @code{PianoStaff} at the same point in
@@ -688,31 +790,39 @@ time.
 
 
 @node Trills
-@unnumberedsubsubsec Trills
+@subsubsection Trills
 
-Short trills are printed with @code{\trill} like normal
-articulation; see @ref{Articulations and ornamentations}.
+@cindex trills
+@funindex \trill
 
-Long running trills are made with @code{\startTrillSpan} and
-@code{\stopTrillSpan}.  In the following example, it is shown in
-the common combination with grace notes.  If a more precise
-control of the placement of the grace notes is needed, see
-@ref{Grace notes}.
+Short @notation{trills} without an extender line are printed with
+@code{\trill}; see @ref{Articulations and ornamentations}.
+
+Long running @notation{trills} are made with
+@code{\startTrillSpan} and @code{\stopTrillSpan}.  In the
+following example, a long running @notation{trill} is shown
+combined with grace notes.  To achieve precise control of the
+placement of the grace notes, see @ref{Grace notes}.
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 c1 \afterGrace
 d1\startTrillSpan { c16[\stopTrillSpan d] }
 c4
 @end lilypond
 
 @cindex pitched trills
+@cindex trills, pitched
 
-Trills that should be executed on an explicitly specified pitch
-can be typeset with the command @code{pitchedTrill}, and the
-syntax @code{\pitchedTrill} @var{mainnote}@code{\startTrillSpan}
-@var{trillnote} @var{endnote} @code{\stopTrillSpan}.
+@notation{Trills} that should be executed on an explicitly
+specified pitch can be typeset with the command
+@code{\pitchedTrill} using the following syntax:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
+@example
+@code{\pitchedTrill} @var{mainnote} @code{\startTrillSpan}
+@var{trillnote} @var{endnote} @code{\stopTrillSpan}
+@end example
+
+@lilypond[verbatim,quote,relative=1]
 \pitchedTrill e2 \startTrillSpan fis
 d\stopTrillSpan
 @end lilypond
@@ -722,7 +832,7 @@ The first argument is the main note.  The pitch of the second is
 printed as a stemless note head in parentheses.
 
 
-@refcommands
+@predefined
 
 @code{\startTrillSpan},
 @funindex \startTrillSpan
@@ -732,6 +842,15 @@ printed as a stemless note head in parentheses.
 
 @seealso
 
-Snippets: @lsrdir{expressive}
+Music Glossary:
+@rglos{trill}.
+
+Notation Reference:
+@ref{Articulations and ornamentations},
+@ref{Grace notes}.
+
+Snippets:
+@rlsr{Expressive marks}.
 
-Internals Reference: @internalsref{TrillSpanner}.
+Internals Reference:
+@rinternals{TrillSpanner}.