@c -*- coding: utf-8; mode: texinfo; -*-
@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.19.21"

@node Expressive marks
@section Expressive marks

@lilypondfile[quote]{snippets/expressive-headword.ly}

This section lists various expressive marks that can be
created in a score.

@menu
* Expressive marks attached to notes::
* Expressive marks as curves::
* Expressive marks as lines::
@end menu


@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.
Methods to create new dynamic markings are also discussed.

@menu
* Articulations and ornamentations::
* Dynamics::
* New dynamic marks::
@end menu

@node Articulations and ornamentations
@unnumberedsubsubsec Articulations and ornamentations


@cindex @q{accent} articulation
@cindex articulation, accent
@cindex @q{marcato} articulation
@cindex articulation, marcato
@cindex @q{staccatissimo} articulation
@cindex articulation, staccatissimo
@cindex @q{espressivo} articulation
@cindex articulation, espressivo
@cindex @q{staccato} articulation
@cindex articulation, staccato
@cindex @q{tenuto} articulation
@cindex articulation, tenuto
@cindex @q{portato} articulation
@cindex articulation, portato
@cindex @q{up-bow} bowing indication
@cindex bowing, up
@cindex @q{down-bow} bowing indication
@cindex bowing, down
@cindex @q{flageolet} harmonics
@cindex harmonics, flageolet
@cindex @q{thumb} fingering
@cindex fingering, thumb
@cindex foot mark
@cindex organ pedal mark
@cindex pedal mark, organ
@cindex @q{heel} pedal mark
@cindex pedal mark, heel
@cindex @q{toe} pedal mark
@cindex pedal mark, toe
@cindex @q{open} articulation
@cindex articulation, open
@cindex open high hat
@cindex high hat, open
@cindex @q{half open} articulation
@cindex articulation, half open
@cindex half-open high hat
@cindex high hat, half open
@cindex @q{stopped} articulation
@cindex articulation, stopped
@cindex pedal high hat
@cindex high hat, pedal
@cindex @q{snappizzicato} sign
@cindex sign, snappizzicato
@cindex @q{turn} ornament
@cindex ornament, turn
@cindex @q{reverse turn} ornament
@cindex ornament, reverse turn
@cindex @q{slash turn} ornament
@cindex ornament, slash turn
@cindex @q{Haydn turn} ornament
@cindex ornament, Haydn turn
@cindex @q{trill} ornament
@cindex ornament, trill
@cindex @q{pralltriller} ornament
@cindex ornament, pralltriller
@cindex @q{mordent} ornament
@cindex ornament, mordent
@cindex @q{pralltriller, long} ornament
@cindex ornament, pralltriller, long
@cindex @q{mordent, upper} ornament
@cindex ornament, mordent, upper
@cindex @q{mordent, lower} ornament
@cindex ornament, mordent, lower
@cindex @q{upper mordent} ornament
@cindex ornament, upper mordent
@cindex @q{lower mordent} ornament
@cindex ornament, lower mordent
@cindex @q{pralltriller, down} ornament
@cindex ornament, pralltriller, down
@cindex @q{pralltriller, up} ornament
@cindex ornament, pralltriller, up
@cindex @q{up pralltriller} ornament
@cindex ornament, up pralltriller
@cindex @q{down pralltriller} ornament
@cindex ornament, down pralltriller
@cindex @q{signum congruentiae} ornament
@cindex ornament, signum congruentiae
@cindex fermata
@cindex fermata, short
@cindex short fermata
@cindex fermata, long
@cindex long fermata
@cindex fermata, Henze
@cindex Henze fermata
@cindex @q{segno} sign
@cindex sign, segno
@cindex @q{coda} sign
@cindex sign, coda
@cindex @q{variant coda} sign
@cindex sign, variant coda
@cindex coda sign, variant

