]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/user/expressive.itely
lilypond-book robustness: ensure EOL at the end of @verbatim
[lilypond.git] / Documentation / user / expressive.itely
index 9bb34c806c45de194bfd9eaad4b0dcd2b9aeb25a..56904b0067206e54fbdb1b3098d45101105e8ae7 100644 (file)
@@ -6,7 +6,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.51"
+@c \version "2.12.0"
 
 @node Expressive marks
 @section Expressive marks
@@ -17,9 +17,9 @@ 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
 
 
@@ -31,15 +31,16 @@ 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
 @unnumberedsubsubsec Articulations and ornamentations
 
 @cindex articulations
+@cindex ornamentation
 @cindex scripts
 @cindex ornaments
 @cindex espressivo
@@ -48,6 +49,7 @@ Methods to create new dynamic markings are also discussed.
 @cindex downbow
 @cindex foot marks
 @cindex organ pedal marks
+@cindex pedal marks, organ
 @cindex turn
 @cindex open
 @cindex stopped
@@ -65,6 +67,8 @@ Methods to create new dynamic markings are also discussed.
 @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:
@@ -82,7 +86,6 @@ c1\fermata
 @end lilypond
 
 @cindex marcato
-@cindex stopped
 @cindex tenuto
 @cindex staccatissimo
 @cindex accent
@@ -104,7 +107,7 @@ c4->  c-.  c2-_
 
 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
+may be manually placed above or below the staff; see
 @ref{Direction and placement}.
 
 
@@ -116,9 +119,10 @@ may be manually placed above or below the staff, see
 @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},
@@ -127,7 +131,8 @@ Music Glossary:
 
 Notation Reference:
 @ref{Direction and placement},
-@ref{List of articulations}.
+@ref{List of articulations},
+@ref{Trills}.
 
 Installed Files:
 @file{scm/@/script@/.scm}.
@@ -146,33 +151,52 @@ Internals Reference:
 @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
 @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}.
+@code{\spp}, @code{\sfz}, and @code{\rfz}.  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
@@ -181,11 +205,17 @@ 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
@@ -208,6 +238,9 @@ c1\!
 
 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,relative=2]
 c4\< c\! d\> e\!
 << f1 { s4 s4\< s4\> s4\! } >>
@@ -215,6 +248,9 @@ c4\< c\! d\> e\!
 
 @cindex espressivo articulation
 
+@funindex \espressivo
+@funindex espressivo
+
 In some situations the @code{\espressivo} articulation mark may be
 the appropriate choice to indicate a crescendo and decrescendo on
 one note:
@@ -224,9 +260,19 @@ c2 b4 a
 g1\espressivo
 @end lilypond
 
-@cindex crescendo
-@cindex decrescendo
-@cindex diminuendo
+
+@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
@@ -247,33 +293,37 @@ c2\< d | e f\!
 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},
-@funindex \crescTextCresc
 @code{\crescTextCresc},
-@funindex \dimTextDim
 @code{\dimTextDim},
-@funindex \dimTextDecr
 @code{\dimTextDecr},
-@funindex \dimTextDecresc
 @code{\dimTextDecresc},
-@funindex \crescHairpin
 @code{\crescHairpin},
-@funindex \dimHairpin
 @code{\dimHairpin}.
+@endpredefined
 
 
 @snippets
@@ -301,19 +351,20 @@ Vertical positioning of dynamics is handled by
 
 
 @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{Direction and placement},
-@ref{New dynamic marks}.
+@ref{New dynamic marks},
+@ref{What goes into the MIDI output?},
+@ref{Controlling MIDI dynamics}.
 
 Snippets:
 @rlsr{Expressive marks}.
@@ -344,27 +395,31 @@ moltoF = \markup { molto \dynamic f }
 
 @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 { \line { \bold { \italic ( }
-         \dynamic f \bold { \italic ) } } } }
-boxf = \markup { \bracket { \dynamic f } }
+roundF = \markup { \center-align \concat { \bold { \italic ( }
+           \dynamic f \bold { \italic ) } } }
+boxF = \markup { \bracket { \dynamic f } }
 \relative c' {
