Merge master into nested-bookparts

[lilypond.git] / Documentation / user / expressive.itely

diff --git a/Documentation/user/expressive.itely b/Documentation/user/expressive.itely
index 3321f2e93215da456bfdba37979fab0db138fb2d..65e197b242aa91151223e57abb549d794d9742ff 100644 (file)
--- 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
 
     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}
 
 
 @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
 @menu

-* Attached to notes::           
-* Curves::                      
-* Lines::                       
+* Attached to notes::
+* Curves::
+* Lines::

 @end menu
 
 
 @node Attached to notes
 @subsection Attached to notes
 
 @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
 @menu

-* Articulations and ornamentations::  
-* Dynamics::                    
-* New dynamic marks::           
+* Articulations and ornamentations::
+* Dynamics::
+* New dynamic marks::

 @end menu
 
 @node Articulations and ornamentations
 @end menu
 
 @node Articulations and ornamentations

-@subsubsection Articulations and ornamentations
+@unnumberedsubsubsec Articulations and ornamentations

 
 @cindex articulations
 
 @cindex articulations

+@cindex ornamentation

 @cindex scripts
 @cindex ornaments
 @cindex espressivo
 @cindex scripts
 @cindex ornaments
 @cindex espressivo


@@ -41,6 +49,7 @@
 @cindex downbow
 @cindex foot marks
 @cindex organ pedal marks
 @cindex downbow
 @cindex foot marks
 @cindex organ pedal marks

+@cindex pedal marks, organ

 @cindex turn
 @cindex open
 @cindex stopped
 @cindex turn
 @cindex open
 @cindex stopped


@@ -58,6 +67,8 @@
 @cindex coda
 @cindex varcoda
 
 @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:
 A variety of symbols that denote articulations, ornamentations,
 and other performance indications can be attached to a note using
 this syntax:


@@ -75,7 +86,6 @@ c1\fermata
 @end lilypond
 
 @cindex marcato
 @end lilypond
 
 @cindex marcato

-@cindex stopped

 @cindex tenuto
 @cindex staccatissimo
 @cindex accent
 @cindex tenuto
 @cindex staccatissimo
 @cindex accent


@@ -84,16 +94,15 @@ c1\fermata
 
 Some of these articulations have shorthands for easier entry.
 Shorthands are appended to the note name, and their syntax
 
 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:
+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-|
 
 @lilypond[verbatim,quote,relative=2]
 c4-^  c-+  c--  c-|

-c4->  c-.  c-_
+c4->  c-.  c2-_

 @end lilypond
 
 The rules for the default placement of articulations are defined
 @end lilypond
 
 The rules for the default placement of articulations are defined


@@ -120,7 +129,9 @@ Music Glossary:
 @rglos{portato}.
 
 Notation Reference:
 @rglos{portato}.
 
 Notation Reference:

-@ref{Direction and placement}.
+@ref{Direction and placement},
+@ref{List of articulations},
+@ref{Trills}.

 
 Installed Files:
 @file{scm/@/script@/.scm}.
 
 Installed Files:
 @file{scm/@/script@/.scm}.


@@ -133,36 +144,49 @@ Internals Reference:
 @rinternals{TextScript}.
 
 
 @rinternals{TextScript}.
 
 

-@knownissues
-
-These signs appear in the printed output but have no effect on the
-MIDI rendering of the music.
-
-

 @node Dynamics
 @node Dynamics

-@subsubsection Dynamics
+@unnumberedsubsubsec Dynamics

 
 @cindex absolute dynamics
 @cindex dynamics
 @cindex dynamics, absolute
 
 @cindex absolute dynamics
 @cindex dynamics
 @cindex dynamics, absolute

+

 @funindex \ppppp
 @funindex \ppppp

+@funindex ppppp

 @funindex \pppp
 @funindex \pppp

+@funindex pppp

 @funindex \ppp
 @funindex \ppp

+@funindex ppp

 @funindex \pp
 @funindex \pp

+@funindex pp

 @funindex \p
 @funindex \p

+@funindex p

 @funindex \mp
 @funindex \mp

+@funindex mp

 @funindex \mf
 @funindex \mf

+@funindex mf

 @funindex \f
 @funindex \f

+@funindex f

 @funindex \ff
 @funindex \ff

+@funindex ff

 @funindex \fff
 @funindex \fff