@funindex \accent
@funindex \marcato
@funindex \staccatissimo
@funindex \espressivo
@funindex \staccato
@funindex \tenuto
@funindex \portato
@funindex \upbow
@funindex \downbow
@funindex \flageolet
@funindex \thumb
@funindex \lheel
@funindex \rheel
@funindex \ltoe
@funindex \rtoe
@funindex \open
@funindex \halfopen
@funindex \stopped
@funindex \snappizzicato
@funindex \turn
@funindex \reverseturn
@funindex \slashturn
@funindex \haydnturn
@funindex \trill
@funindex \prall
@funindex \mordent
@funindex \prallprall
@funindex \prallmordent
@funindex \upprall
@funindex \downprall
@funindex \upmordent
@funindex \downmordent
@funindex \pralldown
@funindex \prallup
@funindex \lineprall
@funindex \signumcongruentiae
@funindex \veryshortfermata
@funindex \shortfermata
@funindex \fermata
@funindex \longfermata
@funindex \verylongfermata
@funindex \henzeshortfermata
@funindex \henzelongfermata
@funindex \segno
@funindex \coda
@funindex \varcoda

@funindex -

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

@example
@var{note}\@var{name}
@end example

The possible values for @code{@var{name}} are listed in
@ref{List of articulations}.  For example:

@lilypond[verbatim,quote]
\relative {
  c''4\staccato c\mordent b2\turn
  c1\fermata
}
@end lilypond

@cindex marcato
@cindex tenuto
@cindex staccatissimo
@cindex accent
@cindex staccato
@cindex portato

Some of these articulations have shorthands for easier entry.
Shorthands are appended to the note name, and their syntax
consists of a dash @code{-} followed by a symbol signifying the
articulation.  Predefined shorthands exist for @notation{marcato},
@notation{stopped}, @notation{tenuto}, @notation{staccatissimo},
@notation{accent}, @notation{staccato}, and @notation{portato}.
Their corresponding output appears as follows:

@lilypond[verbatim,quote]
\relative {
  c''4-^ 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
may be manually placed above or below the staff; see
@ref{Direction and placement}.

Articulations are @code{Script} objects.  Their properties are
described more fully in @rinternals{Script}.

Articulations can be attached to rests and multi-measure rests as
well as notes.  Attaching an articulation to a multi-measure rest
creates a @code{MultiMeasureRestScript} object.

@lilypond[verbatim,quote,fragment]
\override Script.color = #red
\override MultiMeasureRestScript.color = #blue
a'2\fermata r\fermata
R1\fermata
@end lilypond

In addition to articulations, text and markups can be attached to
notes.  See @ref{Text scripts}.

For more information about the ordering of Scripts and TextScripts that
are attached to the notes, see @rlearning{Placement of objects}.


@snippets

@cindex articulation, default values, modifying
@funindex \dashBang
@funindex \dashDash
@funindex \dashDot
@funindex \dashHat
@funindex \dashLarger
@funindex \dashPlus
@funindex \dashUnderscore
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/modifying-default-values-for-articulation-shorthand-notation.ly}

@cindex vertical ordering, of scripts
@cindex ordering, vertical, of scripts
@cindex script, vertical ordering
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/controlling-the-vertical-ordering-of-scripts.ly}

@cindex delayed turn ornamentation
@cindex turn ornamentation, delayed
@cindex ornamentation, turn, delayed
@funindex suggestAccidentals
@funindex AccidentalSuggestion
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/creating-a-delayed-turn.ly}

@morerefs
Music Glossary:
@rglos{tenuto},
@rglos{accent},
@rglos{staccato},
@rglos{portato}.

Learning Manual:
@rlearning{Placement of objects}.

Notation Reference:
@ref{Text scripts},
@ref{Direction and placement},
@ref{List of articulations},
@ref{Trills}.

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

Snippets:
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{Script},
@rinternals{TextScript}.


@node Dynamics
@unnumberedsubsubsec Dynamics

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