-  c1_\roundf
-  c1_\boxf
+  c1_\roundF
+  c1_\boxF
 }
 @end lilypond
 
-By default, markup objects are aligned to the left side of a note
-head, but authentic dynamic marks are always centered on the note
-head.  New, centered dynamic marks can be created using the
-following function:
-
 @cindex make-dynamic-script
+@funindex make-dynamic-script
+
+Simple, centered dynamic marks are easily created with the
+@code{make-dynamic-script} function.
 
 @lilypond[verbatim,quote]
 sfzp = #(make-dynamic-script "sfzp")
@@ -373,33 +428,60 @@ sfzp = #(make-dynamic-script "sfzp")
 }
 @end lilypond
 
-@noindent
-The dynamic font only contains the characters @code{f,m,p,r,s} and
-@code{z}.  In order to use other font families, it is necessary to
-use markup mode in its Scheme form, as explained in
-@ref{Markup construction in Scheme}.
+In general, @code{make-dynamic-script} takes any markup object as its
+argument.  The dynamic font only contains the characters
+@code{f,m,p,r,s} and @code{z}, so if a dynamic mark that includes
+plain text or punctuation symbols is desired, markup commands that
+reverts font family and font encoding to normal text should be used,
+for example @code{\normal-text}.  The interest of using
+@code{make-dynamic-script} instead of an ordinary markup is ensuring
+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 } }
+mfEspress = \markup { \center-align \line {
+              \hspace #3.7 mf \normal-text \italic espress. } }
+roundFdynamic = #(make-dynamic-script roundF)
+boxFdynamic = #(make-dynamic-script boxF)
+mfEspressDynamic = #(make-dynamic-script mfEspress)
+\relative c' {
+  c4_\roundFdynamic\< d e f
+  g,1~_\boxFdynamic\>
+  g
+  g'~\mfEspressDynamic
+  g
+}
+@end lilypond
+
+The Scheme form of markup mode may be used instead.  Its syntax is
+explained in @ref{Markup construction in Scheme}.
 
 @lilypond[verbatim,quote]
-moltoF = #(make-dynamic-script (markup 
-                      #:normal-text "molto"
-                      #:dynamic "f"))
+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}.
+@ref{Selecting font and font size}.
 
 
 @seealso
-
 Notation Reference:
 @ref{Formatting text},
-@ref{Common markup commands},
-@ref{Markup construction in Scheme}.
+@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}.
@@ -413,10 +495,10 @@ 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
@@ -432,19 +514,42 @@ a4 g2 f4)
 <c e>2( <b d>2)
 @end lilypond
 
-Slurs may be manually placed above or below the notes, see
-@ref{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,relative=2]
-c2( d)
-\slurDown
-c2( d)
-\slurNeutral
-c2( d)
-@end lilypond
+Slurs may be manually placed above or below the staff; see
+@ref{Direction and placement}.
 
-Phrasing slurs must be used to print more than one slur at once.
-For details, see @ref{Phrasing slurs}.
+@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 slur, solid
+@cindex slur, dotted
+@cindex slur, dashed
+@cindex solid slur
+@cindex dotted slur
+@cindex dashed slur
+@cindex style, 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:
@@ -459,21 +564,59 @@ c4( e g2)
 g4( e c2)
 @end lilypond
 
+@funindex \slurHalfDashed
+@funindex slurHalfDashed
+@funindex \slurHalfSolid
+@funindex slurHalfSolid
+@cindex slur, half dashed and half solid
+
+Slurs can also be made half-dashed (the first half dashed, the
+second half solid) or half-solid (the first half solid, the second
+half dashed):
+
+@lilypond[verbatim,quote,relative=1]
+c4( e g2)
+\slurHalfDashed
+g4( e c2)
+\slurHalfSolid
+c4( e g2)
+\slurSolid
+g4( e c2)
+@end lilypond
+
+@funindex \slurDashPattern
+@funindex slurDashPattern
+@cindex slur, defining dash patterns
+
+Custom dash patterns for slurs can be defined:
+
+@lilypond[verbatim,quote,relative=1]
+c4( e g2)
+\slurDashPattern #0.7 #0.75
+g4( e c2)
+\slurDashPattern #0.5 #2.0
+c4( e g2)
+\slurSolid
+g4( e c2)
+@end lilypond
+
 
