Update for expressive.itely

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

diff --git a/Documentation/user/expressive.itely b/Documentation/user/expressive.itely
index 8cc02866781c2c1146ff4bb26ea4e9d107068cf7..5f4f3f03963ce2c4842eeaf817979bfb2760f832 100644 (file)
--- a/Documentation/user/expressive.itely
+++ b/Documentation/user/expressive.itely
@@ -6,11 +6,15 @@
     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"
+

 @node Expressive marks
 @section Expressive marks
 
 @node Expressive marks
 @section Expressive marks
 

-@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
-{expressive-headword.ly}
+@lilypondfile[quote]{expressive-headword.ly}
+
+This section lists various expressive marks that can be
+created in a score.

 
 @menu
 * Attached to notes::           
 
 @menu
 * Attached to notes::           


@@ -22,58 +26,24 @@
 @node Attached to notes
 @subsection Attached to notes
 
 @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
 * Articulations and ornamentations::  
 * Dynamics::                    
 
 @menu
 * Articulations and ornamentations::  
 * Dynamics::                    

+* New dynamic marks::           

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

-@cindex Articulations
+@cindex articulations

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

-
-A variety of symbols can appear above and below notes to indicate
-different characteristics of the performance.  All these symbols
-can be attached to a note using the syntax @var{note}@code{\}@var{name}. 
-
-The possible values for @var{name} are listed in @ref{List of
-articulations}.
-
-Some of these articulations have shorthands for easier entry.  They
-are used by adding a dash and the character signifying
-the articulation to the note name.  The available shorthands and
-their output are:
-
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-c4-.  c--   c-+   c-|   
-c->   c-^   c-_         
-@end lilypond
-
-The marks are automatically placed, but the direction can be
-forced as well.  Like other pieces of LilyPond code, @code{_} will
-place them below the staff, and @code{^} will place them above.
-This applies both to the shorthands and the fully named
-articulations.  For the shorthands, the dash itself should be
-omitted; the shorthand signs replace it:
-
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-c4^^ c4_^
-c\fermata c^\fermata c_\fermata
-@end lilypond
-
-
-@cindex accent
-@cindex marcato
-@cindex staccatissimo

 @cindex espressivo
 @cindex fermata
 @cindex espressivo
 @cindex fermata

-@cindex stopped
-@cindex staccato
-@cindex portato
-@cindex tenuto

 @cindex upbow
 @cindex downbow
 @cindex foot marks
 @cindex upbow
 @cindex downbow
 @cindex foot marks


@@ -95,77 +65,83 @@ c\fermata c^\fermata c_\fermata
 @cindex coda
 @cindex varcoda
 
 @cindex coda
 @cindex varcoda
 

+A variety of symbols that denote articulations, ornamentations,
+and other performance indications can be attached to a note using
+this syntax:

 
 

-@commonprop
+@example
+@var{note}\@var{name}
+@end example

 
 

-The meanings of the shorthands can be changed.  They are defined
-in @file{ly/@/script@/-init@/.ly}, where the variables  
-@code{DashDot}, @code{DashDash}, @code{DashPlus}, @code{DashBar},
-@code{DashLarger}, @code{DashHat}, and @code{DashUnderscore}
-are associated with the default articulation marks.  If you want,
-e.g., @code{-+} to produce a trill instead of a "+", you can
-redefine the variable in your document:
+The possible values for @var{name} are listed in @ref{List of
+articulations}.  For example:

 
 

-@lilypond[quote,ragged-right,verbatim]
-\relative c'' { c-+ }       
-dashPlus = "trill"
-\relative c'' { c-+ }       
+@lilypond[verbatim,quote,relative=2]
+c4\staccato c\mordent b2\turn
+c1\fermata

 @end lilypond
 
 @end lilypond
 

-The vertical ordering of scripts is controlled with the
-@code{script-priority} property.  The lower this number, the
-closer it will be put to the note.  In this example, the
-@internalsref{TextScript} (the sharp symbol) first has the lowest
-priority, so it is put lowest in the first example.  In the
-second, the prall trill (the @internalsref{Script}) has the
-lowest, so it is on the inside.  When two objects have the same
-priority, the order in which they are entered decides which one
-comes first.
-
-
-@commonprop
-
-The meanings of the shorthands can be changed.  They are defined
-in @file{ly/@/script@/-init@/.ly}, where the variables  
-@code{DashDot}, @code{DashDash}, @code{DashPlus}, @code{DashBar},
-@code{DashLarger}, @code{DashHat}, and @code{DashUnderscore}
-are associated with the default articulation marks.  If you want,
-e.g., @code{-+} to produce a trill instead of a "+", you can
-redefine the variable in your document:
-
-@lilypond[quote,ragged-right,verbatim]
-\relative c'' { c-+ }       
-dashPlus = "trill"
-\relative c'' { c-+ }       
-@end lilypond
+@cindex marcato
+@cindex stopped
+@cindex tenuto
+@cindex staccatissimo
+@cindex accent
+@cindex staccato
+@cindex portato

 
 