@funindex \ppppp
@funindex \pppp
@funindex \ppp
@funindex \pp
@funindex \p
@funindex \mp
@funindex \mf
@funindex \f
@funindex \ff
@funindex \fff
@funindex \ffff
@funindex \fffff
@funindex \fp
@funindex \sf
@funindex \sff
@funindex \sp
@funindex \spp
@funindex \sfz
@funindex \rfz
@funindex \n

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{\fffff}, @code{\fp}, @code{\sf}, @code{\sff},
@code{\sp}, @code{\spp}, @code{\sfz}, @code{\rfz}, and @code{\n}.
Dynamic marks may be manually placed above or below the staff; see
@ref{Direction and placement}.

@lilypond[verbatim,quote]
\relative c'' {
  c2\ppp c\mp
  c2\rfz c^\mf
  c2_\spp c^\ff
}
@end lilypond

@cindex hairpin
@cindex crescendo
@cindex decrescendo
@cindex diminuendo

@funindexpost \<
@funindexpost \>
@funindexpost \!
@funindex \cr
@funindex \decr
@funindex \endcr
@funindex \enddecr

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{\>}; @code{\endcr} and @code{\enddecr} maybe used instead of
@code{\!} to end a crescendo or decrescendo mark, respectively.
@notation{Hairpins} are engraved by default using this notation.

@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
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.  A hairpin ending on a downbeat will stop at the preceding bar line.

@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
@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 {
  c''1\< | c4 a c\mf a | c1\< | c4 a c\ffff a
}
@end lilypond

@cindex multiple dynamic marks, on one note
@cindex dynamic mark, 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 {
  c''4\< c\! d\> e\!
  << f1 { s4 s4\< s4\> s4\! } >>
}
@end lilypond

@cindex espressivo articulation

@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 {
  c''2 b4 a
  g1\espressivo
}
@end lilypond

@funindex \cresc
@funindex \decresc
@funindexpost \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 {
  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 \dimTextDecresc
@funindex \dimTextDecr
@funindex \dimTextDim
@funindex \crescHairpin
@funindex \dimHairpin

Textual marks for dynamic changes can also replace hairpins:
@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


To create new absolute dynamic marks or text that should be
aligned with dynamics, see @ref{New dynamic marks}.

@cindex dynamics, vertical positioning
@cindex vertical positioning of dynamics

@funindex DynamicLineSpanner


Vertical positioning of dynamics is handled by
@rinternals{DynamicLineSpanner}.
@funindex \dynamicUp
@funindex \dynamicDown
@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'2 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},
@code{\dynamicDown},
@code{\dynamicNeutral},
@code{\crescTextCresc},
@code{\dimTextDim},
@code{\dimTextDecr},
@code{\dimTextDecresc},
@code{\crescHairpin},
@code{\dimHairpin}.
@endpredefined


@snippets

@cindex hairpin, stopping at bar lines
@cindex bar line, hairpin, stopping at
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/setting-hairpin-behavior-at-bar-lines.ly}

@cindex hairpin, minimum length
@cindex minimum length, hairpin
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/setting-the-minimum-length-of-hairpins.ly}

@cindex hairpin, moving ends of
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/moving-the-ends-of-hairpins.ly}

@cindex al niente, hairpin
@cindex niente, al, hairpin
@cindex hairpin, al niente
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/printing-hairpins-using-al-niente-notation.ly}

@cindex Ferneyhough hairpin
@cindex hairpin, Ferneyhough
@cindex flared hairpin
@cindex hairpin, flared
@cindex constante hairpin
@cindex hairpin, constante
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/printing-hairpins-in-various-styles.ly}

@cindex vertical alignment, dynamics
@cindex alignment, vertical, dynamics
@cindex dynamics, vertical alignment
@cindex vertical alignment, text scripts
@cindex text script, vertical alignment
@cindex alignment, vertical, text scripts
@funindex DynamicLineSpanner
@funindex \textLengthOn
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/vertically-aligned-dynamics-and-textscripts.ly}

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

@cindex dynamics, text, style
@cindex text dynamics, style
@cindex style, text dynamics
@funindex crescendoText
@funindex crescendoSpanner
@funindex decrescendoText
@funindex decrescendoSpanner
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/changing-text-and-spanner-styles-for-text-dynamics.ly}

@morerefs
Music Glossary:
@rglos{al niente},
@rglos{crescendo},
@rglos{decrescendo},
@rglos{hairpin}.

