Merge branch 'master' of /home/lilydev/git/lily/

[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 (@tie{}@code{-}) followed by a symbol
signifying the articulation.  Predefined shorthands exist for
@notation{marcato}, @notation{stopped}, @notation{tenuto},
@notation{staccatissimo}, @notation{accent}, @notation{staccato},
and @notation{portato}.  Their corresponding output appears as
follows:

@lilypond[verbatim,quote,relative=2]
c4-^  c-+  c--  c-|
c4->  c-.  c-_
@end lilypond

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


@knownissues

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


@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

Markup mode makes possible, for instance, to add
editorial dynamics, printed in round parenthesis or square
brackets.  Its syntax is described in @ref{Formatting text}.

@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

Markup objects are treated differently from authentic dynamic marks.
Defining dynamic objects that will be entered and printed exactly like
standard dynamic marks is also possible, using the following function:

@cindex make-dynamic-script

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

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

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

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


@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

@c input/new snippet
@c @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
@c {inserting-a-caesura.ly}

Caesura marks can be created by overriding the @code{'text}
property of the @code{BreathingSign} object.  A curved caesura
mark is also available.

@lilypond[verbatim,quote,relative=2]
\override BreathingSign #'text =
  #(make-musicglyph-markup "scripts.caesura.straight")
c8 e4. \breathe g8. e16 c4

\override BreathingSign #'text =
  #(make-musicglyph-markup "scripts.caesura.curved")
g8 e'4. \breathe g8. e16 c4
@end lilypond


@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 (@tie{-}) immediately preceding the @code{\bendAfter}
command is @emph{required} when writing falls and doits.


@snippets

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


@seealso

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

Snippets:
@rlsr{Expressive marks}.


@node Lines
@subsection Lines

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

The direction of an arpeggio is indicated by adding an arrowhead
to the wiggly line.  The commands @code{\arpeggioArrowUp} and
@code{\arpeggioArrowDown} are used for this task.
@code{\arpeggioNormal} reverts back to an arrow-less arpeggio:

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

The command @code{\arpeggioBracket} can be used to create a square
bracket on the left of a chord, indicating that the chord should
@emph{not} be arpeggiated.  @code{\arpeggioNormal} reverts back
to a regular arpeggio:

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

A @emph{parenthesis} style bracket may be attached to a chord
construct instead of a square bracket.

@c Maybe create a new \arpeggioParen command, or something
@c like that. -pm

@lilypond[verbatim,quote,relative=1]
<c e g c>2
\override Arpeggio #'stencil = #ly:arpeggio::brew-chord-slur
\override Arpeggio #'X-extent = #ly:grob::stencil-width
<c e g c>2\arpeggio
\arpeggioNormal
<c e g c>1\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}.


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

Long running trills are made with @code{\startTrillSpan} and
@code{\stopTrillSpan}.  In the following example, a long running
trill is shown combined with grace notes.  To achieve precise
control of the placement of the grace notes, see @ref{Grace
notes}.

@lilypond[verbatim,quote,relative=2]
c1 \afterGrace
d1\startTrillSpan { c16[\stopTrillSpan d] }
c4
@end lilypond

@cindex pitched trills
@cindex trills, pitched

Trills that should be executed on an explicitly specified pitch
can be typeset with the command @code{\pitchedTrill} using the
following syntax:

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

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

@noindent
The first argument is the main note.  The pitch of the second is
printed as a stemless note head in parentheses.


@predefined

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


@seealso

Music Glossary:
@rglos{trill}.

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

Snippets:
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{TrillSpanner}.