Add test file for single-note tuplets

[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

@node Expressive marks
@section Expressive marks

@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
{expressive-headword.ly}

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


@node Attached to notes
@subsection Attached to notes


@menu
* Articulations and ornamentations::  
* Dynamics::                    
@end menu

@node Articulations and ornamentations
@subsubsection Articulations and ornamentations

@cindex articulations
@cindex scripts
@cindex ornaments

A variety of symbols can appear above and below notes to indicate
different characteristics of the performance.  All these symbols
can be attached to a note using the syntax
@var{note}@tie{}@code{\}@var{name}.

@c Add a LilyPond example here soon. -pm

The possible values for @var{name} are listed in @ref{List of
articulations}.

@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,ragged-right,fragment,relative=2]
c4-^  c-+  c--  c-|
c->   c-.  c-_
@end lilypond

The marks are placed automatically by default (either above or
below the note), but their positions can be manually @q{forced}
above or below notes as well.  For details, see
@ref{Controlling direction and placement}.

@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


@snippets

@c Send these snippets to Valentin for the LSR.

The shorthands are defined in @file{ly/@/script@/-init@/.ly},
where the variables @code{dashHat}, @code{dashPlus},
@code{dashDash}, @code{dashBar}, @code{dashLarger},
@code{dashDot}, and @code{dashUnderscore} are assigned default
values.  The default values for the shorthands can be modified.
For example, to associate the @code{-+} (@code{dashPlus})
shorthand with the @notation{trill} symbol instead of the default
@notation{+} symbol, assign the value @code{trill} to the variable
@code{dashPlus}:

@lilypond[verbatim,quote,ragged-right]
\relative c'' { c-+ }
dashPlus = "trill"
\relative c'' { c-+ }
@end lilypond

The vertical ordering of scripts is controlled with the
@code{script-priority} property.  The lower this number, the
closer it will be put to the note.  In this example, the
@code{TextScript} (the sharp symbol) first has the lowest
priority, so it is put lowest in the first example.  In the
second, the @notation{prall trill} (the @code{Script}) has the
lowest, so it is on the inside.  When two objects have the same
priority, the order in which they are entered decides which one
comes first.

@lilypond[verbatim,quote,ragged-right,fragment,relative=3]
\once \override TextScript #'script-priority = #-100
a4^\prall^\markup { \sharp }

\once \override Script #'script-priority = #-100
a4^\prall^\markup { \sharp }
@end lilypond


@seealso

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

Snippets: @lsrdir{Expressive,Expressive-marks}

