Update from Valentin.

[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.38"

@node Expressive marks
@section Expressive marks

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

@menu
* Attached to notes::           
* Curves::                      
* Lines::                       
@end menu


@node Attached to notes
@subsection Attached to notes

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

@node Articulations and ornamentations
@subsubsection 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-|
c->   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}.

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
@subsubsection 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
c\rfz c^\mf
c_\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
@notation{crescendo} or @notation{decrescendo} mark.  A
@notation{decrescendo} mark is started with @code{\>} and is also
terminated with @code{\!}, an absolute dynamic, or another
@notation{crescendo} or @notation{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 notes 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 @notation{crescendo} and
@notation{decrescendo} on one note:

@lilypond[verbatim,quote,relative=2]
c2 b4 a
g1\espressivo
@end lilypond

@cindex crescendo
@cindex decrescendo
@cindex diminuendo
@funindex \setTextCresc
@funindex \setTextDim
@funindex \setTextDecr
@funindex \setTextDecresc
@funindex \setHairpinCresc
@funindex \setHairpinDim
@funindex \setHairpinDecresc

@notation{Crescendos} and @notation{decrescendos} can be engraved
as textual markings instead of hairpins.  The built-in commands
that enable these text modes are @code{\setTextCresc},
@code{\setTextDecresc}, @code{\setTextDecr}, and
@code{\setTextDim}.  The corresponding @code{\setHairpinCresc},
@code{\setHairpinDim}, and @code{\setHairpinDecresc} commands will
revert to hairpins again:

@lilypond[verbatim,quote,relative=2]
c\< d e f\!
e\> d c b\!
\setTextCresc
c\< d e f\!
\setTextDecresc
e\> d c b\!
\setHairpinCresc
c\< 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}.


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

@c I can't figure this one out.  Consider removing this.  -pm

@notation{Crescendi} and @notation{decrescendi} that cross a line
break will be continued on the second line.  If they end on the
first note of a new line, nothing will be printed on that line.
To change this behavior, use

@example
\override Score.Hairpin #'after-line-breaking = ##t
@end example

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

@c The following snippet goes in input/new/
@c @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
@c {changing-text-and-spanner-styles-for-text-dynamics.ly}

