Docs: remove implicit relative from @lilypond[verbatim]; issue 4371

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

@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]{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 articulations
@cindex ornamentation
@cindex scripts
@cindex ornaments
@cindex espressivo
@cindex fermata
@cindex upbow
@cindex downbow
@cindex foot marks
@cindex organ pedal marks
@cindex pedal marks, organ
@cindex turn
@cindex open
@cindex stopped
@cindex flageolet
@cindex reverseturn
@cindex trill
@cindex prall
@cindex mordent
@cindex prallprall
@cindex prallmordent
@cindex prall, up
@cindex prall, down
@cindex mordent, up
@cindex mordent, down
@cindex thumb marking
@cindex segno
@cindex coda
@cindex varcoda

@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 \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 \shortfermata
@funindex \fermata
@funindex \longfermata
@funindex \verylongfermata
@funindex \fermataMarkup
@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 as well as notes but they
cannot be attached to multi-measure rests.  A special predefined
command, @code{\fermataMarkup}, is available for attaching a fermata
to a multi-measure rest (and only a multi-measure rest).  This
creates a @code{MultiMeasureRestText} object.

@lilypond[verbatim,quote,fragment]
\override Script.color = #red
\override MultiMeasureRestText.color = #blue
a'2\fermata r\fermata
R1\fermataMarkup
@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

@lilypondfile[verbatim,quote,texidoc,doctitle]
{modifying-default-values-for-articulation-shorthand-notation.ly}

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

@lilypondfile[verbatim,quote,texidoc,doctitle]
{creating-a-delayed-turn.ly}

@seealso
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 ppppp
@funindex \pppp
@funindex pppp
@funindex \ppp
@funindex ppp
@funindex \pp
@funindex pp
@funindex \p
@funindex p
@funindex \mp
@funindex mp
@funindex \mf
@funindex mf
@funindex \f
@funindex f
@funindex \ff
@funindex ff
@funindex \fff
@funindex fff
@funindex \ffff
@funindex ffff
@funindex \fffff
@funindex fffff
@funindex \fp
@funindex fp
@funindex \sf
@funindex sf
@funindex \sff
@funindex sff
@funindex \sp
@funindex sp
@funindex \spp
@funindex spp
@funindex \sfz
@funindex sfz
@funindex \rfz
@funindex rfz

Absolute dynamic marks are specified using a command after a note,
such as @code{c4\ff}.  The available dynamic marks are
@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}, and @code{\rfz}.  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

@funindex \<
@funindex \>
@funindex \!
@funindex \cr
@funindex cr
@funindex \decr
@funindex decr

A @notation{crescendo} mark is started with @code{\<} and
terminated with @code{\!}, an absolute dynamic, or an additional
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 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.

@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 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 {
  c''4\< c\! d\> e\!
  << f1 { s4 s4\< s4\> s4\! } >>
}
@end lilypond

@cindex espressivo articulation

@funindex \espressivo
@funindex espressivo

The @code{\espressivo} command can be used to indicate a crescendo
and decrescendo on the same note.  However, be warned that this is
implemented as an articulation, not a dynamic.

@lilypond[verbatim,quote]
\relative {
  c''2 b4 a
  g1\espressivo
}
@end lilypond

@funindex \cresc
@funindex cresc
@funindex \decresc
@funindex decresc
@funindex \dim
@funindex dim
Textual crescendo marks begin with @code{\cresc}.
Textual decrescendos begin with @code{\decresc} or @code{\dim}.
Extender lines are engraved as required.

@lilypond[verbatim,quote]
\relative {
  g'8\cresc a b c b c d e\mf |
  f8\decresc e d c e\> d c b |
  a1\dim ~ |
  a2. r4\! |
}
@end lilypond

@funindex \crescTextCresc
@funindex crescTextCresc
@funindex \dimTextDecresc
@funindex dimTextDecresc
@funindex \dimTextDecr
@funindex dimTextDecr
@funindex \dimTextDim
@funindex dimTextDim
@funindex \crescHairpin
@funindex crescHairpin
@funindex \dimHairpin
@funindex dimHairpin

Textual marks for dynamic changes can also replace hairpins:
@lilypond[verbatim,quote]
\relative 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 dynamicUp
@funindex \dynamicDown
@funindex dynamicDown
@funindex \dynamicNeutral
@funindex dynamicNeutral