Internals Reference: @internalsref{Script},
@internalsref{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 dynamics
@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,
like @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 can be placed
above or below the staff: For details, see
@ref{Controlling direction and placement}.

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
c2\ppp c\mp
c\rfz c^\mf
c_\spp c_\staccato^\ff
@end lilypond

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

A @notation{crescendo} mark is started with @code{\<} and
terminated with @code{\!} or an absolute dynamic.  A
@notation{decrescendo} is started with @code{\>} and is also
terminated with @code{\!} or an absolute dynamic.  @code{\cr} and
@code{\decr} may be used instead of @code{\<} and @code{\>}.  They
can be engraved either using a graphical sign (a
@notation{hairpin}), or with textual signs.

Because these marks are bound to notes, you must use spacer notes
if multiple marks are needed during one note.

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

This may give rise to very short hairpins.  To lengthen them, use
for example @code{minimum-length} in
@internalsref{Voice}.@internalsref{Hairpin}:

@example
\override Voice.Hairpin #'minimum-length = #5
@end example

@noindent
A @notation{hairpin} normally starts at the left edge of the
beginning note and ends on the right edge of the ending note.  If
the ending note falls on the downbeat, the @notation{hairpin} ends
on the immediately preceding bar line.  This may be modified by
setting the @code{hairpinToBarline} property:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
e4\< e2. e1\!
\set hairpinToBarline = ##f
e4\< e2. e1\!
@end lilypond

@cindex espressivo, articulation

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

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

@cindex al niente
@cindex niente, al

Hairpins may be printed with a circled tip (al niente notation) by
setting the @code{circled-tip} property:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
\override Hairpin #'circled-tip = ##t
c2\< c\!
c4\> c\< c2\!
@end lilypond

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

You can use text saying @emph{cresc.}, @emph{decr.}, or
@emph{dim.} instead of hairpins with the commands
@code{\setTextCresc}, @code{\setTextDim}, and
@code{\setTextDecresc}.  The corresponding
@code{\setHairpinCresc}, @code{\setHairpinDim}, and
@code{\setHairpinDecresc} will revert to hairpins again:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
\setTextCresc
c\< d e f\!
\setHairpinCresc
e\> d c b\!
\setTextDecresc
e\> d e f\!
\setTextDecr
c\> d e f\!
\setTextDim
e\> d c b\!
@end lilypond

You can also supply your own texts and change the style of the
spanner line with the properties @code{\crescendoText},
@code{\crescendoSpanner}, @code{\decrescendoText}, and
@code{\decrescendoSpanner}.  Available values for the spanner
properties are @code{hairpin}, @code{line}, @code{dashed-line},
and @code{dotted-line}.  If unset, a hairpin crescendo is used:

@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
\set crescendoText = \markup { \italic "cresc. poco" }
\set crescendoSpanner = #'dotted-line
a'2\< a a a a a a a\!\mf
@end lilypond

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

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


@predefined

@funindex \dynamicUp
@code{\dynamicUp},
@funindex \dynamicDown
@code{\dynamicDown},
@funindex \dynamicNeutral
@code{\dynamicNeutral}.


@snippets

Dynamics that occur at, begin on, or end on the same note will be
vertically aligned.  If you want to ensure that dynamics are
aligned when they do not occur on the same note, you can increase
the @code{staff-padding} property.

@example
\override DynamicLineSpanner #'staff-padding = #4
@end example

@noindent
You may also use this property if the dynamics are colliding with
other notation.

Crescendi and 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

Text style dynamic changes (such as @emph{cresc.} and @emph{dim.})
are printed with a dashed line showing their extent.  To surpress
printing this line, use

@example
\override DynamicTextSpanner #'dash-period = #-1.0
@end example


@seealso

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

Learning Manual: @rlearning{Articulation and dynamics}.

Snippets: @lsrdir{Expressive,Expressive-marks}

Internals Reference: @internalsref{DynamicText},
@internalsref{Hairpin}.  Vertical positioning of these symbols is
handled by @internalsref{DynamicLineSpanner}.


@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,ragged-right,fragment,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).  The shorthands are also available: For details, see
@ref{Controlling direction and placement}.

@lilypond[verbatim,quote,ragged-right,fragment,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

Some composers write two slurs when they want legato chords.  This
can be achieved in LilyPond by setting @code{doubleSlurs},

@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
\set doubleSlurs = ##t
<c e>4 ( <d f> <c e> <d f> )
@end lilypond


@seealso

Music Glossary: @rglos{slur}

Snippets: @lsrdir{Expressive,Expressive-marks}

Internals Reference: @internalsref{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,ragged-right,fragment,relative=1]
\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}.  The shorthands work for phrasing
slurs as well: For details, see @ref{Controlling direction and placement}.

You cannot have simultaneous phrasing slurs.


@predefined

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


@seealso

Snippets: @lsrdir{Expressive,Expressive-marks}

Internals Reference: @internalsref{PhrasingSlur}


@node Breath marks
@subsubsection Breath marks

@cindex breath marks
@funindex \breathe

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

@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
c'4 \breathe d4
@end lilypond


@snippets

The glyph of the breath mark can be tuned by overriding the
@code{text} property of the @code{BreathingSign} layout object
with any markup text.  For example,

@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
c'4
\override BreathingSign #'text
  = #(make-musicglyph-markup "scripts.rvarcomma")
\breathe
d4
@end lilypond

