X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fexpressive.itely;h=5f89cc66cf47b872b97e0261f5ed1a6370324f90;hb=2fef7b7eb7ac5d7a2ed237bf22a6ec6fe5d946d9;hp=87a1c7ef9f884b5599f3cd185b56793aaa40e2aa;hpb=e90f0536f9be39ada0bef0aeb0d275dec3b2fb5b;p=lilypond.git

diff --git a/Documentation/notation/expressive.itely b/Documentation/notation/expressive.itely
index 87a1c7ef9f..5f89cc66cf 100644
--- a/Documentation/notation/expressive.itely
+++ b/Documentation/notation/expressive.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.14.0"
+@c \version "2.19.21"
 
 @node Expressive marks
 @section Expressive marks
@@ -127,9 +127,11 @@ this syntax:
 The possible values for @code{@var{name}} are listed in
 @ref{List of articulations}.  For example:
 
-@lilypond[verbatim,quote,relative=2]
-c4\staccato c\mordent b2\turn
-c1\fermata
+@lilypond[verbatim,quote]
+\relative {
+  c''4\staccato c\mordent b2\turn
+  c1\fermata
+}
 @end lilypond
 
 @cindex marcato
@@ -147,9 +149,11 @@ articulation.  Predefined shorthands exist for @notation{marcato},
 @notation{accent}, @notation{staccato}, and @notation{portato}.
 Their corresponding output appears as follows:
 
-@lilypond[verbatim,quote,relative=2]
-c4-^ c-+ c-- c-|
-c4-> c-. c2-_
+@lilypond[verbatim,quote]
+\relative {
+  c''4-^ c-+ c-- c-!
+  c4-> c-. c2-_
+}
 @end lilypond
 
 The rules for the default placement of articulations are defined
@@ -166,10 +170,10 @@ command, @code{\fermataMarkup}, is available for attaching a fermata
 to a multi-measure rest (and only a multi-measure rest).  This
 creates a @code{MultiMeasureRestText} object.
 
-@lilypond[verbatim,quote,relative=2]
-\override Script #'color = #red
-\override MultiMeasureRestText #'color = #blue
-a2\fermata r\fermata
+@lilypond[verbatim,quote,fragment]
+\override Script.color = #red
+\override MultiMeasureRestText.color = #blue
+a'2\fermata r\fermata
 R1\fermataMarkup
 @end lilypond
 
