Docs: move Programming interfaces into Extending.

[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.  See TRANSLATION for details.
@end ignore

@c \version "2.12.0"

@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
* Attached to notes::
* Curves::
* Lines::
@end menu


@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::
* 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 thumb marking
@cindex segno
@cindex coda
@cindex 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 @var{name} are listed in @ref{List of
articulations}.  For example:

@lilypond[verbatim,quote,relative=2]
c4\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=2]
c4-^  c-+  c--  c-|
c4->  c-.  c2-_
@end lilypond

The rules for the default placement of articulations are defined
in @file{scm/@/script@/.scm}.  Articulations and ornamentations
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}

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

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

Notation Reference:
@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=2]
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=2]
c2\< c\!
d2\< d\f
e2\< e\>
f2\> f\!
e2\> e\mp
d2\> d\>
c1\!
@end lilypond

Spacer rests are needed to engrave multiple marks on one note.

@cindex multiple dynamic marks on one note
@cindex dynamic marks, multiple on one note

@lilypond[verbatim,quote,relative=2]
c4\< c\! d\> e\!
<< f1 { s4 s4\< s4\> s4\! } >>
@end lilypond

@cindex espressivo articulation

@funindex \espressivo
@funindex espressivo

In some situations the @code{\espressivo} articulation mark may be
the appropriate choice to indicate a crescendo and decrescendo on
one note:

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

Crescendos and decrescendos can be engraved as textual markings
instead of hairpins.  Dashed lines are printed to indicate their
extent.  The built-in commands that enable these text modes are
@code{\crescTextCresc}, @code{\dimTextDecresc},
@code{\dimTextDecr}, and @code{\dimTextDim}.  The corresponding
@code{\crescHairpin} and @code{\dimHairpin} commands will revert
to hairpins again:

@lilypond[verbatim,quote,relative=2]
\crescTextCresc
c2\< d | e f\!
\dimTextDecresc
e2\> d | c b\!
\crescHairpin
c2\< d | e f\!
\dimHairpin
e2\> 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


@predefined
@code{\dynamicUp},
@code{\dynamicDown},
@code{\dynamicNeutral},
@code{\crescTextCresc},
@code{\dimTextDim},
@code{\dimTextDecr},
@code{\dimTextDecresc},
@code{\crescHairpin},
@code{\dimHairpin}.
@endpredefined


@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

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

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

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

@lilypondfile[verbatim,lilyquote,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{What goes into the MIDI output?},
@ref{Controlling MIDI dynamics}.

Snippets:
@rlsr{Expressive marks}.

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


@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 c' {
  <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' {
  c1_\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' {
  c4 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' {
  c4_\roundFdynamic\< d e f
  g,1~_\boxFdynamic\>
  g
  g'~\mfEspressDynamic
  g
}
@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 c' {
  <d e>16 <d e>
  <d e>2..\moltoF
}
@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{What goes into the MIDI output?},
@ref{Controlling MIDI dynamics}.

Snippets:
@rlsr{Expressive marks}.

Extend:
@rextend{Markup construction in Scheme},



@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::
* 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=2]
f4( 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=1]
c4( e g2)
\slurDashed
g4( e c2)
\slurDotted
c4( e g2)
\slurSolid
g4( e c2)
@end lilypond

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

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

@lilypond[verbatim,quote,relative=1]
c4( e g2)
\slurHalfDashed
g4( e c2)
\slurHalfSolid
c4( e g2)
\slurSolid
g4( e c2)
@end lilypond

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

Custom dash patterns for slurs can be defined:

@lilypond[verbatim,quote,relative=1]
c4( e g2)
\slurDashPattern #0.7 #0.75
g4( e c2)
\slurDashPattern #0.5 #2.0
c4( e g2)
\slurSolid
g4( e c2)
@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,lilyquote,texidoc,doctitle]
{using-double-slurs-for-legato-chords.ly}

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

@lilypondfile[verbatim,lilyquote,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=2]
c4\( 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=1]
c4\( 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=1]
c4\( 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, definind dash patterns for phrasing

Custom dash patterns for phrasing slurs can be defined:

@lilypond[verbatim,quote,relative=1]
c4\( e g2\)
\phrasingSlurDashPattern #0.7 #0.75
g4\( e c2\)
\phrasingSlurDashPattern #0.5 #2.0
c4\( e g2\)
\phrasingSlurSolid
g4\( e c2\)
@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,relative=2]
c2. \breathe d4
@end lilypond

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


@snippets

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{changing-the-breath-mark-symbol.ly}

@cindex caesura
@cindex railroad tracks

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{inserting-a-caesura.ly}


@seealso
Music Glossary:
@rglos{caesura}.

Notation Reference:
@ref{Divisiones}.

Snippets:
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{BreathingSign}.


@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=2]
c2-\bendAfter #+4
c2-\bendAfter #-4
c2-\bendAfter #+8
c2-\bendAfter #-8
@end lilypond

The dash @code{-} immediately preceding the @code{\bendAfter}
command is @emph{required} when writing falls and doits.


@snippets

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


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

Snippets:
@rlsr{Expressive marks}.


@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::
* Trills::
@end menu

@node Glissando
@unnumberedsubsubsec Glissando

@cindex glissando
@funindex \glissando
@funindex glissando

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

@lilypond[verbatim,quote,relative=2]
g2\glissando g'
c2\glissando c,
@end lilypond

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

@snippets

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{contemporary-glissando.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=1]
<c e g c>1\arpeggio
@end lilypond

Different types of arpeggios may be written.
@code{\arpeggioNormal} reverts to a normal arpeggio:

@lilypond[verbatim,quote,relative=1]
<c e g c>2\arpeggio

\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=1]
<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-details} 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,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
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 parenthesis-style arpeggio brackets do not work for
cross-staff arpeggios.


@node Trills
@unnumberedsubsubsec Trills

@cindex trills

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

Short @notation{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=2]
d1~\startTrillSpan
d1
c2\stopTrillSpan r2
@end lilypond

In the following example, a trill is combined with grace notes.
The syntax of this construct and the method to precisely position
the grace notes are described in @ref{Grace notes}.

@lilypond[verbatim,quote,relative=2]
c1 \afterGrace
d1\startTrillSpan { c32[ d]\stopTrillSpan }
e2 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=1]
\pitchedTrill e2\startTrillSpan fis
d\stopTrillSpan
@end lilypond

@cindex pitched trill with forced accidental
@cindex trill, pitched with forced accidental
@cindex accidental, forced for pitched trill

In the following example, the second pitched trill is ambiguous;
the accidental of the trilled note is not printed.  As a
workaround, the accidentals of the trilled notes can be forced.
The second measure illustrates this method:

@lilypond[verbatim,quote,relative=2]
\pitchedTrill eis4\startTrillSpan fis
g\stopTrillSpan
\pitchedTrill eis4\startTrillSpan fis
g\stopTrillSpan
\pitchedTrill eis4\startTrillSpan fis
g\stopTrillSpan
\pitchedTrill eis4\startTrillSpan fis!
g\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}.