X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fexpressive.itely;h=7f1fd966e0c163736b16bac53287715546d6fcb6;hb=9072fef54417606d8e3f972ce0c07da2e0a84abb;hp=8382ef2f38ddd169be4f108b149428bf256f4553;hpb=02762418c52fcc91b223fe406b307d142b6462e2;p=lilypond.git

diff --git a/Documentation/user/expressive.itely b/Documentation/user/expressive.itely
index 8382ef2f38..7f1fd966e0 100644
--- a/Documentation/user/expressive.itely
+++ b/Documentation/user/expressive.itely
@@ -6,33 +6,41 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.38"
+@c \version "2.11.61"
 
 @node Expressive marks
 @section Expressive marks
 
 @lilypondfile[quote]{expressive-headword.ly}
 
+This section lists various expressive marks that can be
+created in a score.
+
 @menu
-* Attached to notes::           
-* Curves::                      
-* Lines::                       
+* Attached to notes::
+* Curves::
+* Lines::
 @end menu
 
 
 @node Attached to notes
 @subsection Attached to notes
 
+This section explains how to create expressive marks that are
+attached to notes: articulations, ornamentations, and dynamics.
+Methods to create new dynamic markings are also discussed.
+
 @menu
-* Articulations and ornamentations::  
-* Dynamics::                    
-* New dynamic marks::           
+* Articulations and ornamentations::
+* Dynamics::
+* New dynamic marks::
 @end menu
 
 @node Articulations and ornamentations
-@subsubsection Articulations and ornamentations
+@unnumberedsubsubsec Articulations and ornamentations
 
 @cindex articulations
+@cindex ornamentation
 @cindex scripts
 @cindex ornaments
 @cindex espressivo
@@ -41,6 +49,7 @@
 @cindex downbow
 @cindex foot marks
 @cindex organ pedal marks
+@cindex pedal marks, organ
 @cindex turn
 @cindex open
 @cindex stopped
@@ -58,6 +67,8 @@
 @cindex coda
 @cindex varcoda
 
+@funindex -
+
 A variety of symbols that denote articulations, ornamentations,
 and other performance indications can be attached to a note using
 this syntax:
@@ -69,13 +80,12 @@ this syntax:
 The possible values for @var{name} are listed in @ref{List of
 articulations}.  For example:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 c4\staccato c\mordent b2\turn
 c1\fermata
 @end lilypond
 
 @cindex marcato
-@cindex stopped
 @cindex tenuto
 @cindex staccatissimo
 @cindex accent
@@ -84,71 +94,35 @@ c1\fermata
 
 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,ragged-right,fragment,relative=2]
+consists of a dash @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-|
-c->   c-.  c-_
+c4->  c-.  c2-_
 @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{Controlling direction and placement}.
+@ref{Direction and placement}.
 
 
 @snippets
 
-@c After next LSR update, this snippet can be used
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {modifying-default-values-for-articulation-shorthand-notation.ly}
-
-The shorthands are defined in @file{ly/@/script@/-init@/.ly},
-where the variables @code{dashHat}, @code{dashPlus},
-@code{dashDash}, @code{dashBar}, @code{dashLarger},
-@code{dashDot}, and @code{dashUnderscore} are assigned default
-values.  The default values for the shorthands can be modified.
-For example, to associate the @code{-+} (@code{dashPlus})
-shorthand with the @notation{trill} symbol instead of the default
-@notation{+} symbol, assign the value @code{trill} to the variable
-@code{dashPlus}:
-
-@lilypond[verbatim,quote,ragged-right]
-\relative c'' { c-+ }
-dashPlus = "trill"
-\relative c'' { c-+ }
-@end lilypond
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{modifying-default-values-for-articulation-shorthand-notation.ly}
 
-@c After next LSR update, this snippet can be used
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {controlling-the-vertical-ordering-of-scripts.ly}
-
-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 @notation{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 }
-@end lilypond
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{controlling-the-vertical-ordering-of-scripts.ly}
 
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{creating-a-delayed-turn.ly}
 
 @seealso
-
 Music Glossary:
 @rglos{tenuto},
 @rglos{accent},
@@ -156,7 +130,9 @@ Music Glossary:
 @rglos{portato}.
 
 Notation Reference:
-@ref{Controlling direction and placement}.
+@ref{Direction and placement},
+@ref{List of articulations},
+@ref{Trills}.
 
 Installed Files:
 @file{scm/@/script@/.scm}.