A @code{Dynamics} context is available to engrave dynamics on
their own horizontal line.  Use spacer rests to indicate timing.
(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

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

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

@cindex al niente
@cindex niente, al

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

@cindex Ferneyhough hairpins
@cindex hairpins, Ferneyhough
@cindex flared hairpins
@cindex hairpins, flared
@cindex constante hairpins
@cindex hairpins, constante

@lilypondfile[verbatim,quote,texidoc,doctitle]
{printing-hairpins-in-various-styles.ly}

@lilypondfile[verbatim,quote,texidoc,doctitle]
{vertically-aligned-dynamics-and-textscripts.ly}

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

@lilypondfile[verbatim,quote,texidoc,doctitle]
{changing-text-and-spanner-styles-for-text-dynamics.ly}

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

Learning Manual:
@rlearning{Articulation 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 marks
@cindex dynamic marks, 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 bracket
@funindex \dynamic
@funindex dynamic

In markup mode, editorial dynamics (within parentheses or square
brackets) can be created.  The syntax for markup mode is described
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

@cindex make-dynamic-script
@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}.

@seealso
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 slurs

@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 slurs, manual placement
@cindex slurs, below notes
@cindex slurs, above notes
@funindex \slurDown
@funindex slurDown
@funindex \slurNeutral
@funindex slurNeutral

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

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

Simultaneous or overlapping slurs are not permitted, but a phrasing
slur can overlap a slur.  This permits two slurs to be printed at
once.  For details, see @ref{Phrasing slurs}.

@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 slurDashed
@funindex \slurDotted
@funindex slurDotted
@funindex \slurSolid
@funindex slurSolid

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

@lilypond[verbatim,quote]
\relative {
  c'4( e g2)
  \slurDashed
  g4( e c2)
  \slurDotted
  c4( e g2)
  \slurSolid
  g4( e c2)
}
@end lilypond

@funindex \slurHalfDashed
@funindex slurHalfDashed
@funindex \slurHalfSolid
@funindex slurHalfSolid
@cindex slur, half dashed and half solid

Slurs can also be made half-dashed (the first half dashed, the
second half solid) or half-solid (the first half solid, the second
half dashed):

@lilypond[verbatim,quote]
\relative {
  c'4( e g2)
  \slurHalfDashed
  g4( e c2)
  \slurHalfSolid
  c4( e g2)
  \slurSolid
  g4( e c2)
}
@end lilypond

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

Custom dash patterns for slurs can be defined:

@lilypond[verbatim,quote]
\relative {
  c'4( e g2)
  \slurDashPattern #0.7 #0.75
  g4( e c2)
  \slurDashPattern #0.5 #2.0
  c4( e g2)
  \slurSolid
  g4( e c2)
}
@end lilypond



@funindex \slurUp
@funindex slurUp


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


@snippets

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

@lilypondfile[verbatim,quote,texidoc,doctitle]
{positioning-text-markups-inside-slurs.ly}

@lilypondfile[verbatim,quote,texidoc,doctitle]
{making-slurs-with-complex-dash-structure.ly}

@seealso
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 slurs
@cindex phrasing marks
@cindex slur, phrasing
@cindex mark, phrasing
@funindex \(
@funindex \)

@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 phrasingSlurUp
@funindex \phrasingSlurDown
@funindex phrasingSlurDown
@funindex \phrasingSlurNeutral
@funindex phrasingSlurNeutral

Typographically, a phrasing slur behaves almost exactly like a
normal slur.  However, they are treated as different objects; a
@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 not permitted.

@funindex phrasingSlurDashed
@funindex \phrasingSlurDashed
@funindex \phrasingSlurDotted
@funindex phrasingSlurDotted
@funindex \phrasingSlurSolid
@funindex phrasingSlurSolid
@cindex phrasing slur, dashed
@cindex dashed phrasing slur
@cindex phrasing slur, dotted
@cindex dotted phrasing slurs
@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 \phrasingSlurHalfDashed
@funindex \phrasingSlurHalfSolid
@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
@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

@seealso
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 marks
@cindex pause mark
@funindex \breathe
@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

@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,quote,texidoc,doctitle]
{inserting-a-caesura.ly}

@seealso
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 falls
@cindex doits
@funindex \bendAfter
@funindex bendAfter

@notation{Falls} and @notation{doits} can be added to notes using
the @code{\bendAfter} command.  The direction of the fall or doit
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]
{adjusting-the-shape-of-falls-and-doits.ly}

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

A glissando can connect notes in chords.  If anything other than a
direct one-to-one pairing of the notes in the two chords is required
the connections between the notes are defined by setting
@code{\glissandoMap}, where the notes of a chord are assumed to be
numbered from zero in the order in which they appear in the input
@file{.ly} file.

@lilypond[verbatim,quote]
\relative {
  <c' e>1\glissando g' |
  <c, e>1\glissando |
  <g' b> |
  \break
  \set glissandoMap = #'((0 . 1) (1 . 0))
  <c, g'>1\glissando |
  <d a'> |
  \set glissandoMap = #'((0 . 0) (0 . 1) (0 . 2))
  c1\glissando |
  <d f a> |
  \set glissandoMap = #'((2 . 0) (1 . 0) (0 . 1))
  <f d a'>1\glissando |
  <c c'> |
}
@end lilypond

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


@snippets
@lilypondfile[verbatim,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:
@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 arpeggio
@funindex \arpeggioArrowUp
@funindex arpeggioArrowUp
@funindex \arpeggioArrowDown
@funindex arpeggioArrowDown
@funindex \arpeggioNormal
@funindex arpeggioNormal

An @notation{arpeggio} on a chord (also known as a broken chord)
is denoted by appending @code{\arpeggio} to the chord construct:

@lilypond[verbatim,quote]
\relative { <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

@cindex arpeggio symbols, special
@cindex special arpeggio symbols

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

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

@lilypond[verbatim,quote]
\relative {
  <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

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

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

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

@lilypondfile[verbatim,quote,texidoc,doctitle]
{creating-arpeggios-across-notes-in-different-voices.ly}

@seealso
Music Glossary:
@rglos{arpeggio}.

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

Snippets:
@rlsr{Expressive marks}.

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

@knownissues
@cindex cross-staff parenthesis-style arpeggio
@cindex arpeggio, parenthesis-style, cross-staff
@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 trills

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

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

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 trills
@cindex trills, pitched
@funindex \pitchedTrill
@funindex pitchedTrill

Trills that require an auxiliary note with an explicit pitch can
be typeset with the @code{\pitchedTrill} command.  The first
argument is the main note, and the second is the @emph{trilled}
note, printed as a stemless note head in parentheses.

@lilypond[verbatim,quote]
\relative {
  \pitchedTrill
  d''2\startTrillSpan fis
  d2
  c2\stopTrillSpan
  r2
}
@end lilypond

@cindex pitched trill with accidental
@cindex trill with accidental

Subsequent accidentals of the same note in the same measure will need
to be added manually.  Only the accidental of the first pitched trill
in a measure is printed.

@lilypond[verbatim,quote]
\relative {
  \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

@seealso
Music Glossary:
@rglos{trill}.

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

Snippets:
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{TrillSpanner}.