Misc minor editing and moving sections around.

[lilypond.git] / Documentation / user / advanced-notation.itely

@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond.tely

@c A menu is needed before every deeper *section nesting of @node's; run 
@c     M-x texinfo-all-menus-update
@c to automatically fill in these menus before saving changes


@node Advanced notation
@chapter Advanced notation

This chapter deals with rarely-used and advanced notation.

@menu
* Text::                        
* Preparing parts::             
* Orchestral music::            
* Contemporary notation::       
* Educational use::             
* Automatic notation::          
@end menu



@node Text
@section Text

This section explains how to include text (with various formatting) in
your scores.

@menu
* Text scripts::                
* Text spanners::               
* Text marks::                  
* Text markup::                 
* Text encoding::               
* Nested scores::               
* Overview of text markup commands::  
* Font selection::              
* New dynamic marks::           
@end menu


@node Text scripts
@subsection Text scripts

@cindex Text scripts
@cindex text items, non-empty
@cindex non-empty texts

It is possible to place arbitrary strings of text or @ref{Text markup}
above or below notes by using a string @code{c^"text"}.  By default,
these indications do not influence the note spacing, but by using the
command @code{\fatText}, the widths will be taken into account

@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
c4^"longtext" \fatText c4_"longlongtext" c4
@end lilypond

More complex formatting may also be added to a note by using the
markup command,
@lilypond[fragment,ragged-right,verbatim,quote]
c'4^\markup { bla \bold bla }
@end lilypond

The @code{\markup} is described in more detail in
@ref{Text markup}.


@refcommands

@cindex @code{\fatText}
@code{\fatText},
@cindex @code{\emptyText}
@code{\emptyText}.


@commonprop

Checking to make sure that text scripts and lyrics are within the margins is a relatively large computational task.  To speed up processing, lilypond does not perform such calculations by default; to enable it, use

@example
\override Score.PaperColumn #'keep-inside-line = ##t
@end example


@seealso

In this manual: @ref{Text markup}.

Program reference: @internalsref{TextScript}.


@node Text spanners
@subsection Text spanners

@cindex Text spanners

Some performance indications, e.g., @i{rallentando} or @i{accelerando},
are written as text and are extended over many measures with dotted
lines.  Such texts are created using text spanners; attach
@code{\startTextSpan} and @code{\stopTextSpan} to the first and last
notes of the spanner.

The string to be printed, as well as the style, is set through object
properties

@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
c1
\textSpannerDown
\override TextSpanner #'edge-text = #'("rall " . "")
c2\startTextSpan b c\stopTextSpan a
\break
\textSpannerUp
\override TextSpanner #'edge-text = #(cons (markup #:italic "rit" ) "")
c2\startTextSpan b c\stopTextSpan a
@end lilypond

@refcommands

@cindex textSpannerUp
@code{textSpannerUp},
@cindex textSpannerDown 
@code{textSpannerDown},
@cindex textSpannerNeutral
@code{textSpannerNeutral}.


@seealso

Program reference: @internalsref{TextSpanner}.

Examples: @inputfileref{input/@/regression,text@/-spanner@/.ly}.


@node Text marks
@subsection Text marks

@cindex coda on bar line
@cindex segno on bar line
@cindex fermata on bar line
@cindex bar lines, symbols on
@cindex @code{\mark}

The @code{\mark} command is primarily used for
@ref{Rehearsal marks},
but it can also be used to put signs like coda,
segno, and fermata on a bar line.  Use @code{\markup} to
access the appropriate symbol