+@funindex fff

 @funindex \ffff
 @funindex \ffff

+@funindex ffff

 @funindex \fp
 @funindex \fp

+@funindex fp

 @funindex \sf
 @funindex \sf

+@funindex sf

 @funindex \sff
 @funindex \sff

+@funindex sff

 @funindex \sp
 @funindex \sp

+@funindex sp

 @funindex \spp
 @funindex \spp

+@funindex spp

 @funindex \sfz
 @funindex \sfz

+@funindex sfz

 @funindex \rfz
 @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
 
 Absolute dynamic marks are specified using a command after a note,
 such as @code{c4\ff}.  The available dynamic marks are


@@ -170,7 +194,7 @@ 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
 @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 
+be manually placed above or below the staff, see

 @ref{Direction and placement}.
 
 @lilypond[verbatim,quote,relative=2]
 @ref{Direction and placement}.
 
 @lilypond[verbatim,quote,relative=2]


@@ -180,20 +204,26 @@ c2_\spp c^\ff
 @end lilypond
 
 @cindex hairpin
 @end lilypond
 
 @cindex hairpin

+@cindex crescendo
+@cindex decrescendo
+@cindex diminuendo
+

 @funindex \<
 @funindex \>
 @funindex \!
 @funindex \cr
 @funindex \<
 @funindex \>
 @funindex \!
 @funindex \cr

+@funindex cr

 @funindex \decr
 @funindex \decr

+@funindex decr

 
 A @notation{crescendo} mark is started with @code{\<} and
 terminated with @code{\!}, an absolute dynamic, or an additional
 
 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.
+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\!
 
 @lilypond[verbatim,quote,relative=2]
 c2\< c\!


@@ -205,7 +235,10 @@ d2\> d\>
 c1\!
 @end lilypond
 
 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,relative=2]
 c4\< c\! d\> e\!
 
 @lilypond[verbatim,quote,relative=2]
 c4\< c\! d\> e\!


@@ -214,60 +247,82 @@ c4\< c\! d\> e\!
 
 @cindex espressivo articulation
 
 
 @cindex espressivo articulation
 

+@funindex \espressivo
+@funindex espressivo
+

 In some situations the @code{\espressivo} articulation mark may be
 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,relative=2]
 c2 b4 a
 g1\espressivo
 @end lilypond
 
 
 @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:
+
+@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]
 
 @lilypond[verbatim,quote,relative=2]

-c4\< d e f\!
-e4\> d c b\!
-\setTextCresc
-c4\< d e f\!
-\setTextDecresc
-e4\> d c b\!
-\setHairpinCresc
-c4\< d e f\!
+\crescTextCresc
+c2\< d | e f\!
+\dimTextDecresc
+e2\> d | c b\!
+\crescHairpin
+c2\< d | e f\!
+\dimHairpin
+e2\> d\!

 @end lilypond
 
 @end lilypond
 

+

 To create new absolute 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}.
 

+@cindex dynamics, vertical positioning
+@cindex vertical positioning of dynamics
+
+@funindex DynamicLineSpanner
+
+

 Vertical positioning of dynamics is handled by
 @rinternals{DynamicLineSpanner}.
 Vertical positioning of dynamics is handled by
 @rinternals{DynamicLineSpanner}.

+@funindex \dynamicUp
+@funindex dynamicUp
+@funindex \dynamicDown
+@funindex dynamicDown
+@funindex \dynamicNeutral
+@funindex dynamicNeutral

 
 
 @predefined
 
 
 
 @predefined
 

-@funindex \dynamicUp

 @code{\dynamicUp},
 @code{\dynamicUp},

-@funindex \dynamicDown

 @code{\dynamicDown},
 @code{\dynamicDown},

-@funindex \dynamicNeutral
-@code{\dynamicNeutral}.
+@code{\dynamicNeutral},
+@code{\crescTextCresc},
+@code{\dimTextDim},
+@code{\dimTextDecr},
+@code{\dimTextDecresc},
+@code{\crescHairpin},
+@code{\dimHairpin}.

 
 
 @snippets
 
 
 @snippets


@@ -285,7 +340,7 @@ Vertical positioning of dynamics is handled by
 {printing-hairpins-using-al-niente-notation.ly}
 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {printing-hairpins-using-al-niente-notation.ly}
 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]

