-@c -*- coding: latin-1; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond.tely
@c A menu is needed before every deeper *section nesting of @node's; run
@c M-x texinfo-all-menus-update
@c to automatically fill in these menus before saving changes
+
@node Advanced notation
@chapter Advanced notation
This chapter deals with rarely-used and advanced notation.
@menu
-* Accidentals::
-* Expressive stuff::
+* Text::
+* Preparing parts::
* Orchestral music::
* Contemporary notation::
* Educational use::
+* Automatic notation::
@end menu
-@node Accidentals
-@section Accidentals
-
-This section describes how to change the way that accidentals are
-inserted automatically before notes.
-
-@menu
-* Automatic accidentals::
-@end menu
-
-@node Automatic accidentals
-@subsection Automatic accidentals
-@cindex Automatic accidentals
-
-Common rules for typesetting accidentals have been placed in a
-function. This function is called as follows
-
-@cindex @code{set-accidental-style}
-@example
-#(set-accidental-style 'STYLE #('CONTEXT#))
-@end example
-
-The function can take two arguments: the name of the accidental style,
-and an optional argument that denotes the context that should be
-changed. If no context name is supplied, @code{Staff} is the default,
-but you may wish to apply the accidental style to a single @code{Voice}
-instead.
-
-The following accidental styles are supported
-@table @code
-@item default
-This is the default typesetting behavior. It corresponds
-to 18th century common practice: Accidentals are
-remembered to the end of the measure in which they occur and
-only on their own octave.
-
-@item voice
-The normal behavior is to remember the accidentals on
-Staff-level. This variable, however, typesets accidentals
-individually for each voice. Apart from that, the rule is similar to
-@code{default}.
-
-As a result, accidentals from one voice do not get canceled in other
-voices, which is often an unwanted result
-
-@lilypond[quote,raggedright,relative=1,fragment,verbatim]
-\context Staff <<
- #(set-accidental-style 'voice)
- <<
- { es g } \\
- { c, e }
->> >>
-@end lilypond
-
-The @code{voice} option should be used if the voices
-are to be read solely by individual musicians. If the staff is to be
-used by one musician (e.g., a conductor) then
-@code{modern} or @code{modern-cautionary}
-should be used instead.
-
-@item modern
-@cindex @code{modern} style accidentals
-This rule corresponds to the common practice in the 20th century. This rule
-prints the same accidentals as @code{default}, but temporary
-accidentals also are canceled in other octaves. Furthermore,
-in the same octave, they also get canceled in the following
-measure
-
-@lilypond[quote,raggedright,fragment,verbatim]
-#(set-accidental-style 'modern)
-cis' c'' cis'2 | c'' c'
-@end lilypond
-
-@item @code{modern-cautionary}
-@cindex @code{modern-cautionary}
-This rule is similar to @code{modern}, but the ``extra'' accidentals
-(the ones not typeset by @code{default}) are typeset as cautionary
-accidentals. They are printed in reduced size or with parentheses
-@lilypond[quote,raggedright,fragment,verbatim]
-#(set-accidental-style 'modern-cautionary)
-cis' c'' cis'2 | c'' c'
-@end lilypond
-
-@cindex @code{modern-voice}
-@item modern-voice
-This rule is used for multivoice accidentals to be read both by musicians
-playing one voice and musicians playing all voices. Accidentals are
-typeset for each voice, but they @emph{are} canceled across voices in
-the same @internalsref{Staff}.
-
-@cindex @code{modern-voice-cautionary}
-@item modern-voice-cautionary
-This rule is the same as @code{modern-voice}, but with the extra
-accidentals (the ones not typeset by @code{voice}) typeset
-as cautionaries. Even though all accidentals typeset by
-@code{default} @emph{are} typeset by this variable,
-some of them are typeset as cautionaries.
-
-@item piano
-@cindex @code{piano} accidentals
-This rule reflects 20th century practice for piano notation. Very similar to
-@code{modern} but accidentals also get canceled
-across the staves in the same @internalsref{GrandStaff} or
-@internalsref{PianoStaff}.
-
-@item piano-cautionary
-@cindex @code{#(set-accidental-style 'piano-cautionary)}
-Same as @code{#(set-accidental-style 'piano)} but with the extra
-accidentals typeset as cautionaries.
-
-@item no-reset
-@cindex @code{no-reset} accidental style
-This is the same as @code{default} but with accidentals lasting
-``forever'' and not only until the next measure
-@lilypond[quote,raggedright,fragment,verbatim,relative=1]
-#(set-accidental-style 'no-reset)
-c1 cis cis c
-@end lilypond
-
-@item forget
-This is sort of the opposite of @code{no-reset}: Accidentals
-are not remembered at all---and hence all accidentals are
-typeset relative to the key signature, regardless of what was
-before in the music
-
-@lilypond[quote,raggedright,fragment,verbatim,relative=1]
-#(set-accidental-style 'forget)
-\key d\major c4 c cis cis d d dis dis
-@end lilypond
-@end table
-
-
-@seealso
-
-Program reference: @internalsref{Accidental_engraver},
-@internalsref{Accidental}, and @internalsref{AccidentalPlacement}.
-
-
-@refbugs
-
-Simultaneous notes are considered to be entered in sequential
-mode. This means that in a chord the accidentals are typeset as if the
-notes in the chord happened once at a time - in the order in which
-they appear in the input file.
-
-This is a problem when accidentals in a chord depend on each other,
-which does not happen for the default accidental style. The problem
-can be solved by manually inserting @code{!} and @code{?} for the
-problematic notes.
-
-@node Expressive stuff
-@section Expressive stuff
+@node Text
+@section Text
-Expressive marks help musicians to bring more to the music than simple
-notes and rhythms.
+This section explains how to include text (with various formatting) in
+your scores.
@menu
-* Metronome marks::
* Text scripts::
* Text spanners::
-* Analysis brackets::
-* Articulations::
+* Text marks::
+* Text markup::
+* Text encoding::
+* Nested scores::
+* Overview of text markup commands::
+* Font selection::
+* New dynamic marks::
@end menu
-@node Metronome marks
-@subsection Metronome marks
-
-@cindex Tempo
-@cindex beats per minute
-@cindex metronome marking
-
-Metronome settings can be entered as follows
-@example
-\tempo @var{duration} = @var{per-minute}
-@end example
-
-In the MIDI output, they are interpreted as a tempo change. In the
-layout output, a metronome marking is printed
-@cindex @code{\tempo}
-@lilypond[quote,raggedright,verbatim,fragment]
-\tempo 8.=120 c''1
-@end lilypond
-
-@seealso
-
-Program reference: @internalsref{MetronomeChangeEvent}.
-
-@refbugs
-
-Collisions are not checked. If you have notes above the top line of
-the staff (or notes with articulations, slurs, text, etc), then the
-metronome marking may be printed on top of musical symbols. If this
-occurs, increase the padding of the metronome mark to place it
-further away from the staff.
-
-@example
-\override Score.MetronomeMark #'padding = #2.5
-@end example
-
-
@node 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
+\break
+\textSpannerUp
+\override TextSpanner #'edge-text = #(cons (markup #:italic "rit" ) "")
+c2\startTextSpan b c\stopTextSpan a
@end lilypond
+@refcommands
+
+@cindex textSpannerUp
+@code{textSpannerUp},
+@cindex textSpannerDown
+@code{textSpannerDown},
+@cindex textSpannerNeutral
+@code{textSpannerNeutral}.
+
@seealso
-Internals @internalsref{TextSpanEvent},
-@internalsref{TextSpanner}.
+Program reference: @internalsref{TextSpanner}.
Examples: @inputfileref{input/@/regression,text@/-spanner@/.ly}.
-@node Analysis brackets
-@subsection Analysis brackets
-@cindex brackets
-@cindex phrasing brackets
-@cindex musicological analysis
-@cindex note grouping bracket
+@node Text marks
+@subsection Text marks
-Brackets are used in musical analysis to indicate structure in musical
-pieces. LilyPond supports a simple form of nested horizontal
-brackets. To use this, add the @internalsref{Horizontal_bracket_engraver}
-to @internalsref{Staff} context. A bracket is started with
-@code{\startGroup} and closed with @code{\stopGroup}
+@cindex coda on bar line
+@cindex segno on bar line
+@cindex fermata on bar line
+@cindex bar lines, symbols on
+@cindex @code{\mark}
-@lilypond[quote,raggedright,verbatim]
-\score {
- \relative c'' {
- c4\startGroup\startGroup
- c4\stopGroup
- c4\startGroup
- c4\stopGroup\stopGroup
- }
- \layout {
- \context {
- \Staff \consists "Horizontal_bracket_engraver"
-}}}
+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
-@seealso
+@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.
-Program reference: @internalsref{HorizontalBracket},
-@internalsref{NoteGroupingEvent}.
-Examples: @inputfileref{input/@/regression,note@/-group@/-bracket@/.ly}.
+@commonprop
+To print the mark at the end of the current line, use
-@node Articulations
-@subsection Articulations
-@cindex Articulations
+@example
+\override Score.RehearsalMark
+ #'break-visibility = #begin-of-line-invisible
+@end example
-@cindex articulations
-@cindex scripts
-@cindex ornaments
+@code{\mark} is often useful for adding text to the end of bar. In
+such cases, changing the @code{#'self-alignment} is very useful
-A variety of symbols can appear above and below notes to indicate
-different characteristics of the performance. They are added to a note
-by adding a dash and the character signifying the
-articulation. They are demonstrated here
+@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
-@lilypondfile[quote,raggedright]{script-abbreviations.ly}
-The meanings of these shorthands can be changed. See
-@file{ly/@/script@/-init@/.ly} for examples.
+@seealso
+Program reference: @internalsref{RehearsalMark}.
-The script is automatically placed, but the direction can be forced as
-well. Like other pieces of LilyPond code, @code{_} will place them
-below the staff, and @code{^} will place them above.
+@node Text markup
+@subsection Text markup
-@lilypond[quote,raggedright,fragment,verbatim]
-c''4^^ c''4_^
-@end lilypond
+@cindex markup
+@cindex text markup
+@cindex markup text
+@cindex typeset text
-Other symbols can be added using the syntax
-@var{note}@code{\}@var{name}. Again, they
-can be forced up or down using @code{^} and @code{_},
-e.g.,
+Use @code{\markup} to typeset text. Commands are entered with the
+backslash @code{\}.
-@lilypond[quote,raggedright,verbatim,fragment,relative=2]
-c\fermata c^\fermata c_\fermata
+@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
-@cindex accent
-@cindex marcato
-@cindex staccatissimo
-@cindex espressivo
-@cindex fermata
-@cindex stopped
-@cindex staccato
-@cindex portato
-@cindex tenuto
-@cindex upbow
-@cindex downbow
-@cindex foot marks
-@cindex organ pedal marks
-@cindex turn
-@cindex open
-@cindex flageolet
-@cindex reverseturn
-@cindex trill
-@cindex prall
-@cindex mordent
-@cindex prallprall
-@cindex prallmordent
-@cindex prall, up
-@cindex prall, down
-@cindex mordent
-@cindex thumb marking
-@cindex segno
-@cindex coda
-@cindex varcoda
+@lilypond[quote,verbatim]
+\header{ title = \markup{ \bold { foo \italic { bar! } } } }
+\score{
+ \relative c'' {
+ \override Score.RehearsalMark
+ #'break-visibility = #begin-of-line-invisible
+ \override Score.RehearsalMark #'self-alignment-X = #right
+
+ \set Staff.instrument = \markup{ \column{ Alto solo } }
+ c2^\markup{ don't be \flat }
+ \override TextSpanner #'edge-text = #(cons (markup #:italic "rit" ) "")
+ b2\startTextSpan
+ a2\mark \markup{ \large \bold Fine }
+ r2\stopTextSpan
+ \bar "||"
+ }
+ \addlyrics { bar, foo \markup{ \italic bar! } }
+}
+@end lilypond
-Here is a chart showing all scripts available,
+Text can also be placed on its own, away from any @code{\score}
+block. This is primarily used in a @code{\book} (see
+@ref{Multiple movements}).
-@lilypondfile[raggedright,quote]{script-chart.ly}
+@lilypond[quote,raggedright,verbatim]
+\markup{ Here is some text. }
+@end lilypond
+@cindex font switching
-The vertical ordering of scripts is controlled with the
-@code{script-priority} property. The lower this number, the closer it
-will be put to the note. In this example, the
-@internalsref{TextScript} (the sharp symbol) first has the lowest
-priority, so it is put lowest in the first example. In the second, the
-prall trill (the @internalsref{Script}) has the lowest, so it is on the
-inside. When two objects have the same priority, the order in which
-they are entered decides which one comes first.
+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
-@lilypond[verbatim,relative=3,raggedright,fragment,quote]
-\once \override TextScript #'script-priority = #-100
-a4^\prall^\markup { \sharp }
+@noindent
+For clarity, you can also do this for single arguments, e.g.,
-\once \override Script #'script-priority = #-100
-a4^\prall^\markup { \sharp }
-@end lilypond
+@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
-@seealso
+@example
+\center-align @{ @{ a b @} @{ c d @} @}
+@end example
-Program reference: @internalsref{ScriptEvent}, and @internalsref{Script}.
+@noindent
-@refbugs
+is equivalent to
-These signs appear in the printed output but have no effect on the
-MIDI rendering of the music.
+@example
+\center-align @{ a b c d @}
+@end example
+@noindent
+To keep lists of words distinct, please use quotes @code{"} or
+the @code{\line} command
+@lilypond[quote,verbatim,fragment,relative=1]
+\fatText
+c4^\markup{ \center-align { on three lines } }
+c4^\markup{ \center-align { "all one line" } }
+c4^\markup{ \center-align { { on three lines } } }
+c4^\markup{ \center-align { \line { on one line } } }
+@end lilypond
+Markups can be stored in variables and these variables
+may be attached to notes, like
+@example
+allegro = \markup @{ \bold \large @{ Allegro @} @}
+ @{ a^\allegro b c d @}
+@end example
+Some objects have alignment procedures of their own, which cancel out
+any effects of alignments applied to their markup arguments as a
+whole. For example, the @internalsref{RehearsalMark} is horizontally
+centered, so using @code{\mark \markup @{ \left-align .. @}} has no
+effect.
+
+In addition, vertical placement is performed after creating the
+text markup object. If you wish to move an entire piece of markup,
+you need to use the #'padding property or create an "anchor" point
+inside the markup (generally with @code{\hspace #0}).
+
+@lilypond[quote,verbatim,fragment,relative=1]
+\fatText
+c'4^\markup{ \raise #5 "not raised" }
+\once \override TextScript #'padding = #3
+c'4^\markup{ raised }
+c'4^\markup{ \hspace #0 \raise #1.5 raised }
+@end lilypond
+@seealso
-@node Orchestral music
-@section Orchestral music
+This manual: @ref{Overview of text markup commands}.
-@cindex Writing parts
+Program reference: @internalsref{TextScript}.
-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.
+Init files: @file{scm/@/new@/-markup@/.scm}.
+@refbugs
-@menu
-* Rehearsal marks::
-* Bar numbers::
-* Instrument names::
-* Instrument transpositions::
-* Multi measure rests::
-* Automatic part combining::
-* Hiding staves::
-* Different editions from one source::
-* Quoting other voices::
-* Formatting cue notes::
-@end menu
+Kerning or generation of ligatures is only done when the @TeX{}
+backend is used. In this case, LilyPond does not account for them so
+texts will be spaced slightly too wide.
+Syntax errors for markup mode are confusing.
+@node Text encoding
+@subsection Text encoding
-@node Rehearsal marks
-@subsection Rehearsal marks
-@cindex Rehearsal marks
-@cindex mark
-@cindex @code{\mark}
+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.
-To print a rehearsal mark, use the @code{\mark} command
+Depending on the fonts installed, the following fragment shows Hebrew
+and Cyrillic lyrics,
-@lilypond[quote,raggedright,fragment,verbatim,relative=2]
-c1 \mark \default
-c1 \mark \default
-c1 \mark #8
-c1 \mark \default
-c1 \mark \default
-@end lilypond
+@cindex Cyrillic
+@cindex Hebrew
+@cindex ASCII, non
-@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.
+@lilypondfile[fontload]{utf-8.ly}
-The mark is incremented automatically if you use @code{\mark
-\default}, but you can also use an integer argument to set the mark
-manually. The value to use is stored in the property
-@code{rehearsalMark}.
+The @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,
-The style is defined by the property @code{markFormatter}. It is a
-function taking the current mark (an integer) and the current context
-as argument. It should return a markup object. In the following
-example, @code{markFormatter} is set to a canned procedure. After a
-few measures, it is set to function that produces a boxed number.
+@example
+lilypond -b texstr input/les-nereides.ly
+latex les-nereides.texstr
+@end example
-@lilypond[fragment,quote,raggedright,verbatim,relative=2]
-\set Score.markFormatter = #format-mark-numbers
-c1 \mark \default
-c1 \mark \default
-\set Score.markFormatter = #format-mark-box-numbers
-c1 \mark \default
-c1 \mark \default
-c1
-@end lilypond
+The last command produces @file{les-nereides.textmetrics}, which is
+read when you execute
-The file @file{scm/@/translation@/-functions@/.scm} contains the definitions
-of @code{format-mark-numbers} (the default format), @code{format-mark-box-numbers},
-@code{format-mark-letters} and @code{format-mark-box-letters}.
-These can be used as inspiration for other formatting functions.
+@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.
-@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
+@seealso
-@lilypond[fragment,quote,raggedright,verbatim,relative=2]
-c1 \mark \markup { \musicglyph #"scripts.ufermata" }
-c1
-@end lilypond
+@inputfileref{input/regression,utf-8.ly}
-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
+@node Nested scores
+@subsection Nested scores
-@cindex fermatas
-@cindex coda
-@cindex segno
-@cindex bar lines, putting symbols on
+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.
-@seealso
+@lilypond[quote,verbatim,raggedright]
+\relative {
+ c4 d^\markup {
+ \score {
+ \relative { c4 d e f }
+ \layout { }
+ }
+ }
+ e f
+}
+@end lilypond
-Program reference: @internalsref{MarkEvent}, @internalsref{RehearsalMark}.
-Init files: @file{scm/@/translation@/-functions@/.scm} contains the
-definition of @code{format-mark-numbers} and
-@code{format-mark-letters}. They can be used as inspiration for other
-formatting functions.
+@node Overview of text markup commands
+@subsection Overview of text markup commands
-Examples: @inputfileref{input/@/regression,rehearsal@/-mark@/-letter@/.ly},
+The following commands can all be used inside @code{\markup @{ @}}.
-@inputfileref{input/@/regression,rehearsal@/-mark@/-number@/.ly}.
+@include markup-commands.tely
-@node Bar numbers
-@subsection Bar numbers
+@node Font selection
+@subsection Font selection
+@cindex font selection
+@cindex font magnification
+@cindex @code{font-interface}
-@cindex Bar numbers
-@cindex measure numbers
-@cindex @code{currentBarNumber}
+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.
-Bar numbers are printed by default at the start of the line. The
-number itself is stored in the @code{currentBarNumber} property, which
-is normally updated automatically for every measure.
-Bar numbers can be typeset at regular intervals instead of at the
-beginning of each line. This is illustrated in the following example,
-whose source is available as
-@inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}
+@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.
-@lilypondfile[raggedright,quote]{bar-number-regular-interval.ly}
+@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.
-Bar numbers can be typeset manually by tweaking the
-@code{markFormatter} property
+@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}.
-@lilypond[verbatim,raggedright,quote]
-\relative c' {
- \set Score.markFormatter
- = #(lambda (mark context)
- (make-bold-markup
- (make-box-markup
- (number->string (ly:context-property context
- 'currentBarNumber)))))
+@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}.
- c1 \bar "||" \mark \default c1 c1 \mark \default c1 \bar "|."
-}
-@end lilypond
+@end itemize
-Bar numbers can be manually changed by setting the
-@code{Staff.currentBarNumber} property
+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[verbatim,raggedright,quote]
-\relative c' {
- \repeat unfold 4 {c4 c c c} \break
- \set Score.currentBarNumber = #50
- \repeat unfold 4 {c4 c c c}
+@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
-@seealso
+@noindent
+Any font can be used, as long as it is available to Pango/FontConfig.
-Program reference: @internalsref{BarNumber}.
+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.
-Examples:
-@inputfileref{input/@/test,bar@/-number@/-every@/-five@/-reset@/.ly},
-and @inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}.
+@cindex font size
+@cindex font magnification
-@refbugs
-Bar numbers can collide with the @internalsref{StaffGroup} bracket, if
-there is one at the top. To solve this, the
-@code{padding} property of @internalsref{BarNumber} can be
-used to position the number correctly.
+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,
-@node Instrument names
-@subsection Instrument names
+@cindex font families, setting
+@cindex Pango
-In an orchestral score, instrument names are printed at the left side
-of the staves.
-This can be achieved by setting @internalsref{Staff}.@code{instrument}
-and @internalsref{Staff}.@code{instr}. This will print a string before
-the start of the staff. For the first staff, @code{instrument} is
-used, for the following ones, @code{instr} is used.
+@lilypond[verbatim]
+\paper {
+ myStaffSize = #20
+
+ #(define fonts
+ (make-pango-font-tree "Times New Roman"
+ "Nimbus Sans"
+ "Luxi Mono"
+ (/ myStaffSize 20)))
+}
-@lilypond[quote,verbatim,raggedright,relative=1,fragment]
-\set Staff.instrument = "Ploink "
-\set Staff.instr = "Plk "
-c1
-\break
-c''
+{
+ c'^\markup { roman: foo \sans bla \typewriter bar }
+}
@end lilypond
-You can also use markup texts to construct more complicated instrument
-names, for example
+@c we don't do Helvetica / Courier, since GS incorrectly loads
+@c Apple TTF fonts
-@lilypond[quote,fragment,verbatim,raggedright]
-\set Staff.instrument = \markup {
- \column { "Clarinetti"
- \line { "in B" \smaller \flat } } }
-c''1
-@end lilypond
-For longer instrument names, it may be useful to increase the
-@code{indent} setting in the @code{\layout} block.
@seealso
-Program reference: @internalsref{InstrumentName}.
-
-@refbugs
+Examples: @file{ly/@/font@/-family@/-override.ly}
-When you put a name on a grand staff or piano staff, the width of the
-brace is not taken into account. You must add extra spaces to the end of
-the name to avoid a collision.
-@node Instrument transpositions
-@subsection Instrument transpositions
+@node New dynamic marks
+@subsection New dynamic marks
-The key of a transposing instrument can also be specified. This
-applies to many wind instruments, for example, clarinets (B-flat, A, and
-E-flat), horn (F) and trumpet (B-flat, C, D, and E-flat).
+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.
-The transposition is entered after the keyword @code{\transposition}
+@cindex make-dynamic-script
-@example
-\transposition bes %% B-flat clarinet
-@end example
+@lilypond[quote,verbatim,raggedright]
+sfzp = #(make-dynamic-script "sfzp")
+\relative c' {
+ c4 c c\sfzp c
+}
+@end lilypond
-@noindent
-This command sets the property @code{instrumentTransposition}. The value of
-this property is used for MIDI output and quotations. It does not
-affect how notes are printed in the current staff. To change the printed
-output, see @ref{Transpose}.
+@cindex Dynamics, editorial
+@cindex Dynamics, parenthesis
-The pitch to use for @code{\transposition} should correspond to the
-transposition of the notes. For example, when entering a score in
-concert pitch, typically all voices are entered in C, so
-they should be entered as
+It is also possible to print dynamics in round parenthesis or square
+brackets. These are often used for adding editorial dynamics.
-@example
-clarinet = @{
- \transposition c'
- ...
-@}
-saxophone = @{
- \transposition c'
- ...
-@}
-@end example
+@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
-The command @code{\transposition} should be used when the music is
-entered from a (transposed) orchestral part. For example, in
-classical horn parts, the tuning of the instrument is often changed
-during a piece. When copying the notes from the part, use
-@code{\transposition}, e.g.,
-@example
-\transposition d'
-c'4^"in D"
-...
-\transposition g'
-c'4^"in G"
-...
-@end example
+@node Preparing parts
+@section Preparing parts
+This section describes various notation that are useful for preparing
+individual parts.
-@cindex transposition, MIDI
-@cindex transposition, instrument
+@menu
+* Multi measure rests::
+* Metronome marks::
+* Rehearsal marks::
+* Bar numbers::
+* Instrument names::
+* Instrument transpositions::
+* Ottava brackets::
+* Different editions from one source::
+@end menu
@node Multi measure rests
@subsection Multi measure rests
+
@cindex multi measure rests
+@cindex full measure rests
@cindex Rests, multi measure
-
+@cindex Rests, full measure
+@cindex whole rests for a full measure
@cindex @code{R}
-Multi-measure rests are entered using `@code{R}'. It is specifically
-meant for full bar rests and for entering parts: the rest can expand
-to fill a score with rests, or it can be printed as a single
+Rests for one full measure (or many bars) are entered using `@code{R}'. It
+is specifically meant for full bar rests and for entering parts: the rest
+can expand to fill a score with rests, or it can be printed as a single
multi-measure rest. This expansion is controlled by the property
@code{Score.skipBars}. If this is set to true, empty measures will not
be expanded, and the appropriate number is added automatically
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
R2.^\fermataMarkup
@end lilypond
+Warning! This text is created by @code{MultiMeasureRestText}, not
+@code{TextScript}.
+
+@lilypond[quote,raggedright,verbatim,fragment]
+\override TextScript #'padding = #5
+R1^"low"
+\override MultiMeasureRestText #'padding = #5
+R1^"high"
+@end lilypond
+
If you want to have text on the left end of a multi-measure rest,
attach the text to a zero-length skip note, i.e.,
@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
When @code{skipBars} is set, the result will look OK, but the bar
numbering will be off.
-@node Automatic part combining
-@subsection Automatic part combining
-@cindex automatic part combining
-@cindex part combiner
+@node Metronome marks
+@subsection Metronome marks
-Automatic part combining is used to merge two parts of music onto a
-staff. It is aimed at typesetting orchestral scores. When the two
-parts are identical for a period of time, only one is shown. In
-places where the two parts differ, they are typeset as separate
-voices, and stem directions are set automatically. Also, solo and
-@emph{a due} parts are identified and can be marked.
-
-The syntax for part combining is
+@cindex Tempo
+@cindex beats per minute
+@cindex metronome marking
+Metronome settings can be entered as follows
@example
-\partcombine @var{musicexpr1} @var{musicexpr2}
+\tempo @var{duration} = @var{per-minute}
@end example
+In the MIDI output, they are interpreted as a tempo change. In the
+layout output, a metronome marking is printed
+@cindex @code{\tempo}
+@lilypond[quote,raggedright,verbatim,fragment]
+\tempo 8.=120 c''1
+@end lilypond
-The following example demonstrates the basic functionality of the part
-combiner: putting parts on one staff, and setting stem directions and
-polyphony
+@commonprop
-@lilypond[quote,verbatim,raggedright,fragment]
-\new Staff \partcombine
- \relative g' { g g a( b) c c r r }
- \relative g' { g g r4 r e e g g }
+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
-The first @code{g} appears only once, although it was
-specified twice (once in each part). Stem, slur, and tie directions are
-set automatically, depending whether there is a solo or unisono. The
-first part (with context called @code{one}) always gets up stems, and
-`Solo', while the second (called @code{two}) always gets down stems and
-`Solo II'.
+@noindent
+See @ref{Text markup} for more details.
-If you just want the merging parts, and not the textual markings, you
-may set the property @code{printPartCombineTexts} to false
-@lilypond[quote,verbatim,raggedright,fragment,relative=2]
-\new Staff <<
- \set Staff.printPartCombineTexts = ##f
- \partcombine
- \relative g' { g a( b) r }
- \relative g' { g r4 r f }
->>
-@end lilypond
+@seealso
-To change the text that is printed for solos or merging, you may
-set the @code{soloText}, @code{soloIIText}, and @code{aDueText}
-properties.
+Program reference: @internalsref{MetronomeMark}.
-@lilypond[quote,verbatim,raggedright,fragment,relative=2]
-\new Staff <<
- \set Score.soloText = #"ichi"
- \set Score.soloIIText = #"ni"
- \set Score.aDueText = #"tachi"
- \partcombine
- \relative g' { g4 g a( b) r }
- \relative g' { g4 g r r f }
->>
-@end lilypond
-Both arguments to @code{\partcombine} will be interpreted as
-@internalsref{Voice} contexts. If using relative octaves,
-@code{\relative} should be specified for both music expressions, i.e.,
+@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
-\partcombine
- \relative @dots{} @var{musicexpr1}
- \relative @dots{} @var{musicexpr2}
+\override Score.MetronomeMark #'padding = #2.5
@end example
-@noindent
-A @code{\relative} section that is outside of @code{\partcombine} has
-no effect on the pitches of @var{musicexpr1} and @var{musicexpr2}.
-@seealso
+@node Rehearsal marks
+@subsection Rehearsal marks
-Program reference: @internalsref{PartCombineMusic},
-@internalsref{SoloOneEvent}, and
-@internalsref{SoloTwoEvent}, and
-@internalsref{UnisonoEvent}.
+@cindex Rehearsal marks
+@cindex @code{\mark}
-@refbugs
+To print a rehearsal mark, use the @code{\mark} command
-When @code{printPartCombineTexts} is set, when the two voices play the
-same notes on and off, the part combiner may typeset @code{a2} more
-than once in a measure.
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+c1 \mark \default
+c1 \mark \default
+c1 \mark #8
+c1 \mark \default
+c1 \mark \default
+@end lilypond
-@code{\partcombine} cannot be inside @code{\times}.
+@noindent
+The letter@tie{}`I' is skipped in accordance with engraving traditions.
+If you wish to include the letter `I', then use
-@code{\partcombine} cannot be inside @code{\relative}.
+@example
+\set Score.markFormatter = #format-mark-alphabet
+@end example
-Internally, the @code{\partcombine} interprets both arguments as
-@code{Voice}s named @code{one} and @code{two}, and then decides when
-the parts can be combined. Consequently, if the arguments switch to
-differently named @internalsref{Voice} contexts, the events in those
-will be ignored.
+The mark is incremented automatically if you use @code{\mark
+\default}, but you can also use an integer argument to set the mark
+manually. The value to use is stored in the property
+@code{rehearsalMark}.
-@node Hiding staves
-@subsection Hiding staves
+The style is defined by the property @code{markFormatter}. It is a
+function taking the current mark (an integer) and the current context
+as argument. It should return a markup object. In the following
+example, @code{markFormatter} is set to a canned procedure. After a
+few measures, it is set to function that produces a boxed number.
-@cindex Frenched scores
-@cindex Hiding staves
+@lilypond[fragment,quote,raggedright,verbatim,relative=2]
+\set Score.markFormatter = #format-mark-numbers
+c1 \mark \default
+c1 \mark \default
+\set Score.markFormatter = #format-mark-box-numbers
+c1 \mark \default
+c1 \mark \default
+c1
+@end lilypond
-In orchestral scores, staff lines that only have rests are usually
-removed. This saves some space. This style is called `French Score'.
-For @internalsref{Lyrics},
-@internalsref{ChordNames} and @internalsref{FiguredBass}, this is
-switched on by default. When the lines of these contexts turn out
-empty after the line-breaking process, they are removed.
+The file @file{scm/@/translation@/-functions@/.scm} contains the definitions
+of @code{format-mark-numbers} (the default format), @code{format-mark-box-numbers},
+@code{format-mark-letters} and @code{format-mark-box-letters}.
+These can be used as inspiration for other formatting functions.
-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,raggedright,verbatim]
-\layout {
- \context { \RemoveEmptyStaffContext }
-}
+@seealso
-{
- \relative c' <<
- \new Staff { e4 f g a \break c1 }
- \new Staff { c4 d e f \break R1 }
- >>
-}
-@end lilypond
+Program reference: @internalsref{RehearsalMark}.
-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
-@internalsref{RemoveEmptyVerticalGroup}.
+Init files: @file{scm/@/translation@/-functions@/.scm} contains the
+definition of @code{format-mark-numbers} and
+@code{format-mark-letters}. They can be used as inspiration for other
+formatting functions.
-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.
+Examples: @inputfileref{input/@/regression,rehearsal@/-mark@/-letter@/.ly},
+@inputfileref{input/@/regression,rehearsal@/-mark@/-number@/.ly}.
-@node Different editions from one source
-@subsection Different editions from one source
-@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.
+@node Bar numbers
+@subsection Bar numbers
-In the following example, we see two versions of a piece of music, one
-for the full score, and one with cue notes for the instrumental part
+@cindex Bar numbers
+@cindex measure numbers
+@cindex @code{currentBarNumber}
-@example
-c1
-<<
- \tag #'part <<
- R1 \\
- @{
- \set fontSize = #-1
- c4_"cue" f2 g4 @}
- >>
- \tag #'score R1
->>
-c1
-@end example
+Bar numbers are printed by default at the start of the line. The
+number itself is stored in the @code{currentBarNumber} property, which
+is normally updated automatically for every measure.
-The same can be applied to articulations, texts, etc.: they are
-made by prepending
-@example
--\tag #@var{your-tag}
-@end example
-to an articulation, for example,
-@example
-c1-\tag #'part ^4
-@end example
+Bar numbers can be typeset at regular intervals instead of at the
+beginning of each line. This is illustrated in the following example,
+whose source is available as
+@inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}
-This defines a note with a conditional fingering indication.
+@lilypondfile[raggedright,quote]{bar-number-regular-interval.ly}
-@cindex keepWithTag
-@cindex removeWithTag
-By applying the @code{\keepWithTag} and @code{\removeWithTag}
-commands, tagged expressions can be filtered. For example,
-@example
-<<
- @var{the music}
- \keepWithTag #'score @var{the music}
- \keepWithTag #'part @var{the music}
->>
-@end example
-would yield
+Bar numbers can be typeset manually by tweaking the
+@code{markFormatter} property
-@lilypondfile[raggedright,quote]{tag-filter.ly}
+@lilypond[verbatim,raggedright,quote]
+\relative c' {
+ \set Score.markFormatter
+ = #(lambda (mark context)
+ (make-bold-markup
+ (make-box-markup
+ (number->string (ly:context-property context
+ 'currentBarNumber)))))
+ c1 \bar "||" \mark \default c1 c1 \mark \default c1 \bar "|."
+}
+@end lilypond
-The argument of the @code{\tag} command should be a symbol, or a list
-of symbols, for example,
-@example
-\tag #'(original-part transposed-part) @dots{}
-@end example
+Bar numbers can be manually changed by setting the
+@code{Staff.currentBarNumber} property
+@lilypond[verbatim,raggedright,quote]
+\relative c' {
+ \repeat unfold 4 {c4 c c c} \break
+ \set Score.currentBarNumber = #50
+ \repeat unfold 4 {c4 c c c}
+}
+@end lilypond
@seealso
-Examples: @inputfileref{input/@/regression,tag@/-filter@/.ly}.
-
-@refbugs
-
-Multiple rests are not merged if you create the score with both tagged
-sections.
-
-
-@node Quoting other voices
-@subsection Quoting other voices
-
-With quotations, fragments of other parts can be inserted into a part
-directly. Before a part can be quoted, it must be marked especially as
-quotable. This is done with the @code{\addquote} command.
-
-@example
-\addquote @var{name} @var{music}
-@end example
+Program reference: @internalsref{BarNumber}.
+Examples:
+@inputfileref{input/@/test,bar@/-number@/-every@/-five@/-reset@/.ly},
+and @inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}.
-@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
+@refbugs
-This command must be entered at toplevel, i.e., outside any music
-blocks.
+Bar numbers can collide with the @internalsref{StaffGroup} bracket, if
+there is one at the top. To solve this, the
+@code{padding} property of @internalsref{BarNumber} can be
+used to position the number correctly.
-After calling @code{\addquote}, the quotation may then be done with
-@code{\quoteDuring} or @code{\cueDuring},
-@example
-\quoteDuring #@var{name} @var{music}
-@end example
+@node Instrument names
+@subsection Instrument names
-During a part, a piece of music can be quoted with the @code{\quoteDuring}
-command.
+In an orchestral score, instrument names are printed at the left side
+of the staves.
-@example
-\quoteDuring #"clarinet" @{ s2. @}
-@end example
+This can be achieved by setting @internalsref{Staff}.@code{instrument}
+and @internalsref{Staff}.@code{instr}. This will print a string before
+the start of the staff. For the first staff, @code{instrument} is
+used, for the following ones, @code{instr} is used.
-This would cite three quarter notes (the duration of @code{s2.}) of
-the previously added @code{clarinet} voice.
+@lilypond[quote,verbatim,raggedright,relative=1,fragment]
+\set Staff.instrument = "Ploink "
+\set Staff.instr = "Plk "
+c1
+\break
+c''
+@end lilypond
+You can also use markup texts to construct more complicated instrument
+names, for example
-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.
+@lilypond[quote,fragment,verbatim,raggedright]
+\set Staff.instrument = \markup {
+ \column { "Clarinetti"
+ \line { "in B" \smaller \flat } } }
+c''1
+@end lilypond
-Quotations take into account the transposition of both source and target
-instruments, if they are specified using the @code{\transposition} command.
+If you wish to center the instrument names, you must center all of them
-@lilypond[quote,raggedright,verbatim]
-\addquote clarinet \relative c' {
- \transposition bes
- f4 fis g gis
+@lilypond[quote,verbatim,raggedright]
+{ <<
+\new Staff {
+ \set Staff.instrument = \markup {
+ \center-align { "Clarinetti"
+ \line { "in B" \smaller \flat } } }
+ c''1
}
-
-{
- e'8 f'8 \quoteDuring #"clarinet" { s2 }
+\new Staff {
+ \set Staff.instrument = \markup{ \center-align { Vibraphone }}
+ c''1
+}
+>>
}
@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
+For longer instrument names, it may be useful to increase the
+@code{indent} setting in the @code{\layout} block.
-@example
-\set Staff.quotedEventTypes =
- #'(note-event articulation-event dynamic-event)
-@end example
+@seealso
-@noindent
-will quote notes (but no rests), together with scripts and dynamics.
+Program reference: @internalsref{InstrumentName}.
@refbugs
-Only the contents of the first @internalsref{Voice} occurring in an
-@code{\addquote} command will be considered for quotation, so
-@var{music} can not contain @code{\new} and @code{\context Voice}
-statements that would switch to a different Voice.
-
-Quoting grace notes is broken and can even cause LilyPond to crash.
-
-@seealso
+When you put a name on a grand staff or piano staff, the width of the
+brace is not taken into account. The following property setting can be
+used to move the instrument names to the left, in such situations.
-In this manual: @ref{Instrument transpositions}.
+@example
+\override Score.InstrumentName #'space-alist = #'((left-edge extra-space . 2.0))
+@end example
-Examples: @inputfileref{input/@/regression,quote@/.ly}
-@inputfileref{input/@/regression,quote@/-transposition@/.ly}
-Program reference: @internalsref{QuoteMusic}.
+@node Instrument transpositions
+@subsection Instrument transpositions
-@node Formatting cue notes
-@subsection Formatting cue notes
+@cindex transposition, MIDI
+@cindex transposition, instrument
-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 key of a transposing instrument can also be specified. This
+applies to many wind instruments, for example, clarinets (B-flat, A, and
+E-flat), horn (F) and trumpet (B-flat, C, D, and E-flat).
-The syntax is
+The transposition is entered after the keyword @code{\transposition}
@example
- \cueDuring #@var{name} #@var{updown} @var{music}
+\transposition bes %% B-flat clarinet
@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.
+@noindent
+This command sets the property @code{instrumentTransposition}. The value of
+this property is used for MIDI output and quotations. It does not
+affect how notes are printed in the current staff. To change the printed
+output, see @ref{Transpose}.
+The pitch to use for @code{\transposition} should correspond to the
+transposition of the notes. For example, when entering a score in
+concert pitch, typically all voices are entered in C, so
+they should be entered as
-@lilypond[verbatim,raggedright]
-smaller = {
- \set fontSize = #-2
- \override Stem #'length = #5.5
- \override Beam #'thickness = #0.384
- \override Beam #'space-function =
- #(lambda (beam mult) (* 0.8 (Beam::space_function beam mult)))
-}
+@example
+clarinet = @{
+ \transposition c'
+ ...
+@}
+saxophone = @{
+ \transposition c'
+ ...
+@}
+@end example
-\addquote clarinet \relative {
- R1*20
- r2 r8 c f f
-}
+The command @code{\transposition} should be used when the music is
+entered from a (transposed) orchestral part. For example, in
+classical horn parts, the tuning of the instrument is often changed
+during a piece. When copying the notes from the part, use
+@code{\transposition}, e.g.,
-\new Staff \relative <<
+@example
+\transposition d'
+c'4^"in D"
+...
+\transposition g'
+c'4^"in G"
+...
+@end example
- % setup a context for cue notes.
- \context Voice = cue { \smaller \skip 1*21 }
-
- \set Score.skipBars = ##t
-
- \new Voice {
- R1*20
- \cueDuring #"clarinet" #1 {
- R1
- }
- g4 g2.
- }
->>
-@end lilypond
+@node Ottava brackets
+@subsection Ottava brackets
-Here are a couple of hints for successful cue notes
+`Ottava' brackets introduce an extra transposition of an octave for
+the staff. They are created by invoking the function
+@code{set-octavation}
-@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.
+@cindex ottava
+@cindex 15ma
+@cindex octavation
- @c really? Are you sure about that last point? I'll check after 3.0 -gp
+@lilypond[quote,raggedright,verbatim,fragment]
+\relative c''' {
+ a2 b
+ #(set-octavation 1)
+ a b
+ #(set-octavation 0)
+ a b
+}
+@end lilypond
-@c Yes, this is good practice. Otherwise, the start of the original
-@c part can only be seen from the font size. This is not good enough
-@c for sight-reading. It is possilbe to use other
-@c markers (eg. a big close-bracket over the staff) to indicate the cue notes are
-@c finished.
-@c -hwn
+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
- 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
+@seealso
+Program reference: @internalsref{OttavaBracket}.
+Examples: @inputfileref{input/@/regression,ottava@/.ly},
+@inputfileref{input/@/regression,ottava@/-broken@/.ly}.
+@refbugs
-@node Contemporary notation
-@section Contemporary notation
+@code{set-octavation} will get confused when clef changes happen
+during an octavation bracket.
-In the 20th century, composers have greatly expanded the musical
-vocabulary. With this expansion, many innovations in musical notation
-have been tried. The book ``Music Notation in the 20th century'' by
-Kurt Stone gives a comprehensive overview (see @ref{Literature
-list}). In general, the use of new, innovative notation makes a piece
-harder to understand and perform and its use should therefore be
-avoided. For this reason, support for contemporary notation in
-LilyPond is limited.
+@node Different editions from one source
+@subsection Different editions from one source
-@menu
-* Polymetric notation::
-* Clusters::
-* Special fermatas::
-* Feathered beams::
-* Improvisation::
-@end menu
+@cindex @code{\tag}
+@cindex tag
-@node Polymetric notation
-@subsection Polymetric notation
+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.
-Double time signatures are not supported explicitly, but they can be
-faked. In the next example, the markup for the time signature is
-created with a markup text. This markup text is inserted in the
-@internalsref{TimeSignature} grob.
+In the following example, we see two versions of a piece of music, one
+for the full score, and one with cue notes for the instrumental part
-@lilypond[verbatim,raggedright]
-% create 2/4 + 5/8
-tsMarkup =\markup {
+@example
+c1
+<<
+ \tag #'part <<
+ R1 \\
+ @{
+ \set fontSize = #-1
+ c4_"cue" f2 g4 @}
+ >>
+ \tag #'score R1
+>>
+c1
+@end example
+
+The same can be applied to articulations, texts, etc.: they are
+made by prepending
+@example
+-\tag #@var{your-tag}
+@end example
+to an articulation, for example,
+@example
+c1-\tag #'part ^4
+@end example
+
+This defines a note with a conditional fingering indication.
+
+@cindex keepWithTag
+@cindex removeWithTag
+By applying the @code{\keepWithTag} and @code{\removeWithTag}
+commands, tagged expressions can be filtered. For example,
+@example
+<<
+ @var{the music}
+ \keepWithTag #'score @var{the music}
+ \keepWithTag #'part @var{the music}
+>>
+@end example
+would yield
+
+@lilypondfile[raggedright,quote]{tag-filter.ly}
+
+The argument of the @code{\tag} command should be a symbol, or a list
+of symbols, for example,
+@example
+\tag #'(original-part transposed-part) @dots{}
+@end example
+
+
+@seealso
+
+Examples: @inputfileref{input/@/regression,tag@/-filter@/.ly}.
+
+
+@refbugs
+
+Multiple rests are not merged if you create the score with both tagged
+sections.
+
+
+
+@node Orchestral music
+@section Orchestral music
+
+Orchestral music involves some special notation, both in the full
+score and the individual parts. This section explains how to tackle
+some common problems in orchestral music.
+
+@menu
+* Automatic part combining::
+* Hiding staves::
+* Quoting other voices::
+* Formatting cue notes::
+* Aligning to cadenzas::
+@end menu
+
+
+@node Automatic part combining
+@subsection Automatic part combining
+@cindex automatic part combining
+@cindex part combiner
+
+Automatic part combining is used to merge two parts of music onto a
+staff. It is aimed at typesetting orchestral scores. When the two
+parts are identical for a period of time, only one is shown. In
+places where the two parts differ, they are typeset as separate
+voices, and stem directions are set automatically. Also, solo and
+@emph{a due} parts are identified and can be marked.
+
+The syntax for part combining is
+
+@example
+\partcombine @var{musicexpr1} @var{musicexpr2}
+@end example
+
+
+The following example demonstrates the basic functionality of the part
+combiner: putting parts on one staff, and setting stem directions and
+polyphony
+
+@lilypond[quote,verbatim,raggedright,fragment]
+\new Staff \partcombine
+ \relative g' { g g a( b) c c r r }
+ \relative g' { g g r4 r e e g g }
+@end lilypond
+
+The first @code{g} appears only once, although it was
+specified twice (once in each part). Stem, slur, and tie directions are
+set automatically, depending whether there is a solo or unisono. The
+first part (with context called @code{one}) always gets up stems, and
+`Solo', while the second (called @code{two}) always gets down stems and
+`Solo II'.
+
+If you just want the merging parts, and not the textual markings, you
+may set the property @code{printPartCombineTexts} to false
+
+@lilypond[quote,verbatim,raggedright,fragment,relative=2]
+\new Staff <<
+ \set Staff.printPartCombineTexts = ##f
+ \partcombine
+ \relative g' { g a( b) r }
+ \relative g' { g r4 r f }
+>>
+@end lilypond
+
+To change the text that is printed for solos or merging, you may
+set the @code{soloText}, @code{soloIIText}, and @code{aDueText}
+properties.
+
+@lilypond[quote,verbatim,raggedright,fragment,relative=2]
+\new Staff <<
+ \set Score.soloText = #"ichi"
+ \set Score.soloIIText = #"ni"
+ \set Score.aDueText = #"tachi"
+ \partcombine
+ \relative g' { g4 g a( b) r }
+ \relative g' { g4 g r r f }
+>>
+@end lilypond
+
+Both arguments to @code{\partcombine} will be interpreted as
+@internalsref{Voice} contexts. If using relative octaves,
+@code{\relative} should be specified for both music expressions, i.e.,
+
+@example
+\partcombine
+ \relative @dots{} @var{musicexpr1}
+ \relative @dots{} @var{musicexpr2}
+@end example
+
+@noindent
+A @code{\relative} section that is outside of @code{\partcombine} has
+no effect on the pitches of @var{musicexpr1} and @var{musicexpr2}.
+
+@seealso
+
+Program reference: @internalsref{PartCombineMusic}.
+
+@refbugs
+
+When @code{printPartCombineTexts} is set, when the two voices play the
+same notes on and off, the part combiner may typeset @code{a2} more
+than once in a measure.
+
+@code{\partcombine} cannot be inside @code{\times}.
+
+@code{\partcombine} cannot be inside @code{\relative}.
+
+Internally, the @code{\partcombine} interprets both arguments as
+@code{Voice}s named @code{one} and @code{two}, and then decides when
+the parts can be combined. Consequently, if the arguments switch to
+differently named @internalsref{Voice} contexts, the events in those
+will be ignored.
+
+
+@node Hiding staves
+@subsection Hiding staves
+
+@cindex Frenched scores
+@cindex Hiding staves
+
+In orchestral scores, staff lines that only have rests are usually
+removed; this saves some space. This style is called `French Score'.
+For @internalsref{Lyrics},
+@internalsref{ChordNames} and @internalsref{FiguredBass}, this is
+switched on by default. When the lines of these contexts turn out
+empty after the line-breaking process, they are removed.
+
+For normal staves, a specialized @internalsref{Staff} context is
+available, which does the same: staves containing nothing (or only
+multi-measure rests) are removed. The context definition is stored in
+@code{\RemoveEmptyStaffContext} variable. Observe how the second staff
+in this example disappears in the second line
+
+@lilypond[quote,raggedright,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{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
+
+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,raggedright,verbatim]
+\addquote clarinet \relative c' {
+ \transposition bes
+ f4 fis g gis
+}
+
+{
+ e'8 f'8 \quoteDuring #"clarinet" { s2 }
+}
+@end lilypond
+
+The type of events that are present in cue notes can be trimmed with
+the @code{quotedEventTypes} property. The default value is
+@code{(note-event rest-event)}, which means that only notes and
+rests of the cued voice end up in the @code{\quoteDuring}.
+Setting
+
+@example
+\set Staff.quotedEventTypes =
+ #'(note-event articulation-event dynamic-event)
+@end example
+
+@noindent
+will quote notes (but no rests), together with scripts and dynamics.
+
+@refbugs
+
+Only the contents of the first @internalsref{Voice} occurring in an
+@code{\addquote} command will be considered for quotation, so
+@var{music} can not contain @code{\new} and @code{\context Voice}
+statements that would switch to a different Voice.
+
+Quoting grace notes is broken and can even cause LilyPond to crash.
+
+@seealso
+
+In this manual: @ref{Instrument transpositions}.
+
+Examples: @inputfileref{input/@/regression,quote@/.ly}
+@inputfileref{input/@/regression,quote@/-transposition@/.ly}
+
+Program reference: @internalsref{QuoteMusic}.
+
+
+@node Formatting cue notes
+@subsection Formatting cue notes
+
+The previous section deals with inserting notes from another voice.
+There is a more advanced music function called @code{\cueDuring},
+which makes formatting cue notes easier.
+
+The syntax is
+
+@example
+ \cueDuring #@var{name} #@var{updown} @var{music}
+@end example
+
+This will insert notes from the part @var{name} into a
+@internalsref{Voice} called @code{cue}. This happens simultaneously
+with @var{music}, which usually is a rest. When the cue notes start,
+the staff in effect becomes polyphonic for a moment. The argument
+@var{updown} determines whether the cue notes should be notated as a
+first or second voice.
+
+
+@lilypond[verbatim,raggedright]
+smaller = {
+ \set fontSize = #-2
+ \override Stem #'length = #5.5
+ \override Beam #'thickness = #0.384
+ \override Beam #'space-function =
+ #(lambda (beam mult) (* 0.8 (Beam::space_function beam mult)))
+}
+
+\addquote clarinet \relative {
+ R1*20
+ r2 r8 c f f
+}
+
+\new Staff \relative <<
+
+ % setup a context for cue notes.
+ \context Voice = cue { \smaller \skip 1*21 }
+
+ \set Score.skipBars = ##t
+
+ \new Voice {
+ R1*20
+ \cueDuring #"clarinet" #1 {
+ R1
+ }
+ g4 g2.
+ }
+>>
+@end lilypond
+
+
+Here are a couple of hints for successful cue notes
+
+@itemize @bullet
+@item
+Cue notes have smaller font sizes.
+@item
+ the cued part is marked with the instrument playing the cue.
+@item
+ when the original part takes over again, this should be marked with
+ the name of the original instrument.
+
+@c really? Are you sure about that last point? I'll check after 3.0 -gp
+
+@c Yes, this is good practice. Otherwise, the start of the original
+@c part can only be seen from the font size. This is not good enough
+@c for sight-reading. It is possilbe to use other
+@c markers (eg. a big close-bracket over the staff) to indicate the cue notes are
+@c finished.
+@c -hwn
+
+
+Any other changes introduced by the cued part should also be
+undone. For example, if the cued instrument plays in a different clef,
+the original clef should be stated once again.
+
+@end itemize
+
+
+@node Aligning to cadenzas
+@subsection Aligning to cadenzas
+
+In an orchestral context, cadenzas present a special problem:
+when constructing a score that includes a cadenza, all other
+instruments should skip just as many notes as the length of the
+cadenza, otherwise they will start too soon or too late.
+
+A solution to this problem are the functions @code{mmrest-of-length}
+and @code{skip-of-length}. These Scheme functions take a piece of music
+as argument, and generate a @code{\skip} or multi-rest, exactly as
+long as the piece. The use of @code{mmrest-of-length} is demonstrated
+in the following example.
+
+@lilypond[verbatim,raggedright,quote]
+cadenza = \relative c' {
+ c4 d8 << { e f g } \\ { d4. } >>
+ g4 f2 g4 g
+}
+
+\new GrandStaff <<
+ \new Staff { \cadenza c'4 }
+ \new Staff {
+ #(ly:export (mmrest-of-length cadenza))
+ c'4
+ }
+>>
+@end lilypond
+
+
+
+
+@node Contemporary notation
+@section Contemporary notation
+
+In the 20th century, composers have greatly expanded the musical
+vocabulary. With this expansion, many innovations in musical notation
+have been tried. The book ``Music Notation in the 20th century'' by
+Kurt Stone gives a comprehensive overview (see @ref{Literature
+list}). In general, the use of new, innovative notation makes a piece
+harder to understand and perform and its use should therefore be
+avoided. For this reason, support for contemporary notation in
+LilyPond is limited.
+
+
+@menu
+* Polymetric notation::
+* Time administration::
+* Clusters::
+* Special fermatas::
+* Special noteheads::
+* Pitched trills::
+* Feathered beams::
+* Improvisation::
+@end menu
+
+
+@node Polymetric notation
+@subsection Polymetric notation
+
+Double time signatures are not supported explicitly, but they can be
+faked. In the next example, the markup for the time signature is
+created with a markup text. This markup text is inserted in the
+@internalsref{TimeSignature} grob.
+
+@lilypond[verbatim,raggedright]
+% create 2/4 + 5/8
+tsMarkup =\markup {
\number {
\column { "2" "4" }
\musicglyph #"scripts.stopped"
}
}
-{
- \override Staff.TimeSignature #'print-function = #Text_interface::print
- \override Staff.TimeSignature #'text = #tsMarkup
- \time 3/2
- c'2 \bar ":" c'4 c'4.
-}
+{
+ \override Staff.TimeSignature #'print-function = #Text_interface::print
+ \override Staff.TimeSignature #'text = #tsMarkup
+ \time 3/2
+ c'2 \bar ":" c'4 c'4.
+}
+@end lilypond
+
+Each staff can also have its own time signature. This is done by
+moving the @internalsref{Timing_translator} to the @internalsref{Staff}
+context.
+
+@example
+\layout @{
+ \context @{ \Score
+ \remove "Timing_translator"
+ \remove "Default_bar_line_engraver"
+ @}
+ \context @{
+ \Staff
+ \consists "Timing_translator"
+ \consists "Default_bar_line_engraver"
+ @}
+
+@}
+@end example
+
+
+Now, each staff has its own time signature.
+@example
+<<
+ \new Staff @{
+ \time 3/4
+ c4 c c | c c c |
+ @}
+ \new Staff @{
+ \time 2/4
+ c4 c | c c | c c
+ @}
+ \new Staff @{
+ \time 3/8
+ c4. c8 c c c4. c8 c c
+ @}
+>>
+@end example
+
+@lilypond[quote,raggedright]
+\layout{
+ \context{
+ \Score
+ \remove "Timing_translator"
+ \remove "Default_bar_line_engraver"
+ }
+ \context{ \Staff
+ \consists "Timing_translator"
+ \consists "Default_bar_line_engraver"
+ }
+}
+
+\relative c' <<
+ \new Staff {
+ \time 3/4
+ c4 c c | c c c |
+ }
+ \new Staff {
+ \time 2/4
+ c4 c | c c | c c
+ }
+ \new Staff {
+ \time 3/8
+ c4. c8 c c c4. c8 c c
+ }
+>>
+@end lilypond
+
+
+A different form of polymetric notation is where note lengths have
+different values across staves.
+
+This notation can be created by setting a common time signature for
+each staff but replacing it manually using
+@code{timeSignatureFraction} to the desired fraction. Then the printed
+durations in each staff are scaled to the common time signature.
+The latter is done with @code{\compressMusic}, which is similar to
+@code{\times}, but does not create a tuplet bracket.
+
+
+In this example, music with the time signatures of 3/4, 9/8, and 10/8 are
+used in parallel. In the second staff, shown durations are multiplied by
+2/3, so that 2/3 * 9/8 = 3/4, and in the third staff, shown durations are
+multiplied by 3/5, so that 3/5 * 10/8 = 3/4.
+
+@lilypond[quote,raggedright,verbatim,fragment]
+\relative c' { <<
+ \new Staff {
+ \time 3/4
+ c4 c c | c c c |
+ }
+ \new Staff {
+ \time 3/4
+ \set Staff.timeSignatureFraction = #'(9 . 8)
+ \compressMusic #'(2 . 3)
+ \repeat unfold 6 { c8[ c c] }
+ }
+ \new Staff {
+ \time 3/4
+ \set Staff.timeSignatureFraction = #'(10 . 8)
+ \compressMusic #'(3 . 5) {
+ \repeat unfold 2 { c8[ c c] }
+ \repeat unfold 2 { c8[ c] }
+ | c4. c4. \times 2/3 { c8 c c } c4
+ }
+ }
+>> }
+@end lilypond
+
+
+
+
+@refbugs
+
+When using different time signatures in parallel, the spacing is
+aligned vertically, but bar lines distort the regular spacing.
+
+
+@node Time administration
+@subsection Time administration
+
+@cindex Time administration
+
+Time is administered by the @internalsref{Time_signature_engraver},
+which usually lives in the @internalsref{Score} context. The
+bookkeeping deals with the following variables
+
+@table @code
+@item currentBarNumber
+The measure number.
+
+@item measureLength
+The length of the measures in the current time signature. For a 4/4
+time this is@tie{}1, and for 6/8 it is 3/4.
+
+@item measurePosition
+The point within the measure where we currently are. This quantity
+is reset to@tie{}0 whenever it exceeds @code{measureLength}. When that
+happens, @code{currentBarNumber} is incremented.
+
+@item timing
+If set to true, the above variables are updated for every time
+step. When set to false, the engraver stays in the current measure
+indefinitely.
+@end table
+
+Timing can be changed by setting any of these variables explicitly.
+In the next example, the 4/4 time signature is printed, but
+@code{measureLength} is set to 5/4. After a while, the measure is
+shortened by 1/8, by setting @code{measurePosition} to 7/8 at 2/4
+in the measure, so the next bar line will fall at 2/4 + 3/8. The
+3/8 arises because 5/4 normally has 10/8, but we have manually
+set the measure position to be 7/8 and 10/8 - 7/8 = 3/8.
+
+@lilypond[quote,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
+
+@cindex cluster
+
+A cluster indicates a continuous range of pitches to be played. They
+can be denoted as the envelope of a set of notes. They are entered by
+applying the function @code{makeClusters} to a sequence of
+chords, e.g.,
+@lilypond[quote,raggedright,relative=2,fragment,verbatim]
+\makeClusters { <c e > <b f'> }
+@end lilypond
+
+The following example (from
+@inputfileref{input/@/regression,cluster@/.ly}) shows what the result
+looks like
+
+@lilypondfile[raggedright,quote]{cluster.ly}
+
+Ordinary notes and clusters can be put together in the same staff,
+even simultaneously. In such a case no attempt is made to
+automatically avoid collisions between ordinary notes and clusters.
+
+@seealso
+
+Program reference: @internalsref{ClusterSpanner},
+@internalsref{ClusterSpannerBeacon},
+@internalsref{Cluster_spanner_engraver}.
+
+Examples: @inputfileref{input/@/regression,cluster@/.ly}.
+
+@refbugs
+
+Music expressions like @code{<< @{ g8 e8 @} a4 >>} are not printed
+accurately. Use @code{<g a>8 <e a>8} instead.
+
+
+
+@node Special fermatas
+@subsection Special fermatas
+
+@cindex fermatas, special
+
+In contemporary music notation, special fermata symbols denote breaks
+of differing lengths. The following fermatas are supported
+
+@lilypond[quote,raggedright]
+<<
+ \oldaddlyrics {
+ b'2
+ ^\shortfermata
+ _\shortfermata
+ r
+
+ b'
+ ^\fermata
+ _\fermata
+ r
+
+ b'
+ ^\longfermata
+ _\longfermata
+ r
+
+ b'
+ ^\verylongfermata
+ _\verylongfermata
+ r
+ }
+ \context Lyrics \lyricmode {
+ \override LyricText #'font-family = #'typewriter
+ "shortfermata" "fermata" "longfermata" "verylongfermata"
+ }
+>>
+@end lilypond
+
+See @ref{Articulations} for general instructions how to apply scripts
+such as fermatas to notes.
+
+
+@node Special noteheads
+@subsection Special noteheads
+
+Different noteheads are used by various instruments for various
+meanings -- crosses are used for ``parlato'' with vocalists, stopped
+notes on guitar; diamonds are used for harmonics on string instruments,
+etc. There is a shorthand (@code{\harmonic}) for diamond shapes; the
+other notehead styles are produced by tweaking the property
+
+@lilypond[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,fragment]
+ \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.
+
+@node Feathered beams
+@subsection Feathered beams
+
+Feathered beams are not supported natively, but they can be faked by
+forcing two beams to overlap. Here is an example,
+
+@c don't change relative setting witout changing positions!
+@lilypond[raggedright,relative=1,fragment,verbatim,quote]
+\new Staff <<
+ \new Voice
+ {
+ \stemUp
+ \once \override Voice.Beam #'positions = #'(0 . 0.5)
+ c8[ c c c c ]
+ }
+ \new Voice {
+ \stemUp
+ \once \override Voice.Beam #'positions = #'(0 . -0.5)
+ c[ c c c c]
+ }
+>>
+@end lilypond
+
+
+@node Improvisation
+@subsection Improvisation
+
+Improvisation is sometimes denoted with slashed note heads. Such note
+heads can be created by adding a @internalsref{Pitch_squash_engraver}
+to the @internalsref{Staff} or @internalsref{Voice} context. Then, the
+following command
+
+@example
+\set squashedPosition = #0
+\override NoteHead #'style = #'slash
+@end example
+
+@noindent
+switches on the slashes.
+
+There are shortcuts @code{\improvisationOn} (and an accompanying
+@code{\improvisationOff}) for this command sequence. They are used in
+the following example
+
+@lilypond[verbatim,raggedright,quote]
+\new Staff \with {
+ \consists Pitch_squash_engraver
+} \transpose c c' {
+ e8 e g a a16(bes)(a8) g \improvisationOn
+ e8
+ ~e2~e8 f4 fis8
+ ~fis2 \improvisationOff a16(bes) a8 g e
+}
+@end lilypond
+
+
+@node Educational use
+@section Educational use
+
+With the amount of control that LilyPond offers, one can make great
+teaching tools in addition to great musical scores.
+
+@menu
+* Balloon help::
+* Blank music sheet::
+* Hidden notes::
+* Shape note heads ::
+* Easy Notation note heads::
+* Analysis brackets::
+* Coloring objects::
+@end menu
+
+@node Balloon help
+@subsection Balloon help
+
+Elements of notation can be marked and named with the help of a square
+balloon. The primary purpose of this feature is to explain notation.
+
+The following example demonstrates its use.
+
+@lilypond[quote,verbatim,fragment,raggedright,relative=2]
+\context Voice {
+ \applyoutput
+ #(add-balloon-text 'NoteHead "heads, or tails?"
+ '(1 . -3))
+ c8
+}
+@end lilypond
+
+@noindent
+The function @code{add-balloon-text} takes the name of a grob, the
+label to print, and the position where to put the label relative to
+the object. In the above example, the text ``heads or tails?'' ends
+3 spaces below and 1 space to the right of the marked head.
+
+@cindex balloon
+@cindex notation, explaining
+
+@seealso
+
+Program reference: @internalsref{text-balloon-interface}.
+
+Examples: @inputfileref{input/@/regression,balloon@/.ly}.
+
+
+
+
+@node Blank music sheet
+@subsection Blank music sheet
+
+A blank music sheet can be produced also by using invisible notes, and
+removing @code{Bar_number_engraver}.
+
+
+@lilypond[quote,verbatim]
+emptymusic = {
+ \repeat unfold 2 % Change this for more lines.
+ { s1\break }
+ \bar "|."
+}
+\new Score \with {
+ \override TimeSignature #'transparent = ##t
+ defaultBarType = #""
+ \remove Bar_number_engraver
+} <<
+ \context Staff \emptymusic
+ \context TabStaff \emptymusic
+>>
+@end lilypond
+
+
+@node Hidden notes
+@subsection Hidden notes
+
+@cindex Hidden notes
+@cindex Invisible notes
+@cindex Transparent notes
+
+@cindex @code{\hideNotes}
+@cindex @code{\unHideNotes}
+Hidden (or invisible or transparent) notes can be useful in preparing theory
+or composition exercises.
+
+@lilypond[quote,raggedright,verbatim,relative=2,fragment]
+c4 d4
+\hideNotes
+e4 f4
+\unHideNotes
+g4 a
+@end lilypond
+
+Hidden notes are also great for performing weird tricks. For example,
+slurs cannot be attached to rests or spacer rests, but you may wish
+to include that in your score -- string instruments use this notation
+when doing pizzicato to indicate that the note should ring for as long
+as possible.
+
+@lilypond[quote,raggedright,verbatim,relative=0,fragment]
+\clef bass
+<< {
+ c4^"pizz"( \hideNotes c)
+ \unHideNotes c( \hideNotes c)
+} {
+ s4 r s r
+} >>
+@end lilypond
+
+
+@node Shape note heads
+@subsection Shape note heads
+
+In shape note head notation, the shape of the note head corresponds
+to the harmonic function of a note in the scale. This notation was
+popular in the 19th century American song books.
+
+Shape note heads can be produced by setting @code{\aikenHeads} or
+@code{\sacredHarpHeads}, depending on the style desired.
+
+@lilypond[verbatim,relative=1,fragment]
+ \aikenHeads
+ c8 d4 e8 a2 g1
+ \sacredHarpHeads
+ c8 d4. e8 a2 g1
@end lilypond
-Each staff can also have its own time signature. This is done by
-moving the @internalsref{Timing_engraver} to the @internalsref{Staff}
-context.
+Shapes are determined on the step in the scale, where the base of the
+scale is determined by the @code{\key} command
-@example
-\layout @{
- \context @{ \Score \remove "Timing_engraver" @}
- \context @{ \Staff \consists "Timing_engraver" @}
-@}
-@end example
+@findex \key
+@findex shapeNoteStyles
+@findex \aikenHeads
+@findex \sacredHarpHeads
+Shape note heads are implemented through the @code{shapeNoteStyles}
+property. Its value is a vector of symbols. The k-th element indicates
+the style to use for the k-th step of the scale. Arbitrary
+combinations are possible, eg.,
-Now, each staff has its own time signature.
-@example
-<<
- \new Staff @{
- \time 3/4
- c4 c c | c c c |
- @}
- \new Staff @{
- \time 2/4
- c4 c | c c | c c
- @}
- \new Staff @{
- \time 3/8
- c4. c8 c c c4. c8 c c
- @}
->>
-@end example
-@lilypond[quote,raggedright]
-\layout{
- \context{ \Score \remove "Timing_engraver" }
- \context{ \Staff \consists "Timing_engraver" }
-}
+@lilypond[verbatim,relative=1,fragment]
+ \set shapeNoteStyles = ##(cross triangle fa #f mensural xcircle diamond)
+ c8 d4. e8 a2 g1
+@end lilypond
-\relative c' <<
- \new Staff {
- \time 3/4
- c4 c c | c c c |
- }
- \new Staff {
- \time 2/4
- c4 c | c c | c c
- }
- \new Staff {
- \time 3/8
- c4. c8 c c c4. c8 c c
- }
->>
+
+@node Easy Notation note heads
+@subsection Easy Notation note heads
+
+@cindex easy notation
+@cindex Hal Leonard
+
+The `easy play' note head includes a note name inside the head. It is
+used in music for beginners
+
+@lilypond[quote,raggedright,verbatim,fragment,staffsize=26]
+ \setEasyHeads
+ c'2 e'4 f' | g'1
@end lilypond
+The command @code{\setEasyHeads} overrides settings for the
+@internalsref{NoteHead} object. To make the letters readable, it has
+to be printed in a large font size. To print with a larger font, see
+@ref{Setting global staff size}.
-A different form of polymetric notation is where note lengths have
-different values across staves.
+@refcommands
-This notation can be created by setting a common time signature for
-each staff but replacing it manually using
-@code{timeSignatureFraction} to the desired fraction. Then the printed
-durations in each staff are scaled to the common time signature.
-The latter is done with @code{\compressmusic}, which is similar to
-@code{\times}, but does not create a tuplet bracket.
+@cindex @code{\setEasyHeads}
+@code{\setEasyHeads}
-In this example, music with the time signatures of 3/4, 9/8, and 10/8 are
-used in parallel. In the second staff, shown durations are multiplied by
-2/3, so that 2/3 * 9/8 = 3/4, and in the third staff, shown durations are
-multiplied by 3/5, so that 3/5 * 10/8 = 3/4.
+@node Analysis brackets
+@subsection Analysis brackets
+@cindex brackets
+@cindex phrasing brackets
+@cindex musicological analysis
+@cindex note grouping bracket
-@lilypond[quote,raggedright,verbatim,fragment]
-\relative c' { <<
- \new Staff {
- \time 3/4
- c4 c c | c c c |
- }
- \new Staff {
- \time 3/4
- \set Staff.timeSignatureFraction = #'(9 . 8)
- \compressmusic #'(2 . 3)
- \repeat unfold 6 { c8[ c c] }
- }
- \new Staff {
- \time 3/4
- \set Staff.timeSignatureFraction = #'(10 . 8)
- \compressmusic #'(3 . 5) {
- \repeat unfold 2 { c8[ c c] }
- \repeat unfold 2 { c8[ c] }
- | c4. c4. \times 2/3 { c8 c c } c4
- }
+Brackets are used in musical analysis to indicate structure in musical
+pieces. LilyPond supports a simple form of nested horizontal
+brackets. To use this, add the @internalsref{Horizontal_bracket_engraver}
+to @internalsref{Staff} context. A bracket is started with
+@code{\startGroup} and closed with @code{\stopGroup}
+
+@lilypond[quote,raggedright,verbatim]
+\score {
+ \relative c'' {
+ c4\startGroup\startGroup
+ c4\stopGroup
+ c4\startGroup
+ c4\stopGroup\stopGroup
}
->> }
+ \layout {
+ \context {
+ \Staff \consists "Horizontal_bracket_engraver"
+}}}
@end lilypond
+@seealso
+Program reference: @internalsref{HorizontalBracket}.
+Examples: @inputfileref{input/@/regression,note@/-group@/-bracket@/.ly}.
-@refbugs
-When using different time signatures in parallel, the spacing is
-aligned vertically, but bar lines distort the regular spacing.
+@node Coloring objects
+@subsection Coloring objects
+Individual objects may be assigned colors. You may use the
+color names listed in the @ref{List of colors}.
+@lilypond[quote,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
-@node Clusters
-@subsection Clusters
+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
-@cindex cluster
+@example
+\override Beam #'color = #(x11-color 'MediumTurquoise)
+@end example
-A cluster indicates a continuous range of pitches to be played. They
-can be denoted as the envelope of a set of notes. They are entered by
-applying the function @code{makeClusters} to a sequence of
-chords, e.g.,
-@lilypond[quote,raggedright,relative=2,fragment,verbatim]
-\makeClusters { <c e > <b f'> }
-@end lilypond
+or a string
-The following example (from
-@inputfileref{input/@/regression,cluster@/.ly}) shows what the result
-looks like
+@example
+\override Beam #'color = #(x11-color "MediumTurquoise")
+@end example
-@lilypondfile[raggedright,quote]{cluster.ly}
+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
-Ordinary notes and clusters can be put together in the same staff,
-even simultaneously. In such a case no attempt is made to
-automatically avoid collisions between ordinary notes and clusters.
+@example
+\override Beam #'color = #(x11-color "medium turquoise")
+@end example
-@seealso
+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.
-Program reference: @internalsref{ClusterSpanner},
-@internalsref{ClusterSpannerBeacon},
-@internalsref{Cluster_spanner_engraver}, and
-@internalsref{ClusterNoteEvent}.
+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.
-Examples: @inputfileref{input/@/regression,cluster@/.ly}.
+@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
-@refbugs
-Music expressions like @code{<< @{ g8 e8 @} a4 >>} are not printed
-accurately. Use @code{<g a>8 <e a>8} instead.
+@seealso
+Appendix: @ref{List of colors}.
-@node Special fermatas
-@subsection Special fermatas
+@refbugs
+Not all x11 colors are distinguishable in a web browser. For web use
+normal colors are recommended.
-@cindex fermatas, special
+An x11 color is not necessarily exactly the same shade as a similarly
+named normal color.
-In contemporary music notation, special fermata symbols denote breaks
-of differing lengths. The following fermatas are supported
-@lilypond[quote,raggedright]
-<<
- \oldaddlyrics {
- b'2
- ^\shortfermata
- _\shortfermata
- r
+@node Automatic notation
+@section Automatic notation
- b'
- ^\fermata
- _\fermata
- r
+This section describes how to change the way that accidentals and
+beams are automatically displayed.
- b'
- ^\longfermata
- _\longfermata
- r
+FIXME: this might get moved into Changing Defaults. Please send
+opinions to lilypond-devel. Thanks! :)
- b'
- ^\verylongfermata
- _\verylongfermata
- r
- }
- \context Lyrics \lyricmode {
- \override LyricText #'font-family = #'typewriter
- "shortfermata" "fermata" "longfermata" "verylongfermata"
- }
->>
-@end lilypond
+@menu
+* Automatic accidentals::
+* Setting automatic beam behavior::
+@end menu
-See @ref{Articulations} for general instructions how to apply scripts
-such as fermatas to notes.
+@node Automatic accidentals
+@subsection Automatic accidentals
+@cindex Automatic accidentals
-@node Feathered beams
-@subsection Feathered beams
+Common rules for typesetting accidentals have been placed in a
+function. This function is called as follows
-Feathered beams are not supported natively, but they can be faked by
-forcing two beams to overlap. Here is an example,
+@cindex @code{set-accidental-style}
+@example
+#(set-accidental-style 'STYLE #('CONTEXT#))
+@end example
-@c don't change relative setting witout changing positions!
-@lilypond[raggedright,relative=1,fragment,verbatim]
-\new Staff <<
- \new Voice
- {
- \stemUp
- \once \override Voice.Beam #'positions = #'(0 . 0.5)
- c8[ c c c c ]
- }
- \new Voice {
- \stemUp
- \once \override Voice.Beam #'positions = #'(0 . -0.5)
- c[ c c c c]
- }
->>
-@end lilypond
+The function can take two arguments: the name of the accidental style,
+and an optional argument that denotes the context that should be
+changed. If no context name is supplied, @code{Staff} is the default,
+but you may wish to apply the accidental style to a single @code{Voice}
+instead.
+The following accidental styles are supported
+@table @code
+@item default
+This is the default typesetting behavior. It corresponds
+to 18th century common practice: Accidentals are
+remembered to the end of the measure in which they occur and
+only on their own octave.
-@node Improvisation
-@subsection Improvisation
+@item voice
+The normal behavior is to remember the accidentals on
+Staff-level. This variable, however, typesets accidentals
+individually for each voice. Apart from that, the rule is similar to
+@code{default}.
-Improvisation is sometimes denoted with slashed note heads. Such note
-heads can be created by adding a @internalsref{Pitch_squash_engraver}
-to the @internalsref{Staff} or @internalsref{Voice} context. Then, the
-following command
+As a result, accidentals from one voice do not get canceled in other
+voices, which is often an unwanted result
-@example
-\set squashedPosition = #0
-\override NoteHead #'style = #'slash
-@end example
+@lilypond[quote,raggedright,relative=1,fragment,verbatim]
+\context Staff <<
+ #(set-accidental-style 'voice)
+ <<
+ { es g } \\
+ { c, e }
+>> >>
+@end lilypond
-@noindent
-switches on the slashes.
+The @code{voice} option should be used if the voices
+are to be read solely by individual musicians. If the staff is to be
+used by one musician (e.g., a conductor) then
+@code{modern} or @code{modern-cautionary}
+should be used instead.
-There are shortcuts @code{\improvisationOn} (and an accompanying
-@code{\improvisationOff}) for this command sequence. They are used in
-the following example
+@item modern
+@cindex @code{modern} style accidentals
+This rule corresponds to the common practice in the 20th century. This rule
+prints the same accidentals as @code{default}, but temporary
+accidentals also are canceled in other octaves. Furthermore,
+in the same octave, they also get canceled in the following
+measure
-@lilypond[verbatim,raggedright,quote]
-\new Staff \with {
- \consists Pitch_squash_engraver
-} \transpose c c' {
- e8 e g a a16(bes)(a8) g \improvisationOn
- e8
- ~e2~e8 f4 fis8
- ~fis2 \improvisationOff a16(bes) a8 g e
-}
+@lilypond[quote,raggedright,fragment,verbatim]
+#(set-accidental-style 'modern)
+cis' c'' cis'2 | c'' c'
@end lilypond
+@item @code{modern-cautionary}
+@cindex @code{modern-cautionary}
+This rule is similar to @code{modern}, but the ``extra'' accidentals
+(the ones not typeset by @code{default}) are typeset as cautionary
+accidentals. They are printed in reduced size or with parentheses
+@lilypond[quote,raggedright,fragment,verbatim]
+#(set-accidental-style 'modern-cautionary)
+cis' c'' cis'2 | c'' c'
+@end lilypond
-@node Educational use
-@section Educational use
+@cindex @code{modern-voice}
+@item modern-voice
+This rule is used for multivoice accidentals to be read both by musicians
+playing one voice and musicians playing all voices. Accidentals are
+typeset for each voice, but they @emph{are} canceled across voices in
+the same @internalsref{Staff}.
-With the amount of control that LilyPond offers, one can make great
-teaching tools in addition to great musical scores.
+@cindex @code{modern-voice-cautionary}
+@item modern-voice-cautionary
+This rule is the same as @code{modern-voice}, but with the extra
+accidentals (the ones not typeset by @code{voice}) typeset
+as cautionaries. Even though all accidentals typeset by
+@code{default} @emph{are} typeset by this variable,
+some of them are typeset as cautionaries.
-@menu
-* Balloon help::
-* Blank music sheet::
-* Hidden notes::
-* Shaped note heads ::
-* Easy Notation note heads::
-@end menu
+@item piano
+@cindex @code{piano} accidentals
+This rule reflects 20th century practice for piano notation. Very similar to
+@code{modern} but accidentals also get canceled
+across the staves in the same @internalsref{GrandStaff} or
+@internalsref{PianoStaff}.
-@node Balloon help
-@subsection Balloon help
+@item piano-cautionary
+@cindex @code{#(set-accidental-style 'piano-cautionary)}
+Same as @code{#(set-accidental-style 'piano)} but with the extra
+accidentals typeset as cautionaries.
-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.
+@item no-reset
+@cindex @code{no-reset} accidental style
+This is the same as @code{default} but with accidentals lasting
+``forever'' and not only until the next measure
+@lilypond[quote,raggedright,fragment,verbatim,relative=1]
+#(set-accidental-style 'no-reset)
+c1 cis cis c
+@end lilypond
-The following example demonstrates its use.
+@item forget
+This is sort of the opposite of @code{no-reset}: Accidentals
+are not remembered at all---and hence all accidentals are
+typeset relative to the key signature, regardless of what was
+before in the music
-@lilypond[quote,verbatim,fragment,raggedright,relative=2]
-\context Voice {
- \applyoutput
- #(add-balloon-text 'NoteHead "heads, or tails?"
- '(1 . -3))
- c8
-}
+@lilypond[quote,raggedright,fragment,verbatim,relative=1]
+#(set-accidental-style 'forget)
+\key d\major c4 c cis cis d d dis dis
@end lilypond
+@end table
-@noindent
-The function @code{add-balloon-text} takes the name of a grob, the
-label to print, and the position where to put the label relative to
-the object. In the above example, the text ``heads or tails?'' ends
-3 spaces below and 1 space to the right of the marked head.
-
-@cindex balloon
-@cindex notation, explaining
@seealso
-Program reference: @internalsref{text-balloon-interface}.
+Program reference: @internalsref{Accidental_engraver},
+@internalsref{Accidental}, and @internalsref{AccidentalPlacement}.
-Examples: @inputfileref{input/@/regression,balloon@/.ly}.
+@refbugs
+Simultaneous notes are considered to be entered in sequential
+mode. This means that in a chord the accidentals are typeset as if the
+notes in the chord happened once at a time - in the order in which
+they appear in the input file.
+This is a problem when accidentals in a chord depend on each other,
+which does not happen for the default accidental style. The problem
+can be solved by manually inserting @code{!} and @code{?} for the
+problematic notes.
-@node Blank music sheet
-@subsection Blank music sheet
-A blank music sheet can be produced also by using invisible notes, and
-removing @code{Bar_number_engraver}.
+@node Setting automatic beam behavior
+@subsection Setting automatic beam behavior
+@cindex @code{autoBeamSettings}
+@cindex @code{(end * * * *)}
+@cindex @code{(begin * * * *)}
+@cindex automatic beams, tuning
+@cindex tuning automatic beaming
-@lilypond[quote,verbatim]
-emptymusic = {
- \repeat unfold 2 % Change this for more lines.
- { s1\break }
- \bar "|."
-}
-\new Score \with {
- \override TimeSignature #'transparent = ##t
- defaultBarType = #""
- \remove Bar_number_engraver
-} <<
- \context Staff \emptymusic
- \context TabStaff \emptymusic
->>
-@end lilypond
+@c [TODO: use \applycontext]
+In normal time signatures, automatic beams can start on any note but can
+only end in a few positions within the measure: beams can end on a beat,
+or at durations specified by the properties in
+@code{autoBeamSettings}. The properties in @code{autoBeamSettings}
+consist of a list of rules for where beams can begin and end. The
+default @code{autoBeamSettings} rules are defined in
+@file{scm/@/auto@/-beam@/.scm}.
-@node Hidden notes
-@subsection Hidden notes
+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
-@cindex Hidden notes
-@cindex Invisible notes
-@cindex Transparent notes
+@itemize @bullet
-@cindex @code{\hideNotes}
-@cindex @code{\unHideNotes}
-Hidden (or invisible or transparent) notes can be useful in preparing theory
-or composition exercises.
+@item @code{be} is either "begin" or "end".
-@lilypond[quote,raggedright,verbatim,relative=2,fragment]
-c4 d4
-\hideNotes
-e4 f4
-\unHideNotes
-g4 a
-@end lilypond
+@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.
-Hidden notes are also great for performing weird tricks. For example,
-slurs cannot be attached to rests or spacer rests, but you may wish
-to include that in your score -- string instruments use this notation
-when doing pizzicato to indicate that the note should ring for as long
-as possible.
+@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.
-@lilypond[quote,raggedright,verbatim,relative=0,fragment]
-\clef bass
-<< {
- c4^"pizz"( \hideNotes c)
- \unHideNotes c( \hideNotes c)
-} {
- s4 r s r
-} >>
-@end lilypond
+@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)}.
-@node Shaped note heads
-@subsection Shaped note heads
+@end itemize
-In shaped 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.
+For example, if automatic beams should always end on the first quarter
+node, use
-Shaped note heads can be produced by setting @code{\aikenHeads} or
-@code{\sacredHarpHeads}, depending on the style desired.
+@example
+#(override-auto-beam-setting '(end * * * *) 1 4)
+@end example
-@lilypond[verbatim,relative=1,fragment]
- \aikenHeads
- c8 d4 e8 a2 g1
- \sacredHarpHeads
- c8 d4. e8 a2 g1
+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
-Shapes are determined on the step in the scale, where the base of the
-scale is determined by the @code{\key} command
+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
-@findex \key
-@findex shapeNoteStyles
-@findex \aikenHeads
-@findex \sacredHarpHeads
+You can also remove a previously set beam-ending rule by using
-Shaped note heads are implemented through the @code{shapeNoteStyles}
-property. Its value is a vector of symbols. The k-th element indicates
-the style to use for the k-th step of the scale. Arbitrary
-combinations are possible, eg.,
+@example
+#(revert-auto-beam-setting '(be p q n m) a b [context])
+@end example
+@noindent
+be, p, q, n, m, a, b and context are the same as above. Note that the
+default rules are specified in @file{scm/@/auto@/-beam@/.scm},
+so you can revert rules that you did not explicitly create.
+
+@lilypond[quote,fragment,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
-@lilypond[verbatim,relative=1,fragment]
- \set shapeNoteStyles = ##(cross triangle fa #f mensural xcircle diamond)
- c8 d4. e8 a2 g1
+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
-@node Easy Notation note heads
-@subsection Easy Notation note heads
-@cindex easy notation
-@cindex Hal Leonard
+@c TODO: old material -- not covered by above stuff, I think.
+If automatic beams should end on every quarter in 5/4 time, specify
+all endings
+@example
+#(override-auto-beam-setting '(end * * * *) 1 4 'Staff)
+#(override-auto-beam-setting '(end * * * *) 1 2 'Staff)
+#(override-auto-beam-setting '(end * * * *) 3 4 'Staff)
+#(override-auto-beam-setting '(end * * * *) 5 4 'Staff)
+@dots{}
+@end example
-The `easy play' note head includes a note name inside the head. It is
-used in music for beginners
+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).
-@lilypond[quote,raggedright,verbatim,fragment,staffsize=26]
- \setEasyHeads
- c'2 e'4 f' | g'1
-@end lilypond
+@cindex automatic beam generation
+@cindex autobeam
+@cindex @code{autoBeaming}
+@cindex lyrics
+
+If beams are used to indicate melismata in songs, then automatic
+beaming should be switched off with @code{\autoBeamOff}.
-The command @code{\setEasyHeads} overrides settings for the
-@internalsref{NoteHead} object. To make the letters readable, it has
-to be printed in a large font size. To print with a larger font, see
-@ref{Setting global staff size}.
@refcommands
-@cindex @code{\setEasyHeads}
-@code{\setEasyHeads}
+@cindex @code{\autoBeamOff}
+@code{\autoBeamOff},
+@cindex @code{\autoBeamOn}
+@code{\autoBeamOn}.
+
+
+@refbugs
+
+If a score ends while an automatic beam has not been ended and is
+still accepting notes, this last beam will not be typeset at all. The
+same holds polyphonic voices, entered with @code{<< @dots{} \\ @dots{}
+>>}. If a polyphonic voice ends while an automatic beam is still
+accepting notes, it is not typeset.
projects / lilypond.git / blobdiff