-The vertical ordering of scripts is controlled with the
-@code{script-priority} property.  The lower this number, the
-closer it will be put to the note.  In this example, the
-@internalsref{TextScript} (the sharp symbol) first has the lowest
-priority, so it is put lowest in the first example.  In the
-second, the prall trill (the @internalsref{Script}) has the
-lowest, so it is on the inside.  When two objects have the same
-priority, the order in which they are entered decides which one
-comes first.
-
-@lilypond[verbatim,relative=3,ragged-right,fragment,quote]
-\once \override TextScript #'script-priority = #-100
-a4^\prall^\markup { \sharp }
-
-\once \override Script #'script-priority = #-100
-a4^\prall^\markup { \sharp }
+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:
+
+@lilypond[verbatim,quote,relative=2]
+c4-^  c-+  c--  c-|
+c4->  c-.  c-_

 @end lilypond
 
 @end lilypond
 

+The rules for the default placement of articulations are defined
+in @file{scm/@/script@/.scm}.  Articulations and ornamentations
+may be manually placed above or below the staff, see
+@ref{Direction and placement}.
+
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{modifying-default-values-for-articulation-shorthand-notation.ly}
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{controlling-the-vertical-ordering-of-scripts.ly}
+

 
 @seealso
 
 
 @seealso
 

-Snippets: @lsrdir{expressive}
+Music Glossary:
+@rglos{tenuto},
+@rglos{accent},
+@rglos{staccato},
+@rglos{portato}.
+
+Notation Reference:
+@ref{Direction and placement},
+@ref{List of articulations}.

 
 

-Internals Reference: @internalsref{Script}.
+Installed Files:
+@file{scm/@/script@/.scm}.

 
 

+Snippets:
+@rlsr{Expressive marks}.

 
 

-@refbugs
+Internals Reference:
+@rinternals{Script},
+@rinternals{TextScript}.
+
+
+@knownissues

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


@@ -174,7 +150,10 @@ MIDI rendering of the music.
 @node Dynamics
 @unnumberedsubsubsec Dynamics
 
 @node Dynamics
 @unnumberedsubsubsec Dynamics
 

-@cindex Dynamics
+@cindex absolute dynamics
+@cindex dynamics
+@cindex dynamics, absolute
+@funindex \ppppp

 @funindex \pppp
 @funindex \ppp
 @funindex \pp
 @funindex \pppp
 @funindex \ppp
 @funindex \pp


@@ -193,186 +172,253 @@ MIDI rendering of the music.
 @funindex \sfz
 @funindex \rfz
 
 @funindex \sfz
 @funindex \rfz
 

-Absolute dynamic marks are specified using a command after a note
-@code{c4\ff}.  The available dynamic marks are @code{\ppppp},
-@code{\pppp}, @code{\ppp}, @code{\pp}, @code{\p}, @code{\mp},
-@code{\mf}, @code{\f}, @code{\ff}, @code{\fff}, @code{\ffff},
-@code{\fp}, @code{\sf}, @code{\sff}, @code{\sp}, @code{\spp},
-@code{\sfz}, and @code{\rfz}.  The dynamic marks can be placed
-above or below the staff with @code{_} and @code{^}, just like
-articulation marks. 
-
-@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
-c2\ppp c\mp 
-c\rfz c^\mf
-c_\spp c_\staccato^\ff
+Absolute dynamic marks are specified using a command after a note,
+such as @code{c4\ff}.  The available dynamic marks are
+@code{\ppppp}, @code{\pppp}, @code{\ppp}, @code{\pp}, @code{\p},
+@code{\mp}, @code{\mf}, @code{\f}, @code{\ff}, @code{\fff},
+@code{\ffff}, @code{\fp}, @code{\sf}, @code{\sff}, @code{\sp},
+@code{\spp}, @code{\sfz}, and @code{\rfz}.  The dynamic marks may
+be manually placed above or below the staff, see 
+@ref{Direction and placement}.
+
+@lilypond[verbatim,quote,relative=2]
+c2\ppp c\mp
+c2\rfz c^\mf
+c2_\spp c^\ff

 @end lilypond
 
 @end lilypond
 

+@cindex hairpin

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

+@funindex \cr
+@funindex \decr
+
+A @notation{crescendo} mark is started with @code{\<} and
+terminated with @code{\!}, an absolute dynamic, or an additional
+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\!
+d2\< d\f
+e2\< e\>
+f2\> f\!
+e2\> e\mp
+d2\> d\>
+c1\!
+@end lilypond

 
 