The text used for @notation{crescendos} and
@notation{decrescendos} can be changed by modifying the context
properties @code{crescendoText} and @code{decrescendoText}.  The
style of the spanner line can be changed by modifying the
@code{'style} property of @code{DynamicTextSpanner}.  The default
value is @code{'hairpin}, and other possible values include
@code{'line}, @code{'dashed-line}, and @code{'dotted-line}:

@lilypond[verbatim,quote,relative=2]
\set crescendoText = \markup { \italic "cresc. poco" }
\set crescendoSpanner = #'text
\override DynamicTextSpanner #'style = #'dotted-line
a2\< a
a2 a
a2 a
a2 a\mf
@end lilypond


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

Snippets:
@rlsr{Expressive marks}.

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


@node New dynamic marks
@subsubsection 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]
rndf = \markup { \center-align { \line { \bold { \italic ( }
         \dynamic f \bold { \italic ) } } } }
boxf = \markup { \bracket { \dynamic f } }
\relative c' {
  c1_\rndf
  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

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

@node Slurs
@subsubsection Slurs

@cindex slurs

A @notation{slur} indicates that notes are to be played bound or
@emph{legato}.  They are entered using parentheses:

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

Just as with ties, the direction of a slur can be specified with
@code{\slur@emph{DIR}}, where @code{@emph{DIR}} is either
@code{Up}, @code{Down}, or @code{Neutral} (@code{Neutral} is the
default).  Slurs may be manually placed above or below the staff,
see @ref{Direction and placement}.

@lilypond[verbatim,quote,relative=2]
c4_( c) c^( c)
@end lilypond

Using this method, only one slur can be printed at once.  To print
a long slur over a few small slurs, see @ref{Phrasing slurs}.


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

Snippets:
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{Slur}.


@node Phrasing slurs
@subsubsection Phrasing slurs

@cindex phrasing slurs
@cindex phrasing marks
@funindex \(
@funindex \)

A phrasing slur (or phrasing mark) connects notes and is used to
indicate a musical sentence.  It is written using @code{\(} and
@code{\)} respectively:

@lilypond[verbatim,quote,relative=2]
\time 6/4 c\( d( e) f( e) d\)
@end lilypond

Typographically, the 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; instead,
use @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and
@code{\phrasingSlurNeutral}.  Phrasing slurs may be manually
placed above or below the staff, see @ref{Direction
and placement}.

You cannot have simultaneous phrasing slurs.


@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
@subsubsection Breath marks

@cindex breath marks
@funindex \breathe

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

@lilypond[verbatim,quote,relative=2]
c4 \breathe d4
@end lilypond


@snippets

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


@seealso

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

Internals Reference:
@rinternals{BreathingSign}.


@node Falls and doits
@subsubsection Falls and doits

@cindex falls
@cindex doits
@funindex \bendAfter

@notation{Falls} and @notation{doits} can be added to notes using
the @code{\bendAfter} command:

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

The dash (@tie{-}) following the note name is @emph{required} when
writing @notation{falls} and @notation{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

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

@node Glissando
@subsubsection Glissando

@cindex glissando
@funindex \glissando

A @notation{glissando} is a smooth change in pitch.  It is denoted
by a line or a wavy line between two notes.  A
@notation{glissando} is created by attaching @code{\glissando} to
a note:

@lilypond[verbatim,quote,relative=2]
c2\glissando c'
\override Glissando #'style = #'zigzag
c2\glissando c,
@end lilypond


@snippets

@c Modify, add description, and put in input/new/
@c @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
@c {suppressing-warnings-for-clashing-note-columns.ly}

@lilypond[verbatim,quote]
I = \once \override NoteColumn #'ignore-collision = ##t

\relative c' <<
  { \oneVoice \stemDown f2 \glissando \stemNeutral a } \\
  { \oneVoice \I c2 \glissando \I d, }
>>
@end lilypond


@seealso

Music Glossary:
@rglos{glissando}.

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

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

@c Add documentation for new 'parenthesis' style arpeggio.  Maybe
@c create a new \arpeggioParen command, or something similar. -pm

You can specify an @notation{arpeggio} (also known as a
@notation{broken chord}) on a chord by attaching an
@code{\arpeggio} to the chord:

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

A square bracket on the left, denoted by @code{\arpeggioBracket},
is used to indicate that the chord should @emph{not} be
arpeggiated:

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

The direction of the arpeggio can be denoted by adding an
arrowhead to the wiggly line.  This is done with the commands
@code{arpeggioUp} and @code{arpeggioDown}.  @code{arpeggioNeutral}
reverts to the arrow-less version:

@lilypond[verbatim,quote,relative=1]
\new Voice {
  \arpeggioUp
  <c e g c>\arpeggio
  \arpeggioDown
  <c e g c>\arpeggio
  \arpeggioNeutral
  <c e g c>\arpeggio
}
@end lilypond

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

@predefined

@funindex \arpeggio
@code{\arpeggio},
@funindex \arpeggioUp
@code{\arpeggioUp},
@funindex \arpeggioDown
@code{\arpeggioDown},
@funindex \arpeggioNeutral
@code{\arpeggioNeutral},
@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

@c TODO: Add 'broken chord' to glossary.

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.


@node Trills
@subsubsection Trills

@cindex trills
@funindex \trill

Short @notation{trills} are printed with @code{\trill} like normal
articulation; see @ref{Articulations and ornamentations}.

Long running @notation{trills} are made with
@code{\startTrillSpan} and @code{\stopTrillSpan}.  In the
following example, a long running @notation{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

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

Snippets:
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{TrillSpanner}.