@@ -169,36 +145,49 @@ Internals Reference:
 @rinternals{TextScript}.
 
 
-@knownissues
-
-These signs appear in the printed output but have no effect on the
-MIDI rendering of the music.
-
-
 @node Dynamics
-@subsubsection Dynamics
+@unnumberedsubsubsec Dynamics
 
 @cindex absolute dynamics
 @cindex dynamics
 @cindex dynamics, absolute
+
 @funindex \ppppp
+@funindex ppppp
 @funindex \pppp
+@funindex pppp
 @funindex \ppp
+@funindex ppp
 @funindex \pp
+@funindex pp
 @funindex \p
+@funindex p
 @funindex \mp
+@funindex mp
 @funindex \mf
+@funindex mf
 @funindex \f
+@funindex f
 @funindex \ff
+@funindex ff
 @funindex \fff
+@funindex fff
 @funindex \ffff
+@funindex ffff
 @funindex \fp
+@funindex fp
 @funindex \sf
+@funindex sf
 @funindex \sff
+@funindex sff
 @funindex \sp
+@funindex sp
 @funindex \spp
+@funindex spp
 @funindex \sfz
+@funindex sfz
 @funindex \rfz
+@funindex rfz
 
 Absolute dynamic marks are specified using a command after a note,
 such as @code{c4\ff}.  The available dynamic marks are
@@ -206,32 +195,38 @@ such as @code{c4\ff}.  The available dynamic marks are
 @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{Controlling
-direction and placement}.
+be manually placed above or below the staff, see
+@ref{Direction and placement}.
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 c2\ppp c\mp
-c\rfz c^\mf
-c_\spp c^\ff
+c2\rfz c^\mf
+c2_\spp c^\ff
 @end lilypond
 
 @cindex hairpin
+@cindex crescendo
+@cindex decrescendo
+@cindex diminuendo
+
 @funindex \<
 @funindex \>
 @funindex \!
 @funindex \cr
+@funindex cr
 @funindex \decr
+@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,ragged-right,fragment,relative=2]
+crescendo or decrescendo mark.  A @notation{decrescendo} mark is
+started with @code{\>} and is also terminated with @code{\!}, an
+absolute dynamic, or another crescendo or 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\>
@@ -241,69 +236,94 @@ d2\> d\>
 c1\!
 @end lilypond
 
-Spacer notes are needed to engrave multiple marks on one note.
+Spacer rests are needed to engrave multiple marks on one note.
+
+@cindex multiple dynamic marks on one note
+@cindex dynamic marks, multiple on one note
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 c4\< c\! d\> e\!
 << f1 { s4 s4\< s4\> s4\! } >>
 @end lilypond
 
 @cindex espressivo articulation
 
+@funindex \espressivo
+@funindex espressivo
+
 In some situations the @code{\espressivo} articulation mark may be
-the appropriate choice to indicate a @notation{crescendo} and
-@notation{decrescendo} on one note:
+the appropriate choice to indicate a crescendo and decrescendo on
+one note:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 c2 b4 a
 g1\espressivo
 @end lilypond
 
-@cindex crescendo
-@cindex decrescendo
-@cindex diminuendo
-@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]
-c\< d e f\!
-e\> d c b\!
-\setTextCresc
-c\< d e f\!
-\setTextDecresc
-e\> d c b\!
-\setHairpinCresc
-c\< d e f\!
+
+@funindex \crescTextCresc
+@funindex crescTextCresc
+@funindex \dimTextDecresc
+@funindex dimTextDecresc
+@funindex \dimTextDecr
+@funindex dimTextDecr
+@funindex \dimTextDim
+@funindex dimTextDim
+@funindex \crescHairpin
+@funindex crescHairpin
+@funindex \dimHairpin
+@funindex dimHairpin
+
+Crescendos and decrescendos can be engraved as textual markings
+instead of hairpins.  Dashed lines are printed to indicate their
+extent.  The built-in commands that enable these text modes are
+@code{\crescTextCresc}, @code{\dimTextDecresc},
+@code{\dimTextDecr}, and @code{\dimTextDim}.  The corresponding
+@code{\crescHairpin} and @code{\dimHairpin} commands will revert
+to hairpins again:
+
+@lilypond[verbatim,quote,relative=2]
+\crescTextCresc
+c2\< d | e f\!
+\dimTextDecresc
+e2\> d | c b\!
+\crescHairpin
+c2\< d | e f\!
+\dimHairpin
+e2\> d\!
 @end lilypond
 