Learning Manual:
@rlearning{Articulations and dynamics}.

Notation Reference:
@ref{Direction and placement},
@ref{New dynamic marks},
@ref{Enhancing MIDI output},
@ref{Controlling MIDI dynamics}.

Snippets:
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{DynamicText},
@rinternals{Hairpin},
@rinternals{DynamicLineSpanner},
@rinternals{Dynamics}.


@node New dynamic marks
@unnumberedsubsubsec New dynamic marks

@cindex new dynamic mark
@cindex dynamic mark, new

The easiest way to create dynamic indications is to use
@code{\markup} objects.

@lilypond[verbatim,quote]
moltoF = \markup { molto \dynamic f }

\relative {
  <d' e>16_\moltoF <d e>
  <d e>2..
}
@end lilypond

@cindex dynamics, editorial
@cindex dynamics, parenthesis
@cindex editorial dynamics
@funindex \bracket
@funindex \dynamic

In markup mode, editorial dynamics (within parentheses or square
brackets) can be created.  The syntax for markup mode is described
in @ref{Formatting text}.

@lilypond[verbatim,quote]
roundF = \markup {
    \center-align \concat { \bold { \italic ( }
           \dynamic f \bold { \italic ) } } }
boxF = \markup { \bracket { \dynamic f } }
\relative {
  c'1_\roundF
  c1_\boxF
}
@end lilypond

@funindex make-dynamic-script

Simple, centered dynamic marks are easily created with the
@code{make-dynamic-script} function.

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

In general, @code{make-dynamic-script} takes any markup object as its
argument.  The dynamic font only contains the characters
@code{f,m,p,r,s} and @code{z}, so if a dynamic mark that includes
plain text or punctuation symbols is desired, markup commands that
reverts font family and font encoding to normal text should be used,
for example @code{\normal-text}.  The interest of using
@code{make-dynamic-script} instead of an ordinary markup is ensuring
the vertical alignment of markup objects and hairpins that are
attached to the same note head.

@lilypond[verbatim,quote]
roundF = \markup { \center-align \concat {
           \normal-text { \bold { \italic ( } }
           \dynamic f
           \normal-text { \bold { \italic ) } } } }