-{vertically-aligning-dynamics-across-multiple-notes.ly}
+{vertically-aligned-dynamics-and-textscripts.ly}

 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {hiding-the-extender-line-for-text-dynamics.ly}
 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {hiding-the-extender-line-for-text-dynamics.ly}


@@ -296,17 +351,20 @@ Vertical positioning of dynamics is handled by
 
 @seealso
 
 
 @seealso
 

-@c TODO: Add hairpin to glossary.
-

 Music Glossary:
 Music Glossary:

+@rglos{al niente},

 @rglos{crescendo},
 @rglos{crescendo},

-@rglos{decrescendo}.
+@rglos{decrescendo},
+@rglos{hairpin}.

 
 Learning Manual:
 @rlearning{Articulation and dynamics}.
 
 Notation Reference:
 
 Learning Manual:
 @rlearning{Articulation and dynamics}.
 
 Notation Reference:

-@ref{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}.
 
 Snippets:
 @rlsr{Expressive marks}.


@@ -318,7 +376,7 @@ Internals Reference:
 
 
 @node New dynamic marks
 
 
 @node New dynamic marks

-@subsubsection New dynamic marks
+@unnumberedsubsubsec New dynamic marks

 
 @cindex new dynamic marks
 @cindex dynamic marks, new
 
 @cindex new dynamic marks
 @cindex dynamic marks, new


@@ -330,33 +388,39 @@ The easiest way to create dynamic indications is to use
 moltoF = \markup { molto \dynamic f }
 
 \relative c' {
 moltoF = \markup { molto \dynamic f }
 
 \relative c' {

-  <d e>16 <d e>
-  <d e>2.._\moltoF
+  <d e>16_\moltoF <d e>
+  <d e>2..

 }
 @end lilypond
 
 @cindex dynamics, editorial
 @cindex dynamics, parenthesis
 }
 @end lilypond
 
 @cindex dynamics, editorial
 @cindex dynamics, parenthesis

+@cindex editorial dynamics
+@funindex \bracket
+@funindex bracket
+@funindex \dynamic
+@funindex dynamic

 
 

-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}.
+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]
 
 @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' {
 \relative c' {

-  c1_\roundf
-  c1_\boxf
+  c1_\roundF
+  c1_\boxF

 }
 @end lilypond
 
 }
 @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
 @cindex make-dynamic-script

+@funindex make-dynamic-script
+
+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")
 
 @lilypond[verbatim,quote]
 sfzp = #(make-dynamic-script "sfzp")


@@ -365,33 +429,51 @@ sfzp = #(make-dynamic-script "sfzp")
 }
 @end lilypond
 
 }
 @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
+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
+
+The Scheme form of markup mode may be used instead.  Its syntax is

 explained in @ref{Markup construction in Scheme}.
 
 @lilypond[verbatim,quote]
 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
 
 \relative c' {
   <d e>16 <d e>
   <d e>2..\moltoF
 }
 @end lilypond
 

-@noindent

 Font settings in markup mode are described in
 Font settings in markup mode are described in

-@ref{Common markup commands}.
+@ref{Selecting font and font size}.

 
 
 @seealso
 
 Notation Reference:
 @ref{Formatting text},
 
 
 @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}.
 
 Snippets:
 @rlsr{Expressive marks}.


@@ -400,6 +482,10 @@ Snippets:
 @node Curves
 @subsection Curves
 
 @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::              
 @menu
 * Slurs::                       
 * Phrasing slurs::              


@@ -408,7 +494,7 @@ Snippets:
 @end menu
 
 @node Slurs
 @end menu
 
 @node Slurs

-@subsubsection Slurs
+@unnumberedsubsubsec Slurs

 
 @cindex slurs
 
 
 @cindex slurs
 


@@ -420,11 +506,16 @@ a4 g2 f4)
 <c e>2( <b d>2)
 @end lilypond
 
 <c e>2( <b d>2)
 @end lilypond
 

-The direction of a @notation{slur} can be specified with
-@code{\slurUp} or @code{\slurDown}.  The @code{\slurNeutral}
-command reverts back to the default slur direction.
-@notation{Slurs} may be manually placed above or below the staff,
-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
+
+Slurs may be manually placed above or below the notes, see
+@ref{Direction and placement}.

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


@@ -434,9 +525,36 @@ c2( d)
 c2( d)
 @end lilypond
 
 c2( d)
 @end lilypond
 

