Text.
This chapter deals with rarely-used and advanced notation.
@menu
-* Text::
* Preparing parts::
-* Orchestral music::
-* Contemporary notation::
-* Educational use::
@end menu
-@node Text
-@section Text
-
-This section explains how to include text (with various formatting) in
-your scores.
-
-@cindex Text, other languages
-To write accented and special text (such as characters from other languages),
-simply
-insert the characters directly into the lilypond file. The file must be
-saved as UTF-8. For more information, see @ref{Text encoding}.
-
-@lilypond[fragment,ragged-right,staffsize=16,quote]
-c'4^\markup { bla \bold bla }
-@end lilypond
-
-@lilypond[fragment,ragged-right,staffsize=16,quote]
-c'4^\markup { bla \bold bla }
-@end lilypond
-
-@lilypond[fragment,ragged-right,staffsize=16,quote]
-c'4^\markup { bla \bold bla }
-@end lilypond
-
-@lilypond[fragment,ragged-right,staffsize=16,quote]
-c'4^\markup { bla \bold bla }
-@end lilypond
-
-@menu
-* Text scripts::
-* Text and line spanners::
-* Text spanners::
-* Text marks::
-* Text markup::
-* Nested scores::
-* Page wrapping text::
-* Overview of text markup commands::
-* Overview of text markup list commands::
-* Font selection::
-* New dynamic marks::
-@end menu
-
-
-@anchor{Text scripts}
-@unnumberedsubsubsec 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
-
-@noindent
-To prevent text from influencing spacing, use @code{\emptyText}.
-
-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
-
-@funindex \fatText
-@code{\fatText},
-@funindex \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}.
-
-
-@anchor{Text and line spanners}
-@unnumberedsubsubsec Text and line spanners
-
-Some performance indications, e.g., @i{rallentando} and
-@i{accelerando} and @i{trills} are written as text and are extended
-over many measures with lines, sometimes dotted or wavy.
-
-These all use the same routines as the glissando for drawing the texts
-and the lines, and tuning their behavior is therefore also done in the
-same way. It is done with a spanner, and the routine responsible for
-drawing the spanners is @code{ly:line-interface::print}. This
-routine determines the exact location of the two @i{span
-points} and draws a line in between, in the style requested.
-
-Here is an example of the different line styles available, and how to
-tune them.
-
-@lilypond[relative=2,ragged-right,verbatim,fragment]
-d2 \glissando d'2
-\once \override Glissando #'dash-fraction = #0.5
-d,2 \glissando d'2
-\override Glissando #'style = #'dotted-line
-d,2 \glissando d'2
-\override Glissando #'style = #'zigzag
-d,2 \glissando d'2
-\override Glissando #'style = #'trill
-d,2 \glissando d'2
-@end lilypond
-
-The information that determines the end-points is computed on-the-fly
-for every graphic object, but it is possible to override these.
-
-@lilypond[relative=2,ragged-right,verbatim,fragment]
-e2 \glissando f
-\once \override Glissando #'bound-details #'right #'Y = #-2
-e2 \glissando f
-@end lilypond
-
-The @code{Glissando} object, like any other using the
-@code{ly:line-interface::print} routine, carries a nested
-association list. In the above statement, the value for @code{Y}
-is set to @code{-2} for the association list corresponding to the right
-end point. Of course, it is also possible to adjust the left side with
-@code{left} instead of @code{right}.
-
-If @code{Y} is not set, the value is computed from the vertical
-position of right attachment point of the spanner.
-
-In case of a line break, the values for the span-points are extended
-with contents of the @code{left-broken} and @code{right-broken}
-sublists, for example
-
-@lilypond[relative=2,ragged-right,verbatim,fragment]
-\override Glissando #'breakable = ##T
-\override Glissando #'bound-details #'right-broken #'Y = #-3
-c1 \glissando \break
-f1
-@end lilypond
-
-The following properties can be used for the
-
-@table @code
-@item Y
-This sets the Y-coordinate of the end point, in staff space. By
-default, it is the center of the bound object, so for a glissando it
-points to the vertical center of the note head.
-
-For horizontal spanners, such as text spanner and trill spanners, it
-is hardcoded to 0.
-
-@item attach-dir
-This determines where the line starts and ends in X-direction,
-relative to the bound object. So, a value of @code{-1} (or
-@code{LEFT}) makes the line start/end at the left side of the note
-head it is attached to.
-
-@item X
-This is the absolute coordinate of the end point. It is usually
-computed on the fly, and there is little use in overriding it.
-
-@item stencil
-Line spanners may have symbols at the beginning or end, which is
-contained in this sub-property. This is for internal use, it is
-recommended to use @code{text}.
-
-@item text
-This is a markup that is evaluated to yield stencil. It is
-used to put @i{cresc.} and @i{tr} on horizontal spanners.
-
-@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
-\override TextSpanner #'bound-details #'left #'text
- = \markup { \small \bold Slower }
-c2\startTextSpan b c a\stopTextSpan
-@end lilypond
-
-@item stencil-align-dir-y
-@item stencil-offset
-Without setting this, the stencil is simply put there at the
-end-point, as defined by the @code{X} and @code{Y} sub properties.
-Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
-will move the symbol at the edge relative to the end point of the line
-
-@lilypond[relative=1,fragment,verbatim]
-\override TextSpanner #'bound-details #'left #'stencil-align-dir-y = #DOWN
-\override TextSpanner #'bound-details #'right #'stencil-align-dir-y = #UP
-
-\override TextSpanner #'bound-details #'left #'text = #"gggg"
-\override TextSpanner #'bound-details #'right #'text = #"hhhh"
-c4^\startTextSpan c c c \stopTextSpan
-@end lilypond
-
-@item arrow
-Setting this sub property to @code{#t} produce an arrowhead at the end
-of the line.
-
-@item padding
-This sub property controls the space between the specified end-point
-of the line and the actual end. Without padding, a glissando would
-start and end in the center of each note head.
-
-@end table
-
-@seealso
-
-Program reference: @internalsref{TextSpanner},
-@internalsref{Glissando}, @internalsref{VoiceFollower},
-@internalsref{TrillSpanner}, @internalsref{line-spanner-interface}.
-
-Examples: @lsr{expressive,line-styles.ly}, @lsr{expressive,line-arrows.ly}
-
-
-@anchor{Text spanners}
-@unnumberedsubsubsec 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 #'bound-details #'left #'text =
- \markup { \upright "rall" }
-c2\startTextSpan b c\stopTextSpan a
-\break
-\textSpannerUp
-\override TextSpanner #'bound-details #'left #'text =
- \markup { \italic "rit" }
-c2\startTextSpan b c\stopTextSpan a
-@end lilypond
-
-@refcommands
-
-@funindex textSpannerUp
-@code{\textSpannerUp},
-@funindex textSpannerDown
-@code{\textSpannerDown},
-@funindex textSpannerNeutral
-@code{\textSpannerNeutral}.
-
-
-@commonprop
-
-To print a solid line, use
-
-@example
-\override TextSpanner #'dash-fraction = #'()
-@end example
-
-
-@seealso
-
-Program reference: @internalsref{TextSpanner}.
-
-
-@anchor{Text marks}
-@unnumberedsubsubsec Text marks
-
-@cindex coda on bar line
-@cindex segno on bar line
-@cindex fermata on bar line
-@cindex bar lines, symbols on
-@funindex \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 (symbols are listed in
-@ref{The Feta font}).
-
-@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
-
-Text marks may be aligned with notation objects other than
-bar lines,
-
-@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
-\relative {
- c1
- \key cis \major
- \clef alto
- \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
- \mark "on key"
- cis
- \key ces \major
- \override Score.RehearsalMark #'break-align-symbols = #'(clef)
- \clef treble
- \mark "on clef"
- ces
- \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
- \key d \minor
- \clef tenor
- \time 3/4
- \mark "on time"
- c
-}
-@end lilypond
-
-Possible symbols for the @code{break-align-symbols} list are
-@code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
-@code{staff-bar}, @code{left-edge}, @code{key-cancellation},
-@code{key-signature}, and @code{time-signature}.
-
-The text marks will, by default, be aligned with the middle of the notation
-object, but this can be changed by overriding the
-@code{break-align-anchor-alignment} and
-@code{break-align-anchor} properties for the appropriate grob.
-
-@lilypond[fragment,quote,ragged-right,verbatim]
-{
- \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
- c1
- \key cis \major
-
- % the RehearsalMark will be aligned with the left edge of the KeySignature
- \once \override Staff.KeySignature #'break-align-anchor-alignment = #LEFT
- \mark \default
- cis1
- \key ces \major
-
- % the RehearsalMark will be aligned with the right edge of the KeySignature
- \once \override Staff.KeySignature #'break-align-anchor-alignment = #RIGHT
- \mark \default
- ces1
- \key cis \major
-
- % the RehearsalMark will be aligned with the left edge of the KeySignature
- % and then shifted right by 2 units.
- \once \override Staff.KeySignature #'break-align-anchor = #2
- \mark \default
- ces1
-}
-@end lilypond
-
-Although text marks are normally only printed above the topmost
-staff, you may alter this to print them on every staff,
-
-@lilypond[quote,ragged-right,verbatim,relative=2]
-{
- \new Score \with {
- \remove "Mark_engraver"
- }
- <<
- \new Staff \with {
- \consists "Mark_engraver"
- }
- { c''1 \mark "foo" c'' }
- \new Staff \with {
- \consists "Mark_engraver"
- }
- { c'1 \mark "foo" c' }
- >>
-}
-@end lilypond
-
-
-@seealso
-
-Program reference: @internalsref{RehearsalMark}.
-
-
-@anchor{Text markup}
-@unnumberedsubsubsec 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 {weird} #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.instrumentName = \markup{ \column{ Alto solo } }
- c2^\markup{ don't be \flat }
- \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
- b2\startTextSpan
- a2\mark \markup{ \large \bold Fine }
- r2\stopTextSpan
- \bar "||"
- }
- \addlyrics { bar, foo \markup{ \italic bar! } }
-}
-@end lilypond
-
-A @code{\markup} command can also be placed on its own, away from any
-@code{\score} block, see @ref{Multiple scores in a book}.
-
-@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 @q{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
-
-Some situations (such as dynamic marks) have preset font-related
-properties. If you are creating text in such situations, it
-is advisable to cancel those properties with
-@code{normal-text}. See @ref{Overview of text markup commands},
-for more details.
-
-
-@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.
-
-
-@anchor{Nested scores}
-@unnumberedsubsubsec 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
-
-@anchor{Page wrapping text}
-@unnumberedsubsubsec Page wrapping text
-Whereas @code{\markup} is used to enter a non-breakable block of text,
-@code{\markuplines} can be used at top-level to enter lines of text that
-can spread over multiple pages:
-
-@verbatim
-\markuplines {
- \justified-lines {
- A very long text of justified lines.
- ...
- }
- \justified-lines {
- An other very long paragraph.
- ...
- }
- ...
-}
-@end verbatim
-
-@code{\markuplines} accepts a list of markup, that is either the result
-of a markup list command, or a list of markups or of markup lists. The
-built-in markup list commands are described in
-@ref{Overview of text markup list commands}.
-
-@seealso
-
-This manual: @ref{Overview of text markup list commands},
-@ref{New markup list command definition}.
-
-@refcommands
-
-@funindex \markuplines
-@code{\markuplines}
-
-@anchor{Overview of text markup commands}
-@unnumberedsubsubsec Overview of text markup commands
-
-The following commands can all be used inside @code{\markup @{ @}}.
-
-@include markup-commands.tely
-
-@anchor{Overview of text markup list commands}
-@unnumberedsubsubsec Overview of text markup list commands
-
-The following commands can all be used with @code{\markuplines}.
-
-@include markup-list-commands.tely
-
-@anchor{Font selection}
-@unnumberedsubsubsec Font selection
-
-@cindex font selection
-@cindex font magnification
-@funindex 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, e.g.
-
-@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.
-To get a full list of all available fonts, run the command
-@example
-lilypond -dshow-available-fonts blabla
-@end example
-(the last argument of the command can be anything, but has to be present).
-
-
-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: @lsr{text,font@/-family@/-override.ly}.
-
-
-@anchor{New dynamic marks}
-@unnumberedsubsubsec 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. Note that the dynamic font only contains the characters
-@code{f,m,p,r,s} and @code{z}.
-
-Some situations (such as dynamic marks) have preset font-related
-properties. If you are creating text in such situations, it
-is advisable to cancel those properties with
-@code{normal-text}. See @ref{Overview of text markup commands},
-for more details.
-
-@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
@end menu
-@anchor{Metronome marks}
-@unnumberedsubsubsec 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
-@funindex \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
-
-
-@anchor{Instrument names}
-@unnumberedsubsubsec 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{instrumentName}
-and @internalsref{Staff}.@code{shortInstrumentName}, or
-@internalsref{PianoStaff}.@code{instrumentName} and
-@internalsref{PianoStaff}.@code{shortInstrumentName}. This will
-print text before
-the start of the staff. For the first staff, @code{instrumentName} is
-used, for the following ones, @code{shortInstrumentName} is used.
-
-@lilypond[quote,verbatim,ragged-right,relative=1,fragment]
-\set Staff.instrumentName = "Ploink "
-\set Staff.shortInstrumentName = "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.instrumentName = \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.instrumentName = \markup {
- \center-align { "Clarinetti"
- \line { "in B" \smaller \flat } } }
- c''1
-}
-\new Staff {
- \set Staff.instrumentName = \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.
-
-To center instrument names while leaving extra space to the right,
-
-@lilypond[quote,verbatim,ragged-right]
-\new StaffGroup \relative
-<<
- \new Staff {
- \set Staff.instrumentName = \markup { \hcenter-in #10 "blabla" }
- c1 c1
- }
- \new Staff {
- \set Staff.instrumentName = \markup { \hcenter-in #10 "blo" }
- c1 c1
- }
->>
-@end lilypond
-
-To add instrument names to other contexts (such as @code{GrandStaff},
-@code{ChoirStaff}, or @code{StaffGroup}), the engraver must
-be added to that context.
-
-@example
-\layout@{
- \context @{\GrandStaff \consists "Instrument_name_engraver"@}
-@}
-@end example
-
-@noindent
-More information about adding and removing engravers can
-be found in @ref{Modifying context plug-ins}.
-
-Instrument names may be changed in the middle of a piece,
-
-@lilypond[quote,fragment,verbatim,ragged-right]
-\set Staff.instrumentName = "First"
-\set Staff.shortInstrumentName = "one"
-c1 c c c \break
-c1 c c c \break
-\set Staff.instrumentName = "Second"
-\set Staff.shortInstrumentName = "two"
-c1 c c c \break
-c1 c c c \break
-@end lilypond
-
-
-@seealso
-
-Program reference: @internalsref{InstrumentName}.
-
-
-
@anchor{Different editions from one source}
@unnumberedsubsubsec Different editions from one source
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
-
-
-@anchor{Hiding staves}
-@unnumberedsubsubsec 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 @q{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.
-
-
-@anchor{Quoting other voices}
-@unnumberedsubsubsec Quoting other voices
-
-@cindex cues
-
-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.
-
-Quoting nested triplets may result in poor notation.
-
-
-@seealso
-
-In this manual: @ref{Instrument transpositions}.
-
-Examples: @lsr{parts,quote.ly}, @lsr{parts,quote-transportation.ly}
-
-Program reference: @internalsref{QuoteMusic}.
-
-
-@anchor{Formatting cue notes}
-@unnumberedsubsubsec Formatting cue notes
-
-@cindex cues, formatting
-
-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" #UP {
- 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 (e.g. a big close-bracket over the staff) to indicate the cue
-@c 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
-
-The macro @code{\transposedCueDuring} is
-useful to add cues to instruments which use a completely different
-octave range (for example, having a cue of a piccolo flute within
-a contra bassoon part).
-
-@lilypond[verbatim,ragged-right,quote]
-picc = \relative c''' {
- \clef "treble^8"
- R1 |
- c8 c c e g2 |
- a4 g g2 |
-}
-\addQuote "picc" { \picc }
-
-cbsn = \relative c, {
- \clef "bass_8"
- c4 r g r
- \transposedCueDuring #"picc" #UP c,, { R1 } |
- c4 r g r |
-}
-
-<<
- \context Staff = "picc" \picc
- \context Staff = "cbsn" \cbsn
->>
-@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 @q{Music Notation in the 20th century} by
-Kurt Stone gives a comprehensive overview (see @ref{Literature
-list}).
-
-This section describes notation that does
-not fit into traditional notation categories, such as pitches,
-tuplet beams, and articulation. For contemporary notation
-that fits into traditional notation categories, such as
-microtones, nested tuplet beams, and unusual fermatas, please
-see those sections of the documentation.
-
-@menu
-* Polymetric notation::
-* Time administration::
-* Proportional notation (introduction)::
-* Clusters::
-* Special noteheads::
-* Feathered beams::
-* Improvisation::
-* Selecting notation font size::
-@end menu
-
-
-
-@anchor{Special noteheads}
-@unnumberedsubsubsec Special noteheads
-
-@cindex note heads, special
-
-Different noteheads are used by various instruments for various
-meanings -- crosses are used for @q{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
-@ref{Note head styles}.
-
-
-@seealso
-
-Program reference: @internalsref{NoteHead}.
-
-
-@anchor{Improvisation}
-@unnumberedsubsubsec 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{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 Voice \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
-
-
-@anchor{Selecting notation font size}
-@unnumberedsubsubsec Selecting notation font size
-
-The easiest method of setting the font size of any context is by
-setting the @code{fontSize} property.
-
-@lilypond[quote,fragment,relative=1,verbatim]
-c8
-\set fontSize = #-4
-c f
-\set fontSize = #3
-g
-@end lilypond
-
-@noindent
-It does not change the size of variable symbols, such as beams or
-slurs.
-
-Internally, the @code{fontSize} context property will cause the
-@code{font-size} property to be set in all layout objects. The value
-of @code{font-size} is a number indicating the size relative to the
-standard size for the current staff height. Each step up is an
-increase of approximately 12% of the font size. Six steps is exactly a
-factor two. The Scheme function @code{magstep} converts a
-@code{font-size} number to a scaling factor. The @code{font-size}
-property can also be set directly, so that only certain layout objects are
-affected.
-
-@lilypond[quote,fragment,relative=1,verbatim]
-c8
-\override NoteHead #'font-size = #-4
-c f
-\override NoteHead #'font-size = #3
-g
-@end lilypond
-
-Font size changes are achieved by scaling the design size that is
-closest to the desired size. The standard font size (for
-@code{font-size} equals 0), depends on the standard staff height. For
-a 20pt staff, a 10pt font is selected.
-
-The @code{font-size} property can only be set on layout objects that
-use fonts. These are the ones supporting the
-@internalsref{font-interface} layout interface.
-
-@refcommands
-
-The following commands set @code{fontSize} for the current voice:
-
-@funindex \tiny
-@code{\tiny},
-@funindex \small
-@code{\small},
-@funindex \normalsize
-@code{\normalsize}.
-
-
-
-@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::
-* Parentheses::
-* Grid lines::
-@end menu
-
-@anchor{Balloon help}
-@unnumberedsubsubsec 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 \with { \consists "Balloon_engraver" }
-{
- \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
- <c-\balloonText #'(-2 . -2) \markup { Hello } >8
-}
-@end lilypond
-
-@noindent
-There are two music functions, @code{balloonText} and
-@code{balloonGrobText}. The latter takes the name of the grob to
-adorn, while the former may be used as an articulation on a note.
-The other arguments are the offset and the text of the label.
-
-@cindex balloon
-@cindex notation, explaining
-
-@seealso
-
-Program reference: @internalsref{text-balloon-interface}.
-
-
-
-
-@anchor{Blank music sheet}
-@unnumberedsubsubsec Blank music sheet
-
-@cindex Sheet music, empty
-@cindex Staves, blank sheet
-
-A blank music sheet can be produced also by using invisible notes, and
-removing @code{Bar_number_engraver}.
-
-
-@lilypond[quote,verbatim]
-\layout{ indent = #0 }
-emptymusic = {
- \repeat unfold 2 % Change this for more lines.
- { s1\break }
- \bar "|."
-}
-\new Score \with {
- \override TimeSignature #'transparent = ##t
-% un-comment this line if desired
-% \override Clef #'transparent = ##t
- defaultBarType = #""
- \remove Bar_number_engraver
-} <<
-
-% modify these to get the staves you want
- \new Staff \emptymusic
- \new TabStaff \emptymusic
->>
-@end lilypond
-
-
-@anchor{Hidden notes}
-@unnumberedsubsubsec Hidden notes
-
-@cindex Hidden notes
-@cindex Invisible notes
-@cindex Transparent notes
-
-@funindex \hideNotes
-@funindex \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
-
-
-@anchor{Shape note heads}
-@unnumberedsubsubsec Shape note heads
-
-@cindex note heads, shape
-
-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
-
-@funindex \key
-@funindex shapeNoteStyles
-@funindex \aikenHeads
-@funindex \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, e.g.
-
-@lilypond[verbatim,relative=1,fragment]
- \set shapeNoteStyles = ##(cross triangle fa #f mensural xcircle diamond)
- c8 d4. e8 a2 g1
-@end lilypond
-
-
-@anchor{Easy Notation note heads}
-@unnumberedsubsubsec Easy Notation note heads
-
-@cindex note heads, practice
-@cindex note heads, easy notation
-@cindex easy notation
-@cindex Hal Leonard
-
-The @q{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 the staff size}.
-
-@refcommands
-
-@funindex \setEasyHeads
-@code{\setEasyHeads}
-
-
-@anchor{Coloring objects}
-@unnumberedsubsubsec 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.instrumentName = \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.
-
-Notes in a chord cannot be colored with @code{\override}; use
-@code{\tweak} instead. See @ref{Objects connected to the input},
-for details.
-
-
-@anchor{Parentheses}
-@unnumberedsubsubsec Parentheses
-
-@cindex ghost notes
-@cindex notes, ghost
-@cindex notes, parenthesized
-
-Objects may be parenthesized by prefixing @code{\parenthesize} to the music
-event,
-
-@lilypond[relative=2,fragment,verbatim,ragged-right]
-<
- c
- \parenthesize d
- g
->4-\parenthesize -.
-@end lilypond
-
-This only functions inside chords, even for single notes
-
-@example
-< \parenthesize NOTE>
-@end example
-
-
-@anchor{Grid lines}
-@unnumberedsubsubsec Grid lines
-
-Vertical lines can be drawn between staves synchronized with
-the notes.
-
-@lilypond[ragged-right,quote,verbatim]
-\layout {
- \context {
- \Staff
- \consists "Grid_point_engraver" %% sets of grid
- gridInterval = #(ly:make-moment 1 4)
- }
-}
-
-\new Score \with {
- \consists "Grid_line_span_engraver"
- %% centers grid lines horizontally below noteheads
- \override NoteColumn #'X-offset = #-0.5
-}
-
-\new ChoirStaff <<
- \new Staff {
- \stemUp
- \relative {
- c'4. d8 e8 f g4
- }
- }
- \new Staff {
- %% centers grid lines vertically
- \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 )
- \stemDown
- \clef bass
- \relative c {
- c4 g' f e
- }
- }
->>
-@end lilypond
-
-Examples: @lsrdir{education}
-
-
--- /dev/null
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@node Educational use
+@section Educational use
+
+@menu
+* Note heads::
+* Inside the staff::
+* Outside the staff::
+@end menu
+
+
+@node Note heads
+@subsection Note heads
+
+@anchor{Easy notation note heads}
+@unnumberedsubsubsec Easy notation note heads
+
+@cindex note heads, practice
+@cindex note heads, easy notation
+@cindex easy notation
+@cindex Hal Leonard
+
+The @q{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 the staff size}.
+
+@refcommands
+
+@funindex \setEasyHeads
+@code{\setEasyHeads}
+
+
+@anchor{Shape note heads}
+@unnumberedsubsubsec Shape note heads
+
+@cindex note heads, shape
+
+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
+
+@funindex \key
+@funindex shapeNoteStyles
+@funindex \aikenHeads
+@funindex \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, e.g.
+
+@lilypond[verbatim,relative=1,fragment]
+ \set shapeNoteStyles = ##(cross triangle fa #f mensural xcircle diamond)
+ c8 d4. e8 a2 g1
+@end lilypond
+
+
+@anchor{Improvisation}
+@unnumberedsubsubsec 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{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 Voice \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
+
+
+@anchor{Special noteheads}
+@unnumberedsubsubsec Special noteheads
+
+@cindex note heads, special
+
+Different noteheads are used by various instruments for various
+meanings -- crosses are used for @q{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
+@ref{Note head styles}.
+
+
+@seealso
+
+Program reference: @internalsref{NoteHead}.
+
+
+
+@node Inside the staff
+@subsection Inside the staff
+
+
+@anchor{Selecting notation font size}
+@unnumberedsubsubsec Selecting notation font size
+
+The easiest method of setting the font size of any context is by
+setting the @code{fontSize} property.
+
+@lilypond[quote,fragment,relative=1,verbatim]
+c8
+\set fontSize = #-4
+c f
+\set fontSize = #3
+g
+@end lilypond
+
+@noindent
+It does not change the size of variable symbols, such as beams or
+slurs.
+
+Internally, the @code{fontSize} context property will cause the
+@code{font-size} property to be set in all layout objects. The value
+of @code{font-size} is a number indicating the size relative to the
+standard size for the current staff height. Each step up is an
+increase of approximately 12% of the font size. Six steps is exactly a
+factor two. The Scheme function @code{magstep} converts a
+@code{font-size} number to a scaling factor. The @code{font-size}
+property can also be set directly, so that only certain layout objects are
+affected.
+
+@lilypond[quote,fragment,relative=1,verbatim]
+c8
+\override NoteHead #'font-size = #-4
+c f
+\override NoteHead #'font-size = #3
+g
+@end lilypond
+
+Font size changes are achieved by scaling the design size that is
+closest to the desired size. The standard font size (for
+@code{font-size} equals 0), depends on the standard staff height. For
+a 20pt staff, a 10pt font is selected.
+
+The @code{font-size} property can only be set on layout objects that
+use fonts. These are the ones supporting the
+@internalsref{font-interface} layout interface.
+
+@refcommands
+
+The following commands set @code{fontSize} for the current voice:
+
+@funindex \tiny
+@code{\tiny},
+@funindex \small
+@code{\small},
+@funindex \normalsize
+@code{\normalsize}.
+
+
+@anchor{Fingering instructions}
+@unnumberedsubsubsec Fingering instructions
+
+@cindex fingering
+@cindex finger change
+
+Fingering instructions can be entered using
+@example
+@var{note}-@var{digit}
+@end example
+For finger changes, use markup texts
+
+@lilypond[quote,verbatim,ragged-right,fragment,relative=1]
+c4-1 c-2 c-3 c-4
+c^\markup { \finger "2 - 3" }
+@end lilypond
+
+You can use the thumb-script to indicate that a note should be
+played with the thumb (e.g., in cello music)
+@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
+<a_\thumb a'-3>8 <b_\thumb b'-3>
+@end lilypond
+
+Fingerings for chords can also be added to individual notes
+of the chord by adding them after the pitches
+@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
+< c-1 e-2 g-3 b-5 >4
+@end lilypond
+
+
+@commonprop
+
+You may exercise greater control over fingering chords by
+setting @code{fingeringOrientations}
+
+@lilypond[quote,verbatim,ragged-right,fragment,relative=1]
+\set fingeringOrientations = #'(left down)
+<c-1 es-2 g-4 bes-5 > 4
+\set fingeringOrientations = #'(up right down)
+<c-1 es-2 g-4 bes-5 > 4
+@end lilypond
+
+Using this feature, it is also possible to put fingering instructions
+very close to note heads in monophonic music,
+
+@lilypond[verbatim,ragged-right,quote,fragment]
+\set fingeringOrientations = #'(right)
+<es'-2>4
+@end lilypond
+
+
+@seealso
+
+Program reference: @internalsref{Fingering}.
+
+Examples: @lsr{expressive,fingering-chords.ly}
+
+
+
+@anchor{Hidden notes}
+@unnumberedsubsubsec Hidden notes
+
+@cindex Hidden notes
+@cindex Invisible notes
+@cindex Transparent notes
+
+@funindex \hideNotes
+@funindex \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
+
+
+@anchor{Coloring objects}
+@unnumberedsubsubsec 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.instrumentName = \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.
+
+Notes in a chord cannot be colored with @code{\override}; use
+@code{\tweak} instead. See @ref{Objects connected to the input},
+for details.
+
+
+@anchor{Parentheses}
+@unnumberedsubsubsec Parentheses
+
+@cindex ghost notes
+@cindex notes, ghost
+@cindex notes, parenthesized
+
+Objects may be parenthesized by prefixing @code{\parenthesize} to the music
+event,
+
+@lilypond[relative=2,fragment,verbatim,ragged-right]
+<
+ c
+ \parenthesize d
+ g
+>4-\parenthesize -.
+@end lilypond
+
+This only functions inside chords, even for single notes
+
+@example
+< \parenthesize NOTE>
+@end example
+
+
+@anchor{Ambitus}
+@unnumberedsubsubsec Ambitus
+@cindex ambitus
+
+The term @emph{ambitus} denotes a range of pitches for a given voice
+in a part of music. It may also denote the pitch range that a musical
+instrument is capable of playing. Ambits are printed on vocal parts,
+so performers can easily determine it meets their capabilities.
+
+Ambits are denoted at the beginning of a piece near the initial clef.
+The range is graphically specified by two note heads that represent the
+minimum and maximum pitch. To print such ambits, add the
+@internalsref{Ambitus_engraver} to the @internalsref{Voice} context,
+for example,
+
+@example
+\layout @{
+ \context @{
+ \Voice
+ \consists Ambitus_engraver
+ @}
+@}
+@end example
+
+This results in the following output
+
+@lilypond[quote,ragged-right]
+\layout {
+ \context {
+ \Staff
+ \consists Ambitus_engraver
+ }
+}
+
+\relative \new Staff {
+ as'' c e2 cis,2
+}
+@end lilypond
+
+If you have multiple voices in a single staff and you want a single
+ambitus per staff rather than per each voice, add the
+@internalsref{Ambitus_engraver} to the @internalsref{Staff} context
+rather than to the @internalsref{Voice} context. Here is an example,
+
+@lilypond[verbatim,ragged-right,quote]
+\new Staff \with {
+ \consists "Ambitus_engraver"
+}
+<<
+ \new Voice \with {
+ \remove "Ambitus_engraver"
+ } \relative c'' {
+ \override Ambitus #'X-offset = #-1.0
+ \voiceOne
+ c4 a d e f2
+ }
+ \new Voice \with {
+ \remove "Ambitus_engraver"
+ } \relative c' {
+ \voiceTwo
+ es4 f g as b2
+ }
+>>
+@end lilypond
+
+@noindent
+This example uses one advanced feature,
+
+@example
+\override Ambitus #'X-offset = #-1.0
+@end example
+
+@noindent
+This code moves the ambitus to the left. The same effect could have
+been achieved with @code{extra-offset}, but then the formatting system
+would not reserve space for the moved object.
+
+@seealso
+
+Program reference: @internalsref{Ambitus},
+@internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead},
+@internalsref{AmbitusAccidental}.
+
+Examples:
+@lsr{vocal,ambitus@/.ly}.
+
+@refbugs
+
+There is no collision handling in the case of multiple per-voice
+ambitus.
+
+
+@anchor{Stems}
+@unnumberedsubsubsec Stems
+
+Whenever a note is found, a @internalsref{Stem} object is created
+automatically. For whole notes and rests, they are also created but
+made invisible.
+
+@refcommands
+
+@funindex \stemUp
+@code{\stemUp},
+@funindex \stemDown
+@code{\stemDown},
+@funindex \stemNeutral
+@code{\stemNeutral}.
+
+
+@commonprop
+
+To change the direction of stems in the middle of the staff, use
+
+@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
+a4 b c b
+\override Stem #'neutral-direction = #up
+a4 b c b
+\override Stem #'neutral-direction = #down
+a4 b c b
+@end lilypond
+
+
+@node Outside the staff
+@subsection Outside the staff
+
+
+@anchor{Balloon help}
+@unnumberedsubsubsec 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 \with { \consists "Balloon_engraver" }
+{
+ \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
+ <c-\balloonText #'(-2 . -2) \markup { Hello } >8
+}
+@end lilypond
+
+@noindent
+There are two music functions, @code{balloonText} and
+@code{balloonGrobText}. The latter takes the name of the grob to
+adorn, while the former may be used as an articulation on a note.
+The other arguments are the offset and the text of the label.
+
+@cindex balloon
+@cindex notation, explaining
+
+@seealso
+
+Program reference: @internalsref{text-balloon-interface}.
+
+
+@anchor{Grid lines}
+@unnumberedsubsubsec Grid lines
+
+Vertical lines can be drawn between staves synchronized with
+the notes.
+
+@lilypond[ragged-right,quote,verbatim]
+\layout {
+ \context {
+ \Staff
+ \consists "Grid_point_engraver" %% sets of grid
+ gridInterval = #(ly:make-moment 1 4)
+ }
+}
+
+\new Score \with {
+ \consists "Grid_line_span_engraver"
+ %% centers grid lines horizontally below noteheads
+ \override NoteColumn #'X-offset = #-0.5
+}
+
+\new ChoirStaff <<
+ \new Staff {
+ \stemUp
+ \relative {
+ c'4. d8 e8 f g4
+ }
+ }
+ \new Staff {
+ %% centers grid lines vertically
+ \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 )
+ \stemDown
+ \clef bass
+ \relative c {
+ c4 g' f e
+ }
+ }
+>>
+@end lilypond
+
+Examples: @lsrdir{education}
+
+
+@anchor{Blank music sheet}
+@unnumberedsubsubsec Blank music sheet
+
+@cindex Sheet music, empty
+@cindex Staves, blank sheet
+
+A blank music sheet can be produced also by using invisible notes, and
+removing @code{Bar_number_engraver}.
+
+
+@lilypond[quote,verbatim]
+\layout{ indent = #0 }
+emptymusic = {
+ \repeat unfold 2 % Change this for more lines.
+ { s1\break }
+ \bar "|."
+}
+\new Score \with {
+ \override TimeSignature #'transparent = ##t
+% un-comment this line if desired
+% \override Clef #'transparent = ##t
+ defaultBarType = #""
+ \remove Bar_number_engraver
+} <<
+
+% modify these to get the staves you want
+ \new Staff \emptymusic
+ \new TabStaff \emptymusic
+>>
+@end lilypond
+
+
+
-@anchor{Ambitus}
-@unnumberedsubsubsec Ambitus
-@cindex ambitus
-
-The term @emph{ambitus} denotes a range of pitches for a given voice
-in a part of music. It may also denote the pitch range that a musical
-instrument is capable of playing. Ambits are printed on vocal parts,
-so performers can easily determine it meets their capabilities.
-
-Ambits are denoted at the beginning of a piece near the initial clef.
-The range is graphically specified by two note heads that represent the
-minimum and maximum pitch. To print such ambits, add the
-@internalsref{Ambitus_engraver} to the @internalsref{Voice} context,
-for example,
-
-@example
-\layout @{
- \context @{
- \Voice
- \consists Ambitus_engraver
- @}
-@}
-@end example
-
-This results in the following output
-
-@lilypond[quote,ragged-right]
-\layout {
- \context {
- \Staff
- \consists Ambitus_engraver
- }
-}
-
-\relative \new Staff {
- as'' c e2 cis,2
-}
-@end lilypond
-
-If you have multiple voices in a single staff and you want a single
-ambitus per staff rather than per each voice, add the
-@internalsref{Ambitus_engraver} to the @internalsref{Staff} context
-rather than to the @internalsref{Voice} context. Here is an example,
-
-@lilypond[verbatim,ragged-right,quote]
-\new Staff \with {
- \consists "Ambitus_engraver"
-}
-<<
- \new Voice \with {
- \remove "Ambitus_engraver"
- } \relative c'' {
- \override Ambitus #'X-offset = #-1.0
- \voiceOne
- c4 a d e f2
- }
- \new Voice \with {
- \remove "Ambitus_engraver"
- } \relative c' {
- \voiceTwo
- es4 f g as b2
- }
->>
-@end lilypond
-
-@noindent
-This example uses one advanced feature,
-
-@example
-\override Ambitus #'X-offset = #-1.0
-@end example
-
-@noindent
-This code moves the ambitus to the left. The same effect could have
-been achieved with @code{extra-offset}, but then the formatting system
-would not reserve space for the moved object.
-
-@seealso
-
-Program reference: @internalsref{Ambitus},
-@internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead},
-@internalsref{AmbitusAccidental}.
-
-Examples:
-@lsr{vocal,ambitus@/.ly}.
-
-@refbugs
-
-There is no collision handling in the case of multiple per-voice
-ambitus.
-
-
@anchor{Other vocal issues}
@unnumberedsubsubsec Other vocal issues
* Musical notation:: Musical notation.
old stuff
-* Basic notation::
* Instrument-specific notation::
* Advanced notation::
@include notation.itely
-@include basic-notation.itely
@include instrument-notation.itely
@include advanced-notation.itely
@include changing-defaults.itely
* Expressive marks:: Adding expression to notes.
* Repeats:: Repeat music.
* Simultaneous notes:: More than one note at once.
+* Staff notation:: Displaying staves.
+* Educational use:: Special notation to increase legibility.
+* Text:: Adding text to scores.
@end menu
@include pitch.itely
@include expressive.itely
@include repeats.itely
@include simultaneous.itely
+@include staff.itely
+@include educational.itely
+@include text.itely
--- /dev/null
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@node Repeats
+@section Repeats
+
+Repetition is a central concept in music, and multiple notations exist
+for repetitions.
+
+@menu
+* Writing repeats::
+* Other repeats::
+@end menu
+
+@node Writing repeats
+@subsection Writing repeats
+
+@anchor{Repeat types}
+@unnumberedsubsubsec Repeat types
+
+@cindex repeats
+
+The following types of repetition are supported
+
+@table @code
+@item unfold
+Repeated music is fully written (played) out. This is useful when
+entering repetitious music. This is the only kind of repeat that
+is included in MIDI output.
+
+@item volta
+Repeats are not written out, but alternative endings (volte) are
+printed, left to right with brackets. This is the standard notation
+for repeats with alternatives. These are not played in MIDI output by
+default.
+
+
+@item tremolo
+Make tremolo beams. These are not played in MIDI output by default.
+
+@item percent
+Make beat or measure repeats. These look like percent signs. These
+are not played in MIDI output by default. Percent repeats must be
+declared within a @code{Voice} context.
+
+@end table
+
+
+@anchor{Repeat syntax}
+@unnumberedsubsubsec Repeat syntax
+
+@cindex volta
+@cindex prima volta
+@cindex seconda volta
+@funindex \repeat
+
+LilyPond has one syntactic construct for specifying different types of
+repeats. The syntax is
+
+@example
+\repeat @var{variant} @var{repeatcount} @var{repeatbody}
+@end example
+
+If you have alternative endings, you may add
+@funindex \alternative
+@example
+\alternative @{
+ @var{alternative1}
+ @var{alternative2}
+ @var{alternative3}
+ @dots{}
+@}
+@end example
+
+@noindent
+where each @var{alternative} is a music expression. If you do not
+give enough alternatives for all of the repeats, the first alternative
+is assumed to be played more than once.
+
+Standard repeats are used like this
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+c1
+\repeat volta 2 { c4 d e f }
+\repeat volta 2 { f e d c }
+@end lilypond
+
+With alternative endings
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+c1
+\repeat volta 2 {c4 d e f}
+\alternative { {d2 d} {f f,} }
+@end lilypond
+
+Repeats with upbeats may be created.
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+\new Staff {
+ \partial 4 e |
+ \repeat volta 4 { c2 d2 | e2 f2 | }
+ \alternative { { g4 g g e } { a a a a | b2. } }
+}
+@end lilypond
+
+@noindent
+or
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+\new Staff {
+ \partial 4
+ \repeat volta 4 { e | c2 d2 | e2 f2 | }
+ \alternative { { \partial 4*3 g4 g g } { a a a a | b2. } }
+}
+@end lilypond
+
+
+
+@funindex \repeatTie
+
+Ties may be added to a second ending,
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+c1
+\repeat volta 2 {c4 d e f ~ }
+\alternative { {f2 d} {f\repeatTie f,} }
+@end lilypond
+
+It is possible to shorten volta brackets
+by setting @code{voltaSpannerDuration}. In the next example, the
+bracket only lasts one measure, which is a duration of 3/4.
+
+@lilypond[verbatim,ragged-right,quote]
+\relative c''{
+ \time 3/4
+ c c c
+ \set Score.voltaSpannerDuration = #(ly:make-moment 3 4)
+ \repeat volta 5 { d d d }
+ \alternative { { e e e f f f }
+ { g g g } }
+}
+@end lilypond
+
+If you want to start a repeat at the beginning of a line and have a
+double bar at the end of the previous line, use
+@example
+@dots{} \bar "||:" \break
+\repeat volta 2 @{ @dots{}
+@end example
+see @ref{Bar lines} for more information.
+
+@seealso
+
+Program reference: @internalsref{VoltaBracket},
+@internalsref{RepeatedMusic},
+@internalsref{VoltaRepeatedMusic}, and
+@internalsref{UnfoldedRepeatedMusic}.
+
+Examples:
+
+Brackets for the repeat are normally only printed over the topmost
+staff. This can be adjusted by moving @code{Volta_engraver} to the
+Staff context where you want the brackets to appear;
+see @ref{Modifying context plug-ins} and
+
+@lsr{repeats,volta@/-multi@/-staff@/.ly}.
+
+
+@refbugs
+
+@cindex repeat, ambiguous
+
+A nested repeat like
+
+@example
+\repeat @dots{}
+\repeat @dots{}
+\alternative
+@end example
+
+@noindent
+is ambiguous, since it is is not clear to which @code{\repeat} the
+@code{\alternative} belongs. This ambiguity is resolved by always
+having the @code{\alternative} belong to the inner @code{\repeat}.
+For clarity, it is advisable to use braces in such situations.
+
+Timing information is not remembered at the start of an alternative,
+so after a repeat timing information must be reset by hand; for
+example, by setting @code{Score.measurePosition} or entering
+@code{\partial}. Similarly, slurs or ties are also not repeated.
+
+
+@anchor{Manual repeat commands}
+@unnumberedsubsubsec Manual repeat commands
+
+@funindex repeatCommands
+
+The property @code{repeatCommands} can be used to control the layout of
+repeats. Its value is a Scheme list of repeat commands.
+
+@table @asis
+@item @code{start-repeat}
+Print a @code{|:} bar line.
+
+@item @code{end-repeat}
+Print a @code{:|} bar line.
+
+@item @code{(volta @var{text})}
+Print a volta bracket saying @var{text}: The text can be specified as
+a text string or as a markup text, see @ref{Text markup}. Do not
+forget to change the font, as the default number font does not contain
+alphabetic characters;
+
+@item @code{(volta #f)}
+Stop a running volta bracket.
+@end table
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c4
+ \set Score.repeatCommands = #'((volta "93") end-repeat)
+c4 c4
+ \set Score.repeatCommands = #'((volta #f))
+c4 c4
+@end lilypond
+
+
+@seealso
+
+Program reference: @internalsref{VoltaBracket},
+@internalsref{RepeatedMusic},
+@internalsref{VoltaRepeatedMusic}, and
+@internalsref{UnfoldedRepeatedMusic}.
+
+@anchor{Repeats and MIDI}
+@unnumberedsubsubsec Repeats and MIDI
+
+@cindex expanding repeats
+@funindex \unfoldRepeats
+
+With a little bit of tweaking, all types of repeats can be present
+in the MIDI output. This is achieved by applying the
+@code{\unfoldRepeats} music function. This function changes all
+repeats to unfold repeats.
+
+@lilypond[quote,verbatim,fragment,line-width=8.0\cm]
+\unfoldRepeats {
+ \repeat tremolo 8 {c'32 e' }
+ \repeat percent 2 { c''8 d'' }
+ \repeat volta 2 {c'4 d' e' f'}
+ \alternative {
+ { g' a' a' g' }
+ {f' e' d' c' }
+ }
+}
+\bar "|."
+@end lilypond
+
+When creating a score file using @code{\unfoldRepeats} for MIDI,
+it is necessary to make two @code{\score} blocks: one for MIDI (with
+unfolded repeats) and one for notation (with volta, tremolo, and
+percent repeats). For example,
+
+@example
+\score @{
+ @var{..music..}
+ \layout @{ .. @}
+@}
+\score @{
+ \unfoldRepeats @var{..music..}
+ \midi @{ .. @}
+@}
+@end example
+
+
+@node Other repeats
+@subsection Other repeats
+
+@anchor{Tremolo repeats}
+@unnumberedsubsubsec Tremolo repeats
+
+@cindex tremolo beams
+
+To place tremolo marks between notes, use @code{\repeat} with tremolo
+style
+@lilypond[quote,verbatim,ragged-right]
+\new Voice \relative c' {
+ \repeat tremolo 8 { c16 d16 }
+ \repeat tremolo 4 { c16 d16 }
+ \repeat tremolo 2 { c16 d16 }
+}
+@end lilypond
+
+Tremolo marks can also be put on a single note. In this case, the
+note should not be surrounded by braces.
+@lilypond[quote,verbatim,ragged-right]
+\repeat tremolo 4 c'16
+@end lilypond
+
+Similar output is obtained using the tremolo subdivision, described in
+@ref{Tremolo subdivisions}.
+
+
+@seealso
+
+In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}.
+
+Program reference: @internalsref{Beam}, @internalsref{StemTremolo}.
+
+
+@anchor{Tremolo subdivisions}
+@unnumberedsubsubsec Tremolo subdivisions
+
+@cindex tremolo marks
+@funindex tremoloFlags
+
+Tremolo marks can be printed on a single note by adding
+@q{@code{:}[@var{number}]} after the note. The number indicates the
+duration of the subdivision, and it must be at least 8. A
+@var{length} value of 8 gives one line across the note stem. If the
+length is omitted, the last value (stored in @code{tremoloFlags}) is
+used
+
+@lilypond[quote,ragged-right,verbatim,fragment]
+c'2:8 c':32 | c': c': |
+@end lilypond
+
+
+@refbugs
+
+Tremolos entered in this way do not carry over into the MIDI output.
+
+
+@seealso
+
+In this manual: @ref{Tremolo repeats}.
+
+Elsewhere: @internalsref{StemTremolo}.
+
+
+@anchor{Measure repeats}
+@unnumberedsubsubsec Measure repeats
+
+@cindex percent repeats
+@cindex measure repeats
+
+In the @code{percent} style, a note pattern can be repeated. It is
+printed once, and then the pattern is replaced with a special sign.
+Patterns of one and two measures are replaced by percent-like signs,
+patterns that divide the measure length are replaced by slashes.
+Percent repeats must be declared within a @code{Voice} context.
+
+@lilypond[quote,verbatim,ragged-right]
+\new Voice \relative c' {
+ \repeat percent 4 { c4 }
+ \repeat percent 2 { c2 es2 f4 fis4 g4 c4 }
+}
+@end lilypond
+
+Measure repeats of more than 2 measures get a counter, if you switch
+on the @code{countPercentRepeats} property,
+
+@lilypond[relative=2,fragment,quote,verbatim,ragged-right]
+\new Voice {
+\set countPercentRepeats = ##t
+ \repeat percent 4 { c1 }
+}
+@end lilypond
+
+
+
+Isolated percents can also be printed. This is done by putting a
+multi-measure rest with a different print function,
+
+@lilypond[fragment,verbatim,quote]
+\override MultiMeasureRest #'stencil
+ = #ly:multi-measure-rest::percent
+R1
+@end lilypond
+
+
+
+
+@seealso
+
+Program reference: @internalsref{RepeatSlash},
+@internalsref{PercentRepeat}, @internalsref{DoublePercentRepeat},
+@internalsref{DoublePercentRepeatCounter},
+@internalsref{PercentRepeatCounter},
+@internalsref{PercentRepeatedMusic}.
+
+
+
For more information about chords, see @ref{Chord names}.
-@c I don't like having this here, but I can't think of
-@c anywhere else to put it. :( -gp
-@anchor{Stems}
-@unnumberedsubsubsec Stems
-
-Whenever a note is found, a @internalsref{Stem} object is created
-automatically. For whole notes and rests, they are also created but
-made invisible.
-
-@refcommands
-
-@funindex \stemUp
-@code{\stemUp},
-@funindex \stemDown
-@code{\stemDown},
-@funindex \stemNeutral
-@code{\stemNeutral}.
-
-
-@commonprop
-
-To change the direction of stems in the middle of the staff, use
-
-@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
-a4 b c b
-\override Stem #'neutral-direction = #up
-a4 b c b
-\override Stem #'neutral-direction = #down
-a4 b c b
-@end lilypond
-
-
@anchor{Clusters}
@unnumberedsubsubsec Clusters
--- /dev/null
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@node Staff notation
+@section Staff notation
+
+staff = singular, staves = plural
+
+@menu
+* Displaying staves::
+* Writing parts::
+@end menu
+
+
+@node Displaying staves
+@subsection Displaying staves
+
+@anchor{System start delimiters}
+@unnumberedsubsubsec System start delimiters
+
+@cindex start of system
+@cindex Staff, multiple
+@cindex bracket, vertical
+@cindex brace, vertical
+@cindex grand staff
+@cindex staff group
+@cindex staff, choir
+
+Many scores consist of more than one staff. These staves can be
+joined in four different ways
+
+@itemize @bullet
+@item The group is started with a brace at the left, and bar lines are
+connected. This is done with the @internalsref{GrandStaff} context.
+
+@lilypond[verbatim,ragged-right,quote]
+\new GrandStaff
+\relative <<
+ \new Staff { c1 c }
+ \new Staff { c c }
+>>
+@end lilypond
+
+@item The group is started with a bracket, and bar lines are connected.
+This is done with the
+@internalsref{StaffGroup} context
+
+@lilypond[verbatim,ragged-right,quote]
+\new StaffGroup
+\relative <<
+ \new Staff { c1 c }
+ \new Staff { c c }
+>>
+@end lilypond
+
+@item The group is started with a bracket, but bar lines are not
+connected. This is done with the @internalsref{ChoirStaff} context.
+
+@lilypond[verbatim,ragged-right,quote]
+\new ChoirStaff
+\relative <<
+ \new Staff { c1 c }
+ \new Staff { c c }
+>>
+@end lilypond
+
+@item The group is started with a vertical line. Bar lines are not
+connected. This is the default for the score.
+
+@lilypond[verbatim,ragged-right,quote]
+\relative <<
+ \new Staff { c1 c }
+ \new Staff { c c }
+>>
+@end lilypond
+@end itemize
+
+
+@seealso
+
+The bar lines at the start of each system are
+@internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and
+@internalsref{SystemStartBracket}. Only one of these types is created
+in every context, and that type is determined by the property
+@code{systemStartDelimiter}.
+
+
+@commonprop
+
+System start delimiters may be deeply nested,
+
+@lilypond[quote,ragged-right,verbatim]
+\new StaffGroup
+\relative <<
+ \set StaffGroup.systemStartDelimiterHierarchy
+ = #'(SystemStartSquare (SystemStartBracket a (SystemStartSquare b)) d)
+ \new Staff { c1 }
+ \new Staff { c1 }
+ \new Staff { c1 }
+ \new Staff { c1 }
+ \new Staff { c1 }
+>>
+@end lilypond
+
+
+@anchor{Staff symbol}
+@unnumberedsubsubsec Staff symbol
+
+@cindex adjusting staff symbol
+
+Notes, dynamic signs, etc., are grouped
+with a set of horizontal lines, called a staff (plural @q{staves}). In
+LilyPond, these lines are drawn using a separate layout object called
+@code{staff symbol}.
+
+The staff symbol may be tuned in the number, thickness and distance
+of lines, using properties. This is demonstrated in the example files
+@lsr{staff,changing-the-number-of-lines-in-a-staff.ly} and
+@lsr{staff,changing-the-staff-size.ly}.
+
+In addition, staves may be started and stopped at will. This is done
+with @code{\startStaff} and @code{\stopStaff}.
+
+@lilypond[verbatim,relative=2,fragment]
+b4 b
+\override Staff.StaffSymbol #'line-count = 2
+\stopStaff \startStaff
+b b
+\revert Staff.StaffSymbol #'line-count
+\stopStaff \startStaff
+b b
+@end lilypond
+
+In combination with Frenched staves, this may be used to typeset ossia
+sections. An example is shown here
+
+@cindex ossia
+
+@lilypondfile{ossia.ly}
+
+@cindex staff lines, setting number of
+@cindex staff lines, setting thickness of
+@cindex thickness of staff lines, setting
+@cindex number of staff lines, setting
+
+@seealso
+
+Program reference: @internalsref{StaffSymbol}.
+
+Examples: @lsrdir{staff}
+
+
+@anchor{Hiding staves}
+@unnumberedsubsubsec 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 @q{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.
+
+
+
+@node Writing parts
+@subsection Writing parts
+
+@anchor{Metronome marks}
+@unnumberedsubsubsec 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
+@funindex \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
+
+
+@anchor{Instrument names}
+@unnumberedsubsubsec 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{instrumentName}
+and @internalsref{Staff}.@code{shortInstrumentName}, or
+@internalsref{PianoStaff}.@code{instrumentName} and
+@internalsref{PianoStaff}.@code{shortInstrumentName}. This will
+print text before
+the start of the staff. For the first staff, @code{instrumentName} is
+used, for the following ones, @code{shortInstrumentName} is used.
+
+@lilypond[quote,verbatim,ragged-right,relative=1,fragment]
+\set Staff.instrumentName = "Ploink "
+\set Staff.shortInstrumentName = "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.instrumentName = \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.instrumentName = \markup {
+ \center-align { "Clarinetti"
+ \line { "in B" \smaller \flat } } }
+ c''1
+}
+\new Staff {
+ \set Staff.instrumentName = \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.
+
+To center instrument names while leaving extra space to the right,
+
+@lilypond[quote,verbatim,ragged-right]
+\new StaffGroup \relative
+<<
+ \new Staff {
+ \set Staff.instrumentName = \markup { \hcenter-in #10 "blabla" }
+ c1 c1
+ }
+ \new Staff {
+ \set Staff.instrumentName = \markup { \hcenter-in #10 "blo" }
+ c1 c1
+ }
+>>
+@end lilypond
+
+To add instrument names to other contexts (such as @code{GrandStaff},
+@code{ChoirStaff}, or @code{StaffGroup}), the engraver must
+be added to that context.
+
+@example
+\layout@{
+ \context @{\GrandStaff \consists "Instrument_name_engraver"@}
+@}
+@end example
+
+@noindent
+More information about adding and removing engravers can
+be found in @ref{Modifying context plug-ins}.
+
+Instrument names may be changed in the middle of a piece,
+
+@lilypond[quote,fragment,verbatim,ragged-right]
+\set Staff.instrumentName = "First"
+\set Staff.shortInstrumentName = "one"
+c1 c c c \break
+c1 c c c \break
+\set Staff.instrumentName = "Second"
+\set Staff.shortInstrumentName = "two"
+c1 c c c \break
+c1 c c c \break
+@end lilypond
+
+
+@seealso
+
+Program reference: @internalsref{InstrumentName}.
+
+
+@anchor{Quoting other voices}
+@unnumberedsubsubsec Quoting other voices
+
+@cindex cues
+
+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.
+
+Quoting nested triplets may result in poor notation.
+
+
+@seealso
+
+In this manual: @ref{Instrument transpositions}.
+
+Examples: @lsr{parts,quote.ly}, @lsr{parts,quote-transportation.ly}
+
+Program reference: @internalsref{QuoteMusic}.
+
+
+@anchor{Formatting cue notes}
+@unnumberedsubsubsec Formatting cue notes
+
+@cindex cues, formatting
+
+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" #UP {
+ 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 (e.g. a big close-bracket over the staff) to indicate the cue
+@c 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
+
+The macro @code{\transposedCueDuring} is
+useful to add cues to instruments which use a completely different
+octave range (for example, having a cue of a piccolo flute within
+a contra bassoon part).
+
+@lilypond[verbatim,ragged-right,quote]
+picc = \relative c''' {
+ \clef "treble^8"
+ R1 |
+ c8 c c e g2 |
+ a4 g g2 |
+}
+\addQuote "picc" { \picc }
+
+cbsn = \relative c, {
+ \clef "bass_8"
+ c4 r g r
+ \transposedCueDuring #"picc" #UP c,, { R1 } |
+ c4 r g r |
+}
+
+<<
+ \context Staff = "picc" \picc
+ \context Staff = "cbsn" \cbsn
+>>
+@end lilypond
+
+
+
+
+
+
--- /dev/null
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@node Text
+@section Text
+
+This section explains how to include text (with various formatting) in
+your scores.
+
+@cindex Text, other languages
+To write accented and special text (such as characters from other languages),
+simply
+insert the characters directly into the lilypond file. The file must be
+saved as UTF-8. For more information, see @ref{Text encoding}.
+
+@lilypond[fragment,ragged-right,staffsize=16,quote]
+c'4^\markup { bla \bold bla }
+@end lilypond
+
+@lilypond[fragment,ragged-right,staffsize=16,quote]
+c'4^\markup { bla \bold bla }
+@end lilypond
+
+@lilypond[fragment,ragged-right,staffsize=16,quote]
+c'4^\markup { bla \bold bla }
+@end lilypond
+
+@lilypond[fragment,ragged-right,staffsize=16,quote]
+c'4^\markup { bla \bold bla }
+@end lilypond
+
+@menu
+* Writing text::
+* Text markup::
+@end menu
+
+
+@node Writing text
+@subsection Writing text
+
+@anchor{Text scripts}
+@unnumberedsubsubsec 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
+
+@noindent
+To prevent text from influencing spacing, use @code{\emptyText}.
+
+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
+
+@funindex \fatText
+@code{\fatText},
+@funindex \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}.
+
+
+@anchor{Text and line spanners}
+@unnumberedsubsubsec Text and line spanners
+
+Some performance indications, e.g., @i{rallentando} and
+@i{accelerando} and @i{trills} are written as text and are extended
+over many measures with lines, sometimes dotted or wavy.
+
+These all use the same routines as the glissando for drawing the texts
+and the lines, and tuning their behavior is therefore also done in the
+same way. It is done with a spanner, and the routine responsible for
+drawing the spanners is @code{ly:line-interface::print}. This
+routine determines the exact location of the two @i{span
+points} and draws a line in between, in the style requested.
+
+Here is an example of the different line styles available, and how to
+tune them.
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+d2 \glissando d'2
+\once \override Glissando #'dash-fraction = #0.5
+d,2 \glissando d'2
+\override Glissando #'style = #'dotted-line
+d,2 \glissando d'2
+\override Glissando #'style = #'zigzag
+d,2 \glissando d'2
+\override Glissando #'style = #'trill
+d,2 \glissando d'2
+@end lilypond
+
+The information that determines the end-points is computed on-the-fly
+for every graphic object, but it is possible to override these.
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+e2 \glissando f
+\once \override Glissando #'bound-details #'right #'Y = #-2
+e2 \glissando f
+@end lilypond
+
+The @code{Glissando} object, like any other using the
+@code{ly:line-interface::print} routine, carries a nested
+association list. In the above statement, the value for @code{Y}
+is set to @code{-2} for the association list corresponding to the right
+end point. Of course, it is also possible to adjust the left side with
+@code{left} instead of @code{right}.
+
+If @code{Y} is not set, the value is computed from the vertical
+position of right attachment point of the spanner.
+
+In case of a line break, the values for the span-points are extended
+with contents of the @code{left-broken} and @code{right-broken}
+sublists, for example
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+\override Glissando #'breakable = ##T
+\override Glissando #'bound-details #'right-broken #'Y = #-3
+c1 \glissando \break
+f1
+@end lilypond
+
+The following properties can be used for the
+
+@table @code
+@item Y
+This sets the Y-coordinate of the end point, in staff space. By
+default, it is the center of the bound object, so for a glissando it
+points to the vertical center of the note head.
+
+For horizontal spanners, such as text spanner and trill spanners, it
+is hardcoded to 0.
+
+@item attach-dir
+This determines where the line starts and ends in X-direction,
+relative to the bound object. So, a value of @code{-1} (or
+@code{LEFT}) makes the line start/end at the left side of the note
+head it is attached to.
+
+@item X
+This is the absolute coordinate of the end point. It is usually
+computed on the fly, and there is little use in overriding it.
+
+@item stencil
+Line spanners may have symbols at the beginning or end, which is
+contained in this sub-property. This is for internal use, it is
+recommended to use @code{text}.
+
+@item text
+This is a markup that is evaluated to yield stencil. It is
+used to put @i{cresc.} and @i{tr} on horizontal spanners.
+
+@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
+\override TextSpanner #'bound-details #'left #'text
+ = \markup { \small \bold Slower }
+c2\startTextSpan b c a\stopTextSpan
+@end lilypond
+
+@item stencil-align-dir-y
+@item stencil-offset
+Without setting this, the stencil is simply put there at the
+end-point, as defined by the @code{X} and @code{Y} sub properties.
+Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
+will move the symbol at the edge relative to the end point of the line
+
+@lilypond[relative=1,fragment,verbatim]
+\override TextSpanner #'bound-details #'left #'stencil-align-dir-y = #DOWN
+\override TextSpanner #'bound-details #'right #'stencil-align-dir-y = #UP
+
+\override TextSpanner #'bound-details #'left #'text = #"gggg"
+\override TextSpanner #'bound-details #'right #'text = #"hhhh"
+c4^\startTextSpan c c c \stopTextSpan
+@end lilypond
+
+@item arrow
+Setting this sub property to @code{#t} produce an arrowhead at the end
+of the line.
+
+@item padding
+This sub property controls the space between the specified end-point
+of the line and the actual end. Without padding, a glissando would
+start and end in the center of each note head.
+
+@end table
+
+@seealso
+
+Program reference: @internalsref{TextSpanner},
+@internalsref{Glissando}, @internalsref{VoiceFollower},
+@internalsref{TrillSpanner}, @internalsref{line-spanner-interface}.
+
+Examples: @lsr{expressive,line-styles.ly}, @lsr{expressive,line-arrows.ly}
+
+
+@anchor{Text spanners}
+@unnumberedsubsubsec 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 #'bound-details #'left #'text =
+ \markup { \upright "rall" }
+c2\startTextSpan b c\stopTextSpan a
+\break
+\textSpannerUp
+\override TextSpanner #'bound-details #'left #'text =
+ \markup { \italic "rit" }
+c2\startTextSpan b c\stopTextSpan a
+@end lilypond
+
+@refcommands
+
+@funindex textSpannerUp
+@code{\textSpannerUp},
+@funindex textSpannerDown
+@code{\textSpannerDown},
+@funindex textSpannerNeutral
+@code{\textSpannerNeutral}.
+
+
+@commonprop
+
+To print a solid line, use
+
+@example
+\override TextSpanner #'dash-fraction = #'()
+@end example
+
+
+@seealso
+
+Program reference: @internalsref{TextSpanner}.
+
+
+@anchor{Text marks}
+@unnumberedsubsubsec Text marks
+
+@cindex coda on bar line
+@cindex segno on bar line
+@cindex fermata on bar line
+@cindex bar lines, symbols on
+@funindex \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 (symbols are listed in
+@ref{The Feta font}).
+
+@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
+
+Text marks may be aligned with notation objects other than
+bar lines,
+
+@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
+\relative {
+ c1
+ \key cis \major
+ \clef alto
+ \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
+ \mark "on key"
+ cis
+ \key ces \major
+ \override Score.RehearsalMark #'break-align-symbols = #'(clef)
+ \clef treble
+ \mark "on clef"
+ ces
+ \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
+ \key d \minor
+ \clef tenor
+ \time 3/4
+ \mark "on time"
+ c
+}
+@end lilypond
+
+Possible symbols for the @code{break-align-symbols} list are
+@code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
+@code{staff-bar}, @code{left-edge}, @code{key-cancellation},
+@code{key-signature}, and @code{time-signature}.
+
+The text marks will, by default, be aligned with the middle of the notation
+object, but this can be changed by overriding the
+@code{break-align-anchor-alignment} and
+@code{break-align-anchor} properties for the appropriate grob.
+
+@lilypond[fragment,quote,ragged-right,verbatim]
+{
+ \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
+ c1
+ \key cis \major
+
+ % the RehearsalMark will be aligned with the left edge of the KeySignature
+ \once \override Staff.KeySignature #'break-align-anchor-alignment = #LEFT
+ \mark \default
+ cis1
+ \key ces \major
+
+ % the RehearsalMark will be aligned with the right edge of the KeySignature
+ \once \override Staff.KeySignature #'break-align-anchor-alignment = #RIGHT
+ \mark \default
+ ces1
+ \key cis \major
+
+ % the RehearsalMark will be aligned with the left edge of the KeySignature
+ % and then shifted right by 2 units.
+ \once \override Staff.KeySignature #'break-align-anchor = #2
+ \mark \default
+ ces1
+}
+@end lilypond
+
+Although text marks are normally only printed above the topmost
+staff, you may alter this to print them on every staff,
+
+@lilypond[quote,ragged-right,verbatim,relative=2]
+{
+ \new Score \with {
+ \remove "Mark_engraver"
+ }
+ <<
+ \new Staff \with {
+ \consists "Mark_engraver"
+ }
+ { c''1 \mark "foo" c'' }
+ \new Staff \with {
+ \consists "Mark_engraver"
+ }
+ { c'1 \mark "foo" c' }
+ >>
+}
+@end lilypond
+
+
+@seealso
+
+Program reference: @internalsref{RehearsalMark}.
+
+
+
+@anchor{New dynamic marks}
+@unnumberedsubsubsec 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. Note that the dynamic font only contains the characters
+@code{f,m,p,r,s} and @code{z}.
+
+Some situations (such as dynamic marks) have preset font-related
+properties. If you are creating text in such situations, it
+is advisable to cancel those properties with
+@code{normal-text}. See @ref{Overview of text markup commands},
+for more details.
+
+@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 Text markup
+@subsection Text markup
+
+@anchor{Text markup introduction}
+@unnumberedsubsubsec Text markup introduction
+
+@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 {weird} #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.instrumentName = \markup{ \column{ Alto solo } }
+ c2^\markup{ don't be \flat }
+ \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
+ b2\startTextSpan
+ a2\mark \markup{ \large \bold Fine }
+ r2\stopTextSpan
+ \bar "||"
+ }
+ \addlyrics { bar, foo \markup{ \italic bar! } }
+}
+@end lilypond
+
+A @code{\markup} command can also be placed on its own, away from any
+@code{\score} block, see @ref{Multiple scores in a book}.
+
+@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 @q{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
+
+Some situations (such as dynamic marks) have preset font-related
+properties. If you are creating text in such situations, it
+is advisable to cancel those properties with
+@code{normal-text}. See @ref{Overview of text markup commands},
+for more details.
+
+
+@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.
+
+
+@anchor{Nested scores}
+@unnumberedsubsubsec 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
+
+@anchor{Page wrapping text}
+@unnumberedsubsubsec Page wrapping text
+Whereas @code{\markup} is used to enter a non-breakable block of text,
+@code{\markuplines} can be used at top-level to enter lines of text that
+can spread over multiple pages:
+
+@verbatim
+\markuplines {
+ \justified-lines {
+ A very long text of justified lines.
+ ...
+ }
+ \justified-lines {
+ An other very long paragraph.
+ ...
+ }
+ ...
+}
+@end verbatim
+
+@code{\markuplines} accepts a list of markup, that is either the result
+of a markup list command, or a list of markups or of markup lists. The
+built-in markup list commands are described in
+@ref{Overview of text markup list commands}.
+
+@seealso
+
+This manual: @ref{Overview of text markup list commands},
+@ref{New markup list command definition}.
+
+@refcommands
+
+@funindex \markuplines
+@code{\markuplines}
+
+@anchor{Overview of text markup commands}
+@unnumberedsubsubsec Overview of text markup commands
+
+The following commands can all be used inside @code{\markup @{ @}}.
+
+@include markup-commands.tely
+
+@anchor{Overview of text markup list commands}
+@unnumberedsubsubsec Overview of text markup list commands
+
+The following commands can all be used with @code{\markuplines}.
+
+@include markup-list-commands.tely
+
+@anchor{Font selection}
+@unnumberedsubsubsec Font selection
+
+@cindex font selection
+@cindex font magnification
+@funindex 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, e.g.
+
+@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.
+To get a full list of all available fonts, run the command
+@example
+lilypond -dshow-available-fonts blabla
+@end example
+(the last argument of the command can be anything, but has to be present).
+
+
+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: @lsr{text,font@/-family@/-override.ly}.
+
+
+
+
projects / lilypond.git / commitdiff