-A crescendo mark is started with @code{\<} and terminated with
-@code{\!} or an absolute dynamic.  A decrescendo is started with
-@code{\>} and is also terminated with @code{\!} or an absolute
-dynamic.  @code{\cr} and @code{\decr} may be used instead of
-@code{\<} and @code{\>}.  They can be engraved either using a
-graphical sign (a @q{hairpin}), or with textual signs.
-
-Because these marks are bound to notes, you must use spacer notes
-if multiple marks are needed during one note.
+Spacer rests are needed to engrave multiple marks on one note.

 
 

-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-c\< c\! d\> e\!
-<< f1 { s4 s4\< s4\! \> s4\! } >>
+@lilypond[verbatim,quote,relative=2]
+c4\< c\! d\> e\!
+<< f1 { s4 s4\< s4\> s4\! } >>

 @end lilypond
 
 @end lilypond
 

-This may give rise to very short hairpins.  Use
-@code{minimum-length} in
-@internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for
-example:
+@cindex espressivo articulation

 
 

-@example
-\override Voice.Hairpin #'minimum-length = #5
-@end example
+In some situations the @code{\espressivo} articulation mark may be
+the appropriate choice to indicate a crescendo and decrescendo on
+one note:

 
 

-@noindent
-A hairpin normally starts at the left edge of the beginning note
-and ends on the right edge of the ending note.  If the ending note
-falls on the downbeat, the hairpin ends on the immediately
-preceding bar line.  This may be modified by setting the
-@code{hairpinToBar line} property,
-@cindex Hairpin
-
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-e4\< e2. e1\!
-\set hairpinToBarline = ##f
-e4\< e2. e1\!
+@lilypond[verbatim,quote,relative=2]
+c2 b4 a
+g1\espressivo

 @end lilypond
 
 @end lilypond
 

-@cindex espressivo, articulation
-In some situations the @code{\espressivo} articulation mark may be
-suitable to indicate a crescendo and decrescendo on the one note:
+@cindex crescendo
+@cindex decrescendo
+@cindex diminuendo
+
+Crescendos and 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:

 
 

-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-c2 b4 a g1\espressivo
+@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\!

 @end lilypond
 
 @end lilypond
 

+To create new absolute dynamic marks or text that should be
+aligned with dynamics, see @ref{New dynamic marks}.
+
+Vertical positioning of dynamics is handled by
+@rinternals{DynamicLineSpanner}.
+
+
+@predefined
+
+@funindex \dynamicUp
+@code{\dynamicUp},
+@funindex \dynamicDown
+@code{\dynamicDown},
+@funindex \dynamicNeutral
+@code{\dynamicNeutral},
+@funindex \setTextCresc
+@code{\setTextCresc},
+@funindex \setTextDim
+@code{\setTextDim},
+@funindex \setTextDecr
+@code{\setTextDecr},
+@funindex \setTextDecresc
+@code{\setTextDecresc},
+@funindex \setHairpinCresc
+@code{\setHairpinCresc},
+@funindex \setHairpinDim
+@code{\setHairpinDim},
+@funindex \setHairpinDecresc
+@code{\setHairpinDecresc}.
+
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{setting-hairpin-behavior-at-bar-lines.ly}
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{setting-the-minimum-length-of-hairpins.ly}
+

 @cindex al niente
 @cindex niente, al
 
 @cindex al niente
 @cindex niente, al
 

-Hairpins may be printed with a circled tip (al niente notation) by
-setting the @code{circled-tip} property:
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{printing-hairpins-using-al-niente-notation.ly}

 
 

-@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
-\override Hairpin #'circled-tip = ##t
-c2\< c\!
-c4\> c\< c2\!
-@end lilypond
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{vertically-aligning-dynamics-across-multiple-notes.ly}

 
 

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

 
 

-@cindex crescendo
-@cindex decrescendo
-@cindex diminuendo
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{changing-text-and-spanner-styles-for-text-dynamics.ly}

 
 

-You can use text saying @emph{cresc.}, @emph{decr.}, or
-@emph{dim.} instead of hairpins with the commands \setTextCresc,
-\setTextDim, and \setTextDecresc.  The corresponding
-\setHairpinCresc, \setHairpinDim, and \setHairpinDecresc will
-revert to hairpins again: 

 
 

-@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
-\setTextCresc
-c\< d e f\!
-\setHairpinCresc
-e\> d c b\!
-\setTextDecresc
-e\> d e f\!
-%  FIXME: uncomment after 2.11.36
-%\setTextDecr
-%c\> d e f\!
-\setTextDim
-e\> d c b\!
-@end lilypond
+@seealso

 
 