+
 To create new absolute dynamic marks or text that should be
 aligned with dynamics, see @ref{New dynamic marks}.
 
+@cindex dynamics, vertical positioning
+@cindex vertical positioning of dynamics
+
+@funindex DynamicLineSpanner
+
+
 Vertical positioning of dynamics is handled by
 @rinternals{DynamicLineSpanner}.
+@funindex \dynamicUp
+@funindex dynamicUp
+@funindex \dynamicDown
+@funindex dynamicDown
+@funindex \dynamicNeutral
+@funindex dynamicNeutral
 
 
 @predefined
-
-@funindex \dynamicUp
 @code{\dynamicUp},
-@funindex \dynamicDown
 @code{\dynamicDown},
-@funindex \dynamicNeutral
-@code{\dynamicNeutral}.
+@code{\dynamicNeutral},
+@code{\crescTextCresc},
+@code{\dimTextDim},
+@code{\dimTextDecr},
+@code{\dimTextDecresc},
+@code{\crescHairpin},
+@code{\dimHairpin}.
+@endpredefined
 
 
 @snippets
@@ -311,103 +331,40 @@ Vertical positioning of dynamics is handled by
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {setting-hairpin-behavior-at-bar-lines.ly}
 
-@c After next LSR update, this snippet can be used
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {setting-the-minimum-length-of-hairpins.ly}
-
-If hairpins are too short, they can be lengthened using the
-following method:
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-c4\< c\! d\> e\!
-\override Voice.Hairpin #'minimum-length = #5
-<< f1 { s4 s4\< s4\> s4\! } >>
-@end lilypond
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{setting-the-minimum-length-of-hairpins.ly}
 
 @cindex al niente
 @cindex niente, al
 
-@c After next LSR update, this snippet can be used
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {printing-hairpins-using-al-niente-notation.ly}
-
-Hairpins may be printed with a circled tip (al niente notation):
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-\override Hairpin #'circled-tip = ##t
-c2\< c\!
-c4\> c\< c2\!
-@end lilypond
-
-@c After next LSR update, this snippet can be used
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {vertically-aligning-dynamics-across-multiple-notes.ly}
-
-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.
-
-@example
-\override DynamicLineSpanner #'staff-padding = #4
-@end example
-
-@c I can't figure this one out.  Consider removing this.  -pm
-
-@notation{Crescendi} and @notation{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
-
-@example
-\override Score.Hairpin #'after-line-breaking = ##t
-@end example
-
-@c After next LSR update, this snippet can be used
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {hiding-the-extender-line-for-text-dynamics.ly}
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{printing-hairpins-using-al-niente-notation.ly}
 
-Text style dynamic changes (such as @notation{cresc.} and
-@notation{dim.}) are printed with a dashed line showing their
-extent.  To suppress printing this line, use
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{vertically-aligned-dynamics-and-textscripts.ly}
 
-@example
-\override DynamicTextSpanner #'dash-period = #-1.0
-@end example
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{hiding-the-extender-line-for-text-dynamics.ly}
 
-@c After next LSR update, this snippet can be used
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {changing-text-and-spanner-styles-for-text-dynamics.ly}
-
-The text used for @notation{crescendos} and
-@notation{decrescendos} can be changed by modifying the context
-properties @code{crescendoText} and @code{decrescendoText}.  The
-style of the spanner line can be changed by modifying the context
-properties @code{crescendoSpanner} 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
-@end lilypond
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{changing-text-and-spanner-styles-for-text-dynamics.ly}
 
 
 @seealso
-
-@c TODO: Add hairpin to glossary.
-
 Music Glossary:
+@rglos{al niente},
 @rglos{crescendo},
-@rglos{decrescendo}.
+@rglos{decrescendo},
+@rglos{hairpin}.
 
 Learning Manual:
 @rlearning{Articulation and dynamics}.
 
 Notation Reference:
-@ref{Controlling direction and placement}.
+@ref{Direction and placement},
+@ref{New dynamic marks},
+@ref{What goes into the MIDI output?},
+@ref{Controlling MIDI dynamics}.
 
 Snippets:
 @rlsr{Expressive marks}.
@@ -419,42 +376,103 @@ Internals Reference:
 
 
 @node New dynamic marks
-@subsubsection New dynamic marks
+@unnumberedsubsubsec New dynamic marks
+
+@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 }
 