@seealso

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

Internals Reference: @internalsref{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,ragged-right,fragment,relative=2]
\override Score.SpacingSpanner #'shortest-duration-space = #3.0
c4-\bendAfter #+5
c4-\bendAfter #-3
@end lilypond


@seealso

Music Glossary: @rglos{falls}, @rglos{doits}.

Snippets: @lsrdir{Expressive,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,ragged-right,fragment,relative=2]
c2\glissando c'
\override Glissando #'style = #'zigzag
c2\glissando c,
@end lilypond


@snippets

@lilypond[verbatim,quote,ragged-right]
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: @lsrdir{Expressive,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: @internalsref{Glissando}


@knownissues

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


@node Arpeggio
@subsubsection Arpeggio

@cindex arpeggio
@cindex broken chord
@funindex \arpeggio

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,ragged-right,fragment,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,ragged-right,fragment,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,ragged-right,fragment,relative=1]
\new Voice {
  \arpeggioUp
  <c e g c>\arpeggio
  \arpeggioDown
  <c e g c>\arpeggio
  \arpeggioNeutral
  <c e g c>\arpeggio
}
@end lilypond


@predefined

@funindex \arpeggioUp
@code{\arpeggioUp},
@funindex \arpeggioDown
@code{\arpeggioDown},
@funindex \arpeggioNeutral
@code{\arpeggioNeutral},
@funindex \arpeggioBracket
@code{\arpeggioBracket}.


@snippets

In a @code{PianoStaff}, it is possible to let an arpeggio cross
between the staves by setting the property
@code{PianoStaff}.@code{connectArpeggios}.

@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
\new PianoStaff <<
  \set PianoStaff.connectArpeggios = ##t
  \new Staff { <c' e g c>\arpeggio }
  \new Staff { \clef bass <c,, e g>\arpeggio }
>>
@end lilypond

The same can be accomplished in contexts other than
@code{PianoStaff} if the @code{Span_arpeggio_engraver} is included
in the Score context.

@lilypond[verbatim,quote,ragged-right]
\score {
  \new StaffGroup {
    \set Score.connectArpeggios = ##t
    <<
      \new Voice \relative c' {
        <e g>4\arpeggio
      }
      \new Voice  \relative c {
        \clef bass
        <c e>4\arpeggio
      }
    >>
  }
  \layout {
    \context {
      \Score
      \consists "Span_arpeggio_engraver"
    }
  }
}
@end lilypond

Similarly, an arpeggio can be drawn across notes in different
voices on the same staff if the @code{Span_arpeggio_engraver} is
moved to the Staff context:

@lilypond[verbatim,quote,ragged-right]
\new Staff
\with {
  \consists "Span_arpeggio_engraver"
} \relative c' {
  \set Staff.connectArpeggios = ##t
    <<
    {<e' g>4\arpeggio <d f> <d f>2 }
  \\
  {<d, f>2\arpeggio  <g b>2  }
  >>
}
@end lilypond


@seealso

Music Glossary: @rglos{arpeggio}, @rglos{broken chord}.

Notation Reference: @ref{Ties}, for writing out arpeggios.

Snippets: @lsrdir{Expressive,Expressive-marks}

Internals Reference: @internalsref{Arpeggio},
@internalsref{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 trills are made with @code{\startTrillSpan} and
@code{\stopTrillSpan}.  In the following example, it is shown in
the common combination with grace notes.  If a more precise
control of the placement of the grace notes is needed, see
@ref{Grace notes}.

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

@cindex pitched trills

Trills that should be executed on an explicitly specified pitch
can be typeset with the command @code{\pitchedTrill}, and the
syntax @code{\pitchedTrill} @var{mainnote} @code{\startTrillSpan}
@var{trillnote} @var{endnote} @code{\stopTrillSpan}.

@lilypond[verbatim,quote,ragged-right,fragment,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: @lsrdir{Expressive,Expressive-marks}

Internals Reference: @internalsref{TrillSpanner}