-You can also supply your own texts and change the style of the
-spanner line with the properties @code{\crescendoText},
-@code{\crescendoSpanner}, @code{\decrescendoText}, and
-@code{\decrescendoSpanner}. Available values for the spanner
-properties are @code{hairpin}, @code{line}, @code{dashed-line},
-and @code{dotted-line}. If unset, a hairpin crescendo is used:
-
-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
-\set crescendoText = \markup { \italic "cresc. poco" }
-\set crescendoSpanner = #'dotted-line
-a'2\< a a a a a a a\!\mf
-@end lilypond
+@c TODO: Add hairpin to glossary.

 
 

+Music Glossary:
+@rglos{crescendo},
+@rglos{decrescendo}.

 
 

-To create new dynamic marks or text that should be aligned with
-dynamics, see @ref{New dynamic marks}.
+Learning Manual:
+@rlearning{Articulation and dynamics}.

 
 

-Vertical positioning of dynamics is handled by
-@internalsref{DynamicLineSpanner}.
+Notation Reference:
+@ref{Direction and placement},
+@ref{New dynamic marks}.

 
 

+Snippets:
+@rlsr{Expressive marks}.

 
 

-@commonprop
+Internals Reference:
+@rinternals{DynamicText},
+@rinternals{Hairpin},
+@rinternals{DynamicLineSpanner}.

 
 

-Dynamics that occur at, begin on, or end on the same note will be
-vertically aligned.  If you want to ensure that dynamics are
-aligned when they do not occur on the same note, you can increase
-the @code{staff-padding} property.

 
 

-@example
-\override DynamicLineSpanner #'staff-padding = #4
-@end example
+@node New dynamic marks
+@unnumberedsubsubsec New dynamic marks

 
 

-You may also use this property if the dynamics are colliding with
-other notation.
+@cindex new dynamic marks
+@cindex dynamic marks, new

 
 

-Crescendi and decrescendi that cross a line break will be
-continued on the second line.  If they end on the first note of a
-new line, nothing will be printed on that line.  To change this
-behavior, use
+The easiest way to create dynamic indications is to use
+@code{\markup} objects.

 
 

-@example
-\override Score.Hairpin #'after-line-breaking = ##t
-@end example
+@lilypond[verbatim,quote]
+moltoF = \markup { molto \dynamic f }

 
 

-Text style dynamic changes (such as @emph{cresc.} and @emph{dim.})
-are printed with a dashed line showing their extent.  To surpress
-printing this line, use
+\relative c' {
+  <d e>16 <d e>
+  <d e>2.._\moltoF
+}
+@end lilypond

 
 

-@example
-\override DynamicTextSpanner #'dash-period = #-1.0
-@end example
+@cindex dynamics, editorial
+@cindex dynamics, parenthesis

 
 

+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}.

 
 

-@refcommands
+@lilypond[verbatim,quote]
+roundf = \markup { \center-align { \line { \bold { \italic ( }
+         \dynamic f \bold { \italic ) } } } }
+boxf = \markup { \bracket { \dynamic f } }
+\relative c' {
+  c1_\roundf
+  c1_\boxf
+}
+@end lilypond

 
 

-@funindex \dynamicUp
-@code{\dynamicUp},
-@funindex \dynamicDown
-@code{\dynamicDown},
-@funindex \dynamicNeutral
-@code{\dynamicNeutral}.
+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

 
 

-@seealso
+@lilypond[verbatim,quote]
+sfzp = #(make-dynamic-script "sfzp")
+\relative c' {
+  c4 c c\sfzp c
+}
+@end lilypond

 
 

-Snippets: @lsrdir{expressive}
+@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
+explained in @ref{Markup construction in Scheme}.
+
+@lilypond[verbatim,quote]
+moltoF = #(make-dynamic-script (markup 
+                      #:normal-text "molto"
+                      #:dynamic "f"))
+\relative c' {
+  <d e>16 <d e>
+  <d e>2..\moltoF
+}
+@end lilypond
+
+@noindent
+Font settings in markup mode are described in
+@ref{Common markup commands}.

 
 

-Internals Reference: @internalsref{DynamicText},
-@internalsref{Hairpin}.  Vertical positioning of these symbols is
-handled by @internalsref{DynamicLineSpanner}.
-Glossary: @rglos{Hairpin}, @rglos{crescendo}, @rglos{decrescendo}

 
 

-@c TODO: add link to LM directions
+@seealso
+
+Notation Reference:
+@ref{Formatting text},
+@ref{Common markup commands},
+@ref{Markup construction in Scheme}.
+
+Snippets:
+@rlsr{Expressive marks}.

 
 
 @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::              