-It is possible to print new dynamic marks or text that should be
-aligned with dynamics.  Use @code{make-dynamic-script} to create
-these marks.  Note that the dynamic font only contains the
-characters @code{f,m,p,r,s} and @code{z}.
+\relative c' {
+  <d e>16_\moltoF <d e>
+  <d e>2..
+}
+@end lilypond
 
-Some situations (such as dynamic marks) have preset font-related
-properties.  If you are creating text in such situations, it is
-advisable to cancel those properties with @code{normal-text}.  See
-@ref{Text markup commands}, for more details.
+@cindex dynamics, editorial
+@cindex dynamics, parenthesis
+@cindex editorial dynamics
+@funindex \bracket
+@funindex bracket
+@funindex \dynamic
+@funindex dynamic
+
+In markup mode, editorial dynamics (within parentheses or square
+brackets) can be created.  The syntax for markup mode is described
+in @ref{Formatting text}.
+
+@lilypond[verbatim,quote]
+roundF = \markup { \center-align \concat { \bold { \italic ( }
+           \dynamic f \bold { \italic ) } } }
+boxF = \markup { \bracket { \dynamic f } }
+\relative c' {
+  c1_\roundF
+  c1_\boxF
+}
+@end lilypond
 
 @cindex make-dynamic-script
+@funindex make-dynamic-script
 
-@lilypond[quote,verbatim,ragged-right]
+Simple, centered dynamic marks are easily created with the
+@code{make-dynamic-script} function.  The dynamic font only
+contains the characters @code{f,m,p,r,s} and @code{z}.
+
+@lilypond[verbatim,quote]
 sfzp = #(make-dynamic-script "sfzp")
 \relative c' {
   c4 c c\sfzp c
 }
 @end lilypond
 
-@cindex Dynamics, editorial
-@cindex Dynamics, parenthesis
+In general, @code{make-dynamic-script} takes any markup object as
+its argument.  In the following example, using
+@code{make-dynamic-script} ensures the vertical alignment of
+markup objects and hairpins that are attached to the same note
+head.
+
+@lilypond[verbatim,quote]
+roundF = \markup { \center-align \concat {
+           \normal-text { \bold { \italic ( } }
+           \dynamic f
+           \normal-text { \bold { \italic ) } } } }
+boxF = \markup { \bracket { \dynamic f } }
+roundFdynamic = #(make-dynamic-script roundF)
+boxFdynamic = #(make-dynamic-script boxF)
+\relative c' {
+  c4_\roundFdynamic\< d e f
+  g,1_\boxFdynamic
+}
+@end lilypond
 
-It is also possible to print dynamics in round parenthesis or
-square brackets.  These are often used for adding editorial
-dynamics.
+The Scheme form of markup mode may be used instead.  Its syntax is
+explained in @ref{Markup construction in Scheme}.
 
-@lilypond[quote,verbatim,ragged-right]
-rndf = \markup{ \center-align {\line { \bold{\italic (}
-  \dynamic f \bold{\italic )} }} }
-boxf = \markup{ \bracket { \dynamic f } }
-{ c'1_\rndf c'1_\boxf }
+@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
 
+Font settings in markup mode are described in
+@ref{Selecting font and font size}.
+
+
 @seealso
+Notation Reference:
+@ref{Formatting text},
+@ref{Selecting font and font size},
+@ref{Markup construction in Scheme},
+@ref{What goes into the MIDI output?},
+@ref{Controlling MIDI dynamics}.
 
 Snippets:
 @rlsr{Expressive marks}.
@@ -463,78 +481,126 @@ Snippets:
 @node Curves
 @subsection Curves
 
+This section explains how to create various expressive marks that
+are curved: normal slurs, phrasing slurs, breath marks, falls, and
+doits.
+
 @menu
-* Slurs::                       
-* Phrasing slurs::              
-* Breath marks::                
-* Falls and doits::             
+* Slurs::
+* Phrasing slurs::
+* Breath marks::
+* Falls and doits::
 @end menu
 
 @node Slurs
-@subsubsection Slurs
+@unnumberedsubsubsec Slurs
 
 @cindex slurs
 