-@predefined
 
 @funindex \slurUp
+@funindex slurUp
+
+
+@predefined
 @code{\slurUp},
-@funindex \slurDown
 @code{\slurDown},
-@funindex \slurNeutral
 @code{\slurNeutral},
-@funindex \slurDashed
 @code{\slurDashed},
-@funindex \slurDotted
 @code{\slurDotted},
-@funindex \slurSolid
+@code{\slurHalfDashed},
+@code{\slurHalfSolid},
+@code{\slurDashPattern},
 @code{\slurSolid}.
+@endpredefined
 
 
 @snippets
@@ -481,12 +624,19 @@ g4( e c2)
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {using-double-slurs-for-legato-chords.ly}
 
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{positioning-text-markups-inside-slurs.ly}
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{making-slurs-with-complex-dash-structure.ly}
 
 @seealso
-
 Music Glossary:
 @rglos{slur}.
 
+Learning Manual:
+@rlearning{On the un-nestedness of brackets and ties}.
+
 Notation Reference:
 @ref{Direction and placement},
 @ref{Phrasing slurs}.
@@ -503,6 +653,8 @@ Internals Reference:
 
 @cindex phrasing slurs
 @cindex phrasing marks
+@cindex slur, phrasing
+@cindex mark, phrasing
 @funindex \(
 @funindex \)
 
@@ -515,35 +667,117 @@ c4\( d( e) f(
 e2) d\)
 @end lilypond
 
+@funindex \phrasingSlurUp
+@funindex phrasingSlurUp
+@funindex \phrasingSlurDown
+@funindex phrasingSlurDown
+@funindex \phrasingSlurNeutral
+@funindex phrasingSlurNeutral
+
 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
+may be manually placed above or below the staff; see
 @ref{Direction and placement}.
 
+@cindex simultaneous phrasing slurs
+@cindex multiple phrasing slurs
+@cindex slur, simultaneous phrasing
+@cindex slur, multiple phrasing
+@cindex phrasing slur, simultaneous
+@cindex phrasing slur, multiple
+
+Simultaneous or overlapping phrasing slurs are not permitted.
+
+@funindex phrasingSlurDashed
+@funindex \phrasingSlurDashed
+@funindex \phrasingSlurDotted
+@funindex phrasingSlurDotted
+@funindex \phrasingSlurSolid
+@funindex phrasingSlurSolid
+@cindex phrasing slur, dashed
+@cindex dashed phrasing slur
+@cindex phrasing slur, dotted
+@cindex dotted phrasing slurs
+@cindex slur, dashed phrasing
+@cindex slur, dotted phrasing
+
+Phrasing slurs can be solid, dotted, or dashed.  Solid is the default
+style for phrasing slurs:
+
 @lilypond[verbatim,quote,relative=1]