-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}
+@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]
 style:
 
 @lilypond[verbatim,quote,relative=1]


@@ -449,24 +567,16 @@ c4( e g2)
 g4( e c2)
 @end lilypond
 
 g4( e c2)
 @end lilypond
 

-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}.
-
+@funindex \slurUp
+@funindex slurUp

 
 @predefined
 
 
 @predefined
 

-@funindex \slurUp

 @code{\slurUp},
 @code{\slurUp},

-@funindex \slurDown

 @code{\slurDown},
 @code{\slurDown},

-@funindex \slurNeutral

 @code{\slurNeutral},
 @code{\slurNeutral},

-@funindex \slurDashed

 @code{\slurDashed},
 @code{\slurDashed},

-@funindex \slurDotted

 @code{\slurDotted},
 @code{\slurDotted},

-@funindex \slurSolid

 @code{\slurSolid}.
 
 
 @code{\slurSolid}.
 
 


@@ -481,8 +591,12 @@ one or more small slurs.  For details, see @ref{Phrasing slurs}.
 Music Glossary:
 @rglos{slur}.
 
 Music Glossary:
 @rglos{slur}.
 

+Learning Manual:
+@rlearning{On the un-nestedness of brackets and ties}.
+

 Notation Reference:
 Notation Reference:

-@ref{Direction and placement}.
+@ref{Direction and placement},
+@ref{Phrasing slurs}.

 
 Snippets:
 @rlsr{Expressive marks}.
 
 Snippets:
 @rlsr{Expressive marks}.


@@ -492,29 +606,36 @@ Internals Reference:
 
 
 @node Phrasing slurs
 
 
 @node Phrasing slurs

-@subsubsection Phrasing slurs
+@unnumberedsubsubsec Phrasing slurs

 
 @cindex phrasing slurs
 @cindex phrasing marks
 
 @cindex phrasing slurs
 @cindex phrasing marks

+@cindex slur, phrasing
+@cindex mark, phrasing

 @funindex \(
 @funindex \)
 
 @funindex \(
 @funindex \)
 

-@notation{Phrasing slurs} (or @notation{phrasing marks}) that
-indicate a musical sentence are written using the commands
-@code{\(} and @code{\)} respectively:
+@notation{Phrasing slurs} (or phrasing marks) that indicate a
+musical sentence are written using the commands @code{\(} and
+@code{\)} respectively:

 
 @lilypond[verbatim,quote,relative=2]
 c4\( d( e) f(
 e2) d\)
 @end lilypond
 
 
 @lilypond[verbatim,quote,relative=2]
 c4\( d( e) f(
 e2) d\)
 @end lilypond
 