-A @notation{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} (@code{Neutral} is the
-default).  Slurs may be manually placed above or below the staff,
-see @ref{Controlling direction and placement}.
+@cindex slurs, manual placement
+@cindex slurs, below notes
+@cindex slurs, above notes
+@funindex \slurDown
+@funindex slurDown
+@funindex \slurNeutral
+@funindex slurNeutral
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-c4_( c) c^( c)
+Slurs may be manually placed above or below the notes, see
+@ref{Direction and placement}.
+
+@lilypond[verbatim,quote,relative=2]
+c2( d)
+\slurDown
+c2( d)
+\slurNeutral
+c2( d)
+@end lilypond
+
+@cindex phrasing slur
+@cindex multiple slurs
+@cindex simultaneous slurs
+@cindex slur, phrasing
+@cindex slurs, multiple
+@cindex slurs, simultaneous
+
+Simultaneous or overlapping slurs are not permitted, but a phrasing
+slur can overlap a slur.  This permits two slurs to be printed at
+once.  For details, see @ref{Phrasing slurs}.
+
+@cindex slur style
+@cindex solid slur
+@cindex dotted slur
+@cindex dashed slur
+@cindex slur, solid
+@cindex slur, dotted
+@cindex slur, dashed
+@cindex solid slur
+@cindex dotted slur
+@cindex dashed slur
+@cindex sytle, slur
+@funindex \slurDashed
+@funindex slurDashed
+@funindex \slurDotted
+@funindex slurDotted
+@funindex \slurSolid
+@funindex slurSolid
+
+Slurs can be solid, dotted, or dashed.  Solid is the default slur
+style:
+
+@lilypond[verbatim,quote,relative=1]
+c4( e g2)
+\slurDashed
+g4( e c2)
+\slurDotted
+c4( e g2)
+\slurSolid
+g4( e c2)
 @end lilypond
 
-Using this method, only one slur can be printed at once.  To print
-a long slur over a few small slurs, see @ref{Phrasing slurs}.
+@funindex \slurUp
+@funindex slurUp
 
 
 @predefined
-
-@funindex \slurUp
 @code{\slurUp},
-@funindex \slurDown
 @code{\slurDown},
-@funindex \slurNeutral
 @code{\slurNeutral},
-@funindex \slurDashed
 @code{\slurDashed},
-@funindex \slurDotted
 @code{\slurDotted},
-@funindex \slurSolid
 @code{\slurSolid}.
+@endpredefined
 
 
 @snippets
 
-@c After next LSR update, this snippet can be used
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {using-double-slurs-for-legato-chords.ly}
-
-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}
 
+@c TODO remove ignores after LSR update
+@ignore
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{positioning-text-markups-inside-slurs}
+@end ignore
 
 @seealso
-
 Music Glossary:
 @rglos{slur}.
 
+Learning Manual:
+@rlearning{On the un-nestedness of brackets and ties}.
+
 Notation Reference:
-@ref{Controlling direction and placement}.
+@ref{Direction and placement},
+@ref{Phrasing slurs}.
 
 Snippets:
 @rlsr{Expressive marks}.
@@ -544,46 +610,88 @@ Internals Reference:
 
 
 @node Phrasing slurs
-@subsubsection Phrasing slurs
+@unnumberedsubsubsec Phrasing slurs
 
 @cindex phrasing slurs
 @cindex phrasing marks
+@cindex slur, phrasing
+@cindex mark, phrasing
 @funindex \(
 @funindex \)
 
