X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fexpressive.itely;h=5f89cc66cf47b872b97e0261f5ed1a6370324f90;hb=07125596018d32e3235e80627915cfac77323272;hp=6d88b53264093a829f672b97dfb813ec5efe8e69;hpb=d47930b56be83c6433a577cb574daee43aa96a84;p=lilypond.git

diff --git a/Documentation/notation/expressive.itely b/Documentation/notation/expressive.itely
index 6d88b53264..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.16.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
 
@@ -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,18 +446,33 @@ items such as text scripts, text spanners, and piano pedal marks.
 
 @snippets
 
+@cindex hairpins at bar lines
+
 @lilypondfile[verbatim,quote,texidoc,doctitle]
 {setting-hairpin-behavior-at-bar-lines.ly}
 
 @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,quote,texidoc,doctitle]
 {printing-hairpins-using-al-niente-notation.ly}
 
+@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}
 
@@ -494,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:
@@ -519,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
@@ -529,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
@@ -542,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
@@ -556,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
 
@@ -582,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
@@ -598,12 +597,26 @@ 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}.
 
@@ -611,7 +624,7 @@ Font settings in markup mode are described in
 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}.
 
 Extending LilyPond:
@@ -645,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}.
@@ -668,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
@@ -682,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
@@ -799,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
@@ -824,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
@@ -842,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
 
@@ -863,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
@@ -928,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,
@@ -952,6 +980,11 @@ divisiones, are supported.  For details, see @ref{Divisiones}.
 @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
 
@@ -980,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
@@ -988,13 +1020,15 @@ 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
 
 @snippets
@@ -1028,15 +1062,16 @@ follow a linear path: glissandos, arpeggios, and trills.
 
 @cindex glissando
 @funindex \glissando
-@funindex glissando
 
 A @notation{glissando} is created by appending @code{\glissando}
 to a note:
 
-@lilypond[verbatim,quote,relative=2]
-g2\glissando g'
-c2\glissando c,
-\afterGrace f,1\glissando f'16
+@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:
@@ -1064,20 +1099,22 @@ the connections between the notes are defined by setting
 numbered from zero in the order in which they appear in the input
 @file{.ly} file.
 
-@lilypond[verbatim,quote,relative=2]
-<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'> |
+@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
@@ -1094,6 +1131,9 @@ Different styles of glissandi can be created.  For details, see
 @lilypondfile[verbatim,quote,texidoc,doctitle]
 {making-glissandi-breakable.ly}
 
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{extending-glissandi-across-repeats.ly}
+
 @seealso
 Music Glossary:
 @rglos{glissando}.
@@ -1120,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}.
@@ -1192,7 +1230,7 @@ information, see @ref{Ties}.
 @code{\arpeggioArrowDown},
 @code{\arpeggioNormal},
 @code{\arpeggioBracket},
-@code{\arpeggioParenthesis}
+@code{\arpeggioParenthesis},
 @code{\arpeggioParenthesisDashed}.
 @endpredefined
 
@@ -1233,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
@@ -1243,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}.
@@ -1255,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
@@ -1320,19 +1364,21 @@ 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