@@ -383,43 +429,45 @@ Glossary: @rglos{Hairpin}, @rglos{crescendo}, @rglos{decrescendo}
 @node Slurs
 @unnumberedsubsubsec Slurs
 
 @node Slurs
 @unnumberedsubsubsec Slurs
 

-@cindex Slurs
+@cindex slurs

 
 

-A slur indicates that notes are to be played bound or
-@emph{legato}.  They are entered using parentheses:
+@notation{Slurs} are entered using parentheses:

 
 

-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
-f( g a) a8 b( a4 g2 f4)
+@lilypond[verbatim,quote,relative=2]
+f4( g a) a8 b(
+a4 g2 f4)

 <c e>2( <b d>2)
 @end lilypond
 
 <c e>2( <b d>2)
 @end lilypond
 

-Just as with ties, the direction of a slur can be specified with
-@code{\slur@emph{DIR}}, where @code{@emph{DIR}} is either
-@code{Up}, @code{Down}, or @code{Neutral} (automatically
-selected).  The shorthands are also available: by adding
-@code{_} or @code{^} before the opening parentheses, the direction
-is also set.  
+Slurs may be manually placed above or below the notes, see
+@ref{Direction and placement}.

 
 

-@lilypond[relative=2,ragged-right,quote,verbatim,fragment]
-c4_( c) c^( c)
+@lilypond[verbatim,quote,relative=2]
+c2( d)
+\slurDown
+c2( d)
+\slurNeutral
+c2( d)

 @end lilypond
 
 @end lilypond
 

-Only one slur can be printed at once.  If you need to print a long
-slur over a few small slurs, please see @ref{Phrasing slurs}.
-
+Phrasing slurs must be used to print more than one slur at once.
+For details, see @ref{Phrasing slurs}.

 
 

-@commonprop
+Slurs can be solid, dotted, or dashed.  Solid is the default slur
+style:

 
 

-Some composers write two slurs when they want legato chords.  This
-can be achieved in LilyPond by setting @code{doubleSlurs},
-
-@lilypond[verbatim,ragged-right,relative,fragment,quote]
-\set doubleSlurs = ##t
-<c e>4 ( <d f> <c e> <d f> )
+@lilypond[verbatim,quote,relative=1]
+c4( e g2)
+\slurDashed
+g4( e c2)
+\slurDotted
+c4( e g2)
+\slurSolid
+g4( e c2)

 @end lilypond
 
 
 @end lilypond
 
 

-@refcommands
+@predefined

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


@@ -434,11 +482,27 @@ can be achieved in LilyPond by setting @code{doubleSlurs},
 @funindex \slurSolid
 @code{\slurSolid}.
 
 @funindex \slurSolid
 @code{\slurSolid}.
 

+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{using-double-slurs-for-legato-chords.ly}
+
+

 @seealso
 
 @seealso
 

-Snippets: @lsrdir{expressive}
+Music Glossary:
+@rglos{slur}.
+
+Notation Reference:
+@ref{Direction and placement},
+@ref{Phrasing slurs}.

 
 

-Internals Reference: @internalsref{Slur}.
+Snippets:
+@rlsr{Expressive marks}.
+
+Internals Reference:
+@rinternals{Slur}.

 
 
 @node Phrasing slurs
 
 
 @node Phrasing slurs


@@ -446,26 +510,34 @@ Internals Reference: @internalsref{Slur}.
 
 @cindex phrasing slurs
 @cindex phrasing marks
 
 @cindex phrasing slurs
 @cindex phrasing marks

+@funindex \(
+@funindex \)

 
 

-A phrasing slur (or phrasing mark) connects notes and is used to
-indicate a musical sentence.  It is written using @code{\(} and
+@notation{Phrasing slurs} (or phrasing marks) that indicate a
+musical sentence are written using the commands @code{\(} and

 @code{\)} respectively:
 
 @code{\)} respectively:
 

-@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
-\time 6/4 c'\( d( e) f( e) d\)
+@lilypond[verbatim,quote,relative=2]
+c4\( d( e) f(
+e2) d\)

 @end lilypond
 
 @end lilypond
 