-A phrasing slur (or phrasing mark) connects notes and is used to
-indicate a musical sentence.  It is written using @code{\(} and
+@notation{Phrasing slurs} (or 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}.  Phrasing slurs may be manually
-placed above or below the staff, see @ref{Controlling direction
-and placement}.
+@funindex \phrasingSlurUp
+@funindex phrasingSlurUp
+@funindex \phrasingSlurDown
+@funindex phrasingSlurDown
+@funindex \phrasingSlurNeutral
+@funindex phrasingSlurNeutral
+@funindex phrasingSlurDashed
+@funindex \phrasingSlurDashed
+@funindex \phrasingSlurDotted
+@funindex phrasingSlurDotted
+@funindex \phrasingSlurSolid
+@funindex phrasingSlurSolid
+
+Typographically, a 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.  Phrasing
+slurs may be manually placed above or below the notes, see
+@ref{Direction and placement}.
+
+@lilypond[verbatim,quote,relative=1]
+c4\( g' c,( b) | c1\)
+\phrasingSlurUp
+c4\( g' c,( b) | c1\)
+@end lilypond
 
-You cannot have simultaneous phrasing slurs.
+@cindex simultaneous phrasing slurs
+@cindex multiple phrasing slurs
+@cindex slurs, simultaneous phrasing
+@cindex slurs, multiple phrasing
+@cindex phrasing slurs, simultaneous
+@cindex phrasing slurs, multiple
+
+Simultaneous or overlapping phrasing slurs are not permitted.
+
+Phrasing slurs can be solid, dotted, or dashed.  Solid is the default
+style for phrasing slurs:
+
+@lilypond[verbatim,quote,relative=1]
+c4\( e g2\)
+\phrasingSlurDashed
+g4\( e c2\)
+\phrasingSlurDotted
+c4\( e g2\)
+\phrasingSlurSolid
+g4\( e c2\)
+@end lilypond
 
 
 @predefined
-
-@funindex \phrasingSlurUp
 @code{\phrasingSlurUp},
-@funindex \phrasingSlurDown
 @code{\phrasingSlurDown},
-@funindex \phrasingSlurNeutral
-@code{\phrasingSlurNeutral}.
+@code{\phrasingSlurNeutral},
+@code{\phrasingSlurDashed},
+@code{\phrasingSlurDotted},
+@code{\phrasingSlurSolid}.
+@endpredefined
 
 
 @seealso
+Learning Manual:
+@rlearning{On the un-nestedness of brackets and ties}.
 
 Notation Reference:
-@ref{Controlling direction and placement}.
+@ref{Direction and placement}.
 
 Snippets:
 @rlsr{Expressive marks}.
@@ -593,90 +701,84 @@ Internals Reference:
 
 
 @node Breath marks
-@subsubsection Breath marks
+@unnumberedsubsubsec Breath marks
 
 @cindex breath marks
+@cindex pause mark
 @funindex \breathe
+@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,
+divisiones, are supported.  For details, see @ref{Divisiones}.
+
 
 @snippets
 
-@c After next LSR update, this snippet can be used
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {changing-the-breath-mark-symbol.ly}
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{changing-the-breath-mark-symbol.ly}
 
-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,
+@cindex caesura
+@cindex railroad tracks
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
-c'4
-\override BreathingSign #'text
-  = #(make-musicglyph-markup "scripts.rvarcomma")
-\breathe
-d4
-@end lilypond
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{inserting-a-caesura.ly}
 
 
 @seealso
+Music Glossary:
+@rglos{caesura}.
+
+Notation Reference:
+@ref{Divisiones}.
 
 Snippets:
 @rlsr{Expressive marks}.
-@c @lsr{expressive,breathing-sign.ly}.
 
 Internals Reference:
 @rinternals{BreathingSign}.
 
 
 @node Falls and doits
-@subsubsection Falls and doits
+@unnumberedsubsubsec Falls and doits
 
 @cindex falls
 @cindex doits
 @funindex \bendAfter
+@funindex bendAfter
 
 @notation{Falls} and @notation{doits} can be added to notes using
-the @code{\bendAfter} command:
+the @code{\bendAfter} command.  The direction of the fall or doit
+is indicated with a plus or minus (up or down).  The number
+indicates the pitch interval that the fall or doit will extend
+@emph{beyond} the main note.
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 c2-\bendAfter #+4
-c-\bendAfter #-4
-c-\bendAfter #+8
-c-\bendAfter #-8
+c2-\bendAfter #-4
+c2-\bendAfter #+8
+c2-\bendAfter #-8
 @end lilypond
 
-The dash (@tie{-}) following the note name is @emph{required} when
-writing @notation{falls} and @notation{doits}.
+The dash @code{-} immediately preceding the @code{\bendAfter}
+command is @emph{required} when writing falls and doits.
 
 
 @snippets
 
-@c After next LSR update, this snippet can be used
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {adjusting-the-shape-of-falls-and-doits.ly}
-
-The @code{shortest-duration-space} property may have to be tweaked
-to adjust the shape of @notation{falls} and @notation{doits}.
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-\override Score.SpacingSpanner #'shortest-duration-space = #3.0
-c4-\bendAfter #+5
-c4-\bendAfter #-3
-@end lilypond
+@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}.
+Music Glossary:
+@rglos{fall},
+@rglos{doit}.
 
 Snippets:
 @rlsr{Expressive marks}.
@@ -685,203 +787,142 @@ Snippets:
 @node Lines
 @subsection Lines
 
+This section explains how to create various expressive marks that
+follow a linear path: glissandos, arpeggios, and trills.
+
 @menu
-* Glissando::                   
-* Arpeggio::                    
-* Trills::                      
+* Glissando::
+* Arpeggio::
+* Trills::
 @end menu
 
 @node Glissando
-@subsubsection Glissando
+@unnumberedsubsubsec Glissando
 
 @cindex glissando
 @funindex \glissando
+@funindex glissando
 
-A @notation{glissando} is a smooth change in pitch.  It is denoted
-by a line or a wavy line between two notes.  A
-@notation{glissando} is created 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
 
+Different styles of glissandi can be created.  For details, see
+@ref{Line styles}.
 
 @snippets
 
-@c After next LSR update, this snippet can be used
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {suppressing-compiler-warnings-when-two-glissandos-intersect.ly}
-
-@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
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{contemporary-glissando.ly}
 
 
 @seealso
-
 Music Glossary:
 @rglos{glissando}.
 
+Notation Reference:
+@ref{Line styles}.
+
 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:
 @rinternals{Glissando}.
 
 
 @knownissues
 
-Printing text over the line (such as @emph{gliss.}) is not
+Printing text over the line (such as @notation{gliss.}) is not
 supported.
 
 
 @node Arpeggio
-@subsubsection Arpeggio
+@unnumberedsubsubsec Arpeggio
 
 @cindex arpeggio
 @cindex broken chord
+@cindex chord, broken
 
-@c Add documentation for new 'parenthesis' style arpeggio.  Maybe
-@c create a new \arpeggioParen command, or something similar. -pm
-
-You can specify an @notation{arpeggio} (also known as a
-@notation{broken chord}) on a chord by attaching an
-@code{\arpeggio} to the chord:
+@funindex \arpeggio
+@funindex arpeggio
+@funindex \arpeggioArrowUp
+@funindex arpeggioArrowUp
+@funindex \arpeggioArrowDown
+@funindex arpeggioArrowDown
+@funindex \arpeggioNormal
+@funindex arpeggioNormal
+
+An @notation{arpeggio} on a chord (also known as a broken chord)
+is denoted by appending @code{\arpeggio} to the chord construct:
+
+@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
+Different types of arpeggios may be written.
+@code{\arpeggioNormal} reverts to a normal arpeggio:
+
+@lilypond[verbatim,quote,relative=1]
+<c e g c>2\arpeggio
+\arpeggioArrowUp
+<c e g c>2\arpeggio
+\arpeggioArrowDown
+<c e g c>2\arpeggio
+\arpeggioNormal
+<c e g c>2\arpeggio
 @end lilypond
 
-A square bracket on the left, denoted by @code{\arpeggioBracket},
-is used to indicate that the chord should @emph{not} be
-arpeggiated:
+@cindex arpeggio symbols, special
+@cindex special arpeggio symbols
+
+@funindex \arpeggioBracket
+@funindex arpeggioBracket
+@funindex \arpeggioParenthesis
+@funindex arpeggioParenthesis
+
+Special @emph{bracketed} arpeggio symbols can be created:
 
-@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
+\arpeggioParenthesis
+<c e g c>2\arpeggio
+\arpeggioNormal
+<c e g c>2\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
-}
-@end lilypond
+Arpeggios can be explicitly written out with ties.  For more
+information, see @ref{Ties}.
 
-@notation{Arpeggios} can be explicitly written out using
-@notation{ties}.  For more information, see @ref{Ties}.
 
 @predefined
-
-@funindex \arpeggio
 @code{\arpeggio},
-@funindex \arpeggioUp
-@code{\arpeggioUp},
-@funindex \arpeggioDown
-@code{\arpeggioDown},
-@funindex \arpeggioNeutral
-@code{\arpeggioNeutral},
-@funindex \arpeggioBracket
-@code{\arpeggioBracket}.
+@code{\arpeggioArrowUp},
+@code{\arpeggioArrowDown},
+@code{\arpeggioNormal},
+@code{\arpeggioBracket},
+@code{\arpeggioParenthesis}.
+@endpredefined
 
 
 @snippets
 
-@c After next LSR update, this snippet can be used
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {creating-cross--staff-arpeggios-in-a-piano-staff.ly}
-
-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}
 