@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
c1 \mark \markup { \musicglyph #"scripts.ufermata" }
c1
@end lilypond

@noindent
@code{\mark} is only typeset above the top stave of the score.  If
you specify the @code{\mark} command at a bar line, the resulting
mark is placed above the bar line.  If you specify it in the middle
of a bar, the resulting mark is positioned between notes.  If it is
specified before the beginning of a score line, it is placed
before the first note of the line.  Finally, if the mark occurs at
a line break, the mark will be printed at the
beginning of the next line.
@c  IMO this is a bug; hopefully it'll be fixed soon, so I can
@c  delete this sentence.   -gp
If there is no next line, then the mark will not be printed at all.


@commonprop

To print the mark at the end of the current line, use

@example
\override Score.RehearsalMark
  #'break-visibility = #begin-of-line-invisible
@end example

@code{\mark} is often useful for adding text to the end of bar.  In
such cases, changing the @code{#'self-alignment} is very useful

@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
\override Score.RehearsalMark
  #'break-visibility = #begin-of-line-invisible
c1 c c c4 c c c
\once \override Score.RehearsalMark #'self-alignment-X = #right
\mark "D.S. al Fine "
@end lilypond


@seealso

Program reference: @internalsref{RehearsalMark}.


@node Text markup
@subsection Text markup

@cindex markup
@cindex text markup
@cindex markup text
@cindex typeset text

Use @code{\markup} to typeset text.  Commands are entered with the
backslash @code{\}.  To enter @code{\} and @code{#}, use double
quotation marks.

@lilypond[quote,verbatim,fragment,relative=1]
c1^\markup { hello }
c1_\markup { hi there }
c1^\markup { hi \bold there, is \italic anyone home? }
c1_\markup { "\special #characters" }
@end lilypond

@noindent
See @ref{Overview of text markup commands} for a list of all
commands.

@code{\markup} is primarily used for @internalsref{TextScript}s,
but it can also be used anywhere text is called in lilypond

@lilypond[quote,verbatim]
\header{ title = \markup{ \bold { foo \italic { bar! } } } }
\score{
  \relative c'' {
    \override Score.RehearsalMark
      #'break-visibility = #begin-of-line-invisible
    \override Score.RehearsalMark #'self-alignment-X = #right

    \set Staff.instrument = \markup{ \column{ Alto solo } }
    c2^\markup{ don't be \flat }
    \override TextSpanner #'edge-text = #(cons (markup #:italic "rit" ) "")
    b2\startTextSpan
    a2\mark \markup{ \large \bold Fine }
    r2\stopTextSpan
    \bar "||"
  }
  \addlyrics { bar, foo \markup{ \italic bar! } }
}
@end lilypond

Text can also be placed on its own, away from any @code{\score}
block.  This is primarily used in a @code{\book} (see
@ref{Multiple movements}).

@lilypond[quote,ragged-right,verbatim]
\markup{ Here is some text. }
@end lilypond

@cindex font switching

The markup in the example demonstrates font switching commands.  The
command @code{\bold} and @code{\italic} apply to the first following 
word only; to apply a command to more than one word, enclose the
words with braces,

@example
\markup @{ \bold @{ hi there @} @}
@end example

@noindent
For clarity, you can also do this for single arguments, e.g.,

@example
\markup @{ is \italic @{ anyone @} home @}
@end example

In markup mode you can compose expressions, similar to mathematical
expressions, XML documents, and music expressions.  You can stack
expressions grouped vertically with the command @code{\column}.
Similarly, @code{\center-align} aligns texts by their center lines:

@lilypond[quote,verbatim,fragment,relative=1]
c1^\markup { \column { a bbbb \line { c d } } }
c1^\markup { \center-align { a bbbb c } }
c1^\markup { \line { a b c } }
@end lilypond

Lists with no previous command are not kept distinct.  The expression

@example
\center-align @{ @{ a b @} @{ c d @} @} 
@end example

@noindent

is equivalent to

@example
\center-align @{ a b c d @}
@end example

@noindent

To keep lists of words distinct, please use quotes @code{"} or
the @code{\line} command

@lilypond[quote,verbatim,fragment,relative=1]
\fatText
c4^\markup{ \center-align { on three lines } }
c4^\markup{ \center-align { "all one line" } }
c4^\markup{ \center-align { { on three lines } } }
c4^\markup{ \center-align { \line { on one line } } }
@end lilypond

Markups can be stored in variables and these variables
may be attached to notes, like
@example
allegro = \markup @{ \bold \large @{ Allegro @} @}
 @{ a^\allegro b c d @}
@end example

Some objects have alignment procedures of their own, which cancel out
any effects of alignments applied to their markup arguments as a
whole.  For example, the @internalsref{RehearsalMark} is horizontally
centered, so using @code{\mark \markup @{ \left-align .. @}} has no
effect.

In addition, vertical placement is performed after creating the
text markup object.  If you wish to move an entire piece of markup,
you need to use the #'padding property or create an "anchor" point
inside the markup (generally with @code{\hspace #0}).

@lilypond[quote,verbatim,fragment,relative=1]
\fatText
c'4^\markup{ \raise #5 "not raised" }
\once \override TextScript #'padding = #3
c'4^\markup{ raised }
c'4^\markup{ \hspace #0 \raise #1.5 raised }
@end lilypond


@seealso

This manual: @ref{Overview of text markup commands}.

Program reference: @internalsref{TextScript}.

Init files: @file{scm/@/new@/-markup@/.scm}.


@refbugs

Kerning or generation of ligatures is only done when the @TeX{}
backend is used.  In this case, LilyPond does not account for them so
texts will be spaced slightly too wide.

Syntax errors for markup mode are confusing.


@node Text encoding
@subsection Text encoding

LilyPond uses the Pango library to format multi-lingual texts, and
does not perform any input-encoding conversions.  This means that any
text, be it title, lyric text, or musical instruction containing
non-ASCII characters, must be utf-8.  Easiest to enter such texts is
by using a Unicode-aware editor, and save using utf-8 encoding.  Most
popular modern editors have utf-8 support, for example, vim, Emacs,
jEdit, and GEdit do.

Depending on the fonts installed, the following fragment shows Hebrew
and Cyrillic lyrics,

@cindex Cyrillic
@cindex Hebrew
@cindex ASCII, non

@lilypondfile[fontload]{utf-8.ly}

The @TeX{} backend does not handle encoding specially at all.  Strings
in the input are put in the output as-is.  Extents of text items in the
@TeX{} backend, are determined by reading a file created via the
@file{texstr} backend,

@example
lilypond -b texstr input/les-nereides.ly
latex les-nereides.texstr
@end example

The last command produces @file{les-nereides.textmetrics}, which is
read when you execute

@example
lilypond -b tex input/les-nereides.ly
@end example

Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
suitable LaTeX wrappers to load appropriate La@TeX{} packages for
interpreting non-ASCII strings.

To use a Unicode escape sequence, use

@example
#(ly:export (ly:wide-char->utf-8 #x2014))
@end example


@seealso

@inputfileref{input/regression,utf-8.ly}


@node Nested scores
@subsection Nested scores

It is possible to nest music inside markups, by adding a @code{\score}
block to a markup expression.  Such a score must contain a @code{\layout}
block.

@lilypond[quote,verbatim,ragged-right]
\relative {
  c4 d^\markup {
    \score {
      \relative { c4 d e f }
      \layout { }
    }
  }
  e f
}
@end lilypond


@node Overview of text markup commands
@subsection Overview of text markup commands

The following commands can all be used inside @code{\markup @{ @}}.

@include markup-commands.tely


@node Font selection
@subsection Font selection

@cindex font selection
@cindex font magnification
@cindex @code{font-interface}

By setting the object properties described below, you can select a
font from the preconfigured font families.  LilyPond has default
support for the feta music fonts. Text fonts are selected through
Pango/FontConfig. The serif font defaults to New Century Schoolbook,
the sans and typewriter to whatever the Pango installation defaults
to.


@itemize @bullet
@item @code{font-encoding}
is a symbol that sets layout of the glyphs.  This should only be set to
select different types of non-text fonts, eg.

@code{fetaBraces} for piano staff braces, @code{fetaMusic} the
standard music font, including ancient glyphs, @code{fetaDynamic} for
dynamic signs and @code{fetaNumber} for the number font.

@item @code{font-family}
is a symbol indicating the general class of the typeface.  Supported are
@code{roman} (Computer Modern), @code{sans}, and @code{typewriter}.
  
@item @code{font-shape}
is a symbol indicating the shape of the font.  There are typically
several font shapes available for each font family.  Choices are
@code{italic}, @code{caps}, and @code{upright}.

@item @code{font-series}
is a symbol indicating the series of the font.  There are typically
several font series for each font family and shape.  Choices are
@code{medium} and @code{bold}. 

@end itemize

Fonts selected in the way sketched above come from a predefined style
sheet. If you want to use a font from outside the style sheet, 
then set the 
@code{font-name} property, 

@lilypond[fragment,verbatim]
{
  \override Staff.TimeSignature #'font-name = #"Charter"
  \override Staff.TimeSignature #'font-size = #2
  \time 3/4
  c'1_\markup {
    \override #'(font-name . "Vera Bold")
      { This text is in Vera Bold }
  }
}
@end lilypond

@noindent
Any font can be used, as long as it is available to Pango/FontConfig.

The size of the font may be set with the @code{font-size}
property. The resulting size is taken relative to the
@code{text-font-size} as defined in the @code{\paper} block.

@cindex font size
@cindex font magnification


It is also possible to change the default font family for the entire
document. This is done by calling the @code{make-pango-font-tree} from
within the @code{\paper} block. The function takes names for the font
families to use for roman, sans serif and monospaced text. For
example,

@cindex font families, setting
@cindex Pango


@lilypond[verbatim]
\paper  {
  myStaffSize = #20
  
  #(define fonts
    (make-pango-font-tree "Times New Roman"
                          "Nimbus Sans"
                          "Luxi Mono"
                           (/ myStaffSize 20)))
}

{
  c'^\markup { roman: foo \sans bla \typewriter bar }
}
@end lilypond

@c we don't do Helvetica / Courier, since GS incorrectly loads
@c Apple TTF fonts  



@seealso

Examples: @file{ly/@/font@/-family@/-override.ly}


@node New dynamic marks
@subsection New dynamic marks

It is possible to print new dynamic marks or text that should be aligned
with dynamics.  Use @code{make-dynamic-script} to create these marks.

@cindex make-dynamic-script

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

@cindex Dynamics, editorial
@cindex Dynamics, parenthesis

It is also possible to print dynamics in round parenthesis or square
brackets.  These are often used for adding editorial dynamics.

@lilypond[quote,verbatim,ragged-right]
rndf = \markup{ \center-align {\line { \bold{\italic (}
  \dynamic f \bold{\italic )} }} }
boxf = \markup{ \bracket { \dynamic f } }
{ c'1_\rndf c'1_\boxf }
@end lilypond



@node Preparing parts
@section Preparing parts

This section describes various notation that are useful for preparing
individual parts.

@menu
* Multi measure rests::         
* Metronome marks::             
* Rehearsal marks::             
* Bar numbers::                 
* Instrument names::            
* Instrument transpositions::   
* Ottava brackets::             
* Different editions from one source::  
@end menu


@node Multi measure rests
@subsection Multi measure rests

@cindex multi measure rests
@cindex full measure rests
@cindex Rests, multi measure
@cindex Rests, full measure
@cindex whole rests for a full measure
@cindex @code{R}

Rests for one full measure (or many bars) are entered using `@code{R}'.  It
is specifically meant for full bar rests and for entering parts: the rest
can expand to fill a score with rests, or it can be printed as a single
multi-measure rest.  This expansion is controlled by the property
@code{Score.skipBars}.  If this is set to true, empty measures will not
be expanded, and the appropriate number is added automatically

@lilypond[quote,ragged-right,fragment,verbatim]
\time 4/4 r1 | R1 | R1*2
\set Score.skipBars = ##t R1*17 R1*4
@end lilypond

The @code{1} in @code{R1} is similar to the duration notation used for
notes.  Hence, for time signatures other than 4/4, you must enter other
durations.  This can be done with augmentation dots or fractions

@lilypond[quote,ragged-right,fragment,verbatim]
\set Score.skipBars = ##t
\time 3/4
R2. | R2.*2
\time 13/8
R1*13/8
R1*13/8*12 |
\time 10/8 R4*5*4 |
@end lilypond

An @code{R} spanning a single measure is printed as either a whole rest
or a breve, centered in the measure regardless of the time signature.

If there are only a few measures of rest, LilyPond prints ``church rests''
(a series of rectangles) in the staff.  To replace that with a simple
rest, use @code{MultiMeasureRest.expand-limit}.

@lilypond[quote,ragged-right,fragment,verbatim]
\set Score.skipBars = ##t
R1*2 | R1*5 | R1*9
\override MultiMeasureRest #'expand-limit = 1
R1*2 | R1*5 | R1*9
@end lilypond

@cindex text on multi-measure rest
@cindex script on multi-measure rest
@cindex fermata on multi-measure rest

Texts can be added to multi-measure rests by using the
@var{note}-@code{markup} syntax @ref{Text markup}.
A variable (@code{\fermataMarkup}) is provided for
adding fermatas

@lilypond[quote,ragged-right,verbatim,fragment]
\set Score.skipBars = ##t
\time 3/4
R2.*10^\markup { \italic "ad lib." }
R2.^\fermataMarkup
@end lilypond

Warning!  This text is created by @code{MultiMeasureRestText}, not
@code{TextScript}.

@lilypond[quote,ragged-right,verbatim,fragment]
\override TextScript #'padding = #5
R1^"low"
\override MultiMeasureRestText #'padding = #5
R1^"high"
@end lilypond

If you want to have text on the left end of a multi-measure rest,
attach the text to a zero-length skip note, i.e.,

@example
s1*0^"Allegro"
R1*4
@end example


@seealso

Program reference: @internalsref{MultiMeasureRestMusicGroup},
@internalsref{MultiMeasureRest}.

The layout object @internalsref{MultiMeasureRestNumber} is for the
default number, and @internalsref{MultiMeasureRestText} for user
specified texts.


@refbugs

It is not possible to use fingerings (e.g., @code{R1-4}) to put numbers
over multi-measure rests.  And the pitch of multi-measure rests (or
staff-centered rests) can not be influenced.

@cindex condensing rests

There is no way to automatically condense multiple rests into a single
multi-measure rest.  Multi-measure rests do not take part in rest
collisions.

Be careful when entering multi-measure rests followed by whole
notes.  The following will enter two notes lasting four measures each
@example
R1*4 cis cis
@end example
When @code{skipBars} is set, the result will look OK, but the bar
numbering will be off.


@node Metronome marks
@subsection Metronome marks

@cindex Tempo
@cindex beats per minute
@cindex metronome marking

Metronome settings can be entered as follows
@example
\tempo @var{duration} = @var{per-minute}
@end example

In the MIDI output, they are interpreted as a tempo change.  In the
layout output, a metronome marking is printed
@cindex @code{\tempo}
@lilypond[quote,ragged-right,verbatim,fragment]
\tempo 8.=120 c''1
@end lilypond


@commonprop

To change the tempo in the MIDI output without printing anything, make
the metronome marking invisible
@example
\once \override Score.MetronomeMark #'transparent = ##t
@end example

To print other metronome markings, use these markup commands
@lilypond[quote,ragged-right,verbatim,relative,fragment]
c4^\markup {
  (
  \smaller \general-align #Y #DOWN \note #"16." #1
  =
  \smaller \general-align #Y #DOWN \note #"8" #1
  ) }
@end lilypond

@noindent
See @ref{Text markup} for more details.


@seealso

Program reference: @internalsref{MetronomeMark}.


@refbugs

Collisions are not checked.  If you have notes above the top line of
the staff (or notes with articulations, slurs, text, etc), then the
metronome marking may be printed on top of musical symbols.  If this
occurs, increase the padding of the metronome mark to place it 
further away from the staff.

@example
\override Score.MetronomeMark #'padding = #2.5
@end example


@node Rehearsal marks
@subsection Rehearsal marks

@cindex Rehearsal marks
@cindex @code{\mark}

To print a rehearsal mark, use the @code{\mark} command

@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
c1 \mark \default
c1 \mark \default
c1 \mark #8
c1 \mark \default
c1 \mark \default
@end lilypond

@noindent
The letter@tie{}`I' is skipped in accordance with engraving traditions.
If you wish to include the letter `I', then use

@example
\set Score.markFormatter = #format-mark-alphabet
@end example

The mark is incremented automatically if you use @code{\mark
\default}, but you can also use an integer argument to set the mark
manually.  The value to use is stored in the property
@code{rehearsalMark}.

The style is defined by the property @code{markFormatter}.  It is a
function taking the current mark (an integer) and the current context
as argument.  It should return a markup object.  In the following
example, @code{markFormatter} is set to a canned procedure.  After a
few measures, it is set to function that produces a boxed number.

@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
\set Score.markFormatter = #format-mark-numbers
c1 \mark \default
c1 \mark \default
\set Score.markFormatter = #format-mark-box-numbers
c1 \mark \default
c1 \mark \default
c1
@end lilypond

The file @file{scm/@/translation@/-functions@/.scm} contains the definitions
of @code{format-mark-numbers} (the default format), @code{format-mark-box-numbers},
@code{format-mark-letters} and @code{format-mark-box-letters}.
These can be used as inspiration for other formatting functions.

You may use @code{format-mark-barnumbers}, @code{format-mark-box-barnumbers},
and @code{format-mark-circle-barnumbers} to get bar numbers instead of
incremented numbers or letters.


@seealso

Program reference: @internalsref{RehearsalMark}.

Init files: @file{scm/@/translation@/-functions@/.scm} contains the
definition of @code{format-mark-numbers} and
@code{format-mark-letters}.  They can be used as inspiration for other
formatting functions.

Examples: @inputfileref{input/@/regression,rehearsal@/-mark@/-letter@/.ly},

@inputfileref{input/@/regression,rehearsal@/-mark@/-number@/.ly}.


@node Bar numbers
@subsection Bar numbers

@cindex Bar numbers
@cindex measure numbers
@cindex @code{currentBarNumber}

Bar numbers are printed by default at the start of the line.  The
number itself is stored in the @code{currentBarNumber} property, which
is normally updated automatically for every measure.

Bar numbers can be typeset at regular intervals instead of at the
beginning of each line.  This is illustrated in the following example,
whose source is available as
@inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}

@lilypondfile[ragged-right,quote]{bar-number-regular-interval.ly}

Bar numbers can be typeset manually by tweaking the
@code{markFormatter} property

@lilypond[verbatim,ragged-right,quote]
\relative c' {
  \set Score.markFormatter
    = #(lambda (mark context)
      (make-bold-markup
        (make-box-markup
          (number->string (ly:context-property context
                                               'currentBarNumber)))))

  c1 \bar "||" \mark \default c1 c1 \mark \default c1 \bar "|."
}
@end lilypond

Bar numbers can be manually changed by setting the
@code{Staff.currentBarNumber} property

@lilypond[verbatim,ragged-right,quote]
\relative c' {
  \repeat unfold 4 {c4 c c c} \break
  \set Score.currentBarNumber = #50
  \repeat unfold 4 {c4 c c c}
}
@end lilypond


@seealso

Program reference: @internalsref{BarNumber}.

Examples:
@inputfileref{input/@/test,bar@/-number@/-every@/-five@/-reset@/.ly},
and @inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}.


@refbugs

Bar numbers can collide with the @internalsref{StaffGroup} bracket, if
there is one at the top.  To solve this, the
@code{padding} property of @internalsref{BarNumber} can be
used to position the number correctly.


@node Instrument names
@subsection Instrument names

In an orchestral score, instrument names are printed at the left side
of the staves.

This can be achieved by setting @internalsref{Staff}.@code{instrument}
and @internalsref{Staff}.@code{instr}.  This will print a string before
the start of the staff.  For the first staff, @code{instrument} is
used, for the following ones, @code{instr} is used.

@lilypond[quote,verbatim,ragged-right,relative=1,fragment]
\set Staff.instrument = "Ploink "
\set Staff.instr = "Plk "
c1
\break
c''
@end lilypond

You can also use markup texts to construct more complicated instrument
names, for example

@lilypond[quote,fragment,verbatim,ragged-right]
\set Staff.instrument = \markup {
  \column { "Clarinetti"
            \line { "in B" \smaller \flat } } }
c''1
@end lilypond

If you wish to center the instrument names, you must center all of them

@lilypond[quote,verbatim,ragged-right]
{ <<
\new Staff {
  \set Staff.instrument = \markup {
    \center-align { "Clarinetti"
      \line { "in B" \smaller \flat } } }
  c''1
}
\new Staff {
  \set Staff.instrument = \markup{ \center-align { Vibraphone }}
  c''1
}
>>
}
@end lilypond

For longer instrument names, it may be useful to increase the
@code{indent} setting in the @code{\layout} block.

@seealso

Program reference: @internalsref{InstrumentName}.

@refbugs

When you put a name on a grand staff or piano staff, the width of the
brace is not taken into account. The following property setting can be
used to move the instrument names to the left, in such situations.

@example
\override Score.InstrumentName #'space-alist = #'((left-edge extra-space . 2.0))
@end example


@node Instrument transpositions
@subsection Instrument transpositions

@cindex transposition, MIDI
@cindex transposition, instrument

The key of a transposing instrument can also be specified.  This
applies to many wind instruments, for example, clarinets (B-flat, A, and
E-flat), horn (F) and trumpet (B-flat, C, D, and E-flat).

The transposition is entered after the keyword @code{\transposition}

@example
\transposition bes   %% B-flat clarinet
@end example

@noindent
This command sets the property @code{instrumentTransposition}.  The value of
this property is used for MIDI output and quotations.  It does not
affect how notes are printed in the current staff.  To change the printed
output, see @ref{Transpose}.

The pitch to use for @code{\transposition} should correspond to the
real sound heard when a @code{c'} written on the staff is played by the
transposing instrument.  For example, when entering a score in
concert pitch, typically all voices are entered in C, so
they should be entered as

@example
clarinet = @{
  \transposition c'
  ...
@}
saxophone = @{
  \transposition c'
  ...
@}
@end example

The command @code{\transposition} should be used when the music is
entered from a (transposed) orchestral part.  For example, in
classical horn parts, the tuning of the instrument is often changed
during a piece.  When copying the notes from the part, use
@code{\transposition}, e.g.,

@example
\transposition d'
c'4^"in D"
...
\transposition g'
c'4^"in G"
...
@end example


@node Ottava brackets
@subsection Ottava brackets

`Ottava' brackets introduce an extra transposition of an octave for
the staff.  They are created by invoking the function
@code{set-octavation}

@cindex ottava
@cindex 15ma
@cindex octavation

@lilypond[quote,ragged-right,verbatim,fragment]
\relative c''' {
  a2 b
  #(set-octavation 1)
  a b
  #(set-octavation 0)
  a b
}
@end lilypond

The @code{set-octavation} function also takes -1 (for 8va bassa) and 2
(for 15ma) as arguments.  Internally the function sets the properties
@code{ottavation} (e.g., to @code{"8va"}) and
@code{centralCPosition}.  For overriding the text of the bracket, set
@code{ottavation} after invoking @code{set-octavation}, i.e.,

@lilypond[quote,ragged-right,verbatim]
{
  #(set-octavation 1)
  \set Staff.ottavation = #"8"
  c'''
}
@end lilypond


@seealso

Program reference: @internalsref{OttavaBracket}.

Examples: @inputfileref{input/@/regression,ottava@/.ly},
@inputfileref{input/@/regression,ottava@/-broken@/.ly}.


@refbugs

@code{set-octavation} will get confused when clef changes happen
during an octavation bracket.


@node Different editions from one source
@subsection Different editions from one source

@cindex @code{\tag}
@cindex tag

The @code{\tag} command marks music expressions with a name.  These
tagged expressions can be filtered out later.  With this mechanism it
is possible to make different versions of the same music source.

In the following example, we see two versions of a piece of music, one
for the full score, and one with cue notes for the instrumental part

@example
c1
<<
  \tag #'part <<
    R1 \\
    @{
      \set fontSize = #-1
      c4_"cue" f2 g4 @}
  >>
  \tag #'score R1
>>
c1
@end example

The same can be applied to articulations, texts, etc.: they are
made by prepending
@example
-\tag #@var{your-tag}
@end example
to an articulation, for example,
@example
c1-\tag #'part ^4
@end example

This defines a note with a conditional fingering indication.

@cindex keepWithTag
@cindex removeWithTag
By applying the @code{\keepWithTag} and @code{\removeWithTag}
commands, tagged expressions can be filtered.  For example,
@example
<<
  @var{the music}
  \keepWithTag #'score @var{the music}
  \keepWithTag #'part @var{the music}
>>
@end example
would yield

@lilypondfile[ragged-right,quote]{tag-filter.ly}

The argument of the @code{\tag} command should be a symbol. It's 
possible to put multiple tags on a piece of music, with multiple
@code{\tag} entries, 
@example
  \tag #'original-part \tag #'transposed-part @dots{}
@end example


@seealso

Examples: @inputfileref{input/@/regression,tag@/-filter@/.ly}.


@refbugs

Multiple rests are not merged if you create the score with both tagged
sections.
 


@node Orchestral music
@section Orchestral music

Orchestral music involves some special notation, both in the full
score and the individual parts.  This section explains how to tackle
some common problems in orchestral music.

@menu
* Automatic part combining::    
* Hiding staves::               
* Quoting other voices::        
* Formatting cue notes::        
* Aligning to cadenzas::        
@end menu


@node Automatic part combining
@subsection Automatic part combining
@cindex automatic part combining
@cindex part combiner

Automatic part combining is used to merge two parts of music onto a
staff.  It is aimed at typesetting orchestral scores.  When the two
parts are identical for a period of time, only one is shown.  In
places where the two parts differ, they are typeset as separate
voices, and stem directions are set automatically.  Also, solo and
@emph{a due} parts are identified and can be marked.

The syntax for part combining is

@example
\partcombine @var{musicexpr1} @var{musicexpr2}
@end example


The following example demonstrates the basic functionality of the part
combiner: putting parts on one staff, and setting stem directions and
polyphony

@lilypond[quote,verbatim,ragged-right,fragment]
\new Staff \partcombine
  \relative g' { g g a( b) c c r r }
  \relative g' { g g r4 r e e g g }
@end lilypond

The first @code{g} appears only once, although it was
specified twice (once in each part).  Stem, slur, and tie directions are
set automatically, depending whether there is a solo or unisono.  The
first part (with context called @code{one}) always gets up stems, and
`Solo', while the second (called @code{two}) always gets down stems and
`Solo II'.

If you just want the merging parts, and not the textual markings, you
may set the property @code{printPartCombineTexts} to false

@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
\new Staff <<
  \set Staff.printPartCombineTexts = ##f
  \partcombine
    \relative g' { g a( b) r }
    \relative g' { g r4 r f }
>>
@end lilypond

To change the text that is printed for solos or merging, you may
set the @code{soloText}, @code{soloIIText}, and @code{aDueText}
properties.

@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
\new Staff <<
  \set Score.soloText = #"ichi"
  \set Score.soloIIText = #"ni"
  \set Score.aDueText = #"tachi"
  \partcombine
    \relative g' { g4 g a( b) r }
    \relative g' { g4 g r r f }
>>
@end lilypond

Both arguments to @code{\partcombine} will be interpreted as
@internalsref{Voice} contexts.  If using relative octaves,
@code{\relative} should be specified for both music expressions, i.e.,

@example
\partcombine
  \relative @dots{} @var{musicexpr1}
  \relative @dots{} @var{musicexpr2}
@end example

@noindent
A @code{\relative} section that is outside of @code{\partcombine} has
no effect on the pitches of @var{musicexpr1} and @var{musicexpr2}.

@seealso

Program reference: @internalsref{PartCombineMusic}.

@refbugs

When @code{printPartCombineTexts} is set, when the two voices play the
same notes on and off, the part combiner may typeset @code{a2} more
than once in a measure.

@code{\partcombine} cannot be inside @code{\times}.

@code{\partcombine} cannot be inside @code{\relative}.

Internally, the @code{\partcombine} interprets both arguments as
@code{Voice}s named @code{one} and @code{two}, and then decides when
the parts can be combined.  Consequently, if the arguments switch to
differently named @internalsref{Voice} contexts, the events in those
will be ignored.


@node Hiding staves
@subsection Hiding staves

@cindex Frenched scores
@cindex Hiding staves

In orchestral scores, staff lines that only have rests are usually
removed; this saves some space.  This style is called `French Score'.
For @internalsref{Lyrics},
@internalsref{ChordNames} and @internalsref{FiguredBass}, this is
switched on by default.  When the lines of these contexts turn out
empty after the line-breaking process, they are removed.

For normal staves, a specialized @internalsref{Staff} context is
available, which does the same: staves containing nothing (or only
multi-measure rests) are removed.  The context definition is stored in
@code{\RemoveEmptyStaffContext} variable.  Observe how the second staff
in this example disappears in the second line

@lilypond[quote,ragged-right,verbatim]
\layout {
  \context { \RemoveEmptyStaffContext }
}

{
  \relative c' <<
    \new Staff { e4 f g a \break c1 }
    \new Staff { c4 d e f \break R1 }
  >>
}
@end lilypond

The first system shows all staves in full.  If empty staves should be
removed from the first system too, set @code{remove-first} to true in
@internalsref{VerticalAxisGroup}.

@example
\override Score.VerticalAxisGroup #'remove-first = ##t
@end example

To remove other types of contexts, use @code{\AncientRemoveEmptyStaffContext}
or @code{\RemoveEmptyRhythmicStaffContext}.

Another application is making ossia sections, i.e., alternative
melodies on a separate piece of staff, with help of a Frenched
staff.  See @inputfileref{input/@/test,ossia@/.ly} for an example.


@node Quoting other voices
@subsection Quoting other voices

With quotations, fragments of other parts can be inserted into a part
directly.  Before a part can be quoted, it must be marked especially as
quotable.  This is done with the @code{\addquote} command.

@example
\addquote @var{name} @var{music}
@end example


@noindent
Here, @var{name} is an identifying string.  The @var{music} is any kind
of music.  Here is an example of @code{\addquote}

@example
\addquote clarinet \relative c' @{
  f4 fis g gis
@}
@end example

This command must be entered at toplevel, i.e., outside any music
blocks.

After calling @code{\addquote}, the quotation may then be done with
@code{\quoteDuring} or @code{\cueDuring},

@example
\quoteDuring #@var{name} @var{music}
@end example

During a part, a piece of music can be quoted with the @code{\quoteDuring}
command.

@example
\quoteDuring #"clarinet" @{ s2. @}
@end example

This would cite three quarter notes (the duration of @code{s2.})  of
the previously added @code{clarinet} voice.


More precisely, it takes the current time-step of the part being
printed, and extracts the notes at the corresponding point of the
@code{\addquote}d voice.  Therefore, the argument to @code{\addquote}
should be the entire part of the voice to be quoted, including any
rests at the beginning.

Quotations take into account the transposition of both source and target
instruments, if they are specified using the @code{\transposition} command.

@lilypond[quote,ragged-right,verbatim]
\addquote clarinet \relative c' {
  \transposition bes
  f4 fis g gis
}

{
  e'8 f'8 \quoteDuring #"clarinet" { s2 }
}
@end lilypond

The type of events that are present in cue notes can be trimmed with
the @code{quotedEventTypes} property.  The default value is
@code{(note-event rest-event)}, which means that only notes and
rests of the cued voice end up in the @code{\quoteDuring}.
Setting

@example
\set Staff.quotedEventTypes =
       #'(note-event articulation-event dynamic-event)
@end example

@noindent
will quote notes (but no rests), together with scripts and dynamics.

@refbugs

Only the contents of the first @internalsref{Voice} occurring in an
@code{\addquote} command will be considered for quotation, so
@var{music} can not contain @code{\new} and @code{\context Voice}
statements that would switch to a different Voice.

Quoting grace notes is broken and can even cause LilyPond to crash.

@seealso

In this manual: @ref{Instrument transpositions}.

Examples: @inputfileref{input/@/regression,quote@/.ly}
@inputfileref{input/@/regression,quote@/-transposition@/.ly}

Program reference: @internalsref{QuoteMusic}.


@node Formatting cue notes
@subsection Formatting cue notes

The previous section deals with inserting notes from another voice.
There is a more advanced music function called @code{\cueDuring},
which makes formatting cue notes easier.

The syntax is

@example
  \cueDuring #@var{name} #@var{updown} @var{music}
@end example

This will insert notes from the part @var{name} into a
@internalsref{Voice} called @code{cue}.  This happens simultaneously
with @var{music}, which usually is a rest.  When the cue notes start,
the staff in effect becomes polyphonic for a moment.  The argument
@var{updown} determines whether the cue notes should be notated as a
first or second voice.


@lilypond[verbatim,ragged-right]
smaller = {
  \set fontSize = #-2
  \override Stem #'length-fraction = #0.8
  \override Beam #'thickness = #0.384
  \override Beam #'length-fraction = #0.8
}

\addquote clarinet \relative {
  R1*20
  r2 r8 c f f
} 

\new Staff \relative  <<

  % setup a context for  cue  notes.
  \new Voice = "cue" { \smaller \skip 1*21 }
  
  \set Score.skipBars = ##t
  
  \new Voice {
    R1*20
    \cueDuring #"clarinet" #1 {
      R1
    }
    g4 g2. 
  }
>>
@end lilypond 


Here are a couple of hints for successful cue notes

@itemize @bullet
@item
Cue notes have smaller font sizes.
@item
 the cued part is marked with the instrument playing the cue.
@item
 when the original part takes over again, this should be marked with
 the name of the original instrument.

@c really?  Are you sure about that last point?  I'll check after 3.0 -gp

@c Yes, this is good practice.  Otherwise, the start of the original
@c part can only be seen from the font size.  This is not good enough
@c for sight-reading.  It is possilbe to use other
@c markers (eg. a big close-bracket over the staff) to indicate the cue notes are
@c finished.
@c -hwn


Any other changes introduced by the cued part should also be
undone.  For example, if the cued instrument plays in a different clef,
the original clef should be stated once again.

@end itemize


@node Aligning to cadenzas
@subsection Aligning to cadenzas

In an orchestral context, cadenzas present a special problem:
when constructing a score that includes a cadenza, all other
instruments should skip just as many notes as the length of the
cadenza, otherwise they will start too soon or too late.

A solution to this problem are the functions @code{mmrest-of-length}
and @code{skip-of-length}.  These Scheme functions take a piece of music
as argument, and generate a @code{\skip} or multi-rest, exactly as
long as the piece.  The use of @code{mmrest-of-length} is demonstrated
in the following example.

@lilypond[verbatim,ragged-right,quote]
cadenza = \relative c' {
  c4 d8 << { e f g } \\ { d4. } >>
  g4 f2 g4 g
}

\new GrandStaff <<
  \new Staff { \cadenza c'4 }
  \new Staff {
    #(ly:export (mmrest-of-length cadenza))
    c'4
  }
>>
@end lilypond




@node Contemporary notation
@section Contemporary notation

In the 20th century, composers have greatly expanded the musical
vocabulary.  With this expansion, many innovations in musical notation
have been tried.  The book ``Music Notation in the 20th century'' by
Kurt Stone gives a comprehensive overview (see @ref{Literature
list}).  In general, the use of new, innovative notation makes a piece
harder to understand and perform and its use should therefore be
avoided.  For this reason, support for contemporary notation in
LilyPond is limited.


@menu
* Polymetric notation::         
* Time administration::         
* Clusters::                    
* Special fermatas::            
* Special noteheads::           
* Feathered beams::             
* Improvisation::               
@end menu


@node Polymetric notation
@subsection Polymetric notation

Double time signatures are not supported explicitly, but they can be
faked.  In the next example, the markup for the time signature is
created with a markup text.  This markup text is inserted in the
@internalsref{TimeSignature} grob.

@lilypond[verbatim,ragged-right]
% create 2/4 + 5/8
tsMarkup =\markup {
  \number {
    \column { "2" "4" }
    \musicglyph #"scripts.stopped"
    \bracket \column { "5" "8" }
  }
}

{
  \override Staff.TimeSignature #'stencil = #ly:text-interface::print
  \override Staff.TimeSignature #'text = #tsMarkup
  \time 3/2
  c'2 \bar ":" c'4 c'4.
}
@end lilypond

Each staff can also have its own time signature.  This is done by
moving the @internalsref{Timing_translator} to the @internalsref{Staff}
context.

@example
\layout @{
  \context @{ \Score
     \remove "Timing_translator"
     \remove "Default_bar_line_engraver"
  @}
  \context @{
    \Staff
    \consists "Timing_translator"
    \consists "Default_bar_line_engraver"
  @}
    
@}
@end example


Now, each staff has its own time signature.
@example
<<
  \new Staff @{
    \time 3/4
    c4 c c | c c c |
  @}
  \new Staff @{
    \time 2/4
    c4 c | c c | c c
  @}
  \new Staff @{
    \time 3/8
    c4. c8 c c c4. c8 c c
  @}
>>
@end example

@lilypond[quote,ragged-right]
\layout{
  \context{
     \Score
     \remove "Timing_translator"
     \remove "Default_bar_line_engraver"
    }
  \context{ \Staff
    \consists "Timing_translator"
    \consists "Default_bar_line_engraver"
  }
}

\relative c' <<
  \new Staff {
    \time 3/4
    c4 c c | c c c |
  }
  \new Staff {
    \time 2/4
    c4 c | c c | c c
  }
  \new Staff {
    \time 3/8
    c4. c8 c c c4. c8 c c
  }
>>
@end lilypond


A different form of polymetric notation is where note lengths have
different values across staves.

This notation can be created by setting a common time signature for
each staff but replacing it manually using
@code{timeSignatureFraction} to the desired fraction.  Then the printed
durations in each staff are scaled to the common time signature.
The latter is done with @code{\compressMusic}, which is used similar
to @code{\times}, but does not create a tuplet bracket. The syntax is
@example
\compressMusic #'(@var{numerator} . @var{denominator}) @var{musicexpr}
@end example



In this example, music with the time signatures of 3/4, 9/8, and 10/8 are
used in parallel.  In the second staff, shown durations are multiplied by
2/3, so that 2/3 * 9/8 = 3/4, and in the third staff, shown durations are
multiplied by 3/5, so that 3/5 * 10/8 = 3/4.

@lilypond[quote,ragged-right,verbatim,fragment]
\relative c' { <<
  \new Staff {
    \time 3/4
    c4 c c | c c c |
  }
  \new Staff {
    \time 3/4
    \set Staff.timeSignatureFraction = #'(9 . 8)
    \compressMusic #'(2 . 3)
      \repeat unfold 6 { c8[ c c] }
  }
  \new Staff {
    \time 3/4
    \set Staff.timeSignatureFraction = #'(10 . 8)
    \compressMusic #'(3 . 5) {
      \repeat unfold 2 { c8[ c c] }
      \repeat unfold 2 { c8[ c] }
      | c4. c4. \times 2/3 { c8 c c } c4
    }
  }
>> }
@end lilypond




@refbugs

When using different time signatures in parallel, the spacing is
aligned vertically, but bar lines distort the regular spacing.


@node Time administration
@subsection Time administration

@cindex Time administration

Time is administered by the @internalsref{Time_signature_engraver},
which usually lives in the @internalsref{Score} context.  The
bookkeeping deals with the following variables

@table @code
@item currentBarNumber
The measure number.

@item measureLength
The length of the measures in the current time signature.  For a 4/4
time this is@tie{}1, and for 6/8 it is 3/4.

@item measurePosition
The point within the measure where we currently are.  This quantity
is reset to@tie{}0 whenever it exceeds @code{measureLength}.  When that
happens, @code{currentBarNumber} is incremented.

@item timing
If set to true, the above variables are updated for every time
step.  When set to false, the engraver stays in the current measure
indefinitely.
@end table

Timing can be changed by setting any of these variables explicitly.
In the next example, the 4/4 time signature is printed, but
@code{measureLength} is set to 5/4.  After a while, the measure is
shortened by 1/8, by setting @code{measurePosition} to 7/8 at 2/4
in the measure, so the next bar line will fall at 2/4 + 3/8.  The
3/8 arises because 5/4 normally has 10/8, but we have manually
set the measure position to be 7/8 and 10/8 - 7/8 = 3/8.

@lilypond[quote,ragged-right,verbatim,relative,fragment]
\set Score.measureLength = #(ly:make-moment 5 4)
c1 c4
c1 c4
c4 c4
\set Score.measurePosition = #(ly:make-moment 7 8)
b8 b b
c4 c1
@end lilypond



@node Clusters
@subsection Clusters

@cindex cluster

A cluster indicates a continuous range of pitches to be played.  They
can be denoted as the envelope of a set of notes.  They are entered by
applying the function @code{makeClusters} to a sequence of
chords, e.g.,
@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
\makeClusters { <c e > <b f'> }
@end lilypond

The following example (from
@inputfileref{input/@/regression,cluster@/.ly}) shows what the result
looks like

@lilypondfile[ragged-right,quote]{cluster.ly}

Ordinary notes and clusters can be put together in the same staff,
even simultaneously.  In such a case no attempt is made to
automatically avoid collisions between ordinary notes and clusters.

@seealso

Program reference: @internalsref{ClusterSpanner},
@internalsref{ClusterSpannerBeacon},
@internalsref{Cluster_spanner_engraver}.

Examples: @inputfileref{input/@/regression,cluster@/.ly}.

@refbugs

Music expressions like @code{<< @{ g8 e8 @} a4 >>} are not printed
accurately.  Use @code{<g a>8 <e a>8} instead.



@node Special fermatas
@subsection Special fermatas

@cindex fermatas, special

In contemporary music notation, special fermata symbols denote breaks
of differing lengths.  The following fermatas are supported

@lilypond[quote,ragged-right]
<<
  \oldaddlyrics {
    b'2
    ^\shortfermata
    _\shortfermata
    r

    b'
    ^\fermata
    _\fermata
    r

    b'
    ^\longfermata
    _\longfermata
    r

    b'
    ^\verylongfermata
    _\verylongfermata
    r
  }
  \new Lyrics \lyricmode {
    \override LyricText #'font-family = #'typewriter
    "shortfermata" "fermata" "longfermata" "verylongfermata"
  }
>>
@end lilypond

See @ref{Articulations} for general instructions how to apply scripts
such as fermatas to notes.


@node Special noteheads
@subsection Special noteheads

Different noteheads are used by various instruments for various
meanings -- crosses are used for ``parlato'' with vocalists, stopped
notes on guitar; diamonds are used for harmonics on string instruments,
etc.  There is a shorthand (@code{\harmonic}) for diamond shapes; the
other notehead styles are produced by tweaking the property

@lilypond[ragged-right,relative=1,fragment,verbatim,quote]
c4 d
\override NoteHead #'style = #'cross
e f
\revert NoteHead #'style
e d <c f\harmonic> <d a'\harmonic>
@end lilypond

@noindent
To see all notehead styles, please see
@inputfileref{input/@/regression,note@/-head@/-style@/.ly}.


@seealso

Program reference: @internalsref{NoteHead}.


@node Feathered beams
@subsection Feathered beams

Feathered beams are not supported natively, but they can be faked by
forcing two beams to overlap.  Here is an example,

@c don't change relative setting witout changing positions!
@lilypond[ragged-right,relative=1,fragment,verbatim,quote]
\new Staff <<
  \new Voice
  {
    \stemUp
    \once \override Voice.Beam #'positions = #'(0 . 0.5)
    c8[ c c c c ]
  }
  \new Voice {
    \stemUp
    \once \override Voice.Beam #'positions = #'(0 . -0.5)
    c[ c c c c]
  }
>>
@end lilypond


@node Improvisation
@subsection Improvisation

Improvisation is sometimes denoted with slashed note heads.  Such note
heads can be created by adding a @internalsref{Pitch_squash_engraver}
to the @internalsref{Staff} or @internalsref{Voice} context.  Then, the
following command

@example
\set squashedPosition = #0
\override NoteHead #'style = #'slash
@end example

@noindent
switches on the slashes.

There are shortcuts @code{\improvisationOn} (and an accompanying
@code{\improvisationOff}) for this command sequence.  They are used in
the following example

@lilypond[verbatim,ragged-right,quote]
\new Staff \with {
  \consists Pitch_squash_engraver
} \transpose c c' {
  e8 e g a a16(bes)(a8) g \improvisationOn
  e8
  ~e2~e8 f4 fis8
  ~fis2 \improvisationOff a16(bes) a8 g e
}
@end lilypond


@node Educational use
@section Educational use

With the amount of control that LilyPond offers, one can make great
teaching tools in addition to great musical scores.

@menu
* Balloon help::                
* Blank music sheet::           
* Hidden notes::                
* Shape note heads ::           
* Easy Notation note heads::    
* Analysis brackets::           
* Coloring objects::            
@end menu

@node Balloon help
@subsection Balloon help

Elements of notation can be marked and named with the help of a square
balloon.  The primary purpose of this feature is to explain notation.

The following example demonstrates its use.

@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
\new Voice {
  \applyOutput
    #(add-balloon-text 'NoteHead "heads, or tails?"
    '(1 . -3))
  c8
}
@end lilypond

@noindent
The function @code{add-balloon-text} takes the name of a grob, the
label to print, and the position where to put the label relative to
the object.  In the above example, the text ``heads or tails?'' ends
3 spaces below and 1 space to the right of the marked head.

@cindex balloon
@cindex notation, explaining

@seealso

Program reference: @internalsref{text-balloon-interface}.

Examples: @inputfileref{input/@/regression,balloon@/.ly}.




@node Blank music sheet
@subsection Blank music sheet

A blank music sheet can be produced also by using invisible notes, and
removing @code{Bar_number_engraver}.


@lilypond[quote,verbatim]
emptymusic = {
  \repeat unfold 2 % Change this for more lines.
  { s1\break }
  \bar "|."
}
\new Score \with {
  \override TimeSignature #'transparent = ##t
  defaultBarType = #""
  \remove Bar_number_engraver
} <<
  \new Staff \emptymusic
  \new TabStaff \emptymusic
>>
@end lilypond


@node Hidden notes
@subsection Hidden notes

@cindex Hidden notes
@cindex Invisible notes
@cindex Transparent notes

@cindex @code{\hideNotes}
@cindex @code{\unHideNotes}
Hidden (or invisible or transparent) notes can be useful in preparing theory
or composition exercises.

@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
c4 d4
\hideNotes
e4 f4
\unHideNotes
g4 a
@end lilypond

Hidden notes are also great for performing weird tricks.  For example,
slurs cannot be attached to rests or spacer rests, but you may wish
to include that in your score -- string instruments use this notation
when doing pizzicato to indicate that the note should ring for as long
as possible.

@lilypond[quote,ragged-right,verbatim,relative=0,fragment]
\clef bass
<< {
  c4^"pizz"( \hideNotes c)
  \unHideNotes c( \hideNotes c)
} {
  s4 r s r
} >>
@end lilypond


@node Shape note heads 
@subsection Shape note heads 

In shape note head notation, the shape of the note head corresponds
to the harmonic function of a note in the scale.  This notation was
popular in the 19th century American song books.

Shape note heads can be produced by setting @code{\aikenHeads} or
@code{\sacredHarpHeads}, depending on the style desired.

@lilypond[verbatim,relative=1,fragment]
  \aikenHeads
  c8 d4 e8 a2 g1
  \sacredHarpHeads
  c8 d4. e8 a2 g1
@end lilypond

Shapes are determined on the step in the scale, where the base of the
scale is determined by  the @code{\key} command

@findex \key
@findex shapeNoteStyles
@findex \aikenHeads
@findex \sacredHarpHeads

Shape note heads are implemented through the @code{shapeNoteStyles}
property.  Its value is a vector of symbols.  The k-th element indicates
the style to use for the k-th step of the scale.  Arbitrary
combinations are possible, eg.,


@lilypond[verbatim,relative=1,fragment]
  \set shapeNoteStyles  = ##(cross triangle fa #f mensural xcircle diamond)
  c8 d4. e8 a2 g1
@end lilypond


@node Easy Notation note heads
@subsection Easy Notation note heads

@cindex easy notation
@cindex Hal Leonard

The `easy play' note head includes a note name inside the head.  It is
used in music for beginners

@lilypond[quote,ragged-right,verbatim,fragment,staffsize=26]
  \setEasyHeads
  c'2 e'4 f' | g'1
@end lilypond

The command @code{\setEasyHeads} overrides settings for the
@internalsref{NoteHead} object.  To make the letters readable, it has
to be printed in a large font size.  To print with a larger font, see
@ref{Setting global staff size}.

@refcommands

@cindex @code{\setEasyHeads}
@code{\setEasyHeads}


@node Analysis brackets
@subsection Analysis brackets
@cindex brackets
@cindex phrasing brackets
@cindex musicological analysis
@cindex note grouping bracket

Brackets are used in musical analysis to indicate structure in musical
pieces.  LilyPond supports a simple form of nested horizontal
brackets.  To use this, add the @internalsref{Horizontal_bracket_engraver}
to @internalsref{Staff} context.  A bracket is started with
@code{\startGroup} and closed with @code{\stopGroup}

@lilypond[quote,ragged-right,verbatim]
\score {
  \relative c'' {
    c4\startGroup\startGroup
    c4\stopGroup
    c4\startGroup
    c4\stopGroup\stopGroup
  }
  \layout {
    \context {
      \Staff \consists "Horizontal_bracket_engraver"
}}}
@end lilypond

@seealso

Program reference: @internalsref{HorizontalBracket}.

Examples: @inputfileref{input/@/regression,note@/-group@/-bracket@/.ly}.


@node Coloring objects
@subsection Coloring objects

Individual objects may be assigned colors.  You may use the
color names listed in the @ref{List of colors}.

@lilypond[quote,ragged-right,verbatim,fragment,relative=1]
\override NoteHead #'color = #red
c4 c
\override NoteHead #'color = #(x11-color 'LimeGreen)
d
\override Stem #'color = #blue
e
@end lilypond

The full range of colors defined for X11 can be accessed by using the
scheme function x11-color.  The function takes one argument that can be a
symbol

@example
\override Beam #'color = #(x11-color 'MediumTurquoise)
@end example

or a string

@example
\override Beam #'color = #(x11-color "MediumTurquoise")
@end example

The first form is quicker to write and is more efficient.  However, using
the second form it is possible to access X11 colors by the multi-word
form of its name

@example
\override Beam #'color = #(x11-color "medium turquoise")
@end example

If x11-color cannot make sense of the parameter then the color returned
defaults to black.  It should be obvious from the final score that
something is wrong.

This example, illustrates the use of x11-color.  Notice that the stem
color remains black after being set to (x11-color 'Boggle), which is
deliberate nonsense.

@lilypond[quote,ragged-right,verbatim]
{
  \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
  \set Staff.instrument = \markup {
    \with-color #(x11-color 'navy) "Clarinet"
  }
  \time 2/4
  gis''8 a''
  \override Beam #'color = #(x11-color "medium turquoise")
  gis'' a''
  \override NoteHead #'color = #(x11-color "LimeGreen")
  gis'' a''
  \override Stem #'color = #(x11-color 'Boggle)
  gis'' a''
}
@end lilypond


@seealso

Appendix: @ref{List of colors}.


@refbugs
Not all x11 colors are distinguishable in a web browser.  For web use
normal colors are recommended. 

An x11 color is not necessarily exactly the same shade as a similarly
named normal color. 


@node Automatic notation
@section Automatic notation

This section describes how to change the way that accidentals and
beams are automatically displayed.

FIXME: this might get moved into Changing Defaults.  Please send
opinions to lilypond-devel.  Thanks!  :)

@menu
* Automatic accidentals::       
* Setting automatic beam behavior::  
@end menu

@node Automatic accidentals
@subsection Automatic accidentals
@cindex Automatic accidentals

Common rules for typesetting accidentals have been placed in a
function.  This function is called as follows

@cindex @code{set-accidental-style}
@example
#(set-accidental-style 'STYLE #('CONTEXT#))
@end example

The function can take two arguments: the name of the accidental style,
and an optional argument that denotes the context that should be
changed.  If no context name is supplied, @code{Staff} is the default,
but you may wish to apply the accidental style to a single @code{Voice}
instead.

The following accidental styles are supported
@table @code
@item default
This is the default typesetting behavior.  It corresponds
to 18th century common practice: Accidentals are
remembered to the end of the measure in which they occur and
only on their own octave.

@item voice
The normal behavior is to remember the accidentals on
Staff-level.  This variable, however, typesets accidentals
individually for each voice.  Apart from that, the rule is similar to
@code{default}.

As a result, accidentals from one voice do not get canceled in other
voices, which is often an unwanted result

@lilypond[quote,ragged-right,relative=1,fragment,verbatim]
\new Staff <<
  #(set-accidental-style 'voice)
  <<
    { es g } \\
    { c, e }
>> >>
@end lilypond

The @code{voice} option should be used if the voices
are to be read solely by individual musicians.  If the staff is to be
used by one musician (e.g., a conductor) then
@code{modern} or @code{modern-cautionary}
should be used instead.

@item modern
@cindex @code{modern} style accidentals
This rule corresponds to the common practice in the 20th century.  This rule
prints the same accidentals as @code{default}, but temporary
accidentals also are canceled in other octaves.  Furthermore,
in the same octave, they also get canceled in the following
measure

@lilypond[quote,ragged-right,fragment,verbatim]
#(set-accidental-style 'modern)
cis' c'' cis'2 | c'' c'
@end lilypond

@item @code{modern-cautionary}
@cindex @code{modern-cautionary}
This rule is similar to @code{modern}, but the ``extra'' accidentals
(the ones not typeset by @code{default}) are typeset as cautionary
accidentals.  They are printed in reduced size or with parentheses
@lilypond[quote,ragged-right,fragment,verbatim]
#(set-accidental-style 'modern-cautionary)
cis' c'' cis'2 | c'' c'
@end lilypond

@cindex @code{modern-voice}
@item modern-voice
This rule is used for multivoice accidentals to be read both by musicians
playing one voice and musicians playing all voices.  Accidentals are
typeset for each voice, but they @emph{are} canceled across voices in
the same @internalsref{Staff}.

@cindex @code{modern-voice-cautionary}
@item modern-voice-cautionary
This rule is the same as @code{modern-voice}, but with the extra
accidentals (the ones not typeset by @code{voice}) typeset
as cautionaries.  Even though all accidentals typeset by
@code{default} @emph{are} typeset by this variable,
some of them are typeset as cautionaries.

@item piano
@cindex @code{piano} accidentals
This rule reflects 20th century practice for piano notation.  Very similar to
@code{modern} but accidentals also get canceled
across the staves in the same @internalsref{GrandStaff} or
@internalsref{PianoStaff}.

@item piano-cautionary
@cindex @code{#(set-accidental-style 'piano-cautionary)}
Same as @code{#(set-accidental-style 'piano)} but with the extra
accidentals typeset as cautionaries.

@item no-reset
@cindex @code{no-reset} accidental style
This is the same as @code{default} but with accidentals lasting
``forever'' and not only until the next measure
@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
#(set-accidental-style 'no-reset)
c1 cis cis c
@end lilypond

@item forget
This is sort of the opposite of @code{no-reset}: Accidentals
are not remembered at all---and hence all accidentals are
typeset relative to the key signature, regardless of what was
before in the music

@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
#(set-accidental-style 'forget)
\key d\major c4 c cis cis d d dis dis
@end lilypond
@end table


@seealso

Program reference: @internalsref{Accidental_engraver},
@internalsref{Accidental}, and @internalsref{AccidentalPlacement}.


@refbugs

Simultaneous notes are considered to be entered in sequential
mode.  This means that in a chord the accidentals are typeset as if the
notes in the chord happened once at a time - in the order in which
they appear in the input file.

This is a problem when accidentals in a chord depend on each other,
which does not happen for the default accidental style.  The problem
can be solved by manually inserting @code{!} and @code{?} for the
problematic notes.


@node Setting automatic beam behavior
@subsection Setting automatic beam behavior

@cindex @code{autoBeamSettings}
@cindex @code{(end * * * *)}
@cindex @code{(begin * * * *)}
@cindex automatic beams, tuning
@cindex tuning automatic beaming

@c [TODO: use \applyContext]

In normal time signatures, automatic beams can start on any note but can
only end in a few positions within the measure: beams can end on a beat,
or at durations specified by the properties in
@code{autoBeamSettings}.  The properties in @code{autoBeamSettings}
consist of a list of rules for where beams can begin and end.  The
default @code{autoBeamSettings} rules are defined in
@file{scm/@/auto@/-beam@/.scm}.

In order to add a rule to the list, use
@example
#(override-auto-beam-setting '(be p q n m) a b [context])
@end example

@itemize @bullet

@item @code{be} is either "begin" or "end".

@item @code{p/q} is the duration of the note for which you want
to add a rule.  A beam is considered to have the duration of its
shortest note.  Set @code{p} and @code{q} to @code{'*'} to
have this apply to any beam.

@item @code{n/m} is the time signature to which
this rule should apply.  Set @code{n} and @code{m} to @code{'*'}
to have this apply in any time signature.

@item @code{a/b} is the position in the bar at which the beam should begin/end.

@item @code{context} is optional, and it specifies the context at which
the change should be made.  The default is @code{'Voice}.
@code{#(score-override-auto-beam-setting '(A B C D) E F)} is equivalent to
@code{#(override-auto-beam-setting '(A B C D) E F 'Score)}.

@end itemize

For example, if automatic beams should always end on the first quarter
node, use

@example
#(override-auto-beam-setting '(end * * * *) 1 4)
@end example

You can force the beam settings to only take effect on beams whose shortest
note is a certain duration

@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
\time 2/4
#(override-auto-beam-setting '(end 1 16 * *) 1 16)
a16 a a a a a a a |
a32 a a a a16 a a a a a |
#(override-auto-beam-setting '(end 1 32 * *) 1 16)
a32 a a a a16 a a a a a |
@end lilypond

You can force the beam settings to only take effect in certain time
signatures

@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
\time 5/8
#(override-auto-beam-setting '(end * * 5 8) 2 8)
c8 c d d d
\time 4/4
e8 e f f e e d d
\time 5/8
c8 c d d d
@end lilypond

You can also remove a previously set beam-ending rule by using

@example
#(revert-auto-beam-setting '(be p q n m) a b [context])
@end example

@noindent
be, p, q, n, m, a, b and context are the same as above.  Note that the
default rules are specified in @file{scm/@/auto@/-beam@/.scm},
so you can revert rules that you did not explicitly create.

@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
\time 4/4
a16 a a a a a a a a a a a a a a a
#(revert-auto-beam-setting '(end 1 16 4 4) 1 4)
a16 a a a a a a a a a a a a a a a
@end lilypond

The rule in a revert-auto-beam-setting statement must exactly match the
original rule.  That is, no wildcard expansion is taken into account.

@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
\time 1/4
#(override-auto-beam-setting '(end 1 16 1 4) 1 8)
a16 a a a
#(revert-auto-beam-setting '(end 1 16 * *) 1 8) % this won't revert it!
a a a a
#(revert-auto-beam-setting '(end 1 16 1 4) 1 8) % this will
a a a a
@end lilypond



@c TODO:  old material -- not covered by above stuff, I think.
If automatic beams should end on every quarter in 5/4 time, specify
all endings
@example
#(override-auto-beam-setting '(end * * * *) 1 4 'Staff)
#(override-auto-beam-setting '(end * * * *) 1 2 'Staff)
#(override-auto-beam-setting '(end * * * *) 3 4 'Staff)
#(override-auto-beam-setting '(end * * * *) 5 4 'Staff)
@dots{}
@end example

The same syntax can be used to specify beam starting points.  In this
example, automatic beams can only end on a dotted quarter note
@example
#(override-auto-beam-setting '(end * * * *) 3 8)
#(override-auto-beam-setting '(end * * * *) 1 2)
#(override-auto-beam-setting '(end * * * *) 7 8)
@end example
In 4/4 time signature, this means that automatic beams could end only on
3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
3/8, has passed within the measure).

@cindex automatic beam generation
@cindex autobeam
@cindex @code{autoBeaming}
@cindex lyrics

If beams are used to indicate melismata in songs, then automatic
beaming should be switched off with @code{\autoBeamOff}.


@refcommands

@cindex @code{\autoBeamOff}
@code{\autoBeamOff},
@cindex @code{\autoBeamOn}
@code{\autoBeamOn}.


@refbugs

If a score ends while an automatic beam has not been ended and is
still accepting notes, this last beam will not be typeset at all.  The
same holds polyphonic voices, entered with @code{<< @dots{} \\ @dots{}
>>}.  If a polyphonic voice ends while an automatic beam is still
accepting notes, it is not typeset.