This chapter deals with rarely-used and advanced notation.
@menu
-* Even more than notes::
+* Text::
* Preparing parts::
* Orchestral music::
* Contemporary notation::
@end menu
-@c really bad section name. :(
-@node Even more than notes
-@section Even more than notes
+
+@node Text
+@section Text
+
+This section explains how to include text (with various formatting) in
+your scores.
@menu
* Text scripts::
* Text spanners::
-* Transpose::
-* Ottava brackets::
-* Multi measure rests::
-* Time administration::
+* Text marks::
+* Text markup::
+* Text encoding::
+* Nested scores::
+* Overview of text markup commands::
+* Font selection::
+* New dynamic marks::
+* Other text markup issues::
@end menu
@node Text scripts
@subsection Text scripts
-@cindex Text scripts
+@cindex Text scripts
@cindex text items, non-empty
@cindex non-empty texts
-It is possible to place arbitrary strings of text or markup text (see
-@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
+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,raggedright,verbatim,relative=1]
c4^"longtext" \fatText c4_"longlongtext" c4
@cindex @code{\emptyText}
@code{\emptyText}.
+
@seealso
In this manual: @ref{Text markup}.
-Program reference: @internalsref{TextScriptEvent}, @internalsref{TextScript}.
+Program reference: @internalsref{TextScript}.
@node Text spanners
@subsection Text spanners
+
@cindex Text spanners
Some performance indications, e.g., @i{rallentando} or @i{accelerando},
@lilypond[quote,raggedright,fragment,relative=1,verbatim]
c1
-\override TextSpanner #'direction = #-1
+\textSpannerDown
\override TextSpanner #'edge-text = #'("rall " . "")
c2\startTextSpan b c\stopTextSpan a
@end lilypond
+@refcommands
+
+@cindex textSpannerUp
+@code{textSpannerUp},
+@cindex textSpannerDown
+@code{textSpannerDown},
+@cindex textSpannerNeutral
+@code{textSpannerNeutral}.
+
@seealso
-Internals @internalsref{TextSpanEvent},
-@internalsref{TextSpanner}.
+Program reference: @internalsref{TextSpanner}.
Examples: @inputfileref{input/@/regression,text@/-spanner@/.ly}.
-@node Transpose
-@subsection Transpose
-@cindex Transpose
-@cindex transposition of pitches
-@cindex @code{\transpose}
+@node Text marks
+@subsection Text marks
+
+@cindex coda on bar line
+@cindex segno on bar line
+@cindex fermata on bar line
+@cindex bar lines, symbols on
+@cindex @code{\mark}
+
+The @code{\mark} command is primarily used for
+@ref{Rehearsal marks},
+but it can also be used to put signs like coda,
+segno, and fermata on a bar line. Use @code{\markup} to
+access the appropriate symbol
+
+@lilypond[fragment,quote,raggedright,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
-A music expression can be transposed with @code{\transpose}. The
-syntax is
@example
-\transpose @var{from} @var{to} @var{musicexpr}
+\override Score.RehearsalMark
+ #'break-visibility = #begin-of-line-invisible
@end example
-This means that @var{musicexpr} is transposed by the interval between
-the pitches @var{from} and @var{to}: any note with pitch @code{from}
-is changed to @code{to}.
+@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,raggedright,verbatim,relative=2]
+\override Score.RehearsalMark
+ #'break-visibility = #begin-of-line-invisible
+c1 c c c4 c c c
+\once \override Score.RehearsalMark #'self-alignment-X = #right
+\mark "D.S. al Fine "
+@end lilypond
+
+
+@seealso
+
+Program reference: @internalsref{RehearsalMark}.
+
+
+@node Text markup
+@subsection Text markup
+
+@cindex markup
+@cindex text markup
+@cindex markup text
+@cindex typeset text
+
+Use @code{\markup} to typeset text. Commands are entered with the
+backslash @code{\}.
+
+@lilypond[quote,verbatim,fragment,relative=1]
+c1^\markup { hello }
+c1_\markup { hi there }
+c1^\markup { hi \bold there, is \italic anyone home? }
+@end lilypond
+
+@noindent
+See @ref{Overview of text markup commands} for a list of all
+commands.
+
+@code{\markup} is primarily used for @internalsref{TextScript}s,
+but it can also be used anywhere text is called in lilypond
+
+@lilypond[quote,verbatim]
+\header{ title = \markup{ \bold { foo \italic { bar! } } } }
+\score{
+ \relative c'' {
+ \override Score.RehearsalMark
+ #'break-visibility = #begin-of-line-invisible
+ \override Score.RehearsalMark #'self-alignment-X = #right
+
+ \set Staff.instrument = \markup{ \column{ Alto solo } }
+ c2^\markup{ don't be \flat }
+ b2
+ a2\mark \markup{ \large \bold Fine }
+ r2
+ \bar "||"
+ }
+ \addlyrics { bar, foo \markup{ \italic bar! } }
+}
+@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,
-For example, consider a piece written in the key of D-major. If
-this piece is a little too low for its performer, it can be
-transposed up to E-major with
@example
-\transpose d e @dots{}
+\markup @{ \bold @{ hi there @} @}
@end example
-Consider a part written for violin (a C instrument). If
-this part is to be played on the A clarinet, the following
-transposition will produce the appropriate part
+@noindent
+For clarity, you can also do this for single arguments, e.g.,
@example
-\transpose a c @dots{}
+\markup @{ is \italic @{ anyone @} home @}
@end example
-@code{\transpose} distinguishes between enharmonic pitches: both
-@code{\transpose c cis} or @code{\transpose c des} will transpose up
-half a tone. The first version will print sharps and the second
-version will print flats
+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,raggedright,verbatim]
-mus = { \key d \major cis d fis g }
-\context Staff {
- \clef "F" \mus
- \clef "G"
- \transpose c g' \mus
- \transpose c f' \mus
-}
+@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
-@code{\transpose} may also be used to input written notes for a
-transposing instrument. Pitches are normally entered into LilyPond
-in C (or ``concert pitch''), but they may be entered in another
-key. For example, when entering music for a B-flat trumpet which
-begins on concert D, one would write
+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
-\transpose c bes @{ e4 @dots{} @}
+\center-align @{ a b c d @}
@end example
-To print this music in B-flat again (ie producing a trumpet part,
-instead of a concert pitch conductor's score) you would wrap the
-existing music with another @code{transpose}
+@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
-\transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @}
+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.
+
@seealso
-Program reference: @internalsref{TransposedMusic}, and
-@internalsref{UntransposableMusic}.
+This manual: @ref{Overview of text markup commands}.
+
+Program reference: @internalsref{TextScript}.
+
+Init files: @file{scm/@/new@/-markup@/.scm}.
+
@refbugs
-If you want to use both @code{\transpose} and @code{\relative},
-you must put @code{\transpose} outside of @code{\relative}, since
-@code{\relative} will have no effect music that appears inside a
-@code{\transpose}.
+Kerning or generation of ligatures is only done when the @TeX{}
+backend is used. In this case, LilyPond does not account for them so
+texts will be spaced slightly too wide.
+Syntax errors for markup mode are confusing.
-@node Ottava brackets
-@subsection Ottava brackets
-`Ottava' brackets introduce an extra transposition of an octave for
-the staff. They are created by invoking the function
-@code{set-octavation}
+@node Text encoding
+@subsection Text encoding
-@cindex ottava
-@cindex 15ma
-@cindex octavation
+LilyPond uses the Pango library to format multi-lingual texts, and
+does not perform any input-encoding conversions. This means that any
+text, be it title, lyric text, or musical instruction containing
+non-ASCII characters, must be utf-8. Easiest to enter such texts is
+by using a Unicode-aware editor, and save using utf-8 encoding. Most
+popular modern editors have utf-8 support, for example, vim, Emacs,
+jEdit, and GEdit do.
-@lilypond[quote,raggedright,verbatim,fragment]
-\relative c''' {
- a2 b
- #(set-octavation 1)
- a b
- #(set-octavation 0)
- a b
+Depending on the fonts installed, the following fragment shows Hebrew
+and Cyrillic lyrics,
+
+@cindex Cyrillic
+@cindex Hebrew
+@cindex ASCII, non
+
+@lilypondfile[fontload]{utf-8.ly}
+
+The @TeX{} backend does not handle encoding specially at all. Strings
+in the input are put in the output as-is. Extents of text items in the
+@TeX{} backend, are determined by reading a file created via the
+@file{texstr} backend,
+
+@example
+lilypond -b texstr input/les-nereides.ly
+latex les-nereides.texstr
+@end example
+
+The last command produces @file{les-nereides.textmetrics}, which is
+read when you execute
+
+@example
+lilypond -b tex input/les-nereides.ly
+@end example
+
+Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
+suitable LaTeX wrappers to load appropriate La@TeX{} packages for
+interpreting non-ASCII strings.
+
+
+@seealso
+
+@inputfileref{input/regression,utf-8.ly}
+
+
+@node Nested scores
+@subsection Nested scores
+
+It is possible to nest music inside markups, by adding a @code{\score}
+block to a markup expression. Such a score must contain a @code{\layout}
+block.
+
+@lilypond[quote,verbatim,raggedright]
+\relative {
+ c4 d^\markup {
+ \score {
+ \relative { c4 d e f }
+ \layout { }
+ }
+ }
+ e f
}
@end lilypond
-The @code{set-octavation} function also takes -1 (for 8va bassa) and 2
-(for 15ma) as arguments. Internally the function sets the properties
-@code{ottavation} (e.g., to @code{"8va"}) and
-@code{centralCPosition}. For overriding the text of the bracket, set
-@code{ottavation} after invoking @code{set-octavation}, i.e.,
-@lilypond[quote,raggedright,verbatim]
+@node Overview of text markup commands
+@subsection Overview of text markup commands
+
+The following commands can all be used inside @code{\markup @{ @}}.
+
+@include markup-commands.tely
+
+
+@node Font selection
+@subsection Font selection
+
+@cindex font selection
+@cindex font magnification
+@cindex @code{font-interface}
+
+By setting the object properties described below, you can select a
+font from the preconfigured font families. LilyPond has default
+support for the feta music fonts. Text fonts are selected through
+Pango/FontConfig. The serif font defaults to New Century Schoolbook,
+the sans and typewriter to whatever the Pango installation defaults
+to.
+
+
+@itemize @bullet
+@item @code{font-encoding}
+is a symbol that sets layout of the glyphs. This should only be set to
+select different types of non-text fonts, eg.
+
+@code{fetaBraces} for piano staff braces, @code{fetaMusic} the
+standard music font, including ancient glyphs, @code{fetaDynamic} for
+dynamic signs and @code{fetaNumber} for the number font.
+
+@item @code{font-family}
+is a symbol indicating the general class of the typeface. Supported are
+@code{roman} (Computer Modern), @code{sans}, and @code{typewriter}.
+
+@item @code{font-shape}
+is a symbol indicating the shape of the font. There are typically
+several font shapes available for each font family. Choices are
+@code{italic}, @code{caps}, and @code{upright}.
+
+@item @code{font-series}
+is a symbol indicating the series of the font. There are typically
+several font series for each font family and shape. Choices are
+@code{medium} and @code{bold}.
+
+@end itemize
+
+Fonts selected in the way sketched above come from a predefined style
+sheet. If you want to use a font from outside the style sheet,
+then set the
+@code{font-name} property,
+
+@lilypond[fragment,verbatim]
{
- #(set-octavation 1)
- \set Staff.ottavation = #"8"
- c'''
+ \override Staff.TimeSignature #'font-name = #"Times"
+ \override Staff.TimeSignature #'font-size = #2
+ \time 3/4
+ c'1_\markup {
+ \override #'(font-name . "Vera Bold")
+ { This text is in Vera Bold }
+ }
}
@end lilypond
+@noindent
+Any font can be used, as long as it is available to Pango/FontConfig.
+
+The size of the font may be set with the @code{font-size}
+property. The resulting size is taken relative to the
+@code{text-font-size} as defined in the @code{\paper} block.
+
+@cindex font size
+@cindex font magnification
+
@seealso
-Program reference: @internalsref{OttavaBracket}.
+@c FIXME.
+Init files: @file{ly/@/declarations@/-init@/.ly} contains hints how new
+fonts may be added to LilyPond.
-Examples: @inputfileref{input/@/regression,ottava@/.ly},
-@inputfileref{input/@/regression,ottava@/-broken@/.ly}.
-@refbugs
+@node New dynamic marks
+@subsection New dynamic marks
-@code{set-octavation} will get confused when clef changes happen
-during an octavation bracket.
+It is possible to print new dynamic marks or text that should be aligned
+with dynamics. Use @code{make-dynamic-script} to create these marks.
+
+@cindex make-dynamic-script
+
+@lilypond[quote,verbatim,raggedright]
+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,raggedright]
+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 Other text markup issues
+@subsection Other text markup issues
+
+To use a normal font within a title, you must define it manually
+
+@example
+#(def-markup-command (normal-font layout props arg) (markup?)
+ "Switch to normal text font"
+ (interpret-markup layout (cons '((font-series . 'medium) (font-shape . 'upright)) props) arg))
+
+\header@{
+ title = \markup@{ ABCD \normal-font ABCD @}
+@}
+@end example
+
+
+
+@node Preparing parts
+@section Preparing parts
+
+This section describes various notation that are useful for preparing
+individual parts.
+
+@menu
+* Multi measure rests::
+* Metronome marks::
+* Rehearsal marks::
+* Bar numbers::
+* Instrument names::
+* Instrument transpositions::
+* Ottava brackets::
+* Different editions from one source::
+@end menu
@node Multi measure rests
@subsection Multi measure rests
+
@cindex multi measure rests
@cindex Rests, multi measure
-
+@cindex whole rests for a full measure
@cindex @code{R}
Multi-measure rests are entered using `@code{R}'. It is specifically
R1*2 | R1*5 | R1*9
@end lilypond
-
@cindex text on multi-measure rest
@cindex script on multi-measure rest
@cindex fermata on multi-measure rest
Texts can be added to multi-measure rests by using the
-@var{note}-@code{markup} syntax (see @ref{Text markup}).
+@var{note}-@code{markup} syntax @ref{Text markup}.
A variable (@code{\fermataMarkup}) is provided for
adding fermatas
@end example
-@cindex whole rests for a full measure
-
@seealso
-Program reference: @internalsref{MultiMeasureRestEvent},
-@internalsref{MultiMeasureTextEvent},
-@internalsref{MultiMeasureRestMusicGroup}, and
+Program reference: @internalsref{MultiMeasureRestMusicGroup},
@internalsref{MultiMeasureRest}.
The layout object @internalsref{MultiMeasureRestNumber} is for the
default number, and @internalsref{MultiMeasureRestText} for user
specified texts.
+
@refbugs
It is not possible to use fingerings (e.g., @code{R1-4}) to put numbers
numbering will be off.
-@node Time administration
-@subsection Time administration
-
-Time is administered by the @internalsref{Time_signature_engraver},
-which usually lives in the @internalsref{Score} context.
-The bookkeeping deals with the following variables
-
-@table @code
-@item currentBarNumber
-The measure number.
-
-@item measureLength
-The length of the measures in the current time signature. For a 4/4
-time this is@tie{}1, and for 6/8 it is 3/4.
-
-@item measurePosition
-The point within the measure where we currently are. This quantity
-is reset to@tie{}0 whenever it exceeds @code{measureLength}. When that
-happens, @code{currentBarNumber} is incremented.
-
-@item timing
-If set to true, the above variables are updated for every time
-step. When set to false, the engraver stays in the current measure
-indefinitely.
-@end table
-
-Timing can be changed by setting any of these variables explicitly.
-In the next example, the 4/4 time signature is printed, but
-@code{measureLength} is set to 5/4. After a while, the measure is
-shortened by 1/8, by setting @code{measurePosition} to 7/8 at 2/4
-in the measure, so the next bar line will fall at 2/4 + 3/8. The
-3/8 arises because 5/4 normally has 10/8, but we have manually
-set the measure position to be 7/8 and 10/8 - 7/8 = 3/8.
-
-@lilypond[quote,raggedright,verbatim,relative,fragment]
-\set Score.measureLength = #(ly:make-moment 5 4)
-c1 c4
-c1 c4
-c4 c4
-\set Score.measurePosition = #(ly:make-moment 7 8)
-b8 b b
-c4 c1
-@end lilypond
-
-
-
-@node Preparing parts
-@section Preparing parts
-
-This section describes various notation that are useful for preparing
-individual parts.
-
-@menu
-* Metronome marks::
-* Rehearsal marks::
-* Bar numbers::
-* Instrument names::
-* Instrument transpositions::
-* Different editions from one source::
-@end menu
-
-
@node Metronome marks
@subsection Metronome marks
\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,raggedright,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{MetronomeChangeEvent}.
+Program reference: @internalsref{MetronomeMark}.
+
@refbugs
@node Rehearsal marks
@subsection Rehearsal marks
+
@cindex Rehearsal marks
-@cindex mark
@cindex @code{\mark}
To print a rehearsal mark, use the @code{\mark} command
@noindent
(The letter@tie{}`I' is skipped in accordance with engraving traditions.)
-@c umm, is the manual the right place for feature requests? :) -gp
-@c FIXME - should make that tunable.
The mark is incremented automatically if you use @code{\mark
\default}, but you can also use an integer argument to set the mark
These can be used as inspiration for other formatting functions.
-@cindex coda on bar line
-@cindex segno on bar line
-@cindex fermata on bar line
-@cindex bar lines, symbols on
-
-The @code{\mark} command can also be used to put signs like coda,
-segno, and fermata on a bar line. Use @code{\markup} to
-access the appropriate symbol
-
-@lilypond[fragment,quote,raggedright,verbatim,relative=2]
-c1 \mark \markup { \musicglyph #"scripts.ufermata" }
-c1
-@end lilypond
-
-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.
-To print the mark at the end of the current line, use
-
-@example
-\override Score.RehearsalMark
- #'break-visibility = #begin-of-line-invisible
-@end example
-
-@cindex fermatas
-@cindex coda
-@cindex segno
-@cindex bar lines, putting symbols on
-
@seealso
-Program reference: @internalsref{MarkEvent}, @internalsref{RehearsalMark}.
+Program reference: @internalsref{RehearsalMark}.
Init files: @file{scm/@/translation@/-functions@/.scm} contains the
definition of @code{format-mark-numbers} and
@node Bar numbers
@subsection Bar numbers
-
@cindex Bar numbers
@cindex measure numbers
@cindex @code{currentBarNumber}
}
@end lilypond
+
@seealso
Program reference: @internalsref{BarNumber}.
@inputfileref{input/@/test,bar@/-number@/-every@/-five@/-reset@/.ly},
and @inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}.
+
@refbugs
Bar numbers can collide with the @internalsref{StaffGroup} bracket, if
@node Instrument transpositions
@subsection Instrument transpositions
+
@cindex transposition, MIDI
@cindex transposition, instrument
@end example
+@node Ottava brackets
+@subsection Ottava brackets
+
+`Ottava' brackets introduce an extra transposition of an octave for
+the staff. They are created by invoking the function
+@code{set-octavation}
+
+@cindex ottava
+@cindex 15ma
+@cindex octavation
+
+@lilypond[quote,raggedright,verbatim,fragment]
+\relative c''' {
+ a2 b
+ #(set-octavation 1)
+ a b
+ #(set-octavation 0)
+ a b
+}
+@end lilypond
+
+The @code{set-octavation} function also takes -1 (for 8va bassa) and 2
+(for 15ma) as arguments. Internally the function sets the properties
+@code{ottavation} (e.g., to @code{"8va"}) and
+@code{centralCPosition}. For overriding the text of the bracket, set
+@code{ottavation} after invoking @code{set-octavation}, i.e.,
+
+@lilypond[quote,raggedright,verbatim]
+{
+ #(set-octavation 1)
+ \set Staff.ottavation = #"8"
+ c'''
+}
+@end lilypond
+
+
+@seealso
+
+Program reference: @internalsref{OttavaBracket}.
+
+Examples: @inputfileref{input/@/regression,ottava@/.ly},
+@inputfileref{input/@/regression,ottava@/-broken@/.ly}.
+
+
+@refbugs
+
+@code{set-octavation} will get confused when clef changes happen
+during an octavation bracket.
+
+
@node Different editions from one source
@subsection Different editions from one source
+@cindex @code{\tag}
@cindex tag
+
The @code{\tag} command marks music expressions with a name. These
tagged expressions can be filtered out later. With this mechanism it
is possible to make different versions of the same music source.
@lilypondfile[raggedright,quote]{tag-filter.ly}
-
The argument of the @code{\tag} command should be a symbol, or a list
of symbols, for example,
@example
@end example
-
@seealso
Examples: @inputfileref{input/@/regression,tag@/-filter@/.ly}.
+
@refbugs
Multiple rests are not merged if you create the score with both tagged
sections.
+
@node Orchestral music
@section Orchestral music
@seealso
-Program reference: @internalsref{PartCombineMusic},
-@internalsref{SoloOneEvent}, and
-@internalsref{SoloTwoEvent}, and
-@internalsref{UnisonoEvent}.
+Program reference: @internalsref{PartCombineMusic}.
@refbugs
differently named @internalsref{Voice} contexts, the events in those
will be ignored.
+
@node Hiding staves
@subsection Hiding staves
@cindex Hiding staves
In orchestral scores, staff lines that only have rests are usually
-removed. This saves some space. This style is called `French Score'.
+removed; this saves some space. This style is called `French Score'.
For @internalsref{Lyrics},
@internalsref{ChordNames} and @internalsref{FiguredBass}, this is
switched on by default. When the lines of these contexts turn out
@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 false in
+removed from the first system too, set @code{remove-first} to true in
@internalsref{RemoveEmptyVerticalGroup}.
+@example
+\override Score.RemoveEmptyVerticalGroup #'remove-first = ##t
+@end example
+
+To remove other types of contexts, use @code{\AncientRemoveEmptyStaffContext}
+or @code{\RemoveEmptyRhythmicStaffContext}.
+
Another application is making ossia sections, i.e., alternative
melodies on a separate piece of staff, with help of a Frenched
staff. See @inputfileref{input/@/test,ossia@/.ly} for an example.
-
-
@node Quoting other voices
@subsection Quoting other voices
@menu
* Polymetric notation::
+* Time administration::
* Clusters::
* Special fermatas::
+* Special noteheads::
* Feathered beams::
* Improvisation::
@end menu
+
@node Polymetric notation
@subsection Polymetric notation
each staff but replacing it manually using
@code{timeSignatureFraction} to the desired fraction. Then the printed
durations in each staff are scaled to the common time signature.
-The latter is done with @code{\compressmusic}, which is similar to
+The latter is done with @code{\compressMusic}, which is similar to
@code{\times}, but does not create a tuplet bracket.
\new Staff {
\time 3/4
\set Staff.timeSignatureFraction = #'(9 . 8)
- \compressmusic #'(2 . 3)
+ \compressMusic #'(2 . 3)
\repeat unfold 6 { c8[ c c] }
}
\new Staff {
\time 3/4
\set Staff.timeSignatureFraction = #'(10 . 8)
- \compressmusic #'(3 . 5) {
+ \compressMusic #'(3 . 5) {
\repeat unfold 2 { c8[ c c] }
\repeat unfold 2 { c8[ c] }
| c4. c4. \times 2/3 { c8 c c } c4
aligned vertically, but bar lines distort the regular spacing.
+@node Time administration
+@subsection Time administration
+
+@cindex Time administration
+
+Time is administered by the @internalsref{Time_signature_engraver},
+which usually lives in the @internalsref{Score} context. The
+bookkeeping deals with the following variables
+
+@table @code
+@item currentBarNumber
+The measure number.
+
+@item measureLength
+The length of the measures in the current time signature. For a 4/4
+time this is@tie{}1, and for 6/8 it is 3/4.
+
+@item measurePosition
+The point within the measure where we currently are. This quantity
+is reset to@tie{}0 whenever it exceeds @code{measureLength}. When that
+happens, @code{currentBarNumber} is incremented.
+
+@item timing
+If set to true, the above variables are updated for every time
+step. When set to false, the engraver stays in the current measure
+indefinitely.
+@end table
+
+Timing can be changed by setting any of these variables explicitly.
+In the next example, the 4/4 time signature is printed, but
+@code{measureLength} is set to 5/4. After a while, the measure is
+shortened by 1/8, by setting @code{measurePosition} to 7/8 at 2/4
+in the measure, so the next bar line will fall at 2/4 + 3/8. The
+3/8 arises because 5/4 normally has 10/8, but we have manually
+set the measure position to be 7/8 and 10/8 - 7/8 = 3/8.
+
+@lilypond[quote,raggedright,verbatim,relative,fragment]
+\set Score.measureLength = #(ly:make-moment 5 4)
+c1 c4
+c1 c4
+c4 c4
+\set Score.measurePosition = #(ly:make-moment 7 8)
+b8 b b
+c4 c1
+@end lilypond
+
+
@node Clusters
@subsection Clusters
Program reference: @internalsref{ClusterSpanner},
@internalsref{ClusterSpannerBeacon},
-@internalsref{Cluster_spanner_engraver}, and
-@internalsref{ClusterNoteEvent}.
+@internalsref{Cluster_spanner_engraver}.
Examples: @inputfileref{input/@/regression,cluster@/.ly}.
See @ref{Articulations} for general instructions how to apply scripts
such as fermatas to notes.
+
+@node Special noteheads
+@subsection Special noteheads
+
+Different noteheads are used by various instruments for various
+meanings -- crosses are used for ``parlato'' with vocalists, stopped
+notes on guitar; diamonds are used for harmonics on string instruments,
+etc. There is a shorthand (@code{\harmonic}) for diamond shapes; the
+other notehead styles are produced by tweaking the property
+
+@lilypond[raggedright,relative=1,fragment,verbatim,quote]
+c4 d
+\override NoteHead #'style = #'cross
+e f
+\revert NoteHead #'style
+e d <c f\harmonic> <d a'\harmonic>
+@end lilypond
+
+@noindent
+To see all notehead styles, please see
+@inputfileref{input/@/regression,note@/-head@/-style@/.ly}.
+
+
+@seealso
+
+Program reference: @internalsref{NoteHead}.
+
+@node Pitched trills
+@subsection Pitched trills
+
+Trills that should be executed on an explicitly specified pitch can be
+typeset with the command @code{pitchedTrill},
+
+@lilypond[raggedright,verbatim]
+ \pitchedTrill c'4\startTrillSpan fis
+ f'\stopTrillSpan
+@end lilypond
+
+The first argument is the main note. The absolute pitch of the second
+is printed as a stemless note head in parentheses.
+
+@refbugs
+
+Relative octave mode ignores the octave of the second argument of
+@code{\pitchedTrill}.
+
@node Feathered beams
@subsection Feathered beams
forcing two beams to overlap. Here is an example,
@c don't change relative setting witout changing positions!
-@lilypond[raggedright,relative=1,fragment,verbatim]
+@lilypond[raggedright,relative=1,fragment,verbatim,quote]
\new Staff <<
\new Voice
{
* Shaped note heads ::
* Easy Notation note heads::
* Analysis brackets::
+* Coloring objects::
@end menu
@node Balloon help
@seealso
-Program reference: @internalsref{HorizontalBracket},
-@internalsref{NoteGroupingEvent}.
+Program reference: @internalsref{HorizontalBracket}.
Examples: @inputfileref{input/@/regression,note@/-group@/-bracket@/.ly}.
@end ignore
+@node Coloring objects
+@subsection Coloring objects
+Individual objects may be assigned colors. You may use the
+color names listed in the @ref{List of colors}.
-@ignore
+@lilypond[quote,raggedright,verbatim,fragment,relative=1]
+\override NoteHead #'color = #red
+c4 c
+\override NoteHead #'color = #(x11-color 'LimeGreen)
+d
+\override Stem #'color = #blue
+e
+@end lilypond
-FIXME: We don't need this section. It will be moved into LSR as soon
-as the safe mode stuff is worked out.
+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
-@n ode Controlling formatting of prefatory matter
-@s ubsection Controlling formatting of prefatory matter
+@example
+\override Beam #'color = #(x11-color 'MediumTurquoise)
+@end example
-@c This section will be moved to somewhere else soon. -gp
-This example demonstrates how to place prefatory matter
-(such as the clef and key signature) at the end of a line.
+or a string
-@lilypond[quote,verbatim]
-\transpose c c' {
- \override Staff.Clef
- #'break-visibility = #end-of-line-visible
- \override Staff.KeySignature
- #'break-visibility = #end-of-line-visible
- \set Staff.explicitClefVisibility = #end-of-line-visible
- \set Staff.explicitKeySignatureVisibility = #end-of-line-visible
-
- % We want the time sig to take space, otherwise there is not
- % enough white at the start of the line.
-
- \override Staff.TimeSignature #'transparent = ##t
- \set Score.defaultBarType = #"empty"
-
- c1 d e f g a b c
- \key d \major
- \break
-
- % see above.
- \time 4/4
-
- d e fis g a b cis d
- \key g \major
- \break
- \time 4/4
+@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,raggedright,verbatim]
+{
+ \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
+ \set Staff.instrument = \markup {
+ \with-color #(x11-color 'navy) "Clarinet"
+ }
+ \time 2/4
+ gis''8 a''
+ \override Beam #'color = #(x11-color "medium turquoise")
+ gis'' a''
+ \override NoteHead #'color = #(x11-color "LimeGreen")
+ gis'' a''
+ \override Stem #'color = #(x11-color 'Boggle)
+ gis'' a''
}
@end lilypond
-@end ignore
+
+@seealso
+
+Appendix: @ref{List of colors}.
+@refbugs
+Not all x11 colors are distinguishable in a web browser. For web use
+normal colors are recommended.
+
+An x11 color is not necessarily exactly the same shade as a similarly
+named normal color.
+
@node Automatic notation
@section Automatic notation
@menu
* Automatic accidentals::
* Setting automatic beam behavior::
-* Beam formatting::
@end menu
@node Automatic accidentals
In normal time signatures, automatic beams can start on any note but can
only end in a few positions within the measure: beams can end on a beat,
or at durations specified by the properties in
-@code{autoBeamSettings}. The defaults for @code{autoBeamSettings}
-are defined in @file{scm/@/auto@/-beam@/.scm}.
+@code{autoBeamSettings}. The properties in @code{autoBeamSettings}
+consist of a list of rules for where beams can begin and end. The
+default @code{autoBeamSettings} rules are defined in
+@file{scm/@/auto@/-beam@/.scm}.
+
+In order to add a rule to the list, use
+@example
+#(override-auto-beam-setting '(be p q n m) a b [context])
+@end example
+
+@itemize @bullet
+
+@item @code{be} is either "begin" or "end".
+
+@item @code{b/q} is the duration of the note for which you want
+to add a rule. A beam is considered to have the duration of its
+shortest note. Set @code{p} and @code{q} to @code{'*'} to
+have this apply to any beam.
+
+@item @code{n/m} is the position in the time signature to which
+this rule should apply. Set @code{n} and @code{m} to @code{'*'}
+to have this apply in any time signature.
+
+@item @code{a/b} is the position in the bar at which the beam should end.
+
+@item @code{context} is optional, and it specifies the context at which
+the change should be made. The default is @code{'Voice}.
+@code{#(score-override-auto-beam-setting '(A B C D) E F)} is equivalent to
+@code{#(override-auto-beam-setting '(A B C D) E F 'Score)}.
+
+@end itemize
+
+For example, if automatic beams should always end on the first quarter
+node, use
+
+@example
+#(override-auto-beam-setting '(end * * * *) 1 4)
+@end example
+
+You can force the beam settings to only take effect on beams whose shortest
+note is a certain duration
+
+@lilypond[quote,fragment,raggedright,verbatim,relative=2]
+\time 2/4
+#(override-auto-beam-setting '(end 1 16 * *) 1 16)
+a16 a a a a a a a |
+a32 a a a a16 a a a a a |
+#(override-auto-beam-setting '(end 1 32 * *) 1 16)
+a32 a a a a16 a a a a a |
+@end lilypond
+
+You can force the beam settings to only take effect in certain time
+signatures
+
+@lilypond[quote,fragment,raggedright,verbatim,relative=2]
+\time 5/8
+#(override-auto-beam-setting '(end * * 5 8) 2 8)
+c8 c d d d
+\time 4/4
+e8 e f f e e d d
+\time 5/8
+c8 c d d d
+@end lilypond
+
+You can also remove a previously set beam-ending rule by using
-The value of @code{autoBeamSettings} is changed with three functions,
@example
-#(override-auto-beam-setting
- '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b}
- [@var{context}])
-#(score-override-auto-beam-setting
- '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b})
-#(revert-auto-beam-setting '(@var{be} @var{p} @var{q} @var{n} @var{m})
- [@var{context}])
+#(revert-auto-beam-setting '(be p q n m) a b [context])
@end example
-Here, @var{be} is the symbol @code{begin} or @code{end}, and
-@var{context} is an optional context (default: @code{'Voice}). It
-determines whether the rule applies to begin or end-points. The
-quantity @var{p}/@var{q} refers to the length of the beamed notes (and
-`@code{* *}' designates notes of any length), @var{n}/@var{M} refers
-to a time signature (wildcards `@code{* *}' may be entered to
-designate all time signatures), @var{a}/@var{b} is a duration. By
-default, this command changes settings for the current voice. It is
-also possible to adjust settings at higher contexts, by adding a
-@var{context} argument. @code{score-override-auto-beam-setting} is
-equal to @code{override-auto-beam-setting} with the argument
-@var{context} set to @code{'Score}.
-
-For example, if automatic beams should end on every quarter note, use
-the following
+
+@noindent
+be, p, q, n, m, a, b and context are the same as above. Note that the
+default rules are specified in @file{scm/@/auto@/-beam@/.scm},
+so you can revert rules that you did not explicitly create.
+
+@lilypond[quote,fragment,raggedright,verbatim,relative=2]
+\time 4/4
+a16 a a a a a a a a a a a a a a a
+#(revert-auto-beam-setting '(end 1 16 4 4) 1 4)
+a16 a a a a a a a a a a a a a a a
+@end lilypond
+
+The rule in a revert-auto-beam-setting statement must exactly match the
+original rule. That is, no wildcard expansion is taken into account.
+
+@lilypond[quote,fragment,raggedright,verbatim,relative=2]
+\time 1/4
+#(override-auto-beam-setting '(end 1 16 1 4) 1 8)
+a16 a a a
+#(revert-auto-beam-setting '(end 1 16 * *) 1 8) % this won't revert it!
+a a a a
+#(revert-auto-beam-setting '(end 1 16 1 4) 1 8) % this will
+a a a a
+@end lilypond
+
+
+
+@c TODO: old material -- not covered by above stuff, I think.
+If automatic beams should end on every quarter in 5/4 time, specify
+all endings
@example
#(override-auto-beam-setting '(end * * * *) 1 4 'Staff)
+#(override-auto-beam-setting '(end * * * *) 1 2 'Staff)
+#(override-auto-beam-setting '(end * * * *) 3 4 'Staff)
+#(override-auto-beam-setting '(end * * * *) 5 4 'Staff)
+@dots{}
@end example
-Since the duration of a quarter note is 1/4 of a whole note, it is
-entered as @code{(ly:make-moment 1 4)}.
The same syntax can be used to specify beam starting points. In this
example, automatic beams can only end on a dotted quarter note
@example
#(override-auto-beam-setting '(end * * * *) 3 8)
+#(override-auto-beam-setting '(end * * * *) 1 2)
+#(override-auto-beam-setting '(end * * * *) 7 8)
@end example
In 4/4 time signature, this means that automatic beams could end only on
3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
3/8, has passed within the measure).
-Rules can also be restricted to specific time signatures. A rule that
-should only be applied in @var{N}/@var{M} time signature is formed by
-replacing the second asterisks by @var{N} and @var{M}. For example, a
-rule for 6/8 time exclusively looks like
-@example
-#(override-auto-beam-setting '(begin * * 6 8) @dots{})
-@end example
-
-If a rule should be to applied only to certain types of beams, use the
-first pair of asterisks. Beams are classified according to the
-shortest note they contain. For a beam ending rule that only applies
-to beams with 32nd notes (and no shorter notes), use @code{(end 1 32 *
-*)}.
-
@cindex automatic beam generation
@cindex autobeam
@cindex @code{autoBeaming}
@cindex lyrics
If beams are used to indicate melismata in songs, then automatic
-beaming should be switched off. This is done by setting
-@code{autoBeaming} to @code{#f}.
+beaming should be switched off with @code{\autoBeamOff}.
+
@refcommands
>>}. If a polyphonic voice ends while an automatic beam is still
accepting notes, it is not typeset.
-The rules for ending a beam depend on the shortest note in a beam.
-So, while it is possible to have different ending rules for eight
-beams and sixteenth beams, a beam that contains both eight and
-sixteenth notes will use the rules for the sixteenth beam.
-
-In the example below, the autobeamer makes eighth beams and sixteenth
-end at three eighths. The third beam can only be corrected by
-specifying manual beaming.
-
-@lilypond[quote,raggedright,fragment,relative=1]
-#(override-auto-beam-setting '(end * * * *) 3 8)
-% rather show case where it goes wrong
-%\time 12/8 c'8 c c c16 c c c c c c[ c c c] c8[ c] c4
-\time 12/8 c'8 c c c16 c c c c c c c c c c8 c c4
-@end lilypond
-It is not possible to specify beaming parameters that act differently in
-different parts of a measure. This means that it is not possible to use
-automatic beaming in irregular meters such as @code{5/8}.
-
-
-@node Beam formatting
-@subsection Beam formatting
-
-When a beam falls in the middle of the staff, the beams point normally
-down. However, this behaviour can be altered with the
-@code{neutral-direction} property.
-
-@lilypond[quote,raggedright,relative=2,fragment,verbatim]
-{
- b8[ b]
- \override Beam #'neutral-direction = #-1
- b[ b]
- \override Beam #'neutral-direction = #1
- b[ b]
-}
-@end lilypond
projects / lilypond.git / blobdiff