-@c After next LSR update, this snippet can be used
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {creating-cross--staff-arpeggios-in-other-contexts.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}
 
-@c After next LSR update, this snippet can be used
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {creating-arpeggios-across-notes-in-different-voices.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
-
-@c TODO: Add 'broken chord' to glossary.
-
 Music Glossary:
 @rglos{arpeggio}.
 
@@ -898,68 +939,105 @@ Internals Reference:
 
 @knownissues
 
+@cindex cross-staff parenthesis-style arpeggio
+@cindex arpeggio, parenthesis-style, cross-staff
+@cindex arpeggio, cross-staff parenthesis-style
+
 It is not possible to mix connected arpeggios and unconnected
 arpeggios in one @code{PianoStaff} at the same point in
 time.
 
+The parenthesis-style arpeggio brackets do not work for
+cross-staff arpeggios.
+
 
 @node Trills
-@subsubsection Trills
+@unnumberedsubsubsec Trills
 
 @cindex trills
+
 @funindex \trill
+@funindex trill
+@funindex \startTrillSpan
+@funindex startTrillSpan
+@funindex \stopTrillSpan
+@funindex stopTrillSpan
 
-Short @notation{trills} are printed with @code{\trill} like normal
-articulation; see @ref{Articulations and ornamentations}.
+Short @notation{trills} without an extender line are printed with
+@code{\trill}; see @ref{Articulations and ornamentations}.
+
+Longer trills with an extender line are made with
+@code{\startTrillSpan} and @code{\stopTrillSpan}:
+
+@lilypond[verbatim,quote,relative=2]
+d1~\startTrillSpan
+d1
+c2\stopTrillSpan r2
+@end lilypond
 
-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}.
+In the following example, a trill is combined with grace notes.
+The syntax of this construct and the method to precisely position
+the grace notes are described in @ref{Grace notes}.
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 c1 \afterGrace
-d1\startTrillSpan { c16[\stopTrillSpan d] }
-c4
+d1\startTrillSpan { c32[ d]\stopTrillSpan }
+e2 r2
 @end lilypond
 
 @cindex pitched trills
