X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fexpressive.itely;h=40326a0eddf7700193bcb6e7cc75d2c36ee785a2;hb=e7aa6c445f463844dbaa52d38ea4aac2882b5601;hp=9ba59343ff61596117f34ea447c5a6849bdeb39f;hpb=a02ca233bc1a2af11980d8eab1e874c559cdff09;p=lilypond.git

diff --git a/Documentation/notation/expressive.itely b/Documentation/notation/expressive.itely
index 9ba59343ff..40326a0edd 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.12.0"
+@c \version "2.18.0"
 
 @node Expressive marks
 @section Expressive marks
@@ -18,14 +18,14 @@ This section lists various expressive marks that can be
 created in a score.
 
 @menu
-* Attached to notes::
-* Curves::
-* Lines::
+* Expressive marks attached to notes::
+* Expressive marks as curves::
+* Expressive marks as lines::
 @end menu
 
 
-@node Attached to notes
-@subsection Attached to notes
+@node Expressive marks attached to notes
+@subsection Expressive marks attached to notes
 
 This section explains how to create expressive marks that are
 attached to notes: articulations, ornamentations, and dynamics.
@@ -124,8 +124,8 @@ this syntax:
 @var{note}\@var{name}
 @end example
 
-The possible values for @var{name} are listed in @ref{List of
-articulations}.  For example:
+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
@@ -148,12 +148,12 @@ articulation.  Predefined shorthands exist for @notation{marcato},
 Their corresponding output appears as follows:
 
 @lilypond[verbatim,quote,relative=2]
-c4-^ c-+ c-- c-|
+c4-^ c-+ c-- c-!
 c4-> c-. c2-_
 @end lilypond
 
 The rules for the default placement of articulations are defined
-in @file{scm/@/script@/.scm}.  Articulations and ornamentations
+in @file{scm/script.scm}.  Articulations and ornamentations
 may be manually placed above or below the staff; see
 @ref{Direction and placement}.
 
@@ -167,8 +167,8 @@ 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
+\override Script.color = #red
+\override MultiMeasureRestText.color = #blue
 a2\fermata r\fermata
 R1\fermataMarkup
 @end lilypond
@@ -181,13 +181,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
@@ -200,7 +200,6 @@ Music Glossary:
 Learning Manual:
 @rlearning{Placement of objects}.
 
-
 Notation Reference:
 @ref{Text scripts},
 @ref{Direction and placement},
@@ -208,7 +207,7 @@ Notation Reference:
 @ref{Trills}.
 
 Installed Files:
-@file{scm/@/script@/.scm}.
+@file{scm/script.scm}.
 
 Snippets:
 @rlsr{Expressive marks}.
@@ -311,10 +310,33 @@ d2\> d\>
 c1\!
 @end lilypond
 
-Spacer rests are needed to engrave multiple marks on one note.
+A hairpin that is terminated with @code{\!} will end at the
+right edge of the note that has the @code{\!} assigned to it.  In the
+case where it is terminated with the start of another @notation{crescendo}
+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.
+
+@lilypond[verbatim,quote,relative=2]
+c1\< | c4 a c\< a | c4 a c\! a\< | c4 a c a\!
+@end lilypond
+
+Hairpins that are terminated with absolute dynamic marks instead of
+@code{\!} will also be engraved in a similar way.  However, the length
+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
+@end lilypond
 
 @cindex multiple dynamic marks on one note
 @cindex dynamic marks, multiple on one note
+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\!
@@ -326,15 +348,31 @@ c4\< c\! d\> e\!
 @funindex \espressivo
 @funindex espressivo
 
-In some situations the @code{\espressivo} articulation mark may be
-the appropriate choice to indicate a crescendo and decrescendo on
-one note:
+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
 @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\! |
+@end lilypond
 
 @funindex \crescTextCresc
 @funindex crescTextCresc
@@ -349,24 +387,19 @@ g1\espressivo
 @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 @code{\crescTextCresc},
-@code{\dimTextDecresc}, @code{\dimTextDecr}, and @code{\dimTextDim}
-will tell LilyPond to use such textual marks instead of hairpins
-for all subsequent @code{\<} and @code{\>} commands.  The corresponding
-@code{\crescHairpin} and @code{\dimHairpin} commands will revert
-to hairpins again:
-
+Textual marks for dynamic changes can also replace hairpins:
 @lilypond[verbatim,quote,relative=2]
 \crescTextCresc
