@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::
+* Even more than notes::
+* 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.
+@c really bad section name. :(
+@node Even more than notes
+@section Even more than 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
-
-Expressive marks help musicians to bring more to the music than simple
-notes and rhythms.
-
-@menu
-* Metronome marks::
* Text scripts::
* Text spanners::
-* Analysis brackets::
-* Articulations::
+* Transpose::
+* Ottava brackets::
+* Multi measure rests::
+* Time administration::
@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
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 Transpose
+@subsection Transpose
+@cindex Transpose
+@cindex transposition of pitches
+@cindex @code{\transpose}
-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}
+A music expression can be transposed with @code{\transpose}. The
+syntax is
+@example
+\transpose @var{from} @var{to} @var{musicexpr}
+@end example
+
+This means that @var{musicexpr} is transposed by the interval between
+the pitches @var{from} and @var{to}: any note with pitch @code{from}
+is changed to @code{to}.
+
+
+For example, consider a piece written in the key of D-major. If
+this piece is a little too low for its performer, it can be
+transposed up to E-major with
+@example
+\transpose d e @dots{}
+@end example
+
+Consider a part written for violin (a C instrument). If
+this part is to be played on the A clarinet, the following
+transposition will produce the appropriate part
+
+@example
+\transpose a c @dots{}
+@end example
+
+@code{\transpose} distinguishes between enharmonic pitches: both
+@code{\transpose c cis} or @code{\transpose c des} will transpose up
+half a tone. The first version will print sharps and the second
+version will print flats
@lilypond[quote,raggedright,verbatim]
-\score {
- \relative c'' {
- c4\startGroup\startGroup
- c4\stopGroup
- c4\startGroup
- c4\stopGroup\stopGroup
- }
- \layout {
- \context {
- \Staff \consists "Horizontal_bracket_engraver"
-}}}
+mus = { \key d \major cis d fis g }
+\context Staff {
+ \clef "F" \mus
+ \clef "G"
+ \transpose c g' \mus
+ \transpose c f' \mus
+}
@end lilypond
-@seealso
+@code{\transpose} may also be used to input written notes for a
+transposing instrument. Pitches are normally entered into LilyPond
+in C (or ``concert pitch''), but they may be entered in another
+key. For example, when entering music for a B-flat trumpet which
+begins on concert D, one would write
-Program reference: @internalsref{HorizontalBracket},
-@internalsref{NoteGroupingEvent}.
+@example
+\transpose c bes @{ e4 @dots{} @}
+@end example
-Examples: @inputfileref{input/@/regression,note@/-group@/-bracket@/.ly}.
+To print this music in B-flat again (ie producing a trumpet part,
+instead of a concert pitch conductor's score) you would wrap the
+existing music with another @code{transpose}
+@example
+\transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @}
+@end example
-@node Articulations
-@subsection Articulations
-@cindex Articulations
-@cindex articulations
-@cindex scripts
-@cindex ornaments
+@seealso
-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
+Program reference: @internalsref{TransposedMusic}, and
+@internalsref{UntransposableMusic}.
-@lilypondfile[quote,raggedright]{script-abbreviations.ly}
+@refbugs
-The meanings of these shorthands can be changed. See
-@file{ly/@/script@/-init@/.ly} for examples.
+If you want to use both @code{\transpose} and @code{\relative},
+you must put @code{\transpose} outside of @code{\relative}, since
+@code{\relative} will have no effect music that appears inside a
+@code{\transpose}.
-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 Ottava brackets
+@subsection Ottava brackets
+`Ottava' brackets introduce an extra transposition of an octave for
+the staff. They are created by invoking the function
+@code{set-octavation}
-@lilypond[quote,raggedright,fragment,verbatim]
-c''4^^ c''4_^
+@cindex ottava
+@cindex 15ma
+@cindex octavation
+
+@lilypond[quote,raggedright,verbatim,fragment]
+\relative c''' {
+ a2 b
+ #(set-octavation 1)
+ a b
+ #(set-octavation 0)
+ a b
+}
@end lilypond
-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.,
+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,fragment,relative=2]
-c\fermata c^\fermata c_\fermata
+@lilypond[quote,raggedright,verbatim]
+{
+ #(set-octavation 1)
+ \set Staff.ottavation = #"8"
+ c'''
+}
@end lilypond
+@seealso
+Program reference: @internalsref{OttavaBracket}.
-@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
+Examples: @inputfileref{input/@/regression,ottava@/.ly},
+@inputfileref{input/@/regression,ottava@/-broken@/.ly}.
-Here is a chart showing all scripts available,
+@refbugs
-@lilypondfile[raggedright,quote]{script-chart.ly}
+@code{set-octavation} will get confused when clef changes happen
+during an octavation bracket.
-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.
+@node Multi measure rests
+@subsection Multi measure rests
+@cindex multi measure rests
+@cindex Rests, multi measure
+@cindex @code{R}
-@lilypond[verbatim,relative=3,raggedright,fragment,quote]
-\once \override TextScript #'script-priority = #-100
-a4^\prall^\markup { \sharp }
+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
+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
-\once \override Script #'script-priority = #-100
-a4^\prall^\markup { \sharp }
+@lilypond[quote,raggedright,fragment,verbatim]
+\time 4/4 r1 | R1 | R1*2
+\set Score.skipBars = ##t R1*17 R1*4
@end lilypond
+The @code{1} in @code{R1} is similar to the duration notation used for
+notes. Hence, for time signatures other than 4/4, you must enter other
+durations. This can be done with augmentation dots or fractions
+@lilypond[quote,raggedright,fragment,verbatim]
+\set Score.skipBars = ##t
+\time 3/4
+R2. | R2.*2
+\time 13/8
+R1*13/8
+R1*13/8*12 |
+\time 10/8 R4*5*4 |
+@end lilypond
+An @code{R} spanning a single measure is printed as either a whole rest
+or a breve, centered in the measure regardless of the time signature.
+
+If there are only a few measures of rest, LilyPond prints ``church rests''
+(a series of rectangles) in the staff. To replace that with a simple
+rest, use @code{MultiMeasureRest.expand-limit}.
+
+@lilypond[quote,raggedright,fragment,verbatim]
+\set Score.skipBars = ##t
+R1*2 | R1*5 | R1*9
+\override MultiMeasureRest #'expand-limit = 1
+R1*2 | R1*5 | R1*9
+@end lilypond
+
+
+@cindex text on multi-measure rest
+@cindex script on multi-measure rest
+@cindex fermata on multi-measure rest
+
+Texts can be added to multi-measure rests by using the
+@var{note}-@code{markup} syntax (see @ref{Text markup}).
+A variable (@code{\fermataMarkup}) is provided for
+adding fermatas
+
+@lilypond[quote,raggedright,verbatim,fragment]
+\set Score.skipBars = ##t
+\time 3/4
+R2.*10^\markup { \italic "ad lib." }
+R2.^\fermataMarkup
+@end lilypond
+
+If you want to have text on the left end of a multi-measure rest,
+attach the text to a zero-length skip note, i.e.,
+
+@example
+s1*0^"Allegro"
+R1*4
+@end example
+
+
+@cindex whole rests for a full measure
@seealso
-Program reference: @internalsref{ScriptEvent}, and @internalsref{Script}.
+Program reference: @internalsref{MultiMeasureRestEvent},
+@internalsref{MultiMeasureTextEvent},
+@internalsref{MultiMeasureRestMusicGroup}, and
+@internalsref{MultiMeasureRest}.
+
+The layout object @internalsref{MultiMeasureRestNumber} is for the
+default number, and @internalsref{MultiMeasureRestText} for user
+specified texts.
@refbugs
-These signs appear in the printed output but have no effect on the
-MIDI rendering of the music.
+It is not possible to use fingerings (e.g., @code{R1-4}) to put numbers
+over multi-measure rests. And the pitch of multi-measure rests (or
+staff-centered rests) can not be influenced.
+@cindex condensing rests
+There is no way to automatically condense multiple rests into a single
+multi-measure rest. Multi-measure rests do not take part in rest
+collisions.
+
+Be careful when entering multi-measure rests followed by whole
+notes. The following will enter two notes lasting four measures each
+@example
+R1*4 cis cis
+@end example
+When @code{skipBars} is set, the result will look OK, but the bar
+numbering will be off.
+@node Time administration
+@subsection Time administration
+Time is administered by the @internalsref{Time_signature_engraver},
+which usually lives in the @internalsref{Score} context.
+The bookkeeping deals with the following variables
+@table @code
+@item currentBarNumber
+The measure number.
+
+@item measureLength
+The length of the measures in the current time signature. For a 4/4
+time this is@tie{}1, and for 6/8 it is 3/4.
+
+@item measurePosition
+The point within the measure where we currently are. This quantity
+is reset to@tie{}0 whenever it exceeds @code{measureLength}. When that
+happens, @code{currentBarNumber} is incremented.
+
+@item timing
+If set to true, the above variables are updated for every time
+step. When set to false, the engraver stays in the current measure
+indefinitely.
+@end table
+
+Timing can be changed by setting any of these variables explicitly.
+In the next example, the 4/4 time signature is printed, but
+@code{measureLength} is set to 5/4. After a while, the measure is
+shortened by 1/8, by setting @code{measurePosition} to 7/8 at 2/4
+in the measure, so the next bar line will fall at 2/4 + 3/8. The
+3/8 arises because 5/4 normally has 10/8, but we have manually
+set the measure position to be 7/8 and 10/8 - 7/8 = 3/8.
+
+@lilypond[quote,raggedright,verbatim,relative,fragment]
+\set Score.measureLength = #(ly:make-moment 5 4)
+c1 c4
+c1 c4
+c4 c4
+\set Score.measurePosition = #(ly:make-moment 7 8)
+b8 b b
+c4 c1
+@end lilypond
-@node Orchestral music
-@section Orchestral music
-@cindex Writing parts
+@node Preparing parts
+@section Preparing parts
+
+This section describes various notation that are useful for preparing
+individual parts.
+
+@menu
+* Metronome marks::
+* Rehearsal marks::
+* Bar numbers::
+* Instrument names::
+* Instrument transpositions::
+* Different editions from one source::
+@end menu
+
+
+@node Metronome marks
+@subsection Metronome marks
+
+@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
+
+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
-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.
+@noindent
+See @ref{Text markup} for more details.
+@seealso
-@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
+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 Rehearsal marks
@code{padding} property of @internalsref{BarNumber} can be
used to position the number correctly.
+
@node Instrument names
@subsection Instrument names
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
+@cindex transposition, MIDI
+@cindex transposition, instrument
The key of a transposing instrument can also be specified. This
applies to many wind instruments, for example, clarinets (B-flat, A, and
@end example
+@node Different editions from one source
+@subsection Different editions from one source
-@cindex transposition, MIDI
-@cindex transposition, instrument
-
-
-@node Multi measure rests
-@subsection Multi measure rests
-@cindex multi measure rests
-@cindex Rests, multi 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
-multi-measure rest. This expansion is controlled by the property
-@code{Score.skipBars}. If this is set to true, empty measures will not
-be expanded, and the appropriate number is added automatically
-
-@lilypond[quote,raggedright,fragment,verbatim]
-\time 4/4 r1 | R1 | R1*2
-\set Score.skipBars = ##t R1*17 R1*4
-@end lilypond
-
-The @code{1} in @code{R1} is similar to the duration notation used for
-notes. Hence, for time signatures other than 4/4, you must enter other
-durations. This can be done with augmentation dots or fractions
-
-@lilypond[quote,raggedright,fragment,verbatim]
-\set Score.skipBars = ##t
-\time 3/4
-R2. | R2.*2
-\time 13/8
-R1*13/8
-R1*13/8*12 |
-\time 10/8 R4*5*4 |
-@end lilypond
-
-An @code{R} spanning a single measure is printed as either a whole rest
-or a breve, centered in the measure regardless of the time signature.
+@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.
-If there are only a few measures of rest, LilyPond prints ``church rests''
-(a series of rectangles) in the staff. To replace that with a simple
-rest, use @code{MultiMeasureRest.expand-limit}.
+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[quote,raggedright,fragment,verbatim]
-\set Score.skipBars = ##t
-R1*2 | R1*5 | R1*9
-\override MultiMeasureRest #'expand-limit = 1
-R1*2 | R1*5 | R1*9
-@end lilypond
+@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
-@cindex text on multi-measure rest
-@cindex script on multi-measure rest
-@cindex fermata on multi-measure rest
+This defines a note with a conditional fingering indication.
-Texts can be added to multi-measure rests by using the
-@var{note}-@code{markup} syntax (see @ref{Text markup}).
-A variable (@code{\fermataMarkup}) is provided for
-adding fermatas
+@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
-@lilypond[quote,raggedright,verbatim,fragment]
-\set Score.skipBars = ##t
-\time 3/4
-R2.*10^\markup { \italic "ad lib." }
-R2.^\fermataMarkup
-@end lilypond
+@lilypondfile[raggedright,quote]{tag-filter.ly}
-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.,
+The argument of the @code{\tag} command should be a symbol, or a list
+of symbols, for example,
@example
-s1*0^"Allegro"
-R1*4
+\tag #'(original-part transposed-part) @dots{}
@end example
-@cindex whole rests for a full measure
@seealso
-Program reference: @internalsref{MultiMeasureRestEvent},
-@internalsref{MultiMeasureTextEvent},
-@internalsref{MultiMeasureRestMusicGroup}, and
-@internalsref{MultiMeasureRest}.
-
-The layout object @internalsref{MultiMeasureRestNumber} is for the
-default number, and @internalsref{MultiMeasureRestText} for user
-specified texts.
+Examples: @inputfileref{input/@/regression,tag@/-filter@/.ly}.
@refbugs
-It is not possible to use fingerings (e.g., @code{R1-4}) to put numbers
-over multi-measure rests. And the pitch of multi-measure rests (or
-staff-centered rests) can not be influenced.
+Multiple rests are not merged if you create the score with both tagged
+sections.
+
-@cindex condensing rests
+@node Orchestral music
+@section Orchestral music
-There is no way to automatically condense multiple rests into a single
-multi-measure rest. Multi-measure rests do not take part in rest
-collisions.
+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
-Be careful when entering multi-measure rests followed by whole
-notes. The following will enter two notes lasting four measures each
-@example
-R1*4 cis cis
-@end example
-When @code{skipBars} is set, the result will look OK, but the bar
-numbering will be off.
@node 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
@end example
-
The following example demonstrates the basic functionality of the part
combiner: putting parts on one staff, and setting stem directions and
polyphony
removed from the first system too, set @code{remove-first} to false in
@internalsref{RemoveEmptyVerticalGroup}.
+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 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.
-
-In the following example, we see two versions of a piece of music, one
-for the full score, and one with cue notes for the instrumental part
-
-@example
-c1
-<<
- \tag #'part <<
- R1 \\
- @{
- \set fontSize = #-1
- c4_"cue" f2 g4 @}
- >>
- \tag #'score R1
->>
-c1
-@end example
-
-The same can be applied to articulations, texts, etc.: they are
-made by prepending
-@example
--\tag #@var{your-tag}
-@end example
-to an articulation, for example,
-@example
-c1-\tag #'part ^4
-@end example
-
-This defines a note with a conditional fingering indication.
-
-@cindex keepWithTag
-@cindex removeWithTag
-By applying the @code{\keepWithTag} and @code{\removeWithTag}
-commands, tagged expressions can be filtered. For example,
-@example
-<<
- @var{the music}
- \keepWithTag #'score @var{the music}
- \keepWithTag #'part @var{the music}
->>
-@end example
-would yield
-
-@lilypondfile[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
+staff. See @inputfileref{input/@/test,ossia@/.ly} for an example.
-Multiple rests are not merged if you create the score with both tagged
-sections.
-
@node Quoting other voices
@subsection Quoting other voices
Program reference: @internalsref{QuoteMusic}.
+
@node Formatting cue notes
@subsection Formatting cue notes
@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
+
* Hidden notes::
* Shaped note heads ::
* Easy Notation note heads::
+* Analysis brackets::
@end menu
@node Balloon help
@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.
@code{\setEasyHeads}
+@node Analysis brackets
+@subsection Analysis brackets
+@cindex brackets
+@cindex phrasing brackets
+@cindex musicological analysis
+@cindex note grouping bracket
+
+Brackets are used in musical analysis to indicate structure in musical
+pieces. LilyPond supports a simple form of nested horizontal
+brackets. To use this, add the @internalsref{Horizontal_bracket_engraver}
+to @internalsref{Staff} context. A bracket is started with
+@code{\startGroup} and closed with @code{\stopGroup}
+
+@lilypond[quote,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},
+@internalsref{NoteGroupingEvent}.
+
+Examples: @inputfileref{input/@/regression,note@/-group@/-bracket@/.ly}.
+
+
+
+@ignore
+
+I don't think we need this info.
+
+@n ode Stems
+@s ubsection Stems
+
+Whenever a note is found, a @internalsref{Stem} object is created
+automatically. For whole notes and rests, they are also created but
+made invisible.
+
+@refcommands
+
+@cindex @code{\stemUp}
+@code{\stemUp},
+@cindex @code{\stemDown}
+@code{\stemDown},
+@cindex @code{\stemNeutral}
+@code{\stemNeutral}.
+
+@end ignore
+
+
+
+
+@ignore
+
+FIXME: We don't need this section. It will be moved into LSR as soon
+as the safe mode stuff is worked out.
+
+@n ode Controlling formatting of prefatory matter
+@s ubsection Controlling formatting of prefatory matter
+
+@c This section will be moved to somewhere else soon. -gp
+This example demonstrates how to place prefatory matter
+(such as the clef and key signature) at the end of a line.
+
+@lilypond[quote,verbatim]
+\transpose c c' {
+ \override Staff.Clef
+ #'break-visibility = #end-of-line-visible
+ \override Staff.KeySignature
+ #'break-visibility = #end-of-line-visible
+ \set Staff.explicitClefVisibility = #end-of-line-visible
+ \set Staff.explicitKeySignatureVisibility = #end-of-line-visible
+
+ % We want the time sig to take space, otherwise there is not
+ % enough white at the start of the line.
+
+ \override Staff.TimeSignature #'transparent = ##t
+ \set Score.defaultBarType = #"empty"
+
+ c1 d e f g a b c
+ \key d \major
+ \break
+
+ % see above.
+ \time 4/4
+
+ d e fis g a b cis d
+ \key g \major
+ \break
+ \time 4/4
+}
+@end lilypond
+
+@end ignore
+
+
+
+@node Automatic notation
+@section Automatic notation
+
+This section describes how to change the way that accidentals and
+beams are automatically displayed.
+
+FIXME: this might get moved into Changing Defaults. Please send
+opinions to lilypond-devel. Thanks! :)
+
+@menu
+* Automatic accidentals::
+* Setting automatic beam behavior::
+* Beam formatting::
+@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 Setting automatic beam behavior
+@subsection Setting automatic beam behavior
+
+@cindex @code{autoBeamSettings}
+@cindex @code{(end * * * *)}
+@cindex @code{(begin * * * *)}
+@cindex automatic beams, tuning
+@cindex tuning automatic beaming
+
+@c [TODO: use \applycontext]
+
+In normal time signatures, automatic beams can start on any note but can
+only end in a few positions within the measure: beams can end on a beat,
+or at durations specified by the properties in
+@code{autoBeamSettings}. The defaults for @code{autoBeamSettings}
+are defined in @file{scm/@/auto@/-beam@/.scm}.
+
+The value of @code{autoBeamSettings} is changed with three functions,
+@example
+#(override-auto-beam-setting
+ '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b}
+ [@var{context}])
+#(score-override-auto-beam-setting
+ '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b})
+#(revert-auto-beam-setting '(@var{be} @var{p} @var{q} @var{n} @var{m})
+ [@var{context}])
+@end example
+Here, @var{be} is the symbol @code{begin} or @code{end}, and
+@var{context} is an optional context (default: @code{'Voice}). It
+determines whether the rule applies to begin or end-points. The
+quantity @var{p}/@var{q} refers to the length of the beamed notes (and
+`@code{* *}' designates notes of any length), @var{n}/@var{M} refers
+to a time signature (wildcards `@code{* *}' may be entered to
+designate all time signatures), @var{a}/@var{b} is a duration. By
+default, this command changes settings for the current voice. It is
+also possible to adjust settings at higher contexts, by adding a
+@var{context} argument. @code{score-override-auto-beam-setting} is
+equal to @code{override-auto-beam-setting} with the argument
+@var{context} set to @code{'Score}.
+
+For example, if automatic beams should end on every quarter note, use
+the following
+@example
+#(override-auto-beam-setting '(end * * * *) 1 4 'Staff)
+@end example
+Since the duration of a quarter note is 1/4 of a whole note, it is
+entered as @code{(ly:make-moment 1 4)}.
+
+The same syntax can be used to specify beam starting points. In this
+example, automatic beams can only end on a dotted quarter note
+@example
+#(override-auto-beam-setting '(end * * * *) 3 8)
+@end example
+In 4/4 time signature, this means that automatic beams could end only on
+3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
+3/8, has passed within the measure).
+
+Rules can also be restricted to specific time signatures. A rule that
+should only be applied in @var{N}/@var{M} time signature is formed by
+replacing the second asterisks by @var{N} and @var{M}. For example, a
+rule for 6/8 time exclusively looks like
+@example
+#(override-auto-beam-setting '(begin * * 6 8) @dots{})
+@end example
+
+If a rule should be to applied only to certain types of beams, use the
+first pair of asterisks. Beams are classified according to the
+shortest note they contain. For a beam ending rule that only applies
+to beams with 32nd notes (and no shorter notes), use @code{(end 1 32 *
+*)}.
+
+@cindex automatic beam generation
+@cindex autobeam
+@cindex @code{autoBeaming}
+@cindex lyrics
+
+If beams are used to indicate melismata in songs, then automatic
+beaming should be switched off. This is done by setting
+@code{autoBeaming} to @code{#f}.
+
+@refcommands
+
+@cindex @code{\autoBeamOff}
+@code{\autoBeamOff},
+@cindex @code{\autoBeamOn}
+@code{\autoBeamOn}.
+
+
+@refbugs
+
+If a score ends while an automatic beam has not been ended and is
+still accepting notes, this last beam will not be typeset at all. The
+same holds polyphonic voices, entered with @code{<< @dots{} \\ @dots{}
+>>}. If a polyphonic voice ends while an automatic beam is still
+accepting notes, it is not typeset.
+
+The rules for ending a beam depend on the shortest note in a beam.
+So, while it is possible to have different ending rules for eight
+beams and sixteenth beams, a beam that contains both eight and
+sixteenth notes will use the rules for the sixteenth beam.
+
+In the example below, the autobeamer makes eighth beams and sixteenth
+end at three eighths. The third beam can only be corrected by
+specifying manual beaming.
+
+@lilypond[quote,raggedright,fragment,relative=1]
+#(override-auto-beam-setting '(end * * * *) 3 8)
+% rather show case where it goes wrong
+%\time 12/8 c'8 c c c16 c c c c c c[ c c c] c8[ c] c4
+\time 12/8 c'8 c c c16 c c c c c c c c c c8 c c4
+@end lilypond
+It is not possible to specify beaming parameters that act differently in
+different parts of a measure. This means that it is not possible to use
+automatic beaming in irregular meters such as @code{5/8}.
+
+
+@node Beam formatting
+@subsection Beam formatting
+
+When a beam falls in the middle of the staff, the beams point normally
+down. However, this behaviour can be altered with the
+@code{neutral-direction} property.
+
+@lilypond[quote,raggedright,relative=2,fragment,verbatim]
+{
+ b8[ b]
+ \override Beam #'neutral-direction = #-1
+ b[ b]
+ \override Beam #'neutral-direction = #1
+ b[ b]
+}
+@end lilypond
+
projects / lilypond.git / blobdiff