-c4\( g' c,( b) | c1\)
-\phrasingSlurUp
-c4\( g' c,( b) | c1\)
+c4\( e g2\)
+\phrasingSlurDashed
+g4\( e c2\)
+\phrasingSlurDotted
+c4\( e g2\)
+\phrasingSlurSolid
+g4\( e c2\)
 @end lilypond
 
-Simultaneous phrasing slurs are not permitted.
+@funindex phrasingSlurHalfDashed
+@funindex \phrasingSlurHalfDashed
+@funindex \phrasingSlurHalfSolid
+@funindex phrasingSlurHalfSolid
+@cindex phrasing slur, half solid and half dashed
+@cindex slur, half solid and half dashed phrasing
 
+Phrasing slurs can also be made half-dashed (the first half dashed, the
+second half solid) or half-solid (the first half solid, the second
+half dashed):
 
-@predefined
+@lilypond[verbatim,quote,relative=1]
+c4\( e g2\)
+\phrasingSlurHalfDashed
+g4\( e c2\)
+\phrasingSlurHalfSolid
+c4\( e g2\)
+\phrasingSlurSolid
+g4\( e c2\)
+@end lilypond
 
-@funindex \phrasingSlurUp
+@funindex \phrasingSlurDashPattern
+@funindex phrasingSlurDashPattern
+@cindex phrasing slur, defining dash patterns
+@cindex slur, phrasing, defining dash patterns
+@cindex slur, definind dash patterns for phrasing
+
+Custom dash patterns for phrasing slurs can be defined:
+
+@lilypond[verbatim,quote,relative=1]
+c4\( e g2\)
+\phrasingSlurDashPattern #0.7 #0.75
+g4\( e c2\)
+\phrasingSlurDashPattern #0.5 #2.0
+c4\( e g2\)
+\phrasingSlurSolid
+g4\( e c2\)
+@end lilypond
+
+Dash pattern definitions for phrasing slurs have the same structure
+as dash pattern definitions for slurs.  For more information about
+complex dash patterns, see the snippets under @ref{Slurs}.
+
+@predefined
 @code{\phrasingSlurUp},
-@funindex \phrasingSlurDown
 @code{\phrasingSlurDown},
-@funindex \phrasingSlurNeutral
-@code{\phrasingSlurNeutral}.
+@code{\phrasingSlurNeutral},
+@code{\phrasingSlurDashed},
+@code{\phrasingSlurDotted},
+@code{\phrasingSlurHalfDashed},
+@code{\phrasingSlurHalfSolid},
+@code{\phrasingSlurDashPattern},
+@code{\phrasingSlurSolid}.
+@endpredefined
 
 
 @seealso
+Learning Manual:
+@rlearning{On the un-nestedness of brackets and ties}.
 
 Notation Reference:
-@ref{Direction and placement}.
+@ref{Direction and placement},
+@ref{Slurs}.
 
 Snippets:
 @rlsr{Expressive marks}.
@@ -556,7 +790,9 @@ Internals Reference:
 @unnumberedsubsubsec Breath marks
 
 @cindex breath marks
+@cindex pause mark
 @funindex \breathe
+@funindex breathe
 
 Breath marks are entered using @code{\breathe}:
 
@@ -581,13 +817,14 @@ divisiones, are supported.  For details, see @ref{Divisiones}.
 
 
 @seealso
+Music Glossary:
+@rglos{caesura}.
 
 Notation Reference:
 @ref{Divisiones}.
 
 Snippets:
 @rlsr{Expressive marks}.
-@c @lsr{expressive,breathing-sign.ly}.
 
 Internals Reference:
 @rinternals{BreathingSign}.
@@ -599,6 +836,7 @@ Internals Reference:
 @cindex falls
 @cindex doits
 @funindex \bendAfter
+@funindex bendAfter
 
 @notation{Falls} and @notation{doits} can be added to notes using
 the @code{\bendAfter} command.  The direction of the fall or doit
@@ -624,11 +862,9 @@ command is @emph{required} when writing falls and doits.
 
 
 @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}.
@@ -641,9 +877,9 @@ 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
@@ -651,6 +887,7 @@ follow a linear path: glissandos, arpeggios, and trills.
 
 @cindex glissando
 @funindex \glissando
+@funindex glissando
 
 A @notation{glissando} is created by attaching @code{\glissando}
 to a note:
@@ -670,7 +907,6 @@ Different styles of glissandi can be created.  For details, see
 
 
 @seealso
-
 Music Glossary:
 @rglos{glissando}.
 
@@ -680,17 +916,13 @@ Notation Reference:
 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.
 
 
@@ -701,6 +933,15 @@ supported.
 @cindex broken chord
 @cindex chord, broken
 
+@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:
 
@@ -721,6 +962,16 @@ Different types of arpeggios may be written.
 <c e g c>2\arpeggio
 @end lilypond
 
+@cindex arpeggio symbols, special
+@cindex special arpeggio symbols
+
+@funindex \arpeggioBracket
+@funindex arpeggioBracket
+@funindex \arpeggioParenthesis
+@funindex arpeggioParenthesis
+@funindex \arpeggioParenthesisDashed
+@funindex arpeggioParenthesisDashed
+
 Special @emph{bracketed} arpeggio symbols can be created:
 
 @lilypond[verbatim,quote,relative=1]
@@ -729,27 +980,28 @@ Special @emph{bracketed} arpeggio symbols can be created:
 <c e g c>2\arpeggio
 \arpeggioParenthesis
 <c e g c>2\arpeggio
+\arpeggioParenthesisDashed
+<c e g c>2\arpeggio
 \arpeggioNormal
 <c e g c>2\arpeggio
 @end lilypond
 
+The dash properties of the parenthesis arpeggio are controlled
+with the @code{'dash-details} property, which is described at @ref{Slurs}.
+
 Arpeggios can be explicitly written out with ties.  For more
 information, see @ref{Ties}.
 
-@predefined
 
-@funindex \arpeggio
+@predefined
 @code{\arpeggio},
-@funindex \arpeggioArrowUp
 @code{\arpeggioArrowUp},
-@funindex \arpeggioArrowDown
 @code{\arpeggioArrowDown},
-@funindex \arpeggioNormal
 @code{\arpeggioNormal},
-@funindex \arpeggioBracket
 @code{\arpeggioBracket},
-@funindex \arpeggioParenthesis
-@code{\arpeggioParenthesis}.
+@code{\arpeggioParenthesis}
+@code{\arpeggioParenthesisDashed}.
+@endpredefined
 
 
 @snippets
@@ -765,11 +1017,11 @@ information, see @ref{Ties}.
 
 
 @seealso
-
 Music Glossary:
 @rglos{arpeggio}.
 
 Notation Reference:
+@ref{Slurs},
 @ref{Ties}.
 
 Snippets:
@@ -777,11 +1029,16 @@ Snippets:
 
 Internals Reference:
 @rinternals{Arpeggio},
+@rinternals{Slur},
 @rinternals{PianoStaff}.
 
 
 @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.
@@ -794,16 +1051,29 @@ cross-staff arpeggios.
 @unnumberedsubsubsec Trills
 
 @cindex trills
+
 @funindex \trill
+@funindex trill
+@funindex \startTrillSpan
+@funindex startTrillSpan
+@funindex \stopTrillSpan
+@funindex stopTrillSpan
 
 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}.  In the
-following example, the trill is combined with grace notes.  To
-achieve precise control over the placement of the grace notes, see
-@ref{Grace notes}.
+@code{\startTrillSpan} and @code{\stopTrillSpan}:
+
+@lilypond[verbatim,quote,relative=2]
+d1~\startTrillSpan
+d1
+c2\stopTrillSpan r2
+@end lilypond
+
+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,relative=2]
 c1 \afterGrace
@@ -813,24 +1083,23 @@ e2 r2
 
 @cindex pitched trills
 @cindex trills, pitched
+@funindex \pitchedTrill
+@funindex pitchedTrill
 
 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.
 
-@c This syntax example doesn't look nice. -pm
-
-@c @example
-@c @code{\pitchedTrill} @var{mainnote} @code{\startTrillSpan}
-@c @var{trillnote} @var{endnote} @code{\stopTrillSpan}
-@c @end example
-
 @lilypond[verbatim,quote,relative=1]
 \pitchedTrill e2\startTrillSpan fis
 d\stopTrillSpan
 @end lilypond
 
+@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.
@@ -849,15 +1118,12 @@ g\stopTrillSpan
 
 
 @predefined
-
-@funindex \startTrillSpan
 @code{\startTrillSpan},
-@funindex \stopTrillSpan
 @code{\stopTrillSpan}.
+@endpredefined
 
 
 @seealso
-
 Music Glossary:
 @rglos{trill}.
 
@@ -870,3 +1136,4 @@ Snippets:
 
 Internals Reference:
 @rinternals{TrillSpanner}.
+