+@cindex trills, pitched
+@funindex \pitchedTrill
+@funindex pitchedTrill
 
-@notation{Trills} that should be executed on an explicitly
-specified pitch can be typeset with the command
-@code{\pitchedTrill} using the following syntax:
+Trills that require an auxiliary note with an explicit pitch can
+be typeset with the @code{\pitchedTrill} command.  The first
+argument is the main note, and the second is the @emph{trilled}
+note, printed as a stemless note head in parentheses.
 
-@example
-@code{\pitchedTrill} @var{mainnote} @code{\startTrillSpan}
-@var{trillnote} @var{endnote} @code{\stopTrillSpan}
-@end example
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
-\pitchedTrill e2 \startTrillSpan fis
+@lilypond[verbatim,quote,relative=1]
+\pitchedTrill e2\startTrillSpan fis
 d\stopTrillSpan
 @end lilypond
 
-@noindent
-The first argument is the main note.  The pitch of the second is
-printed as a stemless note head in parentheses.
+@cindex pitched trill with forced accidental
+@cindex trill, pitched with forced accidental
+@cindex accidental, forced for pitched trill
+
+In the following example, the second pitched trill is ambiguous;
+the accidental of the trilled note is not printed.  As a
+workaround, the accidentals of the trilled notes can be forced.
+The second measure illustrates this method:
+
+@lilypond[verbatim,quote,relative=2]
+\pitchedTrill eis4\startTrillSpan fis
+g\stopTrillSpan
+\pitchedTrill eis4\startTrillSpan fis
+g\stopTrillSpan
+\pitchedTrill eis4\startTrillSpan fis
+g\stopTrillSpan
+\pitchedTrill eis4\startTrillSpan fis!
+g\stopTrillSpan
+@end lilypond
 
 
 @predefined
-
 @code{\startTrillSpan},
-@funindex \startTrillSpan
 @code{\stopTrillSpan}.
-@funindex \stopTrillSpan
+@endpredefined
 
 
 @seealso
-
 Music Glossary:
 @rglos{trill}.
 
+Notation Reference:
+@ref{Articulations and ornamentations},
+@ref{Grace notes}.
+
 Snippets:
 @rlsr{Expressive marks}.
 
 Internals Reference:
 @rinternals{TrillSpanner}.
+