-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}.  The commands @code{\phrasingSlurUp},
-@code{\phrasingSlurDown}, and @code{\phrasingSlurNeutral} are used
-instead.  Phrasing slurs may be manually placed above or below the
-staff, see @ref{Direction and placement}.
+@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
+@ref{Direction and placement}.

 
 @lilypond[verbatim,quote,relative=1]
 c4\( g' c,( b) | c1\)
 
 @lilypond[verbatim,quote,relative=1]
 c4\( g' c,( b) | c1\)


@@ -522,21 +643,28 @@ c4\( g' c,( b) | c1\)
 c4\( g' c,( b) | c1\)
 @end lilypond
 
 c4\( g' c,( b) | c1\)
 @end lilypond
 

-Simultaneous phrasing slurs are not permitted.
+@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.

 
 
 @predefined
 
 
 
 @predefined
 

-@funindex \phrasingSlurUp

 @code{\phrasingSlurUp},
 @code{\phrasingSlurUp},

-@funindex \phrasingSlurDown

 @code{\phrasingSlurDown},
 @code{\phrasingSlurDown},

-@funindex \phrasingSlurNeutral

 @code{\phrasingSlurNeutral}.
 
 
 @seealso
 
 @code{\phrasingSlurNeutral}.
 
 
 @seealso
 

+Learning Manual:
+@rlearning{On the un-nestedness of brackets and ties}.
+

 Notation Reference:
 @ref{Direction and placement}.
 
 Notation Reference:
 @ref{Direction and placement}.
 


@@ -548,10 +676,12 @@ Internals Reference:
 
 
 @node Breath marks
 
 
 @node Breath marks

-@subsubsection Breath marks
+@unnumberedsubsubsec Breath marks

 
 @cindex breath marks
 
 @cindex breath marks

+@cindex pause mark

 @funindex \breathe
 @funindex \breathe

+@funindex breathe

 
 Breath marks are entered using @code{\breathe}:
 
 
 Breath marks are entered using @code{\breathe}:
 


@@ -559,32 +689,50 @@ Breath marks are entered using @code{\breathe}:
 c2. \breathe d4
 @end lilypond
 
 c2. \breathe d4
 @end lilypond
 

+Musical indicators for breath marks in ancient notation,
+divisiones, are supported.  For details, see @ref{Divisiones}.
+

 
 @snippets
 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {changing-the-breath-mark-symbol.ly}
 
 
 @snippets
 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {changing-the-breath-mark-symbol.ly}
 

+@cindex caesura
+@cindex railroad tracks
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{inserting-a-caesura.ly}
+

 
 @seealso
 
 
 @seealso
 

+Music Glossary: 
+@rglos{caesura}.
+
+Notation Reference:
+@ref{Divisiones}.
+

 Snippets:
 @rlsr{Expressive marks}.
 Snippets:
 @rlsr{Expressive marks}.

-@c @lsr{expressive,breathing-sign.ly}.

 
 Internals Reference:
 @rinternals{BreathingSign}.
 
 
 @node Falls and doits
 
 Internals Reference:
 @rinternals{BreathingSign}.
 
 
 @node Falls and doits

-@subsubsection Falls and doits
+@unnumberedsubsubsec Falls and doits

 
 @cindex falls
 @cindex doits
 @funindex \bendAfter
 
 @cindex falls
 @cindex doits
 @funindex \bendAfter

+@funindex bendAfter

 
 @notation{Falls} and @notation{doits} can be added to notes using
 
 @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,relative=2]
 c2-\bendAfter #+4
 
 @lilypond[verbatim,quote,relative=2]
 c2-\bendAfter #+4


@@ -593,9 +741,8 @@ c2-\bendAfter #+8
 c2-\bendAfter #-8
 @end lilypond
 
 c2-\bendAfter #-8
 @end lilypond
 

-The dash (@tie{-}) immediately preceding the @code{\bendAfter}
-command 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
 
 
 @snippets


@@ -606,10 +753,9 @@ command is @emph{required} when writing @notation{falls} and
 
 @seealso
 
 
 @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}.
 
 Snippets:
 @rlsr{Expressive marks}.


@@ -618,42 +764,37 @@ Snippets:
 @node Lines
 @subsection Lines
 
 @node Lines
 @subsection Lines
 

+This section explains how to create various expressive marks that
+follow a linear path: glissandos, arpeggios, and trills.
+

 @menu
 @menu

-* Glissando::                   
-* Arpeggio::                    
-* Trills::                      
+* Glissando::
+* Arpeggio::
+* Trills::

 @end menu
 
 @node Glissando
 @end menu
 
 @node Glissando

-@subsubsection Glissando
+@unnumberedsubsubsec Glissando

 
 @cindex glissando
 @funindex \glissando
 
 @cindex glissando
 @funindex \glissando

+@funindex glissando

 
 A @notation{glissando} is created by attaching @code{\glissando}
 to a note:
 
 @lilypond[verbatim,quote,relative=2]
 
 A @notation{glissando} is created by attaching @code{\glissando}
 to a note:
 
 @lilypond[verbatim,quote,relative=2]

-c2\glissando c'
-\override Glissando #'style = #'zigzag
+g2\glissando g'

 c2\glissando c,
 @end lilypond
 
 c2\glissando c,
 @end lilypond
 

+Different styles of glissandi can be created.  For details, see
+@ref{Line styles}.

 
 @snippets
 
 
 @snippets
 

-@c Modify, add description, and put in input/new/
-@c @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
-@c {suppressing-warnings-for-clashing-note-columns.ly}
-
-@lilypond[verbatim,quote]
-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
 
 
 @seealso


@@ -661,96 +802,89 @@ I = \once \override NoteColumn #'ignore-collision = ##t
 Music Glossary:
 @rglos{glissando}.
 
 Music Glossary:
 @rglos{glissando}.
 

+Notation Reference:
+@ref{Line styles}.
+

 Snippets:
 @rlsr{Expressive marks}.
 
 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
 
 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
 supported.
 
 
 @node Arpeggio

-@subsubsection Arpeggio
+@unnumberedsubsubsec Arpeggio

 
 @cindex arpeggio
 @cindex broken chord
 @cindex chord, broken
 
 
 @cindex arpeggio
 @cindex broken chord
 @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:
+@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,relative=1]
 <c e g c>1\arpeggio
 @end lilypond
 

-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}:
+Different types of arpeggios may be written.
+@code{\arpeggioNormal} reverts to a normal arpeggio:

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

-\arpeggioUp

 <c e g c>2\arpeggio
 <c e g c>2\arpeggio

-\arpeggioDown
+\arpeggioArrowUp

 <c e g c>2\arpeggio
 <c e g c>2\arpeggio

-\arpeggioNeutral
-<c e g c>1\arpeggio
-@end lilypond
-
-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,relative=1]
-<c e g c>2
-\arpeggioBracket
+\arpeggioArrowDown
+<c e g c>2\arpeggio
+\arpeggioNormal

 <c e g c>2\arpeggio
 <c e g c>2\arpeggio

