Update for expressive.itely

[lilypond.git] / Documentation / user / 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.11.51"

@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 scripts
@cindex ornaments
@cindex espressivo
@cindex fermata
@cindex upbow
@cindex downbow
@cindex foot marks
@cindex organ pedal marks
@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

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 stopped
@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}


@seealso

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

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

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

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

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

A @notation{crescendo} mark is started with @code{\<} and
terminated with @code{\!}, an absolute dynamic, or an additional
crescendo or decrescendo mark.  A @notation{decrescendo} mark is
started with @code{\>} and is also terminated with @code{\!}, an
absolute dynamic, or another crescendo or decrescendo mark.
@code{\cr} and @code{\decr} may be used instead of @code{\<} and
@code{\>}.  @notation{Hairpins} are engraved by default using this
notation.

@lilypond[verbatim,quote,relative=2]
c2\< c\!
d2\< d\f
e2\< e\>
f2\> f\!
e2\> e\mp
d2\> d\>
c1\!
@end lilypond

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

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

@cindex espressivo articulation

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

@cindex crescendo
@cindex decrescendo
@cindex diminuendo

Crescendos and decrescendos can be engraved as textual markings
instead of hairpins.  The built-in commands that enable these text
modes are @code{\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]
c4\< d e f\!
e4\> d c b\!
\crescTextCresc
c4\< d e f\!
\dimTextDecresc
e4\> d c b\!
\crescHairpin
c4\< d e f\!
@end lilypond

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

Vertical positioning of dynamics is handled by
@rinternals{DynamicLineSpanner}.


@predefined

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


@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-aligning-dynamics-across-multiple-notes.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

@c TODO: Add hairpin to glossary.

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

Learning Manual:
@rlearning{Articulation and dynamics}.

Notation Reference:
@ref{Direction and placement},
@ref{New dynamic marks}.

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 <d e>
  <d e>2.._\moltoF
}
@end lilypond

@cindex dynamics, editorial
@cindex dynamics, parenthesis

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 { \line { \bold { \italic ( }
         \dynamic f \bold { \italic ) } } } }
boxf = \markup { \bracket { \dynamic f } }
\relative c' {
  c1_\roundf
  c1_\boxf
}
@end lilypond

By default, markup objects are aligned to the left side of a note
head, but authentic dynamic marks are always centered on the note
head.  New, centered dynamic marks can be created using the
following function:

@cindex make-dynamic-script

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

@noindent
The dynamic font only contains the characters @code{f,m,p,r,s} and
@code{z}.  In order to use other font families, it is necessary to
use markup mode in its Scheme form, as explained in
@ref{Markup construction in Scheme}.

@lilypond[verbatim,quote]
moltoF = #(make-dynamic-script (markup 
                      #:normal-text "molto"
                      #:dynamic "f"))
\relative c' {
  <d e>16 <d e>
  <d e>2..\moltoF
}
@end lilypond

@noindent
Font settings in markup mode are described in
@ref{Common markup commands}.


@seealso

Notation Reference:
@ref{Formatting text},
@ref{Common markup commands},
@ref{Markup construction in Scheme}.

Snippets:
@rlsr{Expressive marks}.


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

@lilypond[verbatim,quote,relative=2]
f4( g a) a8 b(
a4 g2 f4)
<c e>2( <b d>2)
@end lilypond

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

@lilypond[verbatim,quote,relative=2]
c2( d)
\slurDown
c2( d)
\slurNeutral
c2( d)
@end lilypond

Phrasing slurs must be used to print more than one slur at once.
For details, see @ref{Phrasing slurs}.

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


@predefined

@funindex \slurUp
@code{\slurUp},
@funindex \slurDown
@code{\slurDown},
@funindex \slurNeutral
@code{\slurNeutral},
@funindex \slurDashed
@code{\slurDashed},
@funindex \slurDotted
@code{\slurDotted},
@funindex \slurSolid
@code{\slurSolid}.


@snippets

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


@seealso

Music Glossary:
@rglos{slur}.

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

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

@lilypond[verbatim,quote,relative=1]
c4\( g' c,( b) | c1\)
\phrasingSlurUp
c4\( g' c,( b) | c1\)
@end lilypond

Simultaneous phrasing slurs are not permitted.


@predefined

@funindex \phrasingSlurUp
@code{\phrasingSlurUp},
@funindex \phrasingSlurDown
@code{\phrasingSlurDown},
@funindex \phrasingSlurNeutral
@code{\phrasingSlurNeutral}.


@seealso

Notation Reference:
@ref{Direction and placement}.

Snippets:
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{PhrasingSlur}.


@node Breath marks
@unnumberedsubsubsec Breath marks

@cindex breath marks
@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

Notation Reference:
@ref{Divisiones}.

Snippets:
@rlsr{Expressive marks}.
@c @lsr{expressive,breathing-sign.ly}.

Internals Reference:
@rinternals{BreathingSign}.


@node Falls and doits
@unnumberedsubsubsec Falls and doits

@cindex falls
@cindex doits
@funindex \bendAfter

@notation{Falls} and @notation{doits} can be added to notes using
the @code{\bendAfter} command.  The direction of the fall or doit
is indicated with a plus or minus (up or down).  The number
indicates the pitch interval that the fall or doit will extend
@emph{beyond} the main note.

@lilypond[verbatim,quote,relative=2]
c2-\bendAfter #+4
c2-\bendAfter #-4
c2-\bendAfter #+8
c2-\bendAfter #-8
@end lilypond

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

@c TODO: add falls and doits to glossary.
@c Music Glossary:
@c @rglos{falls},
@c @rglos{doits}.

Snippets:
@rlsr{Expressive marks}.


@node Lines
@subsection Lines

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

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

Internals Reference:
@rinternals{Glissando}.


@knownissues

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


@node Arpeggio
@unnumberedsubsubsec Arpeggio

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

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

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

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

@predefined

@funindex \arpeggio
@code{\arpeggio},
@funindex \arpeggioArrowUp
@code{\arpeggioArrowUp},
@funindex \arpeggioArrowDown
@code{\arpeggioArrowDown},
@funindex \arpeggioNormal
@code{\arpeggioNormal},
@funindex \arpeggioBracket
@code{\arpeggioBracket},
@funindex \arpeggioParenthesis
@code{\arpeggioParenthesis}.


@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{Ties}.

Snippets:
@rlsr{Expressive marks}.

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


@knownissues

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

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}.  In the
following example, the trill is combined with grace notes.  To
achieve precise control over the placement of the grace notes, see
@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

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.

@c This syntax example doesn't look nice. -pm

@c @example
@c @code{\pitchedTrill} @var{mainnote} @code{\startTrillSpan}
@c @var{trillnote} @var{endnote} @code{\stopTrillSpan}
@c @end example

@lilypond[verbatim,quote,relative=1]
\pitchedTrill e2\startTrillSpan fis
d\stopTrillSpan
@end lilypond

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

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


@seealso

Music Glossary:
@rglos{trill}.

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

Snippets:
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{TrillSpanner}.