-c2\< d | e f\!
+c4\< d e f\! |
 \dimTextDecresc
-e2\> d | c b\!
+g4\> e d c\! |
+\dimTextDecr
+e4\> d c b\! |
+\dimTextDim
+d4\> c b a\! |
 \crescHairpin
-c2\< d | e f\!
 \dimHairpin
-e2\> d\!
+c4\< d\! e\> d\! |
 @end lilypond
 
 
@@ -388,6 +421,29 @@ Vertical positioning of dynamics is handled by
 @funindex \dynamicNeutral
 @funindex dynamicNeutral
 
+A @code{Dynamics} context is available to engrave dynamics on
+their own horizontal line.  Use spacer rests to indicate timing.
+(Notes in a @code{Dynamics} context will also take up
+musical time, but will not be engraved.)
+The @code{Dynamics} context can usefully contain some other
+items such as text scripts, text spanners, and piano pedal marks.
+
+@lilypond[verbatim,quote]
+<<
+  \new Staff \relative c' {
+    c2 d4 e |
+    c4 e e,2 |
+    g'4 a g a |
+    c1 |
+  }
+  \new Dynamics {
+    s1\< |
+    s1\f |
+    s2\dim s2-"rit." |
+    s1\p |
+  }
+>>
+@end lilypond
 
 @predefined
 @code{\dynamicUp},
@@ -404,28 +460,37 @@ Vertical positioning of dynamics is handled by
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@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}
 
 @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},
@@ -448,7 +513,8 @@ Snippets:
 Internals Reference:
 @rinternals{DynamicText},
 @rinternals{Hairpin},
-@rinternals{DynamicLineSpanner}.
+@rinternals{DynamicLineSpanner},
+@rinternals{Dynamics}.
 
 
 @node New dynamic marks
@@ -548,10 +614,23 @@ moltoF = #(make-dynamic-script
 }
 @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 c' {
+  <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},
@@ -559,16 +638,15 @@ Notation Reference:
 @ref{What goes into the MIDI output?},
 @ref{Controlling MIDI dynamics}.
 
-Snippets:
-@rlsr{Expressive marks}.
-
-Extend:
+Extending LilyPond:
 @rextend{Markup construction in Scheme}.
 
+Snippets:
+@rlsr{Expressive marks}.
 
 
-@node Curves
-@subsection Curves
+@node Expressive marks as curves
+@subsection Expressive marks as curves
 
 This section explains how to create various expressive marks that
 are curved: normal slurs, phrasing slurs, breath marks, falls, and
@@ -704,16 +782,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}.
@@ -824,7 +901,7 @@ g4\( e c2\)
 @funindex phrasingSlurDashPattern
 @cindex phrasing slur, defining dash patterns
 @cindex slur, phrasing, defining dash patterns
-@cindex slur, definind dash patterns for phrasing
+@cindex slur, defining dash patterns for phrasing
 
 Custom dash patterns for phrasing slurs can be defined:
 
@@ -854,7 +931,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}.
@@ -884,6 +960,12 @@ Breath marks are entered using @code{\breathe}:
 c2. \breathe d4
 @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}.
 
@@ -897,16 +979,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}.
@@ -938,24 +1024,19 @@ 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
+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},
@@ -965,8 +1046,8 @@ Snippets:
 @rlsr{Expressive marks}.
 
 
-@node Lines
-@subsection Lines
+@node Expressive marks as lines
+@subsection Expressive marks as lines
 
 This section explains how to create various expressive marks that
 follow a linear path: glissandos, arpeggios, and trills.
@@ -984,22 +1065,72 @@ follow a linear path: glissandos, arpeggios, and trills.
 @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,
+\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=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'> |
 @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:
@@ -1014,9 +1145,7 @@ Snippets:
 Internals Reference:
 @rinternals{Glissando}.
 
-
 @knownissues
-
 Printing text over the line (such as @notation{gliss.}) is not
 supported.
 
@@ -1108,16 +1237,15 @@ information, see @ref{Ties}.
 
 @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}.
@@ -1134,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
@@ -1145,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
@@ -1247,7 +1373,6 @@ eis4\startTrillSpan fis!
 eis4\stopTrillSpan
 @end lilypond
 
-
 @predefined
 @code{\startTrillSpan},
 @code{\stopTrillSpan}.
@@ -1266,4 +1391,3 @@ Snippets:
 
 Internals Reference:
 @rinternals{TrillSpanner}.
-