-\arpeggioNeutral
-<c e g c>1\arpeggio

 @end lilypond
 
 @end lilypond
 

-A @emph{parenthesis} style bracket may be attached to an
-@notation{arpeggio} instead of a square bracket.
+@cindex arpeggio symbols, special
+@cindex special arpeggio symbols
+
+@funindex \arpeggioBracket
+@funindex arpeggioBracket
+@funindex \arpeggioParenthesis
+@funindex arpeggioParenthesis

 
 

-@c Maybe create a new \arpeggioParen command, or something
-@c like that. -pm
+Special @emph{bracketed} arpeggio symbols can be created:

 
 @lilypond[verbatim,quote,relative=1]
 <c e g c>2
 
 @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
+\arpeggioBracket
+<c e g c>2\arpeggio
+\arpeggioParenthesis
+<c e g c>2\arpeggio
+\arpeggioNormal

 <c e g c>2\arpeggio
 <c e g c>2\arpeggio

-\arpeggioNeutral
-<c e g c>1\arpeggio

 @end lilypond
 
 @end lilypond
 

-@notation{Arpeggios} can be explicitly written out with
-@notation{ties}.  For more information, see @ref{Ties}.
+Arpeggios can be explicitly written out with ties.  For more
+information, see @ref{Ties}.

 
 @predefined
 
 
 @predefined
 

-@funindex \arpeggio

 @code{\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}.

 
 
 @snippets
 
 
 @snippets


@@ -767,8 +901,6 @@ A @emph{parenthesis} style bracket may be attached to an
 
 @seealso
 
 
 @seealso
 

-@c TODO: Add 'broken chord' to glossary.
-

 Music Glossary:
 @rglos{arpeggio}.
 
 Music Glossary:
 @rglos{arpeggio}.
 


@@ -785,60 +917,92 @@ Internals Reference:
 
 @knownissues
 
 
 @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.
 
 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
 
 @node Trills

-@subsubsection Trills
+@unnumberedsubsubsec Trills

 
 @cindex trills
 
 @cindex trills

+

 @funindex \trill
 @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}.

 
 

-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}.
+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
+
+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
 
 @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
 @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:
-
-@example
-@code{\pitchedTrill} @var{mainnote} @code{\startTrillSpan}
-@var{trillnote} @var{endnote} @code{\stopTrillSpan}
-@end example
+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.

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

-\pitchedTrill e2 \startTrillSpan fis
+\pitchedTrill e2\startTrillSpan fis

 d\stopTrillSpan
 @end lilypond
 
 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},
 
 
 @predefined
 
 @code{\startTrillSpan},

-@funindex \startTrillSpan

 @code{\stopTrillSpan}.
 @code{\stopTrillSpan}.

-@funindex \stopTrillSpan

 
 
 @seealso
 
 
 @seealso


@@ -846,8 +1010,13 @@ printed as a stemless note head in parentheses.
 Music Glossary:
 @rglos{trill}.
 
 Music Glossary:
 @rglos{trill}.
 

+Notation Reference:
+@ref{Articulations and ornamentations},
+@ref{Grace notes}.
+

 Snippets:
 @rlsr{Expressive marks}.
 
 Internals Reference:
 @rinternals{TrillSpanner}.
 Snippets:
 @rlsr{Expressive marks}.
 
 Internals Reference:
 @rinternals{TrillSpanner}.

+