-Typographically, the 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; instead,
-use @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and
-@code{\phrasingSlurNeutral}, or use the shorthands @code{_} and
-@code{^}.
+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\)
+\phrasingSlurUp
+c4\( g' c,( b) | c1\)
+@end lilypond

 
 

-You cannot have simultaneous phrasing slurs.
+Simultaneous phrasing slurs are not permitted.

 
 
 
 

-@refcommands
+@predefined

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


@@ -477,59 +549,119 @@ You cannot have simultaneous phrasing slurs.
 
 @seealso
 
 
 @seealso
 

-Snippets: @lsrdir{expressive}
+Notation Reference:
+@ref{Direction and placement}.

 
 

-Internals Reference: @internalsref{PhrasingSlur}.
+Snippets:
+@rlsr{Expressive marks}.
+
+Internals Reference:
+@rinternals{PhrasingSlur}.

 
 
 @node Breath marks
 @unnumberedsubsubsec Breath marks
 
 
 
 @node Breath marks
 @unnumberedsubsubsec Breath marks
 

-Breath marks are entered using @code{\breathe}
+@cindex breath marks
+@funindex \breathe
+
+Breath marks are entered using @code{\breathe}:

 
 

-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
-c'4 \breathe d4
+@lilypond[verbatim,quote,relative=2]
+c2. \breathe d4

 @end lilypond
 
 @end lilypond
 

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

 
 

-@commonprop

 
 

-The glyph of the breath mark can be tuned by overriding the
-@code{text} property of the @code{BreathingSign} layout object
-with any markup text.  For example,
+@snippets

 
 

-@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
-c'4
-\override BreathingSign #'text
-  = #(make-musicglyph-markup "scripts.rvarcomma")
-\breathe
-d4
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{changing-the-breath-mark-symbol.ly}
+
+@cindex caesura
+@cindex railroad tracks
+
+@c input/new snippet
+@c @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@c {inserting-a-caesura.ly}
+
+Caesura marks can be created by overriding the @code{'text}
+property of the @code{BreathingSign} object.  A curved caesura
+mark is also available.
+
+@lilypond[verbatim,quote,relative=2]
+\override BreathingSign #'text =
+  #(make-musicglyph-markup "scripts.caesura.straight")
+c8 e4. \breathe g8. e16 c4
+
+\override BreathingSign #'text =
+  #(make-musicglyph-markup "scripts.caesura.curved")
+g8 e'4. \breathe g8. e16 c4

 @end lilypond
 
 @end lilypond
 

+

 @seealso
 
 @seealso
 

-Snippets: @lsrdir{expressive}
+Notation Reference:
+@ref{Divisiones}.

 
 

-Internals Reference: @internalsref{BreathingSign}.
+Snippets:
+@rlsr{Expressive marks}.
+@c @lsr{expressive,breathing-sign.ly}.

 
 

-Examples: @lsr{expressive,breathing-sign.ly}
+Internals Reference:
+@rinternals{BreathingSign}.

 
 
 @node Falls and doits
 @unnumberedsubsubsec Falls and doits
 
 
 
 @node Falls and doits
 @unnumberedsubsubsec Falls and doits
 

-Falls and doits can be added to notes using the @code{\bendAfter}
-command,
-
-@lilypond[fragment,ragged-right,relative=2]
-\override Score.SpacingSpanner #'shortest-duration-space = #3.0
-c4-\bendAfter #+5
-c4-\bendAfter #-3
+@cindex falls
+@cindex doits
+@funindex \bendAfter
+
+@notation{Falls} and @notation{doits} can be added to notes using
+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
+c2-\bendAfter #-4
+c2-\bendAfter #+8
+c2-\bendAfter #-8

 @end lilypond
 
 @end lilypond
 

+The dash (@tie{-}) immediately preceding the @code{\bendAfter}
+command is @emph{required} when writing falls and doits.
+
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{adjusting-the-shape-of-falls-and-doits.ly}
+
+
+@seealso
+
+@c TODO: add falls and doits to glossary.
+@c Music Glossary:
+@c @rglos{falls},
+@c @rglos{doits}.
+
+Snippets:
+@rlsr{Expressive marks}.
+
+

 @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
 * Glissando::                   
 * Arpeggio::                    
 @menu
 * Glissando::                   
 * Arpeggio::                    


@@ -539,45 +671,46 @@ c4-\bendAfter #-3
 @node Glissando
 @unnumberedsubsubsec Glissando
 
 @node Glissando
 @unnumberedsubsubsec Glissando
 

-@cindex Glissando
+@cindex glissando

 @funindex \glissando
 
 @funindex \glissando
 

-A glissando is a smooth change in pitch.  It is denoted by a line
-or a wavy line between two notes.  It is requested by attaching
-@code{\glissando} to a note
+A @notation{glissando} is created by attaching @code{\glissando}
+to a note:

 
 

-@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
-c2\glissando c'
-\override Glissando #'style = #'zigzag
+@lilypond[verbatim,quote,relative=2]
+g2\glissando g'

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

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

 
 

+@snippets

 
 

-@lilypond[quote,ragged-right,verbatim]
-I = \once \override NoteColumn #'ignore-collision = ##t
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{contemporary-glissando.ly}

 
 

-\relative <<
-  { \oneVoice \stemDown f2 \glissando \stemNeutral a } \\
-  { \oneVoice \I c2 \glissando \I d, }
->>
-@end lilypond

 
 

+@seealso

 
 

+Music Glossary:
+@rglos{glissando}.

 
 

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

 
 

-Snippets: @lsrdir{expressive}
+Snippets:
+@rlsr{Expressive marks}.

 
 

-Internals Reference: @internalsref{Glissando}.
+@c FIXME: I need to figure out what's up with these.  -gp
+@c @lsr{expressive,glissando.ly},
+@c @lsr{expressive,line-styles.ly}

 
 

-Glossary: @rglos{falls}, @rglos{doits}
-Example files:
-@lsr{expressive,glissando.ly}, @lsr{expressive,line-styles.ly}
+Internals Reference:
+@rinternals{Glissando}.

 
 
 
 

-@refbugs
+@knownissues

 
 Printing text over the line (such as @emph{gliss.}) is not
 supported.
 
 Printing text over the line (such as @emph{gliss.}) is not
 supported.


@@ -586,105 +719,65 @@ supported.
 @node Arpeggio
 @unnumberedsubsubsec Arpeggio
 
 @node Arpeggio
 @unnumberedsubsubsec Arpeggio
 

-@cindex Arpeggio
+@cindex arpeggio

 @cindex broken chord
 @cindex broken chord

-@funindex \arpeggio
-
-You can specify an arpeggio sign (also known as broken chord) on a
-chord by attaching an @code{\arpeggio} to the chord:
+@cindex chord, broken

 
 

-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
-<c e g c>\arpeggio
-@end lilypond
+An @notation{arpeggio} on a chord (also known as a broken chord)
+is denoted by appending @code{\arpeggio} to the chord construct:

 
 

-A square bracket on the left is used to indicate that the chord should
-@emph{not} be arpeggiated:
-
-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
-\arpeggioBracket
-<c' e g c>\arpeggio
+@lilypond[verbatim,quote,relative=1]
+<c e g c>1\arpeggio

 @end lilypond
 
 @end lilypond
 

-The direction of the arpeggio can be denoted by adding an
-arrowhead to the wiggly line. This is done with the commands
-@code{arpeggioUp} and @code{arpeggioDown}. @code{arpeggioNeutral}
-reverts to the arrow-less version:
-
-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
-\new Voice {
-  \arpeggioUp
-  <c e g c>\arpeggio
-  \arpeggioDown
-  <c e g c>\arpeggio
-  \arpeggioNeutral
-  <c e g c>\arpeggio
-}
+The direction of an 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 arpeggio:
+
+@lilypond[verbatim,quote,relative=1]
+\arpeggioUp
+<c e g c>2\arpeggio
+\arpeggioDown
+<c e g c>2\arpeggio
+\arpeggioNeutral
+<c e g c>1\arpeggio

 @end lilypond
 
 @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:

 
 

-@commonprop
-
-In a @code{PianoStaff}, it is possible to let an arpeggio cross
-between the staves by setting the property
-@internalsref{PianoStaff}.@code{connectArpeggios}. 
-
-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
-\new PianoStaff <<
-  \set PianoStaff.connectArpeggios = ##t
-  \new Staff { <c' e g c>\arpeggio }
-  \new Staff { \clef bass <c,, e g>\arpeggio }
->>
+@lilypond[verbatim,quote,relative=1]
+<c e g c>2
+\arpeggioBracket
+<c e g c>2\arpeggio
+\arpeggioNeutral
+<c e g c>1\arpeggio

 @end lilypond
 
 @end lilypond
 

-The same can be accomplished in contexts other than
-@code{PianoStaff} if the @code{Span_arpeggio_engraver} is included
-in the Score context.
-
-@lilypond[quote,ragged-right,verbatim]
-\score {
-  \new StaffGroup {
-    \set Score.connectArpeggios = ##t
-    <<
-      \new Voice \relative c' {
-        <e g>4\arpeggio
-      }
-      \new Voice  \relative c {
-        \clef bass
-        <c e>4\arpeggio
-      }
-    >>
-  }
-  \layout {
-    \context {
-      \Score 
-      \consists "Span_arpeggio_engraver"
-    } 
-  }
-}
-@end lilypond
+A @emph{parenthesis} style bracket may be attached to a chord
+construct instead of a square bracket.

 
 

-Similarly,  an arpeggio can be drawn across notes in
-different voices on the same staff if the Span_arpeggio_engraver
-is moved to the Staff context:
-
-@lilypond[quote,ragged-right,verbatim]
-\new Staff
-\with {
-  \consists "Span_arpeggio_engraver"
-} \relative c' {
-  \set Staff.connectArpeggios = ##t
-    <<
-    {<e' g>4\arpeggio <d f> <d f>2 }
-  \\
-  {<d, f>2\arpeggio  <g b>2  }
-  >>
-}
-@end lilypond
+@c Maybe create a new \arpeggioParen command, or something
+@c like that. -pm

 
 

+@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
+<c e g c>2\arpeggio
+\arpeggioNeutral
+<c e g c>1\arpeggio
+@end lilypond

 
 

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

 
 

-@refcommands
+@predefined

 
 

+@funindex \arpeggio

 @code{\arpeggio},
 @funindex \arpeggioUp
 @code{\arpeggioUp},
 @code{\arpeggio},
 @funindex \arpeggioUp
 @code{\arpeggioUp},


@@ -696,60 +789,88 @@ is moved to the Staff context:
 @code{\arpeggioBracket}.
 
 
 @code{\arpeggioBracket}.
 
 

+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{creating-cross-staff-arpeggios-in-a-piano-staff.ly}
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{creating-cross-staff-arpeggios-in-other-contexts.ly}
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{creating-arpeggios-across-notes-in-different-voices.ly}
+
+

 @seealso
 
 @seealso
 

-Notation manual: @ref{Ties}, for writing out arpeggios.
+Music Glossary:
+@rglos{arpeggio}.
+
+Notation Reference:
+@ref{Ties}.

 
 

-Snippets: @lsrdir{expressive}
+Snippets:
+@rlsr{Expressive marks}.

 
 

-Internals Reference: @internalsref{Arpeggio}.
+Internals Reference:
+@rinternals{Arpeggio},
+@rinternals{PianoStaff}.

 
 
 
 

-@refbugs
+@knownissues

 
 It is not possible to mix connected arpeggios and unconnected
 
 It is not possible to mix connected arpeggios and unconnected

-arpeggios in one @internalsref{PianoStaff} at the same point in
+arpeggios in one @code{PianoStaff} at the same point in

 time.
 
 time.
 

+The parenthesis-style arpeggio brackets do not work for
+cross-staff arpeggios.
+

 
 @node Trills
 @unnumberedsubsubsec Trills
 
 
 @node Trills
 @unnumberedsubsubsec Trills
 

-Short trills are printed with @code{\trill} like normal
-articulation; see @ref{Articulations and ornamentations}.
+@cindex trills
+@funindex \trill
+
+Short @notation{trills} without an extender line are printed with
+@code{\trill}; see @ref{Articulations and ornamentations}.

 
 Long running trills are made with @code{\startTrillSpan} and
 
 Long running trills are made with @code{\startTrillSpan} and

-@code{\stopTrillSpan}. In the following example, it is shown in
-the common combination with grace notes.  If a more precise
-control of the placement of the grace notes is needed, see
-@ref{Grace notes}.
+@code{\stopTrillSpan}.  In the following example, a long running
+trill is shown combined with grace notes.  To achieve precise
+control of the placement of the grace notes, see @ref{Grace
+notes}.

 
 

-@lilypond[verbatim,ragged-right,relative=2,quote,fragment]
-\relative c''
-{c1 \afterGrace 
+@lilypond[verbatim,quote,relative=2]
+c1 \afterGrace

 d1\startTrillSpan { c16[\stopTrillSpan d] }
 d1\startTrillSpan { c16[\stopTrillSpan d] }

-c4 }
+c4

 @end lilypond
 
 @end lilypond
 

-@cindex Pitched trills
+@cindex pitched trills
+@cindex trills, pitched

 
 Trills that should be executed on an explicitly specified pitch
 
 Trills that should be executed on an explicitly specified pitch

-can be typeset with the command @code{pitchedTrill}, and the
-syntax @code{\pitchedTrill} @var{mainnote}@code{\startTrillSpan}
-@var{trillnote} @var{endnote} @code{\stopTrillSpan}.
+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

 
 

-@lilypond[ragged-right,verbatim,fragment,relative=1,quote]
+@lilypond[verbatim,quote,relative=1]

 \pitchedTrill e2 \startTrillSpan fis
 d\stopTrillSpan
 @end lilypond
 
 \pitchedTrill e2 \startTrillSpan fis
 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.
 
 
 @noindent
 The first argument is the main note.  The pitch of the second is
 printed as a stemless note head in parentheses.
 
 

-@refcommands
+@predefined

 
 @code{\startTrillSpan},
 @funindex \startTrillSpan
 
 @code{\startTrillSpan},
 @funindex \startTrillSpan


@@ -759,10 +880,15 @@ printed as a stemless note head in parentheses.
 
 @seealso
 
 
 @seealso
 

-Snippets: @lsrdir{expressive}
-
-Internals Reference: @internalsref{TrillSpanner}.
-
+Music Glossary:
+@rglos{trill}.

 
 

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

 
 

+Snippets:
+@rlsr{Expressive marks}.

 
 

+Internals Reference:
+@rinternals{TrillSpanner}.