boxF = \markup { \bracket { \dynamic f } }
mfEspress = \markup { \center-align \line {
              \hspace #3.7 mf \normal-text \italic espress. } }
roundFdynamic = #(make-dynamic-script roundF)
boxFdynamic = #(make-dynamic-script boxF)
mfEspressDynamic = #(make-dynamic-script mfEspress)
\relative {
  c'4_\roundFdynamic\< d e f
  g,1~_\boxFdynamic\>
  g1
  g'1~\mfEspressDynamic
  g1
}
@end lilypond

The Scheme form of markup mode may be used instead.  Its syntax is
explained in @rextend{Markup construction in Scheme}.

@lilypond[verbatim,quote]
moltoF = #(make-dynamic-script
            (markup #:normal-text "molto"
                    #:dynamic "f"))
\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}.

@morerefs
Notation Reference:
@ref{Formatting text},
@ref{Selecting font and font size},
@ref{Enhancing MIDI output},
@ref{Controlling MIDI dynamics}.

Extending LilyPond:
@rextend{Markup construction in Scheme}.

Snippets:
@rlsr{Expressive marks}.


@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
doits.

@menu
* Slurs::
* Phrasing slurs::
* Breath marks::
* Falls and doits::
@end menu

@node Slurs
@unnumberedsubsubsec Slurs

@cindex slur

@funindex (
@funindex )
@notation{Slurs} are entered using parentheses:

@warning{In polyphonic music, a slur must be terminated
in the same voice it began.}

@lilypond[verbatim,quote]
\relative {
  f''4( g a) a8 b(
  a4 g2 f4)
  <c e>2( <b d>2)
}
@end lilypond

@cindex slur, manual placement
@cindex slur, below notes
@cindex slur, above notes
@funindex \slurDown
@funindex \slurNeutral

Slurs may be manually placed above or below the staff; see
@ref{Direction and placement}.

@cindex phrasing slur
@cindex multiple slurs
@cindex simultaneous slurs
@cindex slur, phrasing
@cindex slur, multiple
@cindex slur, simultaneous

@c some entries for `\=' are auto-generated; don't use @funindexpost
@funindex \=

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
@cindex slur, dotted
@cindex slur, dashed
@cindex solid slur
@cindex dotted slur
@cindex dashed slur
@cindex style, slur
@funindex \slurDashed
@funindex \slurDotted
@funindex \slurSolid

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

@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 \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 {
  c'4( e g2)
  \slurHalfDashed
  g4( e c2)
  \slurHalfSolid
  c4( e g2)
  \slurSolid
  g4( e c2)
}
@end lilypond

@funindex \slurDashPattern
@cindex slur, defining dash patterns
@cindex dash patterns, slur

Custom dash patterns for slurs can be defined:

@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


@predefined
@code{\slurUp},
@code{\slurDown},
@code{\slurNeutral},
@code{\slurDashed},
@code{\slurDotted},
@code{\slurHalfDashed},
@code{\slurHalfSolid},
@code{\slurDashPattern},
@code{\slurSolid}.
@endpredefined


@snippets

@cindex slurs, double, for legato chords
@cindex double slurs, for legato chords
@findex doubleSlurs
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/using-double-slurs-for-legato-chords.ly}

@cindex markup, text, inside slurs
@cindex text markup, inside slurs
@cindex slur, text markup inside
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/positioning-text-markups-inside-slurs.ly}

@cindex slur, defining dash patterns
@cindex dash patterns, slur
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/making-slurs-with-complex-dash-structure.ly}


@morerefs
Music Glossary:
@rglos{slur}.

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

Notation Reference:
@ref{Direction and placement},
@ref{Phrasing slurs}.

Snippets:
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{Slur}.


@node Phrasing slurs
@unnumberedsubsubsec Phrasing slurs

@cindex phrasing slur
@cindex phrasing mark
@cindex slur, phrasing
@cindex mark, phrasing
@funindexpost \(
@funindexpost \)

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

@lilypond[verbatim,quote]
\relative {
  c''4\( d( e) f(
  e2) d\)
}
@end lilypond

@funindex \phrasingSlurUp
@funindex \phrasingSlurDown
@funindex \phrasingSlurNeutral

Typographically, a phrasing slur behaves almost exactly like a
normal slur.  However, they are treated as different objects; a
@code{\slurUp} will have no effect on a phrasing slur.  Phrasing
may be manually placed above or below the staff; see
@ref{Direction and placement}.

@cindex simultaneous phrasing slurs
@cindex multiple phrasing slurs
@cindex slur, simultaneous phrasing
@cindex slur, multiple phrasing
@cindex phrasing slur, simultaneous
@cindex phrasing slur, multiple

Simultaneous or overlapping phrasing slurs are entered using
@code{\=} as with regular slurs, see @ref{Slurs}.

@funindex \phrasingSlurDashed
@funindex \phrasingSlurDotted
@funindex \phrasingSlurSolid
@cindex phrasing slur, dashed
@cindex dashed phrasing slur
@cindex phrasing slur, dotted
@cindex dotted phrasing slur
@cindex slur, dashed phrasing
@cindex slur, dotted phrasing

Phrasing slurs can be solid, dotted, or dashed.  Solid is the default
style for phrasing slurs:

@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 \phrasingSlurHalfSolid
@cindex phrasing slur, half solid and half dashed
@cindex slur, half solid and half dashed phrasing

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 {
  c'4\( e g2\)
  \phrasingSlurHalfDashed
  g4\( e c2\)
  \phrasingSlurHalfSolid
  c4\( e g2\)
  \phrasingSlurSolid
  g4\( e c2\)
}
@end lilypond

@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 {
  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
as dash pattern definitions for slurs.  For more information about
complex dash patterns, see the snippets under @ref{Slurs}.

@predefined
@code{\phrasingSlurUp},
@code{\phrasingSlurDown},
@code{\phrasingSlurNeutral},
@code{\phrasingSlurDashed},
@code{\phrasingSlurDotted},
@code{\phrasingSlurHalfDashed},
@code{\phrasingSlurHalfSolid},
@code{\phrasingSlurDashPattern},
@code{\phrasingSlurSolid}.
@endpredefined

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

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

Snippets:
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{PhrasingSlur}.


@node Breath marks
@unnumberedsubsubsec Breath marks

@cindex breath mark
@cindex pause mark
@funindex \breathe

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

@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 { c''8 \breathe d e f g2 }
@end lilypond

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


@snippets

@cindex breath mark symbol, changing
@cindex changing breath mark symbol
@cindex symbol, breath mark, changing
@funindex BreathingSign
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/changing-the-breath-mark-symbol.ly}

@cindex tick mark
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/using-a-tick-as-the-breath-mark-symbol.ly}

@cindex caesura
@cindex railroad tracks
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/inserting-a-caesura.ly}


@morerefs
Music Glossary:
@rglos{caesura}.

Notation Reference:
@ref{Divisiones}.

Snippets:
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{BreathingEvent},
@rinternals{BreathingSign},
@rinternals{Breathing_sign_engraver}.


@node Falls and doits
@unnumberedsubsubsec Falls and doits

@cindex fall
@cindex doit
@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 c'' {
  c2\bendAfter #+4
  c2\bendAfter #-4
  c2\bendAfter #+6.5
  c2\bendAfter #-6.5
  c2\bendAfter #+8
  c2\bendAfter #-8
}
@end lilypond


@snippets

@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/adjusting-the-shape-of-falls-and-doits.ly}

@morerefs
Music Glossary:
@rglos{fall},
@rglos{doit}.

Snippets:
@rlsr{Expressive marks}.


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

@menu
* Glissando::
* Arpeggio::
* Trills::
@end menu

@node Glissando
@unnumberedsubsubsec Glissando

@cindex glissando
@funindex \glissando

A @notation{glissando} is created by appending @code{\glissando}
to a note:

@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

@funindex \glissandoMap

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

@cindex contemporary glissando
@cindex glissando, contemporary
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/contemporary-glissando.ly}

@cindex timing mark, for glissando
@cindex glissando, timing marks
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/adding-timing-marks-to-long-glissandi.ly}

@cindex breakable glissando
@cindex glissando, breakable
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/making-glissandi-breakable.ly}

@cindex glissando, across repeats
@cindex repeat, and glissandi
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/extending-glissandi-across-repeats.ly}

@morerefs
Music Glossary:
@rglos{glissando}.

Notation Reference:
@ref{Line styles}.

Snippets:
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{Glissando}.

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


@node Arpeggio
@unnumberedsubsubsec Arpeggio

@cindex arpeggio
@cindex broken chord
@cindex chord, broken

@funindex \arpeggio
@funindex \arpeggioArrowUp
@funindex \arpeggioArrowDown
@funindex \arpeggioNormal
@funindex arpeggio-direction

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 { <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 {
  <c' e g c>2\arpeggio

  \arpeggioArrowUp
  <c e g c>2\arpeggio

  \arpeggioArrowDown
  <c e g c>2\arpeggio

  \arpeggioNormal
  <c e g c>2\arpeggio
}
@end lilypond

These predefined commands internally modify the 
@code{'arpeggio-direction} property; see their full
definition in the @file{ly/property-init.ly} file.

@cindex arpeggio symbol, special
@cindex special arpeggio symbol

@funindex \arpeggioBracket
@funindex \arpeggioParenthesis
@funindex \arpeggioParenthesisDashed

Special @emph{bracketed} arpeggio symbols can be created:

@lilypond[verbatim,quote]
\relative {
  <c' e g c>2

  \arpeggioBracket
  <c e g c>2\arpeggio

  \arpeggioParenthesis
  <c e g c>2\arpeggio

  \arpeggioParenthesisDashed
  <c e g c>2\arpeggio

  \arpeggioNormal
  <c e g c>2\arpeggio
}
@end lilypond

These predefined commands internally override the @code{Arpeggio}
object’s @code{'stencil} property, and may also adapt its
@code{'X-extent} (that is, the horizontal dimension it takes
not to collide with other objects).

The dash properties of the parenthesis arpeggio are controlled
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}.


@predefined
@code{\arpeggio},
@code{\arpeggioArrowUp},
@code{\arpeggioArrowDown},
@code{\arpeggioNormal},
@code{\arpeggioBracket},
@code{\arpeggioParenthesis},
@code{\arpeggioParenthesisDashed}.
@endpredefined


@snippets

@cindex arpeggio, cross-staff
@cindex cross-staff arpeggio
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/creating-cross-staff-arpeggios-in-a-piano-staff.ly}

@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/creating-cross-staff-arpeggios-in-other-contexts.ly}

@cindex arpeggio, cross-voice
@cindex cross-voice arpeggio
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/creating-arpeggios-across-notes-in-different-voices.ly}

@morerefs
Music Glossary:
@rglos{arpeggio}.

Notation Reference:
@ref{Slurs},
@ref{Ties}.

Installed Files:
@file{ly/property-init.ly}.

Snippets:
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{Arpeggio},
@rinternals{Slur},
@rinternals{PianoStaff}.

@knownissues
Predefined commands such as @code{\arpeggioArrowUp} only
apply to the current context, and thus will not affect
arpeggios spanning several voices or staves.  In such cases,
these commands need to be used in a @code{\context} block within
@code{\layout}, or in a @code{\with} block, as explained in
@ref{Changing context default settings}.
Alternatively, rather than using predefined shortcuts, it may be
advisable to directly override the relevant properties for the
@code{Arpeggio} object in the appropriate context; for example:

@example
\override Staff.Arpeggio.stencil = #ly:arpeggio::brew-chord-bracket
@end example

@noindent
to print cross-voice arpeggio brackets at the @code{Staff} level, or

@example
\override PianoStaff.Arpeggio.arpeggio-direction = #UP
@end example

@noindent
to print cross-staff arrowed arpeggios (pointing upwards) in a
@code{PianoStaff} context.

@cindex cross-staff parenthesis-style arpeggio
@cindex arpeggio, cross-staff parenthesis-style

It is not possible to mix connected arpeggios and unconnected
arpeggios in one @code{PianoStaff} at the same point in
time.

The simple way of setting parenthesis-style arpeggio brackets does not work for
cross-staff arpeggios; see @ref{Cross-staff stems}.


@node Trills
@unnumberedsubsubsec Trills

@cindex trill

@funindex \trill
@funindex \startTrillSpan
@funindex \stopTrillSpan

Short trills without an extender line are printed with
@code{\trill}; see @ref{Articulations and ornamentations}.

Longer trills with an extender line are made with
@code{\startTrillSpan} and @code{\stopTrillSpan}:

@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 {
  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 {
  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 {
  d''1~\afterGrace
  d1\startTrillSpan { c32[ d]\stopTrillSpan }
  c2 r2
}
@end lilypond

@cindex pitched trill
@cindex trill, pitched
@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 {
  \pitchedTrill
  d''2\startTrillSpan fis
  d2
  c2\stopTrillSpan
  r2
}
@end lilypond

@cindex pitched trill, with accidental
@cindex trill, with accidental

The Accidental of the first pitched trill in a measure is always
printed, even for naturals.

@lilypond[verbatim,quote,relative]
{
  \key d \major
  \pitchedTrill
  d'2\startTrillSpan cis d\stopTrillSpan 
  \pitchedTrill
  d2\startTrillSpan c d\stopTrillSpan
  \pitchedTrill
  d2\startTrillSpan e d\stopTrillSpan
}
@end lilypond

@noindent
Subsequent accidentals (of the same note in the same measure) will need
to be added manually.

@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}.
@endpredefined

@morerefs
Music Glossary:
@rglos{trill}.

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

Snippets:
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{TrillSpanner}.