@@ -181,13 +185,13 @@ are attached to the notes, see @rlearning{Placement of objects}.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {modifying-default-values-for-articulation-shorthand-notation.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {controlling-the-vertical-ordering-of-scripts.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {creating-a-delayed-turn.ly}
 
 @seealso
@@ -225,43 +229,24 @@ Internals Reference:
 @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 \fffff
-@funindex fffff
 @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
@@ -272,10 +257,12 @@ such as @code{c4\ff}.  The available dynamic marks are
 marks may be manually placed above or below the staff; see
 @ref{Direction and placement}.
 
-@lilypond[verbatim,quote,relative=2]
-c2\ppp c\mp
-c2\rfz c^\mf
-c2_\spp c^\ff
+@lilypond[verbatim,quote]
+\relative c'' {
+  c2\ppp c\mp
+  c2\rfz c^\mf
+  c2_\spp c^\ff
+}
 @end lilypond
 
 @cindex hairpin
@@ -287,9 +274,7 @@ c2_\spp c^\ff
 @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
@@ -300,14 +285,16 @@ absolute dynamic, or another crescendo or decrescendo mark.
 @code{\>}.  @notation{Hairpins} are engraved by default using this
 notation.
 
-@lilypond[verbatim,quote,relative=2]
-c2\< c\!
-d2\< d\f
-e2\< e\>
-f2\> f\!
-e2\> e\mp
-d2\> d\>
-c1\!
+@lilypond[verbatim,quote]
+\relative c'' {
+  c2\< c\!
+  d2\< d\f
+  e2\< e\>
+  f2\> f\!
+  e2\> e\mp
+  d2\> d\>
+  c1\!
+}
 @end lilypond
 
 A hairpin that is terminated with @code{\!} will end at the
@@ -317,10 +304,12 @@ or @notation{decrescendo} mark, it will end at the centre of the note
 that has the next @code{\<} or @code{\>} assigned to it.  The next
 hairpin will then start at the right edge of the same note
 instead of the usual left edge had it been terminated with @code{\!}
-before.
+before.  A hairpin ending on a downbeat will stop at the preceding bar line.
 
-@lilypond[verbatim,quote,relative=2]
-c1\< | c4 a c\< a | c4 a c\! a\< | c4 a c a\!
+@lilypond[verbatim,quote]
+\relative {
+  c''1\< | c4 a c\< a | c4 a c\! a\< | c4 a c a\!
+}
 @end lilypond
 
 Hairpins that are terminated with absolute dynamic marks instead of
@@ -328,8 +317,10 @@ Hairpins that are terminated with absolute dynamic marks instead of
 of the absolute dynamic itself can alter where the preceding hairpin
 ends.
 
-@lilypond[verbatim,quote,relative=2]
-c1\< | c4 a c\mf a | c1\< | c4 a c\ffff a
+@lilypond[verbatim,quote]
+\relative {
+  c''1\< | c4 a c\mf a | c1\< | c4 a c\ffff a
+}
 @end lilypond
 
 @cindex multiple dynamic marks on one note
@@ -338,68 +329,66 @@ Spacer rests are needed to engrave multiple marks on one note.
 This is particularly useful when adding a @notation{crescendo} and
 @notation{decrescendo} to the same note:
 
-@lilypond[verbatim,quote,relative=2]
-c4\< c\! d\> e\!
-<< f1 { s4 s4\< s4\> s4\! } >>
+@lilypond[verbatim,quote]
+\relative {
+  c''4\< c\! d\> e\!
+  << f1 { s4 s4\< s4\> s4\! } >>
+}
 @end lilypond
 
 @cindex espressivo articulation
 
 @funindex \espressivo
-@funindex espressivo
 
 The @code{\espressivo} command can be used to indicate a crescendo
 and decrescendo on the same note.  However, be warned that this is
 implemented as an articulation, not a dynamic.
 
-@lilypond[verbatim,quote,relative=2]
-c2 b4 a
-g1\espressivo
+@lilypond[verbatim,quote]
+\relative {
+  c''2 b4 a
+  g1\espressivo
+}
 @end lilypond
 
 @funindex \cresc
-@funindex cresc
 @funindex \decresc
-@funindex decresc
 @funindex \dim
-@funindex dim
 Textual crescendo marks begin with @code{\cresc}.
 Textual decrescendos begin with @code{\decresc} or @code{\dim}.
 Extender lines are engraved as required.
 
-@lilypond[verbatim,quote,relative=2]
-g8\cresc a b c b c d e\mf |
-f8\decresc e d c e\> d c b |
-a1\dim ~ |
-a2. r4\! |
+@lilypond[verbatim,quote]
+\relative {
+  g'8\cresc a b c b c d e\mf |
+  f8\decresc e d c e\> d c b |
+  a1\dim ~ |
+  a2. r4\! |
+}
 @end lilypond
 
 @funindex \crescTextCresc
-@funindex crescTextCresc
 @funindex \dimTextDecresc
-@funindex dimTextDecresc
 @funindex \dimTextDecr
-@funindex dimTextDecr
 @funindex \dimTextDim
-@funindex dimTextDim
 @funindex \crescHairpin
-@funindex crescHairpin
 @funindex \dimHairpin
-@funindex dimHairpin
 
 Textual marks for dynamic changes can also replace hairpins:
-@lilypond[verbatim,quote,relative=2]
-\crescTextCresc
-c4\< d e f\! |
-\dimTextDecresc
-g4\> e d c\! |
-\dimTextDecr
-e4\> d c b\! |
-\dimTextDim
-d4\> c b a\! |
-\crescHairpin
-\dimHairpin
-c4\< d\! e\> d\! |
+@lilypond[verbatim,quote]
+\relative c'' {
+  \crescTextCresc
+  c4\< d e f\! |
+  \dimTextDecresc
+  g4\> e d c\! |
+  \dimTextDecr
+  e4\> d c b\! |
+  \dimTextDim
+  d4\> c b a\! |
+  \crescHairpin
+  \dimHairpin
+  c4\< d\! e\> d\! |
+}
 @end lilypond
 
 
@@ -415,11 +404,8 @@ aligned with dynamics, see @ref{New dynamic marks}.
 Vertical positioning of dynamics is handled by
 @rinternals{DynamicLineSpanner}.
 @funindex \dynamicUp
-@funindex dynamicUp
 @funindex \dynamicDown
-@funindex dynamicDown
 @funindex \dynamicNeutral
-@funindex dynamicNeutral
 
 A @code{Dynamics} context is available to engrave dynamics on
 their own horizontal line.  Use spacer rests to indicate timing.
@@ -430,8 +416,8 @@ items such as text scripts, text spanners, and piano pedal marks.
 
 @lilypond[verbatim,quote]
 <<
-  \new Staff \relative c' {
-    c2 d4 e |
+  \new Staff \relative {
+    c'2 d4 e |
     c4 e e,2 |
     g'4 a g a |
     c1 |
@@ -460,28 +446,42 @@ items such as text scripts, text spanners, and piano pedal marks.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@cindex hairpins at bar lines
+
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {setting-hairpin-behavior-at-bar-lines.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {setting-the-minimum-length-of-hairpins.ly}
 
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{moving-the-ends-of-hairpins.ly}
+
 @cindex al niente
 @cindex niente, al
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {printing-hairpins-using-al-niente-notation.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@cindex Ferneyhough hairpins
+@cindex hairpins, Ferneyhough
+@cindex flared hairpins
+@cindex hairpins, flared
+@cindex constante hairpins
+@cindex hairpins, constante
+
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{printing-hairpins-in-various-styles.ly}
+
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {vertically-aligned-dynamics-and-textscripts.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {hiding-the-extender-line-for-text-dynamics.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {changing-text-and-spanner-styles-for-text-dynamics.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{al niente},
@@ -495,7 +495,7 @@ Learning Manual:
 Notation Reference:
 @ref{Direction and placement},
 @ref{New dynamic marks},
-@ref{What goes into the MIDI output?},
+@ref{Enhancing MIDI output},
 @ref{Controlling MIDI dynamics}.
 
 Snippets:
@@ -520,8 +520,8 @@ The easiest way to create dynamic indications is to use
 @lilypond[verbatim,quote]
 moltoF = \markup { molto \dynamic f }
 
-\relative c' {
-  <d e>16_\moltoF <d e>
+\relative {
+  <d' e>16_\moltoF <d e>
   <d e>2..
 }
 @end lilypond
@@ -530,9 +530,7 @@ moltoF = \markup { molto \dynamic f }
 @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
@@ -543,8 +541,8 @@ roundF = \markup {
     \center-align \concat { \bold { \italic ( }
            \dynamic f \bold { \italic ) } } }
 boxF = \markup { \bracket { \dynamic f } }
-\relative c' {
-  c1_\roundF
+\relative {
+  c'1_\roundF
   c1_\boxF
 }
 @end lilypond
@@ -557,8 +555,8 @@ Simple, centered dynamic marks are easily created with the
 
 @lilypond[verbatim,quote]
 sfzp = #(make-dynamic-script "sfzp")
-\relative c' {
-  c4 c c\sfzp c
+\relative {
+  c'4 c c\sfzp c
 }
 @end lilypond
 
@@ -583,8 +581,8 @@ mfEspress = \markup { \center-align \line {
 roundFdynamic = #(make-dynamic-script roundF)
 boxFdynamic = #(make-dynamic-script boxF)
 mfEspressDynamic = #(make-dynamic-script mfEspress)
-\relative c' {
-  c4_\roundFdynamic\< d e f
+\relative {
+  c'4_\roundFdynamic\< d e f
   g,1~_\boxFdynamic\>
   g1
   g'1~\mfEspressDynamic
@@ -599,29 +597,41 @@ explained in @rextend{Markup construction in Scheme}.
 moltoF = #(make-dynamic-script
             (markup #:normal-text "molto"
                     #:dynamic "f"))
-\relative c' {
-  <d e>16 <d e>
+\relative {
+  <d' e>16 <d e>
   <d e>2..\moltoF
 }
 @end lilypond
 
+To left-align the dynamic text rather than centering it on a note
+use a @code{\tweak}:
+
+@lilypond[verbatim,quote]
+moltoF = \tweak DynamicText.self-alignment-X #LEFT
+         #(make-dynamic-script
+            (markup #:normal-text "molto"
+                    #:dynamic "f"))
+\relative {
+  <d' e>16 <d e>
+  <d e>2..\moltoF <d e>1
+}
+@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{What goes into the MIDI output?},
+@ref{Enhancing MIDI output},
 @ref{Controlling MIDI dynamics}.
 
-Snippets:
-@rlsr{Expressive marks}.
-
-Extend:
+Extending LilyPond:
 @rextend{Markup construction in Scheme}.
 
+Snippets:
+@rlsr{Expressive marks}.
 
 
 @node Expressive marks as curves
@@ -648,19 +658,19 @@ doits.
 @warning{In polyphonic music, a slur must be terminated
 in the same voice it began.}
 
-@lilypond[verbatim,quote,relative=2]
-f4( g a) a8 b(
-a4 g2 f4)
-<c e>2( <b d>2)
+@lilypond[verbatim,quote]
+\relative {
+  f''4( g a) a8 b(
+  a4 g2 f4)
+  <c e>2( <b d>2)
+}
 @end lilypond
 
 @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 staff; see
 @ref{Direction and placement}.
@@ -671,10 +681,21 @@ Slurs may be manually placed above or below the staff; see
 @cindex slur, phrasing
 @cindex slurs, multiple
 @cindex slurs, simultaneous
+@funindex \=
 
-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}.
+Simultaneous or overlapping slurs require special attention.  Most
+occurences of outer slurs actually indicate phrasing, and phrasing
+slurs may overlap a regular slur, see @ref{Phrasing slurs}.  When
+multiple regular slurs are needed in a single @code{Voice},
+matching slur starts and ends need to be labelled by preceding
+them with @code{\=} followed by an identifying key (a symbol or
+non-negative integer).
+
+@lilypond[verbatim,quote]
+\fixed c' {
+  <c~ f\=1( g\=2( >2 <c e\=1) a\=2) >
+}
+@end lilypond
 
 @cindex slur style
 @cindex slur, solid
@@ -685,65 +706,64 @@ once.  For details, see @ref{Phrasing slurs}.
 @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:
 
-@lilypond[verbatim,quote,relative=1]
-c4( e g2)
-\slurDashed
-g4( e c2)
-\slurDotted
-c4( e g2)
-\slurSolid
-g4( e c2)
+@lilypond[verbatim,quote]
+\relative {
+  c'4( e g2)
+  \slurDashed
+  g4( e c2)
+  \slurDotted
+  c4( e g2)
+  \slurSolid
+  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)
+@lilypond[verbatim,quote]
+\relative {
+  c'4( 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)
+@lilypond[verbatim,quote]
+\relative {
+  c'4( e g2)
+  \slurDashPattern #0.7 #0.75
+  g4( e c2)
+  \slurDashPattern #0.5 #2.0
+  c4( e g2)
+  \slurSolid
+  g4( e c2)
+}
 @end lilypond
 
 
 
 @funindex \slurUp
-@funindex slurUp
 
 
 @predefined
@@ -761,16 +781,15 @@ g4( e c2)
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {using-double-slurs-for-legato-chords.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {positioning-text-markups-inside-slurs.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {making-slurs-with-complex-dash-structure.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{slur}.
@@ -803,17 +822,16 @@ Internals Reference:
 musical sentence are written using the commands @code{\(} and
 @code{\)} respectively:
 
-@lilypond[verbatim,quote,relative=2]
-c4\( d( e) f(
-e2) d\)
+@lilypond[verbatim,quote]
+\relative {
+  c''4\( 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
@@ -828,14 +846,12 @@ may be manually placed above or below the staff; see
 @cindex phrasing slur, simultaneous
 @cindex phrasing slur, multiple
 
-Simultaneous or overlapping phrasing slurs are not permitted.
+Simultaneous or overlapping phrasing slurs are entered using
+@code{\=} as with regular slurs, see @ref{Slurs}.
 
-@funindex phrasingSlurDashed
 @funindex \phrasingSlurDashed
 @funindex \phrasingSlurDotted
-@funindex phrasingSlurDotted
 @funindex \phrasingSlurSolid
-@funindex phrasingSlurSolid
 @cindex phrasing slur, dashed
 @cindex dashed phrasing slur
 @cindex phrasing slur, dotted
@@ -846,20 +862,20 @@ 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\)
+@lilypond[verbatim,quote]
+\relative {
+  c'4\( e g2\)
+  \phrasingSlurDashed
+  g4\( e c2\)
+  \phrasingSlurDotted
+  c4\( e g2\)
+  \phrasingSlurSolid
+  g4\( e c2\)
+}
 @end lilypond
 
-@funindex phrasingSlurHalfDashed
 @funindex \phrasingSlurHalfDashed
 @funindex \phrasingSlurHalfSolid
-@funindex phrasingSlurHalfSolid
 @cindex phrasing slur, half solid and half dashed
 @cindex slur, half solid and half dashed phrasing
 
@@ -867,32 +883,35 @@ 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):
 
-@lilypond[verbatim,quote,relative=1]
-c4\( e g2\)
-\phrasingSlurHalfDashed
-g4\( e c2\)
-\phrasingSlurHalfSolid
-c4\( e g2\)
-\phrasingSlurSolid
-g4\( e c2\)
+@lilypond[verbatim,quote]
+\relative {
+  c'4\( e g2\)
+  \phrasingSlurHalfDashed
+  g4\( e c2\)
+  \phrasingSlurHalfSolid
+  c4\( e g2\)
+  \phrasingSlurSolid
+  g4\( e c2\)
+}
 @end lilypond
 
 @funindex \phrasingSlurDashPattern
-@funindex phrasingSlurDashPattern
 @cindex phrasing slur, defining dash patterns
 @cindex slur, phrasing, defining dash patterns
 @cindex slur, defining 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\)
+@lilypond[verbatim,quote]
+\relative {
+  c'4\( 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
@@ -911,7 +930,6 @@ complex dash patterns, see the snippets under @ref{Slurs}.
 @code{\phrasingSlurSolid}.
 @endpredefined
 
-
 @seealso
 Learning Manual:
 @rlearning{On the un-nestedness of brackets and ties}.
@@ -933,19 +951,24 @@ Internals Reference:
 @cindex breath marks
 @cindex pause mark
 @funindex \breathe
-@funindex breathe
 
 Breath marks are entered using @code{\breathe}:
 
-@lilypond[verbatim,quote,relative=2]
-c2. \breathe d4
+@lilypond[verbatim,quote]
+{ c''2. \breathe d''4 }
 @end lilypond
 
+Unlike other expressive marks, a breath mark is not associated with
+the preceding note but is a separate music event.  So all the
+expressive marks which are attached to the preceding note, any square
+brackets indicating manual beams, and any brackets indicating slurs
+and phrasing slurs must be placed before @code{\breathe}.
+
 A breath mark will end an automatic beam; to override this behavior, see
 @ref{Manual beams}.
 
-@lilypond[verbatim,quote,relative=2]
-c8 \breathe d e f g2
+@lilypond[verbatim,quote]
+\relative { c''8 \breathe d e f g2 }
 @end lilypond
 
 Musical indicators for breath marks in ancient notation,
@@ -954,16 +977,20 @@ divisiones, are supported.  For details, see @ref{Divisiones}.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {changing-the-breath-mark-symbol.ly}
 
+@cindex tick mark
+
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{using-a-tick-as-the-breath-mark-symbol.ly}
+
 @cindex caesura
 @cindex railroad tracks
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {inserting-a-caesura.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{caesura}.
@@ -986,7 +1013,6 @@ 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
@@ -994,25 +1020,22 @@ 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
-c2-\bendAfter #-4
-c2-\bendAfter #+6.5
-c2-\bendAfter #-6.5
-c2-\bendAfter #+8
-c2-\bendAfter #-8
+@lilypond[verbatim,quote]
+\relative c'' {
+  c2\bendAfter #+4
+  c2\bendAfter #-4
+  c2\bendAfter #+6.5
+  c2\bendAfter #-6.5
+  c2\bendAfter #+8
+  c2\bendAfter #-8
+}
 @end lilypond
 
-The dash @code{-} immediately preceding the @code{\bendAfter}
-command is @emph{required} when writing falls and doits.
-
-
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {adjusting-the-shape-of-falls-and-doits.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{fall},
@@ -1039,24 +1062,77 @@ follow a linear path: glissandos, arpeggios, and trills.
 
 @cindex glissando
 @funindex \glissando
-@funindex glissando
 
-A @notation{glissando} is created by attaching @code{\glissando}
+A @notation{glissando} is created by appending @code{\glissando}
 to a note:
 
-@lilypond[verbatim,quote,relative=2]
-g2\glissando g'
-c2\glissando c,
+@lilypond[verbatim,quote]
+\relative {
+  g'2\glissando g'
+  c2\glissando c,
+  \afterGrace f,1\glissando f'16
+}
+@end lilypond
+
+A glissando can connect notes across staves:
+
+@lilypond[verbatim,quote]
+\new PianoStaff <<
+  \new Staff = "right" {
+    e'''2\glissando
+    \change Staff = "left"
+    a,,4\glissando
+    \change Staff = "right"
+    b''8 r |
+  }
+  \new Staff = "left" {
+    \clef bass
+    s1
+  }
+>>
+@end lilypond
+
+A glissando can connect notes in chords.  If anything other than a
+direct one-to-one pairing of the notes in the two chords is required
+the connections between the notes are defined by setting
+@code{\glissandoMap}, where the notes of a chord are assumed to be
+numbered from zero in the order in which they appear in the input
+@file{.ly} file.
+
+@lilypond[verbatim,quote]
+\relative {
+  <c' e>1\glissando g' |
+  <c, e>1\glissando |
+  <g' b> |
+  \break
+  \set glissandoMap = #'((0 . 1) (1 . 0))
+  <c, g'>1\glissando |
+  <d a'> |
+  \set glissandoMap = #'((0 . 0) (0 . 1) (0 . 2))
+  c1\glissando |
+  <d f a> |
+  \set glissandoMap = #'((2 . 0) (1 . 0) (0 . 1))
+  <f d a'>1\glissando |
+  <c c'> |
+}
 @end lilypond
 
 Different styles of glissandi can be created.  For details, see
 @ref{Line styles}.
 
-@snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@snippets
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {contemporary-glissando.ly}
 
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{adding-timing-marks-to-long-glissandi.ly}
+
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{making-glissandi-breakable.ly}
+
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{extending-glissandi-across-repeats.ly}
 
 @seealso
 Music Glossary:
@@ -1071,9 +1147,7 @@ Snippets:
 Internals Reference:
 @rinternals{Glissando}.
 
-
 @knownissues
-
 Printing text over the line (such as @notation{gliss.}) is not
 supported.
 
@@ -1086,67 +1160,65 @@ supported.
 @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:
 
-@lilypond[verbatim,quote,relative=1]
-<c e g c>1\arpeggio
+@lilypond[verbatim,quote]
+\relative { <c' e g c>1\arpeggio }
 @end lilypond
 
 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
+@lilypond[verbatim,quote]
+\relative {
+  <c' e g c>2\arpeggio
 
-\arpeggioArrowUp
-<c e g c>2\arpeggio
+  \arpeggioArrowUp
+  <c e g c>2\arpeggio
 
-\arpeggioArrowDown
-<c e g c>2\arpeggio
+  \arpeggioArrowDown
+  <c e g c>2\arpeggio
 
-\arpeggioNormal
-<c e g c>2\arpeggio
+  \arpeggioNormal
+  <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]
-<c e g c>2
+@lilypond[verbatim,quote]
+\relative {
+  <c' e g c>2
 
-\arpeggioBracket
-<c e g c>2\arpeggio
+  \arpeggioBracket
+  <c e g c>2\arpeggio
 
-\arpeggioParenthesis
-<c e g c>2\arpeggio
+  \arpeggioParenthesis
+  <c e g c>2\arpeggio
 
-\arpeggioParenthesisDashed
-<c e g c>2\arpeggio
+  \arpeggioParenthesisDashed
+  <c e g c>2\arpeggio
 
-\arpeggioNormal
-<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}.
+with the @code{'dash-definition} property, which is described at
+@ref{Slurs}.
 
 Arpeggios can be explicitly written out with ties.  For more
 information, see @ref{Ties}.
@@ -1158,23 +1230,22 @@ information, see @ref{Ties}.
 @code{\arpeggioArrowDown},
 @code{\arpeggioNormal},
 @code{\arpeggioBracket},
-@code{\arpeggioParenthesis}
+@code{\arpeggioParenthesis},
 @code{\arpeggioParenthesisDashed}.
 @endpredefined
 
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {creating-cross-staff-arpeggios-in-a-piano-staff.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {creating-cross-staff-arpeggios-in-other-contexts.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {creating-arpeggios-across-notes-in-different-voices.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{arpeggio}.
@@ -1191,9 +1262,7 @@ Internals Reference:
 @rinternals{Slur},
 @rinternals{PianoStaff}.
 
-
 @knownissues
-
 @cindex cross-staff parenthesis-style arpeggio
 @cindex arpeggio, parenthesis-style, cross-staff
 @cindex arpeggio, cross-staff parenthesis-style
@@ -1202,8 +1271,8 @@ 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.
+The simple way of setting parenthesis-style arpeggio brackets does not work for
+cross-staff arpeggios; see @ref{Cross-staff stems}.
 
 
 @node Trills
@@ -1212,11 +1281,8 @@ cross-staff arpeggios.
 @cindex trills
 
 @funindex \trill
-@funindex trill
 @funindex \startTrillSpan
-@funindex startTrillSpan
 @funindex \stopTrillSpan
-@funindex stopTrillSpan
 
 Short trills without an extender line are printed with
 @code{\trill}; see @ref{Articulations and ornamentations}.
@@ -1224,62 +1290,71 @@ Short trills without an extender line are printed with
 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
+@lilypond[verbatim,quote]
+\relative {
+  d''1\startTrillSpan
+  d1
+  c2\stopTrillSpan
+  r2
+}
 @end lilypond
 
 A trill spanner crossing a line break will restart exactly above
 the first note on the new line.
 
-@lilypond[ragged-right,verbatim,quote,relative=2]
-d1\startTrillSpan
-\break
-d1
-c2\stopTrillSpan
-r2
+@lilypond[ragged-right,verbatim,quote]
+\relative {
+  d''1\startTrillSpan
+  \break
+  d1
+  c2\stopTrillSpan
+  r2
+}
 @end lilypond
 
 Consecutive trill spans will work without explicit
 @code{\stopTrillSpan} commands, since successive trill spanners will
 automatically become the right bound of the previous trill.
 
-@lilypond[verbatim,quote,relative=2]
-d1\startTrillSpan
-d1
-b1\startTrillSpan
-d2\stopTrillSpan
-r2
+@lilypond[verbatim,quote]
+\relative {
+  d''1\startTrillSpan
+  d1
+  b1\startTrillSpan
+  d2\stopTrillSpan
+  r2
+}
 @end lilypond
 
 Trills can also be 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]
-d1~\afterGrace
-d1\startTrillSpan { c32[ d]\stopTrillSpan }
-c2 r2
+@lilypond[verbatim,quote]
+\relative {
+  d''1~\afterGrace
+  d1\startTrillSpan { c32[ d]\stopTrillSpan }
+  c2 r2
+}
 @end lilypond
 
 @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.
 
-@lilypond[verbatim,quote,relative=2]
-\pitchedTrill
-d2\startTrillSpan fis
-d2
-c2\stopTrillSpan
-r2
+@lilypond[verbatim,quote]
+\relative {
+  \pitchedTrill
+  d''2\startTrillSpan fis
+  d2
+  c2\stopTrillSpan
+  r2
+}
 @end lilypond
 
 @cindex pitched trill with accidental
@@ -1289,22 +1364,23 @@ Subsequent accidentals of the same note in the same measure will need
 to be added manually.  Only the accidental of the first pitched trill
 in a measure is printed.
 
-@lilypond[verbatim,quote,relative=2]
-\pitchedTrill
-eis4\startTrillSpan fis
-eis4\stopTrillSpan
-\pitchedTrill
-eis4\startTrillSpan cis
-eis4\stopTrillSpan
-\pitchedTrill
-eis4\startTrillSpan fis
-eis4\stopTrillSpan
-\pitchedTrill
-eis4\startTrillSpan fis!
-eis4\stopTrillSpan
+@lilypond[verbatim,quote]
+\relative {
+  \pitchedTrill
+  eis''4\startTrillSpan fis
+  eis4\stopTrillSpan
+  \pitchedTrill
+  eis4\startTrillSpan cis
+  eis4\stopTrillSpan
+  \pitchedTrill
+  eis4\startTrillSpan fis
+  eis4\stopTrillSpan
+  \pitchedTrill
+  eis4\startTrillSpan fis!
+  eis4\stopTrillSpan
+}
 @end lilypond
 
-
 @predefined
 @code{\startTrillSpan},
 @code{\stopTrillSpan}.
@@ -1323,4 +1399,3 @@ Snippets:
 
 Internals Reference:
 @rinternals{TrillSpanner}.
-