From: Graham Percival Date: Mon, 28 Feb 2005 04:20:47 +0000 (+0000) Subject: Moved material from notation.itely X-Git-Tag: release/2.5.14~63 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=77c0027182a170dc3aea49ce826cb08aca3e7112;p=lilypond.git Moved material from notation.itely --- diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely index 3f717a8eb8..e0026e3de6 100644 --- a/Documentation/user/advanced-notation.itely +++ b/Documentation/user/advanced-notation.itely @@ -1,6 +1,1674 @@ @c -*- coding: latin-1; 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 is a placeholder for very-near future reorganization of the manual. +This chapter deals with rarely-used and advanced notation. + +@menu +* Accidentals:: +* Expressive stuff:: +* Orchestral music:: +* Contemporary notation:: +* Educational use:: +@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 + +Expressive marks help musicians to bring more to the music than simple +notes and rhythms. + +@menu +* Metronome marks:: +* Text scripts:: +* Text spanners:: +* Analysis brackets:: +@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 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 + +@lilypond[quote,fragment,raggedright,verbatim,relative=1] +c4^"longtext" \fatText c4_"longlongtext" c4 +@end lilypond + +More complex formatting may also be added to a note by using the +markup command, +@lilypond[fragment,raggedright,verbatim,quote] +c'4^\markup { bla \bold bla } +@end lilypond + +The @code{\markup} is described in more detail in +@ref{Text markup}. + + +@refcommands + +@cindex @code{\fatText} +@code{\fatText}, +@cindex @code{\emptyText} +@code{\emptyText}. + +@seealso + +In this manual: @ref{Text markup}. + +Program reference: @internalsref{TextScriptEvent}, @internalsref{TextScript}. + + +@node Text spanners +@subsection Text spanners +@cindex Text spanners + +Some performance indications, e.g., @i{rallentando} or @i{accelerando}, +are written as text and are extended over many measures with dotted +lines. Such texts are created using text spanners; attach +@code{\startTextSpan} and @code{\stopTextSpan} to the first and last +notes of the spanner. + +The string to be printed, as well as the style, is set through object +properties + +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +c1 +\override TextSpanner #'direction = #-1 +\override TextSpanner #'edge-text = #'("rall " . "") +c2\startTextSpan b c\stopTextSpan a +@end lilypond + + +@seealso + +Internals @internalsref{TextSpanEvent}, +@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 + +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}. + + +@node Articulations +@subsection Articulations +@cindex Articulations + +@cindex articulations +@cindex scripts +@cindex ornaments + +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 + +@lilypondfile[quote,raggedright]{script-abbreviations.ly} + +The meanings of these shorthands can be changed. See +@file{ly/@/script@/-init@/.ly} for examples. + + +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. + + +@lilypond[quote,raggedright,fragment,verbatim] +c''4^^ c''4_^ +@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., + +@lilypond[quote,raggedright,verbatim,fragment,relative=2] +c\fermata c^\fermata c_\fermata +@end 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 + +Here is a chart showing all scripts available, + +@lilypondfile[raggedright,quote]{script-chart.ly} + + +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. + + +@lilypond[verbatim,relative=3,raggedright,fragment,quote] +\once \override TextScript #'script-priority = #-100 +a4^\prall^\markup { \sharp } + +\once \override Script #'script-priority = #-100 +a4^\prall^\markup { \sharp } +@end lilypond + + + + +@seealso + +Program reference: @internalsref{ScriptEvent}, and @internalsref{Script}. + +@refbugs + +These signs appear in the printed output but have no effect on the +MIDI rendering of the music. + + + + + + + + +@node Orchestral music +@section Orchestral music + +@cindex Writing parts + +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 +* Aligning to cadenzas:: +* 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 + + + + +@node Rehearsal marks +@subsection Rehearsal marks +@cindex Rehearsal marks +@cindex mark +@cindex @code{\mark} + +To print a rehearsal mark, use the @code{\mark} command + +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +c1 \mark \default +c1 \mark \default +c1 \mark #8 +c1 \mark \default +c1 \mark \default +@end lilypond + +@noindent +(The letter@tie{}`I' is skipped in accordance with engraving traditions.) +@c umm, is the manual the right place for feature requests? :) -gp +@c FIXME - should make that tunable. + +The mark is incremented automatically if you use @code{\mark +\default}, but you can also use an integer argument to set the mark +manually. The value to use is stored in the property +@code{rehearsalMark}. + +The style is defined by the property @code{markFormatter}. It is a +function taking the current mark (an integer) and the current context +as argument. It should return a markup object. In the following +example, @code{markFormatter} is set to a canned procedure. After a +few measures, it is set to function that produces a boxed number. + +@lilypond[fragment,quote,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 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. + + +@cindex coda on bar line +@cindex segno on bar line +@cindex fermata on bar line +@cindex bar lines, symbols on + +The @code{\mark} command can also be used to put signs like coda, +segno, and fermata on a bar line. Use @code{\markup} to +access the appropriate symbol + +@lilypond[fragment,quote,raggedright,verbatim,relative=2] +c1 \mark \markup { \musicglyph #"scripts.ufermata" } +c1 +@end lilypond + +If the mark occurs at a line break, the mark will be printed at the +beginning of the next line. +@c IMO this is a bug; hopefully it'll be fixed soon, so I can +@c delete this sentence. -gp +If there is no next line, then the mark will not be printed at all. +To print the mark at the end of the current line, use + +@example +\override Score.RehearsalMark + #'break-visibility = #begin-of-line-invisible +@end example + +@cindex fermatas +@cindex coda +@cindex segno +@cindex bar lines, putting symbols on + +@seealso + +Program reference: @internalsref{MarkEvent}, @internalsref{RehearsalMark}. + +Init files: @file{scm/@/translation@/-functions@/.scm} contains the +definition of @code{format-mark-numbers} and +@code{format-mark-letters}. They can be used as inspiration for other +formatting functions. + +Examples: @inputfileref{input/@/regression,rehearsal@/-mark@/-letter@/.ly}, + +@inputfileref{input/@/regression,rehearsal@/-mark@/-number@/.ly}. + + +@node Bar numbers +@subsection Bar numbers + + +@cindex Bar numbers +@cindex measure numbers +@cindex @code{currentBarNumber} + +Bar numbers are printed by default at the start of the line. The +number itself is stored in the @code{currentBarNumber} property, which +is normally updated automatically for every measure. + +Bar numbers can be typeset at regular intervals instead of at the +beginning of each line. This is illustrated in the following example, +whose source is available as +@inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly} + +@lilypondfile[raggedright,quote]{bar-number-regular-interval.ly} + +Bar numbers can be typeset manually by tweaking the +@code{markFormatter} property + +@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 + +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 + +Program reference: @internalsref{BarNumber}. + +Examples: +@inputfileref{input/@/test,bar@/-number@/-every@/-five@/-reset@/.ly}, +and @inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}. + +@refbugs + +Bar numbers can collide with the @internalsref{StaffGroup} bracket, if +there is one at the top. To solve this, the +@code{padding} property of @internalsref{BarNumber} can be +used to position the number correctly. + +@node Instrument names +@subsection Instrument names + +In an orchestral score, instrument names are printed at the left side +of the staves. + +This can be achieved by setting @internalsref{Staff}.@code{instrument} +and @internalsref{Staff}.@code{instr}. This will print a string before +the start of the staff. For the first staff, @code{instrument} is +used, for the following ones, @code{instr} is used. + +@lilypond[quote,verbatim,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 + +@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 + +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 + +The key of a transposing instrument can also be specified. This +applies to many wind instruments, for example, clarinets (B-flat, A, and +E-flat), horn (F) and trumpet (B-flat, C, D, and E-flat). + +The transposition is entered after the keyword @code{\transposition} + +@example +\transposition bes %% B-flat clarinet +@end example + +@noindent +This command sets the property @code{instrumentTransposition}. The value of +this property is used for MIDI output and quotations. It does not +affect how notes are printed in the current staff. To change the printed +output, see @ref{Transpose}. + +The pitch to use for @code{\transposition} should correspond to the +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 + +@example +clarinet = @{ + \transposition c' + ... +@} +saxophone = @{ + \transposition c' + ... +@} +@end example + +The command @code{\transposition} should be used when the music is +entered from a (transposed) orchestral part. For example, in +classical horn parts, the tuning of the instrument is often changed +during a piece. When copying the notes from the part, use +@code{\transposition}, e.g., + +@example +\transposition d' +c'4^"in D" +... +\transposition g' +c'4^"in G" +... +@end example + + + +@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. + +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{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 + +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 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}, +@internalsref{SoloOneEvent}, and +@internalsref{SoloTwoEvent}, and +@internalsref{UnisonoEvent}. + +@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 false in +@internalsref{RemoveEmptyVerticalGroup}. + +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 + +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 + + +@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 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:: +* Clusters:: +* Special fermatas:: +* 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" + \bracket \column { "5" "8" } + } +} + +{ + \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_engraver} to the @internalsref{Staff} +context. + +@example +\layout @{ + \context @{ \Score \remove "Timing_engraver" @} + \context @{ \Staff \consists "Timing_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_engraver" } + \context{ \Staff \consists "Timing_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 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 { } +@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}, and +@internalsref{ClusterNoteEvent}. + +Examples: @inputfileref{input/@/regression,cluster@/.ly}. + +@refbugs + +Music expressions like @code{<< @{ g8 e8 @} a4 >>} are not printed +accurately. Use @code{8 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 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] +\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:: +* Shaped note heads :: +* Easy Notation note heads:: +@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 + +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 Shaped note heads +@subsection Shaped note heads + +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. + +Shaped note heads can be produced by setting @code{\aikenHeads} or +@code{\sacredHarpHeads}, depending on the style desired. + +@lilypond[verbatim,relative=1,fragment] + \aikenHeads + c8 d4 e8 a2 g1 + \sacredHarpHeads + c8 d4. e8 a2 g1 +@end lilypond + +Shapes are determined on the step in the scale, where the base of the +scale is determined by the @code{\key} command + +@findex \key +@findex shapeNoteStyles +@findex \aikenHeads +@findex \sacredHarpHeads + +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., + + +@lilypond[verbatim,relative=1,fragment] + \set shapeNoteStyles = ##(cross triangle fa #f mensural xcircle diamond) + c8 d4. e8 a2 g1 +@end lilypond + + +@node Easy Notation note heads +@subsection Easy Notation note heads + +@cindex easy notation +@cindex Hal Leonard + +The `easy play' note head includes a note name inside the head. It is +used in music for beginners + +@lilypond[quote,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}. + +@refcommands + +@cindex @code{\setEasyHeads} +@code{\setEasyHeads} + + diff --git a/Documentation/user/basic-notation.itely b/Documentation/user/basic-notation.itely index d1af0cd0ee..bd3e94ef20 100644 --- a/Documentation/user/basic-notation.itely +++ b/Documentation/user/basic-notation.itely @@ -1,6 +1,3029 @@ @c -*- coding: latin-1; 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 Basic notation @chapter Basic notation -This is a placeholder for very-near future reorganization of the manual. +This chapter explains how to use all basic notation features. + +@menu +* Note entry:: +* Easier music entry:: +* Staff notation:: +* Polyphony:: +* Beaming:: +* Repeats:: +* Expressive marks:: +@end menu + + + +@node Note entry +@section Note entry +@cindex Note entry + +This section is about basic notation elements like notes, rests, and +related constructs, such as stems, tuplets and ties. + +@menu +* Notes:: +* Pitches:: +* Chromatic alterations:: +* Micro tones:: +* Chords:: +* Rests:: +* Skips:: +* Durations:: +* Augmentation dots:: +* Scaling durations:: +* Stems:: +* Ties:: +* Tuplets:: +* Transposition:: +@end menu + + +@node Notes +@subsection Notes + + +A note is printed by specifying its pitch and then its duration, + +@lilypond[quote,verbatim,raggedright] +{ cis'4 d'8 e'16 c'16 } +@end lilypond + + +@node Pitches +@subsection Pitches + +@cindex Pitch names +@cindex Note specification +@cindex pitches +@cindex entering notes + +The most common syntax for pitch entry is used for standard notes and +@code{\chordmode} modes. In these modes, pitches may be designated by +names. The notes are specified by the letters @code{a} through +@code{g}. The octave is formed with notes ranging from @code{c} +to @code{b}. The pitch @code{c} is an octave below middle C and the +letters span the octave above that C + +@lilypond[quote,fragment,verbatim] +\clef bass +a,4 b, c d e f g a b c' d' e' \clef treble f' g' a' b' c'' +@end lilypond + +@cindex note names, Dutch + +A sharp is formed by adding @code{-is} to the end of a pitch name and +a flat is formed by adding @code{-es}. Double sharps and double flats +are obtained by adding @code{-isis} or @code{-eses}. These +names are the Dutch note names. In Dutch, @code{aes} is contracted to +@code{as}, but both forms are accepted. Similarly, both +@code{es} and @code{ees} are accepted + +@lilypond[fragment,quote,raggedright,verbatim,relative=2] +ceses4 +ces +c +cis +cisis +@end lilypond + +In accordance with standard typsetting rules, a natural sign is printed +before a sharp or flat if a previous accidental needs to be +cancelled. To change this behaviour, use +@code{\set Staff.extraNatural = ##f} + +@lilypond[fragment,quote,raggedright,verbatim,relative=2] +ceses4 ces cis c +\set Staff.extraNatural = ##f +ceses4 ces cis c +@end lilypond + +There are predefined sets of note names for various other languages. +To use them, include the language specific init file. For +example: @code{\include "english.ly"}. The available language files +and the note names they define are + +@anchor{note name} +@anchor{note names} +@example + Note Names sharp flat +nederlands.ly c d e f g a bes b -is -es +english.ly c d e f g a bf b -s/-sharp -f/-flat + -x (double) +deutsch.ly c d e f g a b h -is -es +norsk.ly c d e f g a b h -iss/-is -ess/-es +svenska.ly c d e f g a b h -iss -ess +italiano.ly do re mi fa sol la sib si -d -b +catalan.ly do re mi fa sol la sib si -d/-s -b +espanol.ly do re mi fa sol la sib si -s -b +@end example + +@cindex @code{'} +@cindex @code{,} + + + +The optional octave specification takes the form of a series of +single quote (`@code{'}') characters or a series of comma +(`@code{,}') characters. Each @code{'} raises the pitch by one +octave; each @code{,} lowers the pitch by an octave + +@lilypond[quote,raggedright,fragment,verbatim] +c' c'' es' g' as' gisis' ais' +@end lilypond + + +@ignore +@c FIXME: we need this info (hide/unhide) somewhere in the manual, but this ain't the place. -gp +@c wait; this is already in advanced notation. +@refcommands +Notes can be hidden and unhidden with the following commands + +@cindex @code{\hideNotes} +@code{\hideNotes}, +@cindex @code{\unHideNotes} +@code{\unHideNotes}. +@end ignore + +@seealso + +Program reference: @internalsref{NoteEvent}, and @internalsref{NoteHead}. + + + +@node Chromatic alterations +@subsection Chromatic alterations + +Normally accidentals are printed automatically, but you may also +print them manually. A reminder accidental +@cindex reminder accidental +@cindex @code{?} +can be forced by adding an exclamation mark @code{!} +after the pitch. A cautionary accidental +@cindex cautionary accidental +@cindex parenthesized accidental +(i.e., an accidental within parentheses) can be obtained by adding the +question mark `@code{?}' after the pitch. + +@lilypond[quote,raggedright,fragment,verbatim] +cis' cis' cis'! cis'? +@end lilypond + + +@seealso + +The automatic production of accidentals can be tuned in many +ways. For more information, refer to @ref{Automatic accidentals}. + + + +@node Micro tones +@subsection Micro tones + +Half-flats and half-sharps are formed by adding @code{-eh} and +@code{-ih}; the following is a series of Cs with increasing pitches + +@cindex quarter tones +@cindex semi-flats, semi-sharps + +@lilypond[verbatim,raggedright,quote,relative=2,fragment] +{ ceseh ceh cih cisih } +@end lilypond + +Micro tones are also exported to the MIDI file + + +@refbugs + +There are no generally accepted standards for denoting three quarter +flats, so LilyPond's symbol does not conform to any standard. + +@node Chords +@subsection Chords + +A chord is formed by a enclosing a set of pitches in @code{<} and +@code{>}. A chord may be followed by a duration, and a set of +articulations, just like simple notes + +@lilypond[verbatim,raggedright,fragment,quote,relative=1] +4 8 +@end lilypond + +@node Rests +@subsection Rests +@cindex Rests + + +@cindex @code{\rest} +@cindex @code{r} + +Rests are entered like notes, with the note name @code{r} + +@lilypond[fragment,quote,raggedright,verbatim] +r1 r2 r4 r8 +@end lilypond + +Whole bar rests, centered in middle of the bar, +must be done with multi-measure rests. They are discussed in +@ref{Multi measure rests}. + + +A rest's vertical position may be explicitly specified by entering a +note with the @code{\rest} keyword appended, the rest will be placed at +the note's place. This makes manual formatting in polyphonic music +easier. Automatic rest collision formatting will leave these rests +alone + +@lilypond[fragment,quote,raggedright,verbatim] +a'4\rest d'4\rest +@end lilypond + +@seealso + +Program reference: @internalsref{RestEvent}, and @internalsref{Rest}. + + +@c FIXME: naming. +@node Skips +@subsection Skips +@cindex Skip +@cindex Invisible rest +@cindex Space note + +@cindex @code{\skip} +@cindex @code{s} +An invisible rest (also called a `skip') can be entered like a note +with note name `@code{s}' or with @code{\skip @var{duration}} + +@lilypond[fragment,quote,raggedright,verbatim,relative=2] +a4 a4 s4 a4 \skip 1 a4 +@end lilypond + +The @code{s} syntax is only available in note mode and chord mode. In +other situations, for example, when entering lyrics, you should use +the @code{\skip} command + +@lilypond[quote,raggedright,verbatim] +<< + \relative { a'2 a1 } + \new Lyrics \lyricmode { \skip 2 bla1 } +>> +@end lilypond + +The skip command is merely an empty musical placeholder. It does not +produce any output, not even transparent output. + +The @code{s} skip command does create @internalsref{Staff} and +@internalsref{Voice} when necessary, similar to note and rest +commands. For example, the following results in an empty staff. + +@lilypond[quote,raggedright,verbatim] +{ s4 } +@end lilypond + +The fragment @code{@{ \skip 4 @} } would produce an empty page. + +@seealso + +Program reference: @internalsref{SkipEvent}, @internalsref{SkipMusic}. + + + +@node Durations +@subsection Durations + + +@cindex duration +@cindex @code{\longa} +@cindex @code{\breve} +@cindex @code{\maxima} + + +In Note, Chord, and Lyrics mode, durations are designated by numbers and +dots: durations are entered as their reciprocal values. For example, a +quarter note is entered using a @code{4} (since it is a 1/4 note), while +a half note is entered using a @code{2} (since it is a 1/2 note). For +notes longer than a whole you must use the variables @code{\longa} and +@code{\breve} + +@example +c'\breve +c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 +r\longa r\breve +r1 r2 r4 r8 r16 r32 r64 r64 +@end example + +@lilypond[quote] +\score { + \relative c'' { + a\breve*1/2 \autoBeamOff + a1 a2 a4 a8 a16 a32 a64 a64 + \bar "empty" + \break + r\longa*1/4 r\breve *1/2 + r1 r2 r4 r8 r16 r32 r64 r64 + } + \layout { + raggedright = ##t + \context { + \Staff + \remove "Clef_engraver" + \override StaffSymbol #'transparent = ##t + \override TimeSignature #'transparent = ##t + \override BarLine #'transparent = ##t + \consists "Pitch_squash_engraver" + } + } +} +@end lilypond + +If the duration is omitted then it is set to the previously entered +duration. The default for the first note is a quarter note. + +@lilypond[quote,raggedright,verbatim,fragment] +{ a a a2 a a4 a a1 a } +@end lilypond + + + +@node Augmentation dots +@subsection Augmentation dots + +@cindex @code{.} +To obtain dotted note lenghts, simply add a dot (`@code{.}') to +the number. Double-dotted notes are produced in a similar way. + +@lilypond[quote,raggedright,fragment,verbatim] +a'4 b' c''4. b'8 a'4. b'4.. c''8. +@end lilypond + +@refcommands + +Dots are normally moved up to avoid staff lines, except in polyphonic +situations. The following commands may be used to force a particular +direction manually + +@cindex @code{\dotsUp} +@code{\dotsUp}, +@cindex @code{\dotsDown} +@code{\dotsDown}, +@cindex @code{\dotsNeutral} +@code{\dotsNeutral}. + +@seealso + +Program reference: @internalsref{Dots}, and @internalsref{DotColumn}. + +@node Scaling durations +@subsection Scaling durations + +You can alter the length of duration by a fraction @var{N/M} +appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This +will not affect the appearance of the notes or rests produced. + +In the following example, the first three notes take up exactly two +beats, but no triplet bracket is printed. +@lilypond[quote,raggedright,fragment,relative=2,verbatim] +\time 2/4 +a4*2/3 gis4*2/3 a4*2/3 +a4 a4 a4*2 +b16*4 c4 +@end lilypond + + +@seealso + +This manual: @ref{Tuplets} + + +@c TODO: I'm not certain that Stems belong here in the manual. -gp +@node Stems +@subsection 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}. + + +@node Ties +@subsection Ties + +@cindex Tie +@cindex ties +@cindex @code{~} + +A tie connects two adjacent note heads of the same pitch. The tie in +effect extends the length of a note. Ties should not be confused with +slurs, which indicate articulation, or phrasing slurs, which indicate +musical phrasing. A tie is entered using the tilde symbol `@code{~}' + +@lilypond[quote,raggedright,fragment,verbatim] +e' ~ e' ~ +@end lilypond + +When a tie is applied to a chord, all note heads whose pitches match +are connected. When no note heads match, no ties will be created. + +A tie is just a way of extending a note duration, similar to the +augmentation dot. The following example shows two ways of notating +exactly the same concept +@c +@lilypond[quote,fragment,raggedright] +\time 3/4 c'2. c'2 ~ c'4 +@end lilypond + +@noindent +Ties are used either when the note crosses a bar line, or when dots +cannot be used to denote the rhythm. When using ties, larger note +values should be aligned to subdivisions of the measure, eg. + +@lilypond[fragment,quote,raggedright] +\relative { + r8 c8 ~ c2 r4 | r8^"not" c2 ~ c8 r4 +} +@end lilypond + +If you need to tie a lot of notes over bars, it may be easier to use +automatic note splitting (see @ref{Automatic note splitting}). This +mechanism automatically splits long notes, and ties them across bar +lines. + +Ties are sometimes used to write out arpeggios. In this case, two tied +notes need not be consecutive. This can be achieved by setting the +@code{tieWaitForNote} property to true. For example, + +@lilypond[fragment,verbatim,relative=1,raggedright] +\set tieWaitForNote = ##t +\grace { c16[~ e~ g]~ } 4 +@end lilypond + + +@refcommands + + +@cindex @code{\tieUp} +@code{\tieUp}, +@cindex @code{\tieDown} +@code{\tieDown}, +@cindex @code{\tieNeutral} +@code{\tieNeutral}, +@cindex @code{\tieDotted} +@code{\tieDotted}, +@cindex @code{\tieSolid} +@code{\tieSolid}. + +@seealso + +In this manual: @ref{Automatic note splitting}. + +Program reference: @internalsref{TieEvent}, @internalsref{Tie}. + +@refbugs + + +Switching staves when a tie is active will not produce a slanted tie. + +Formatting of ties is a difficult subject. The results are often not +optimal. + +@node Tuplets +@subsection Tuplets + +@cindex tuplets +@cindex triplets +@cindex @code{\times} + +Tuplets are made out of a music expression by multiplying all durations +with a fraction + +@cindex @code{\times} +@example +\times @var{fraction} @var{musicexpr} +@end example + +@noindent +The duration of @var{musicexpr} will be multiplied by the fraction. +The fraction's denominator will be printed over the notes, optionally +with a bracket. The most common tuplet is the triplet in which 3 +notes have the length of 2, so the notes are 2/3 of their written +length + +@lilypond[quote,raggedright,fragment,verbatim] +g'4 \times 2/3 {c'4 c' c'} d'4 d'4 +@end lilypond + +The property @code{tupletSpannerDuration} specifies how long each +bracket should last. With this, you can make lots of tuplets while +typing @code{\times} only once, thus saving lots of typing. In the next +example, there are two triplets shown, while @code{\times} was only +used once + +@lilypond[quote,fragment,relative=1,raggedright,verbatim] +\set tupletSpannerDuration = #(ly:make-moment 1 4) +\times 2/3 { c'8 c c c c c } +@end lilypond + +The format of the number is determined by the property +@code{tupletNumberFormatFunction}. The default prints only the +denominator, but if it is set to the Scheme function +@code{fraction-tuplet-formatter}, @var{num}:@var{den} will be printed +instead. + + +@cindex @code{tupletNumberFormatFunction} +@cindex tuplet formatting + + +@refcommands + +@cindex @code{\tupletUp} +@code{\tupletUp}, +@cindex @code{\tupletDown} +@code{\tupletDown}, +@cindex @code{\tupletNeutral} +@code{\tupletNeutral}. + +@seealso + +User manual: @ref{Changing context properties on the fly} for the +@code{\set} command. + + +Program reference: @internalsref{TupletBracket}, and @internalsref{TimeScaledMusic}. + +Examples: @inputfileref{input/@/regression,tuplet@/-nest@/.ly}. + +@refbugs + +Nested tuplets are not formatted automatically. In this case, outer +tuplet brackets should be moved manually, which is demonstrated in +@inputfileref{input/@/regression,tuplet@/-nest@/.ly}. + + +@node Transpose +@subsection Transpose +@cindex Transpose +@cindex transposition of pitches +@cindex @code{\transpose} + +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] +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 + +@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 + +@example +\transpose c bes @{ e4 @dots{} @} +@end example + +To print this music in B-flat again (ie producing a trumpet part, +instead of a concert pitch conductor's score) you would wrap the +existing music with another @code{transpose} + +@example +\transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @} +@end example + + +@seealso + +Program reference: @internalsref{TransposedMusic}, and +@internalsref{UntransposableMusic}. + +@refbugs + +If you want to use both @code{\transpose} and @code{\relative}, +you must put @code{\transpose} outside of @code{\relative}, since +@code{\relative} will have no effect music that appears inside a +@code{\transpose}. + + +@node Easier music entry +@section Easier music entry +@cindex Music entry + +This section deals with tricks and features of the input language that +were added solely to help entering music and finding and correcting +mistakes. There are also external tools that make debugging easier. +See @ref{Point and click} for more information. + +It is also possible to enter and edit music using other programs, such as +GUI interfaces or MIDI sequencers. Refer to the LilyPond +website for more information. + + +@menu +* Relative octaves:: +* Octave check:: +* Bar check:: +* Skipping corrected music:: +* Automatic note splitting:: +@end menu + + + + +@node Relative octaves +@subsection Relative octaves +@cindex Relative +@cindex relative octave specification + +Octaves are specified by adding @code{'} and @code{,} to pitch names. +When you copy existing music, it is easy to accidentally put a pitch +in the wrong octave and hard to find such an error. The relative +octave mode prevents these errors by making the mistakes much +larger: a single error puts the rest of the piece off by one octave + +@cindex @code{\relative} +@example +\relative @var{startpitch} @var{musicexpr} +@end example + +@noindent +or + +@example +\relative @var{musicexpr} +@end example + +The octave of notes that appear in @var{musicexpr} are calculated as +follows: if no octave changing marks are used, the basic interval +between this and the last note is always taken to be a fourth or +less. This distance is determined without regarding alterations; a +@code{fisis} following a @code{ceses} will be put above the +@code{ceses}. In other words, a doubly-augmented fourth is considered +a smaller interval than a diminshed fifth, even though the fourth is +seven semitones while the fifth is only six semitones. + +The octave changing marks @code{'} and @code{,} can be added to raise +or lower the pitch by an extra octave. Upon entering relative mode, +an absolute starting pitch can be specified that will act as the +predecessor of the first note of @var{musicexpr}. If no starting pitch +is specified, then middle C is used as a start. + +Here is the relative mode shown in action +@lilypond[quote,fragment,raggedright,verbatim] +\relative c'' { + b c d c b c bes a +} +@end lilypond + +Octave changing marks are used for intervals greater than a fourth +@lilypond[quote,raggedright,fragment,verbatim] +\relative c'' { + c g c f, c' a, e'' +} +@end lilypond + +If the preceding item is a chord, the first note of the chord is used +to determine the first note of the next chord + +@lilypond[quote,raggedright,fragment,verbatim] +\relative c' { + c + + +} +@end lilypond + +The pitch after the @code{\relative} contains a note name. + + +The relative conversion will not affect @code{\transpose}, +@code{\chordmode} or @code{\relative} sections in its argument. To use +relative within transposed music, an additional @code{\relative} must +be placed inside @code{\transpose}. + +@node Octave check +@subsection Octave check + + +Octave checks make octave errors easier to correct: a note may be +followed by @code{=}@var{quotes} which indicates what its absolute +octave should be. In the following example, +@example +\relative c'' @{ c='' b=' d,='' @} +@end example + +@noindent +@c take care with @code, adds confusing quotes. +the @code{d} will generate a warning, because a @code{d''} is expected +(because @code{b'} to @code{d''} is only a third), but a @code{d}' is +found. In the output, the octave is corrected to be a @code{d''} and +the next note is calculated relative to @code{d''} instead of @code{d'}. + + + +There is also a syntax that is separate from the notes. The syntax + +@example +\octave @var{pitch} +@end example + +This checks that @var{pitch} (without quotes) yields @var{pitch} (with +quotes) in \relative mode. If not, a warning is printed, and the +octave is corrected. + +In the example below, the first check passes without incident, since +the @code{e} (in relative mode) is within a fifth of @code{a'}. However, +the second check produces a warning, since the @code{e} is not within +a fifth of @code{b'}. The warning message is printed, and the octave +is adjusted so that the following notes are in the correct octave +once again. + +@example +\relative c' @{ + e + \octave a' + \octave b' +@} +@end example + + +The octave of a note following an octave check is determined with +respect to the note preceding it. In the next fragment, the last note +is a @code{a'}, above middle C. That means that the @code{\octave} +check passes successfully, so the check could be deleted without changing +the output of the piece. + +@lilypond[quote,raggedright,verbatim,fragment] +\relative c' { + e + \octave b + a +} +@end lilypond + +@node Bar check +@subsection Bar check +@cindex Bar check + +@cindex bar check +@cindex @code{barCheckSynchronize} +@cindex @code{|} + +Bar checks help detect errors in the durations. A bar check is +entered using the bar symbol, `@code{|}'. Whenever it is encountered +during interpretation, it should fall on a measure boundary. If it +does not, a warning is printed. In the next example, the second bar +check will signal an error +@example +\time 3/4 c2 e4 | g2 | +@end example + +Bar checks can also be used in lyrics, for example + +@example +\lyricmode @{ + \time 2/4 + Twin -- kle | Twin -- kle +@} +@end example + + +@cindex @code{skipTypesetting} + +Failed bar checks are caused by entering incorrect +durations. Incorrect durations often completely garble up the score, +especially if the score is polyphonic, so a good place to start correcting +input is by scanning for failed bar checks and incorrect durations. To +speed up this process, the @code{skipTypesetting} feature may be +used. It is described in the next section. + +@cindex @code{|} +@cindex @code{pipeSymbol} + +It is also possible to redefine the meaning of @code{|}. This is done +by assigning a music expression to @code{pipeSymbol}, + +@lilypond[quote,raggedright,verbatim] +pipeSymbol = \bar "||" + +{ c'2 c' | c'2 c } +@end lilypond + + +@node Skipping corrected music +@subsection Skipping corrected music + +The property @code{Score.skipTypesetting} can be used to switch on and +off typesetting completely during the interpretation phase. When +typesetting is switched off, the music is processed much more +quickly. This can be used to skip over the parts of a score that +have already been checked for errors + +@lilypond[quote,fragment,raggedright,verbatim] +\relative c'' { + c8 d + \set Score.skipTypesetting = ##t + e e e e e e e e + \set Score.skipTypesetting = ##f + c d b bes a g c2 } +@end lilypond + +In polyphonic music, @code{Score.skipTypesetting} will affect all +voices and staves, saving even more time. + +@node Automatic note splitting +@subsection Automatic note splitting + +Long notes can be converted automatically to tied notes. This is done +by replacing the @internalsref{Note_heads_engraver} by the +@internalsref{Completion_heads_engraver}. +In the following examples, notes crossing the bar line are split and tied. + + +@lilypond[quote,fragment,verbatim,relative=1,linewidth=12\cm] +\new Voice \with { + \remove "Note_heads_engraver" + \consists "Completion_heads_engraver" +} { + c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 +} +@end lilypond + +This engraver splits all running notes at the bar line, and inserts +ties. One of its uses is to debug complex scores: if the measures are +not entirely filled, then the ties exactly show how much each measure +is off. + +@refbugs + +Not all durations (especially those containing tuplets) can be +represented exactly with normal notes and dots, but the engraver will +not insert tuplets. + +@seealso + +Examples: @inputfileref{input/@/regression,completion@/-heads@/.ly}. + +@noindent + +Program reference: @internalsref{Completion_heads_engraver}. + + +@node Staff notation +@section Staff notation + +This section describes music notation that occurs on staff level, +such as key signatures, clefs and time signatures. + +@cindex Staff notation + +@menu +* Staff symbol:: +* Key signature:: +* Clef:: +* Ottava brackets:: +* Time signature:: +* Partial measures:: +* Unmetered music:: +* Bar lines:: +* Time administration:: +* Controlling formatting of prefatory matter:: +* System start delimiters:: +@end menu + +@node Staff symbol +@subsection Staff symbol + +@cindex adjusting staff symbol + +Notes, dynamic signs, etc., are grouped +with a set of horizontal lines, into a staff (plural `staves'). In our +system, these lines are drawn using a separate layout object called +staff symbol. + + +@cindex staff lines, setting number of +@cindex staff lines, setting thickness of +@cindex thickness of staff lines, setting +@cindex number of staff lines, setting + +@seealso + +Program reference: @internalsref{StaffSymbol}. + +Examples: @inputfileref{input/@/test,staff@/-lines@/.ly}, +@inputfileref{input/@/test,staff@/-size@/.ly}. + +@refbugs + +If a staff is ended halfway a piece, the staff symbol may not end +exactly on the bar line. + + +@node Key signature +@subsection Key signature +@cindex Key signature + +@cindex @code{\key} + +The key signature indicates the tonality in which a piece is played. It +is denoted by a set of alterations (flats or sharps) at the start of the +staff. + + +Setting or changing the key signature is done with the @code{\key} +command +@example +@code{\key} @var{pitch} @var{type} +@end example + +@cindex @code{\minor} +@cindex @code{\major} +@cindex @code{\minor} +@cindex @code{\ionian} +@cindex @code{\locrian} +@cindex @code{\aeolian} +@cindex @code{\mixolydian} +@cindex @code{\lydian} +@cindex @code{\phrygian} +@cindex @code{\dorian} + +Here, @var{type} should be @code{\major} or @code{\minor} to get +@var{pitch}-major or @var{pitch}-minor, respectively. +The standard mode names @code{\ionian}, +@code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian}, +@code{\phrygian}, and @code{\dorian} are also defined. + +This command sets the context property +@internalsref{Staff}.@code{keySignature}. Non-standard key signatures +can be specified by setting this property directly. + +A natural sign is printed to cancel any previous accidentals. This +can be suppressed by setting the @code{Staff.printKeyCancellation} +property. + +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +{ + \key d \major + a b cis d + \key g \minor + a bes c d + \set Staff.printKeyCancellation = ##f + \key d \major + a b cis d + \key g \minor + a bes c d +} +@end lilypond + +Accidentals and key signatures often confuse new users, because +unaltered notes get natural signs depending on the key signature. For +more information, see @ref{More about pitches}. + +@seealso + +Program reference: @internalsref{KeyChangeEvent}, +@internalsref{KeyCancellation} and @internalsref{KeySignature}. + +@cindex @code{keySignature} + + +@node Clef +@subsection Clef +@cindex @code{\clef} + +The clef indicates which lines of the staff correspond to which +pitches. + + +The clef can be set with the @code{\clef} command +@lilypond[quote,raggedright,fragment,verbatim] +{ c''2 \clef alto g'2 } +@end lilypond + +Supported clef-names include +@c Moved standard clefs to the top /MB +@table @code +@cindex treble clef +@cindex violin clef +@item treble, violin, G, G2 +G clef on 2nd line +@item alto, C +@cindex alto clef + C clef on 3rd line +@item tenor +@cindex tenor clef + C clef on 4th line. +@item bass, F +@cindex bass clef + F clef on 4th line +@item french +@cindex french clef + G clef on 1st line, so-called French violin clef +@item soprano +@cindex soprano clef + C clef on 1st line +@item mezzosoprano +@cindex mezzosoprano clef + C clef on 2nd line +@item baritone +@cindex baritone clef + C clef on 5th line +@item varbaritone +@cindex varbaritone clef + F clef on 3rd line +@item subbass +@cindex subbass clef + F clef on 5th line +@item percussion + percussion clef +@item tab + tablature clef +@end table + +By adding @code{_8} or @code{^8} to the clef name, the clef is +transposed one octave down or up, respectively, and @code{_15} and +@code{^15} transposes by two octaves. The argument @var{clefname} +must be enclosed in quotes when it contains underscores or digits. For +example, + + +@cindex choral tenor clef +@lilypond[quote,raggedright,verbatim,fragment,relative=1] +\clef "G_8" c4 +@end lilypond + +This command is equivalent to setting @code{clefGlyph}, +@code{clefPosition} (which controls the Y position of the clef), +@code{middleCPosition} and @code{clefOctavation}. A clef is printed +when any of these properties are changed. The following example shows +possibilities when setting properties manually. + +@lilypond[quote,raggedright,verbatim] +{ + \set Staff.clefGlyph = #"clefs.F" + \set Staff.clefPosition = #2 + c'4 + \set Staff.clefGlyph = #"clefs.G" + c'4 + \set Staff.clefGlyph = #"clefs.C" + c'4 + \set Staff.clefOctavation = #7 + c'4 + \set Staff.clefOctavation = #0 + \set Staff.clefPosition = #0 + c'4 + \clef "bass" + c'4 + \set Staff.middleCPosition = #4 + c'4 +} +@end lilypond + +@seealso + +Program reference: @internalsref{Clef}. + + + +@node Ottava brackets +@subsection Ottava brackets + +`Ottava' brackets introduce an extra transposition of an octave for +the staff. They are created by invoking the function +@code{set-octavation} + +@cindex ottava +@cindex 15ma +@cindex octavation + +@lilypond[quote,raggedright,verbatim,fragment] +\relative c''' { + a2 b + #(set-octavation 1) + a b + #(set-octavation 0) + a b +} +@end lilypond + +The @code{set-octavation} function also takes -1 (for 8va bassa) and 2 +(for 15ma) as arguments. Internally the function sets the properties +@code{ottavation} (e.g., to @code{"8va"}) and +@code{centralCPosition}. For overriding the text of the bracket, set +@code{ottavation} after invoking @code{set-octavation}, i.e., + +@lilypond[quote,raggedright,verbatim] +{ + #(set-octavation 1) + \set Staff.ottavation = #"8" + c''' +} +@end lilypond + +@seealso + +Program reference: @internalsref{OttavaBracket}. + +Examples: @inputfileref{input/@/regression,ottava@/.ly}, +@inputfileref{input/@/regression,ottava@/-broken@/.ly}. + +@refbugs + +@code{set-octavation} will get confused when clef changes happen +during an octavation bracket. + + + + +@node Time signature +@subsection Time signature +@cindex Time signature +@cindex meter +@cindex @code{\time} + +Time signature indicates the metrum of a piece: a regular pattern of +strong and weak beats. It is denoted by a fraction at the start of the +staff. + + +The time signature is set or changed by the @code{\time} +command +@lilypond[quote,raggedright,fragment,verbatim] +\time 2/4 c'2 \time 3/4 c'2. +@end lilypond + +The symbol that is printed can be customized with the @code{style} +property. Setting it to @code{#'()} uses fraction style for 4/4 and +2/2 time, + +@lilypond[fragment,quote,raggedright,verbatim] +\time 4/4 c'1 +\time 2/2 c'1 +\override Staff.TimeSignature #'style = #'() +\time 4/4 c'1 +\time 2/2 c'1 +@end lilypond + + + +There are many more options for its layout. See @ref{Ancient time +signatures} for more examples. + + +This command sets the property @code{timeSignatureFraction}, +@code{beatLength} and @code{measureLength} in the @code{Timing} +context, which is normally aliased to @internalsref{Score}. The +property @code{measureLength} determines where bar lines should be +inserted, and how automatic beams should be generated. Changing the +value of @code{timeSignatureFraction} also causes the symbol to be +printed. + +More options are available through the Scheme function +@code{set-time-signature}. In combination with the +@internalsref{Measure_grouping_engraver}, it will create +@internalsref{MeasureGrouping} signs. Such signs ease reading +rhythmically complex modern music. In the following example, the 9/8 +measure is subdivided in 2, 2, 2 and 3. This is passed to +@code{set-time-signature} as the third argument @code{(2 2 2 3)} + +@lilypond[quote,raggedright,verbatim] +\score { + \relative c'' { + #(set-time-signature 9 8 '(2 2 2 3)) + g8[ g] d[ d] g[ g] a8[( bes g]) | + #(set-time-signature 5 8 '(3 2)) + a4. g4 + } + \layout { + \context { + \Staff + \consists "Measure_grouping_engraver" + } + } +} +@end lilypond + +@seealso + +Program reference: @internalsref{TimeSignature}, and @internalsref{Timing_engraver}. + + +@refbugs + +Automatic beaming does not use the measure grouping specified with +@code{set-time-signature}. + +@node Partial measures +@subsection Partial measures +@cindex Partial +@cindex anacrusis +@cindex partial measure +@cindex measure, partial +@cindex shorten measures +@cindex @code{\partial} + +Partial measures, for example in upsteps, are entered using the +@code{\partial} command +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +\partial 16*5 c16 cis d dis e | a2. c,4 | b2 +@end lilypond + +The syntax for this command is +@example +\partial @var{duration} +@end example +This is internally translated into +@example +\set Timing.measurePosition = -@var{length of duration} +@end example +@cindex @code{|} +The property @code{measurePosition} contains a rational number +indicating how much of the measure has passed at this point. + +@refbugs + +This command does not take into account grace notes at the start of +the music. When a piece starts with graces notes in the pickup, then +the @code{\partial} should follow the grace notes + +@lilypond[verbatim,quote,raggedright,relative,fragment] +{ + \grace f16 + \partial 4 + g4 + a2 g2 +} +@end lilypond + + +@node Unmetered music +@subsection Unmetered music + +@cindex @code{\bar} + +Bar lines and bar numbers are calculated automatically. For unmetered +music (cadenzas, for example), this is not desirable. By setting +@code{Score.timing} to false, this automatic timing can be switched +off. Empty bar lines, + +@example +\bar "" +@end example + +@noindent +indicate where line breaks can occur. + +@refcommands + +@cindex @code{\cadenzaOn} +@code{\cadenzaOn}, +@cindex @code{\cadenzaOff} +@code{\cadenzaOff}. + + + + +@node Bar lines +@subsection Bar lines +@cindex Bar lines + +@cindex @code{\bar} +@cindex measure lines +@cindex repeat bars + + +Bar lines delimit measures, but are also used to indicate repeats. +Normally, they are inserted automatically. Line breaks may only +happen on bar lines. + +Special types of bar lines can be forced with the @code{\bar} command +@c +@lilypond[quote,raggedright,relative=2,fragment,verbatim] +c4 \bar "|:" c4 +@end lilypond + +The following bar types are available +@lilypondfile[raggedright,quote]{bar-lines.ly} + +For allowing line breaks, there is a special command, +@example +\bar "" +@end example +This will insert an invisible bar line, and allow line breaks at this +point. + +In scores with many staves, a @code{\bar} command in one staff is +automatically applied to all staves. The resulting bar lines are +connected between different staves of a @internalsref{StaffGroup} +@c +@lilypond[quote,raggedright,fragment,verbatim] +<< + \context StaffGroup << + \new Staff { + e'4 d' + \bar "||" + f' e' + } + \new Staff { \clef bass c4 g e g } + >> + \new Staff { \clef bass c2 c2 } +>> +@end lilypond + + +The command @code{\bar }@var{bartype} is a short cut for doing +@code{\set Timing.whichBar = }@var{bartype}. Whenever @code{whichBar} +is set to a string, a bar line of that type is created. + +A bar line is created whenever the @code{whichBar} property is set. +At the start of a measure it is set to the contents of +@code{Timing.defaultBarType}. The contents of @code{repeatCommands} are used +to override default measure bars. + +@cindex @code{whichBar} +@cindex @code{repeatCommands} +@cindex @code{defaultBarType} + +You are encouraged to use @code{\repeat} for repetitions. See +@ref{Repeats}. + + + +@seealso + +In this manual: @ref{Repeats}, @ref{System start delimiters}. + + +Program reference: @internalsref{BarLine} (created at +@internalsref{Staff} level), @internalsref{SpanBar} (across staves). + +@cindex bar lines at start of system +@cindex start of system + + + +Examples: @inputfileref{input/@/test,bar@/-lines@/.ly}, + + +@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 Controlling formatting of prefatory matter +@subsection 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 + + +@node System start delimiters +@subsection System start delimiters + +Polyphonic scores consist of many staves. These staves can be +constructed in three different ways +@itemize @bullet +@item The group is started with a brace at the left, and bar lines are +connected. This is done with the @internalsref{GrandStaff} context. + +@lilypond[verbatim,raggedright,quote] +\new GrandStaff +\relative << + \new Staff { c1 c } + \new Staff { c c } +>> +@end lilypond + + +@item The group is started with a bracket, and bar lines are connected. +This is done with the +@internalsref{StaffGroup} context + +@lilypond[verbatim,raggedright,quote] +\new StaffGroup +\relative << + \new Staff { c1 c } + \new Staff { c c } +>> +@end lilypond + + +@item The group is started with a vertical line. Bar lines are not +connected. This is the default for the score. + +@lilypond[verbatim,raggedright,quote] +\relative << + \new Staff { c1 c } + \new Staff { c c } +>> +@end lilypond + +@end itemize + +@cindex Staff, multiple +@cindex bracket, vertical +@cindex brace, vertical +@cindex grand staff +@cindex staff group + + +@seealso + +The bar lines at the start of each system are +@internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and +@internalsref{SystemStartBracket}. Only one of these types is created +in every context, and that type is determined by the property +@code{systemStartDelimiter}. + +@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 Polyphony +@section Polyphony + +Polyphony in music refers to having more than one voice occuring in +a piece of music. Polyphony in LilyPond refers to having more than +one voice on the same staff. + +@menu +* Basic polyphony:: +* Explicitly instantiating voices:: +* Collision Resolution:: +@end menu + +@node Basic polyphony +@subsection Basic polyphony +@cindex polyphony + +The easiest way to enter fragments with more than one voice on a staff +is to enter each voice as a sequence (with @code{@{...@}}), and combine +them simultaneously, separating the voices with @code{\\} + +@cindex @code{\\} + +@lilypond[quote,verbatim,fragment] +\new Staff \relative c' { + c16 d e f + << { g4 f e | d2 e2 } \\ + { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\ + { s2. | s4 b4 c2 } + >> +} +@end lilypond + +The separator causes @internalsref{Voice} contexts@footnote{Polyphonic +voices are sometimes called ``layers'' in other notation packages} +@cindex layers +to be instantiated. They bear the names @code{"1"}, @code{"2"}, etc. In +each of these contexts, vertical direction of slurs, stems, etc., is set +appropriately. + +These voices are all seperate from the voice that contains the notes just +outside the @code{<< \\ >>} construct. This should be noted when making +changes at the voice level. This also means that slurs and ties cannot go +into or out of a @code{<< \\ >>} construct. +Conversely, parallel voices from separate @code{<< \\ >>} constructs on the +same staff are the the same voice. +Here is the same example, with different noteheads for each voice. +Note that the change to the note-head style in the main voice does not affect +the inside of the @code{<< \\ >>} constructs. Also, the change to the second +voice in the first @code{<< \\ >>} construct is effective in the second +@code{<< \\ >>}, and the voice is tied accross the two constructs. + +@lilypond[quote,verbatim,fragment] +\new Staff \relative c' { + \override NoteHead #'style = #'cross + c16 d e f + << + { g4 f e } \\ + { \override NoteHead #'style = #'triangle + r8 e4 d c8 ~ + } + >> | + << + { d2 e2 } \\ + { c8 b16 a b8 g ~ g2 } \\ + { \override NoteHead #'style = #'slash s4 b4 c2 } + >> +} +@end lilypond + +@node Explicitly instantiating voices +@subsection Explicitly instantiating voices + +@internalsref{Voice} contexts can also also be instantiated manually +inside a @code{<< >>} block to create polyphonic music, using +@code{\voiceOne}, up to @code{\voiceFour} to assign stem directions +and a horizontal shift for each part. + +Specifically, +@example +<< \upper \\ \lower >> +@end example + +@noindent +is equivalent to + +@example +<< + \context Voice = "1" @{ \voiceOne \upper @} + \context Voice = "2" @{ \voiceTwo \lower @} +>> +@end example + +@cindex @code{\voiceOne} +@cindex @code{\voiceFour} + +The @code{\voiceXXX} commands set the direction of stems, slurs, ties, +articulations, text annotations, augmentation dots of dotted +notes, and fingerings. @code{\voiceOne} and @code{\voiceThree} make +these objects point upwards, while @code{\voiceTwo} and @code{\voiceFour} +make them point downwards. +The command @code{\oneVoice} will revert back to the normal setting. +@cindex @code{\oneVoice} + +An expression that appears directly inside a @code{<< >>} belongs to +the main voice. This is useful when extra voices appear while the main +voice is playing. Here is a more correct rendition of the example from +the previous section. The crossed noteheads demonstrate that the main +melody is now in a single voice context. + +@lilypond[quote,raggedright,verbatim] +\new Staff \relative c' { + \override NoteHead #'style = #'cross + c16 d e f + \voiceOne + << + { g4 f e | d2 e2} + \context Voice="1" { \voiceTwo + r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 + \oneVoice + } + \new Voice { \voiceThree + s2. | s4 b4 c2 + \oneVoice + } + >> + \oneVoice +} +@end lilypond + +The correct definition of the voices allows the melody to be slurred. +@lilypond[quote,raggedright,verbatim] +\new Staff \relative c' { + c16^( d e f + \voiceOne + << + { g4 f e | d2 e2) } + \context Voice="1" { \voiceTwo + r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 + \oneVoice + } + \new Voice { \voiceThree + s2. s4 b4 c2 + \oneVoice + } + >> + \oneVoice +} +@end lilypond + +Avoiding the @code{\\} seperator also allows nesting polyphony +constructs, which in some case might be a more natural way to typeset +the music. + +@lilypond[quote,raggedright,verbatim] +\new Staff \relative c' { + c16^( d e f + \voiceOne + << + { g4 f e | d2 e2) } + \context Voice="1" { \voiceTwo + r8 e4 d c8 ~ | + << + {c8 b16 a b8 g ~ g2} + \new Voice { \voiceThree + s4 b4 c2 + \oneVoice + } + >> + \oneVoice + } + >> + \oneVoice +} +@end lilypond + +@node Collision Resolution +@subsection Collision Resolution + +Normally, note heads with a different number of dots are not merged, but +when the object property @code{merge-differently-dotted} is set in +the @internalsref{NoteCollision} object, they are merged +@lilypond[quote,verbatim,fragment,raggedright,relative=2] +\context Voice << { + g8 g8 + \override Staff.NoteCollision + #'merge-differently-dotted = ##t + g8 g8 +} \\ { g8.[ f16] g8.[ f16] } >> +@end lilypond + +Similarly, you can merge half note heads with eighth notes, by setting +@code{merge-differently-headed} +@lilypond[quote,raggedright,fragment,relative=2,verbatim] +\context Voice << { + c8 c4. + \override Staff.NoteCollision + #'merge-differently-headed = ##t +c8 c4. } \\ { c2 c2 } >> +@end lilypond + +LilyPond also vertically shifts rests that are opposite of a stem, +for example + +@lilypond[quote,raggedright,fragment,verbatim] +\context Voice << c''4 \\ r4 >> +@end lilypond + + +@refcommands + + + +@cindex @code{\oneVoice} +@code{\oneVoice}, +@cindex @code{\voiceOne} +@code{\voiceOne}, +@cindex @code{\voiceTwo} +@code{\voiceTwo}, +@cindex @code{\voiceThree} +@code{\voiceThree}, +@cindex @code{\voiceFour} +@code{\voiceFour}. + + + +@cindex @code{\shiftOn} +@code{\shiftOn}, +@cindex @code{\shiftOnn} +@code{\shiftOnn}, +@cindex @code{\shiftOnnn} +@code{\shiftOnnn}, +@cindex @code{\shiftOff} +@code{\shiftOff}: these commands specify in what chords of the current +voice should be shifted. The outer voices (normally: voice one and +two) have @code{\shiftOff}, while the inner voices (three and four) +have @code{\shiftOn}. @code{\shiftOnn} and @code{\shiftOnnn} define +further shift levels. + + +When LilyPond cannot cope, the @code{force-hshift} +property of the @internalsref{NoteColumn} object and pitched rests can +be used to override typesetting decisions. + +@lilypond[quote,verbatim,raggedright] +\relative << +{ + + +} \\ { + + \once \override NoteColumn #'force-hshift = #1.7 + +} >> +@end lilypond + + + +@seealso + +Program reference: the objects responsible for resolving collisions are +@internalsref{NoteCollision} and @internalsref{RestCollision}. + +Examples: +@inputfileref{input/@/regression,collision@/-dots@/.ly}, +@inputfileref{input/@/regression,collision@/-head-chords@/.ly}, +@inputfileref{input/@/regression,collision@/-heads@/.ly}, +@inputfileref{input/@/regression,collision@/-mesh@/.ly}, and +@inputfileref{input/@/regression,collisions@/.ly}. + + +@refbugs + + +When using @code{merge-differently-headed} with an upstem eighth or a +shorter note, and a downstem half note, the eighth note gets the wrong +offset. + +There is no support for clusters where the same note occurs with +different accidentals in the same chord. In this case, it is +recommended to use enharmonic transcription, or to use special cluster +notation (see @ref{Clusters}). + +@node Beaming +@section Beaming + +@c todo: split this up; noBeaming and manual beams stay in basic; +@c seting automatic beam behavior and beam formatting goes into +@c advanced. -gp + +Beams are used to group short notes into chunks that are aligned with +the metrum. LilyPond normally inserts beams automatically, but if you +wish you may control them manually or change how beams are automatically +grouped. + +@cindex Automatic beams +@menu +* Automatic beams:: +* Manual beams:: +* Setting automatic beam behavior:: +* Beam formatting:: +@end menu + +@node Automatic beams +@subsection Automatic beams + +LilyPond inserts beams automatically + +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +\time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8 +@end lilypond + +When these automatic decisions are not good enough, beaming can be +entered explicitly. It is also possible to define beaming patterns +that differ from the defaults. + +Individual notes may be marked with @code{\noBeam}, to prevent them +from being beamed + +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +\time 2/4 c8 c\noBeam c c +@end lilypond + + +@seealso + +Program reference: @internalsref{Beam}. + + +@node Manual beams +@subsection Manual beams +@cindex beams, manual +@cindex @code{]} +@cindex @code{[} + +In some cases it may be necessary to override the automatic beaming +algorithm. For example, the autobeamer will not put beams over rests +or bar lines. Such beams are specified manually by marking the begin +and end point with @code{[} and @code{]} + +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +{ + r4 r8[ g' a r8] r8 g[ | a] r8 +} +@end lilypond + +@cindex @code{stemLeftBeamCount} + +Normally, beaming patterns within a beam are determined automatically. +If necessary, the properties @code{stemLeftBeamCount} and +@code{stemRightBeamCount} can be used to override the defaults. If +either property is set, its value will be used only once, and then it +is erased + +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +{ + f8[ r16 + f g a] + f8[ r16 + \set stemLeftBeamCount = #1 + f g a] +} +@end lilypond +@cindex @code{stemRightBeamCount} + + +The property @code{subdivideBeams} can be set in order to subdivide +all 16th or shorter beams at beat positions, as defined by the +@code{beatLength} property. + + +@lilypond[fragment,quote,relative=2,verbatim] +c16[ c c c c c c c] +\set subdivideBeams = ##t +c16[ c c c c c c c] +\set Score.beatLength = #(ly:make-moment 1 8) +c16[ c c c c c c c] +@end lilypond +@cindex @code{subdivideBeams} + +Normally, line breaks are forbidden when beams cross bar lines. This +behavior can be changed by setting @code{allowBeamBreak}. + +@cindex @code{allowBeamBreak} +@cindex beams and line breaks + +@cindex beams, kneed +@cindex kneed beams +@cindex auto-knee-gap + + +@seealso + +User manual: @ref{Changing context properties on the fly} for the +@code{\set} command + + +@refbugs + +@cindex Frenched staves +Kneed beams are inserted automatically, when a large gap is detected +between the note heads. This behavior can be tuned through the object. + + +Automatically kneed cross-staff beams cannot be used together with +hidden staves. See @ref{Hiding staves}. + +Beams do not avoid collisions with symbols around the notes, such as +texts and accidentals. + +@c FIXME. + + +@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 + + +@node Repeats +@section Repeats + +Repetition is a central concept in music, and multiple notations exist +for repetitions. + +@menu +* Repeat types:: +* Repeat syntax:: +* Repeats and MIDI:: +* Manual repeat commands:: +* Tremolo repeats:: +* Tremolo subdivisions:: +* Measure repeats:: +@end menu + +@node Repeat types +@subsection Repeat types + +@cindex repeats +@cindex @code{\repeat} + +The following types of repetition are supported + +@table @code +@item unfold +Repeated music is fully written (played) out. This is useful when +entering repetitious music. This is the only kind of repeat that +is included in MIDI output. + +@item volta +Repeats are not written out, but alternative endings (volte) are +printed, left to right with brackets. This is the standard notation +for repeats with alternatives. These are not played in MIDI output by default. + +@ignore +@item fold +Alternative endings are written stacked. This has limited use but may be +used to typeset two lines of lyrics in songs with repeats, see +@inputfileref{input,star-spangled-banner@/.ly}. +@end ignore + +@c tremolo, beamed +@item tremolo +Make tremolo beams. These are not played in MIDI output by default. + +@item percent +Make beat or measure repeats. These look like percent signs. These +are not played in MIDI output by default. Percent repeats must be +declared within a Voice context. + +@end table + +@node Repeat syntax +@subsection Repeat syntax + + +LilyPond has one syntactic construct for specifying different types of +repeats. The syntax is + +@example +\repeat @var{variant} @var{repeatcount} @var{repeatbody} +@end example + +If you have alternative endings, you may add +@cindex @code{\alternative} +@example +\alternative @{ @var{alternative1} + @var{alternative2} + @var{alternative3} @dots{} @} +@end example +where each @var{alternative} is a music expression. If you do not +give enough alternatives for all of the repeats, the first alternative +is assumed to be played more than once. + +Standard repeats are used like this +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +c1 +\repeat volta 2 { c4 d e f } +\repeat volta 2 { f e d c } +@end lilypond + +With alternative endings +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +c1 +\repeat volta 2 {c4 d e f} +\alternative { {d2 d} {f f,} } +@end lilypond + + +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +\context Staff { + \partial 4 + \repeat volta 4 { e | c2 d2 | e2 f2 | } + \alternative { { g4 g g } { a | a a a a | b2. } } +} +@end lilypond + +It is possible to shorten volta brackets +by setting @code{voltaSpannerDuration}. In the next example, the +bracket only lasts one measure, which is a duration of 3/4. + + + +@lilypond[verbatim,raggedright,quote] +\relative c''{ + \time 3/4 + c c c + \set Staff.voltaSpannerDuration = #(ly:make-moment 3 4) + \repeat "volta" 5 { d d d } + \alternative { { e e e f f f } + { g g g } } +} +@end lilypond + + +@seealso + +Examples: + +Brackets for the repeat are normally only printed over the topmost +staff. This can be adjusted by setting the @code{voltaOnThisStaff} +property; see @inputfileref{input/@/regression,volta@/-multi@/-staff@/.ly}. + +@c not necessary +@c @inputfileref{input/@/regression,volta@/-chord@/-names@/.ly}. + + +@refbugs + +A nested repeat like + +@example +\repeat @dots{} +\repeat @dots{} +\alternative +@end example + +@noindent +is ambiguous, since it is is not clear to which @code{\repeat} the +@code{\alternative} belongs. This ambiguity is resolved by always +having the @code{\alternative} belong to the inner @code{\repeat}. +For clarity, it is advisable to use braces in such situations. +@cindex ambiguity + + + +Timing information is not remembered at the start of an alternative, +so after a repeat timing information must be reset by hand, for +example by setting @code{Score.measurePosition} or entering +@code{\partial}. Similarly, slurs or ties are also not repeated. + + + + +@node Repeats and MIDI +@subsection Repeats and MIDI + +@cindex expanding repeats + +With a little bit of tweaking, all types of repeats can be present +in the MIDI output. This is achieved by applying the +@code{\unfoldrepeats} music function. This functions changes all +repeats to unfold repeats. + +@lilypond[quote,verbatim,fragment,linewidth=8.0\cm] +\unfoldrepeats { + \repeat tremolo 8 {c'32 e' } + \repeat percent 2 { c''8 d'' } + \repeat volta 2 {c'4 d' e' f'} + \alternative { + { g' a' a' g' } + {f' e' d' c' } + } +} +\bar "|." +@end lilypond + +When creating a score file using @code{\unfoldrepeats} for midi, then +it is necessary to make two @code{\score} blocks. One for MIDI (with +unfolded repeats) and one for notation (with volta, tremolo, and +percent repeats). For example, + +@example +\score @{ + @var{..music..} + \layout @{ .. @} +@} +\score @{ + \unfoldrepeats @var{..music..} + \midi @{ .. @} +@} +@end example + +@node Manual repeat commands +@subsection Manual repeat commands + +@cindex @code{repeatCommands} + +The property @code{repeatCommands} can be used to control the layout of +repeats. Its value is a Scheme list of repeat commands. + +@table @asis +@item @code{start-repeat} +Print a @code{|:} bar line. + +@item @code{end-repeat} +Print a @code{:|} bar line. + +@item @code{(volta @var{text})} +Print a volta bracket saying @var{text}: The text can be specified as +a text string or as a markup text, see @ref{Text markup}. Do not +forget to change the font, as the default number font does not contain +alphabetic characters; + +@item @code{(volta #f)} +Stop a running volta bracket. +@end table + +@lilypond[quote,raggedright,verbatim,fragment,relative=2] +c4 + \set Score.repeatCommands = #'((volta "93") end-repeat) +c4 c4 + \set Score.repeatCommands = #'((volta #f)) +c4 c4 +@end lilypond + + + +@seealso + +Program reference: @internalsref{VoltaBracket}, @internalsref{RepeatedMusic}, +@internalsref{VoltaRepeatedMusic}, +@internalsref{UnfoldedRepeatedMusic}, and +@internalsref{FoldedRepeatedMusic}. + +@node Tremolo repeats +@subsection Tremolo repeats +@cindex tremolo beams + +To place tremolo marks between notes, use @code{\repeat} with tremolo +style +@lilypond[quote,verbatim,raggedright] +\new Voice \relative c' { + \repeat "tremolo" 8 { c16 d16 } + \repeat "tremolo" 4 { c16 d16 } + \repeat "tremolo" 2 { c16 d16 } +} +@end lilypond + +Tremolo marks can also be put on a single note. In this case, the +note should not be surrounded by braces. +@lilypond[quote,verbatim,raggedright] +\repeat "tremolo" 4 c'16 +@end lilypond + +Similar output is obtained using the tremolo subdivision, described in +@ref{Tremolo subdivisions}. + +@seealso + +In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}. + +Program reference: tremolo beams are @internalsref{Beam} objects. Single stem +tremolos are @internalsref{StemTremolo} objects. The music expression is +@internalsref{TremoloEvent}. + +Example files: @inputfileref{input/@/regression,chord@/-tremolo@/.ly}, +@inputfileref{input/@/regression,stem@/-tremolo@/.ly}. + +@node Tremolo subdivisions +@subsection Tremolo subdivisions +@cindex tremolo marks +@cindex @code{tremoloFlags} + +Tremolo marks can be printed on a single note by adding +`@code{:}[@var{number}]' after the note. The number indicates the +duration of the subdivision, and it must be at least 8. A +@var{length} value of 8 gives one line across the note stem. If the +length is omitted, the last value (stored in @code{tremoloFlags}) is +used + +@lilypond[quote,raggedright,verbatim,fragment] +c'2:8 c':32 | c': c': | +@end lilypond + +@c [TODO: stok is te kort bij 32en] +@c somebody want to translate that into English? +@c `Stem is too short for 32nds' (wl) + +@refbugs + +Tremolos entered in this way do not carry over into the MIDI output. + +@seealso + +In this manual: @ref{Tremolo repeats}. + +Elsewhere: @internalsref{StemTremolo}, @internalsref{TremoloEvent}. + +@node Measure repeats +@subsection Measure repeats + +@cindex percent repeats +@cindex measure repeats + +In the @code{percent} style, a note pattern can be repeated. It is +printed once, and then the pattern is replaced with a special sign. +Patterns of one and two measures are replaced by percent-like signs, +patterns that divide the measure length are replaced by slashes. +Percent repeats must be declared within a @code{Voice} context. + +@lilypond[quote,verbatim,raggedright] +\new Voice \relative c' { + \repeat "percent" 4 { c4 } + \repeat "percent" 2 { c2 es2 f4 fis4 g4 c4 } +} +@end lilypond + +@seealso + +Program reference: @internalsref{RepeatSlash}, @internalsref{PercentRepeat}, +@internalsref{PercentRepeatedMusic}, and +@internalsref{DoublePercentRepeat}. + + +@node Expressive marks +@section Expressive marks + + +@c todo: should change ordering +@c where to put text spanners, metronome marks, +@c fingering? + +Expressive marks help musicians to bring more to the music than simple +notes and rhythms. + +@menu +* Slurs:: +* Phrasing slurs:: +* Breath marks:: +* Articulations:: +* Running trills:: +* Fingering instructions:: +* Grace notes:: +* Glissando:: +* Dynamics:: +@end menu + + +@node Slurs +@subsection Slurs +@cindex Slurs + +A slur indicates that notes are to be played bound or @emph{legato}. + +They are entered using parentheses +@lilypond[quote,raggedright,relative=2,fragment,verbatim] +f( g a) a8 b( a4 g2 f4) +2( 2) +@end lilypond + +The direction of a slur can be set with the +generic commands + +@example +\override Slur #'direction = #UP +\slurUp % shortcut for the previous line +@end example + +@noindent +However, there is a convenient shorthand for forcing slur +directions. By adding @code{_} or @code{^} before the opening +parentheses, the direction is also set. For example, + +@lilypond[relative=2,raggedright,quote,verbatim,fragment] +c4_( c) c^( c) +@end lilypond + +Some composers write two slurs when they want legato chords. This can +be achieved in LilyPond by setting @code{doubleSlurs}, + +@lilypond[verbatim,raggedright,relative,fragment,quote] +\set doubleSlurs = ##t +4 ( ) +@end lilypond + + +@refcommands + + +@cindex @code{\slurUp} +@code{\slurUp}, +@cindex @code{\slurDown} +@code{\slurDown}, +@cindex @code{\slurNeutral} +@code{\slurNeutral}, +@cindex @code{\slurDashed} +@code{\slurDashed}, +@cindex @code{\slurDotted} +@code{\slurDotted}, +@cindex @code{\slurSolid} +@code{\slurSolid}. + +@seealso + +Program reference: @seeinternals{Slur}, and @internalsref{SlurEvent}. + + +@node Phrasing slurs +@subsection Phrasing slurs + +@cindex phrasing slurs +@cindex phrasing marks + +A phrasing slur (or phrasing mark) connects chords and is used to +indicate a musical sentence. It is written using @code{\(} and @code{\)} +respectively + +@lilypond[quote,raggedright,fragment,verbatim,relative=1] +\time 6/4 c'\( d( e) f( e) d\) +@end lilypond + +Typographically, the phrasing slur behaves almost exactly like a +normal slur. However, they are treated as different objects. A +@code{\slurUp} will have no effect on a phrasing slur; instead, use +@code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and +@code{\phrasingSlurNeutral}. + +The commands @code{\slurUp}, @code{\slurDown}, and @code{\slurNeutral} +will only affect normal slurs and not phrasing slurs. + +@refcommands + +@cindex @code{\phrasingSlurUp} +@code{\phrasingSlurUp}, +@cindex @code{\phrasingSlurDown} +@code{\phrasingSlurDown}, +@cindex @code{\phrasingSlurNeutral} +@code{\phrasingSlurNeutral}. + +@seealso + +Program reference: see also @internalsref{PhrasingSlur}, and +@internalsref{PhrasingSlurEvent}. + +@refbugs + +Putting phrasing slurs over rests leads to spurious warnings. + +@node Breath marks +@subsection Breath marks + +Breath marks are entered using @code{\breathe} + + +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +c'4 \breathe d4 +@end lilypond + +The glyph of the breath mark can be tuned by overriding the +@code{text} property of the @code{BreathingSign} layout object with +any markup text. For example, +@lilypond[quote,raggedright,fragment,verbatim,relative=1] +c'4 +\override BreathingSign #'text + = #(make-musicglyph-markup "scripts.rvarcomma") +\breathe +d4 +@end lilypond + +@seealso + +Program reference: @internalsref{BreathingSign}, +@internalsref{BreathingSignEvent}. + +Examples: @inputfileref{input/@/regression,breathing@/-sign@/.ly}. + + +@node Running trills +@subsection Running trills + +Long running trills are made with @code{\startTrillSpan} and +@code{\stopTrillSpan}, + + +@lilypond[verbatim,raggedright,relative=2,quote,fragment] +\new Voice { + << { c1 \startTrillSpan } + { s2. \grace { d16[\stopTrillSpan e] } } >> + c4 } +@end lilypond + +@refcommands + +@code{\startTrillSpan}, +@cindex @code{\startTrillSpan} +@code{\stopTrillSpan}. +@cindex @code{\stopTrillSpan} + +@seealso + +Program reference: @internalsref{TrillSpanner}, +@internalsref{TrillSpanEvent}. + +@node Fingering instructions +@subsection Fingering instructions + +@cindex fingering + +Fingering instructions can be entered using +@example +@var{note}-@var{digit} +@end example +For finger changes, use markup texts + +@lilypond[quote,verbatim,raggedright,fragment,relative=1] +c4-1 c-2 c-3 c-4 +c^\markup { \finger "2-3" } +@end lilypond + +@cindex finger change +@cindex scripts +@cindex superscript +@cindex subscript + +You can use the thumb-script to indicate that a note should be +played with the thumb (e.g., in cello music) +@lilypond[quote,verbatim,raggedright,fragment,relative=2] +8 +@end lilypond + +Fingerings for chords can also be added to individual notes +of the chord by adding them after the pitches +@lilypond[quote,verbatim,raggedright,fragment,relative=2] +< c-1 e-2 g-3 b-5 >4 +@end lilypond + +@noindent +In this case, setting @code{fingeringOrientations} will put fingerings next +to note heads + +@lilypond[quote,verbatim,raggedright,fragment,relative=1] +\set fingeringOrientations = #'(left down) + 4 +\set fingeringOrientations = #'(up right down) + 4 +@end lilypond + +Using this feature, it is also possible to put fingering instructions +very close to note heads in monophonic music, + +@lilypond[verbatim,raggedright,quote,fragment] +\set fingeringOrientations = #'(right) +4 +@end lilypond + + +@seealso + +Program reference: @internalsref{FingerEvent}, and @internalsref{Fingering}. + +Examples: @inputfileref{input/@/regression,finger@/-chords@/.ly}. + + + + +@node Grace notes +@subsection Grace notes + + +@c should have blurb about accaciatura / appogiatura + +@cindex @code{\grace} +@cindex ornaments +@cindex grace notes + +Grace notes are ornaments that are written out. The most common ones +are acciaccatura, which should be played as very short. It is denoted +by a slurred small note with a slashed stem. The appoggiatura is a +grace note that takes a fixed fraction of the main note, and is +denoted as a slurred note in small print without a slash. They +are entered with the commands @code{\acciaccatura} and +@code{\appoggiatura}, as demonstrated in the following example + + +@cindex appoggiatura +@cindex acciaccatura + +@lilypond[quote,raggedright,relative=2,verbatim,fragment] +b4 \acciaccatura d8 c4 \appoggiatura e8 d4 +\acciaccatura { g16[ f] } e4 +@end lilypond + +Both are special forms of the @code{\grace} command. By prefixing this +keyword to a music expression, a new one is formed, which will be +printed in a smaller font and takes up no logical time in a measure. + +@lilypond[quote,raggedright,relative=2,verbatim,fragment] +c4 \grace c16 c4 +\grace { c16[ d16] } c2 c4 +@end lilypond + +@noindent +Unlike @code{\acciaccatura} and @code{\appoggiatura}, the +@code{\grace} command does not start a slur. + +Internally, timing for grace notes is done using a second, `grace' +timing. Every point in time consists of two rational numbers: one +denotes the logical time, one denotes the grace timing. The above +example is shown here with timing tuples + +@lilypond[quote,raggedright] +<< + \relative c''{ + c4 \grace c16 c4 \grace { + c16[ d16] } c2 c4 + } + \new Lyrics \lyricmode { + \override LyricText #'font-family = #'typewriter + + \markup { (0,0) } 4 + \grace { \markup { + ( \fraction 1 4 , \fraction -1 16 ) } 16 } + \markup { (\fraction 1 4 , 0 ) } 4 + \grace { + \markup { (\fraction 2 4 , \fraction "-1" 8 ) } 16 + \markup { (\fraction 2 4 , \fraction "-1" 16 ) } 16 + } + \markup { ( \fraction 2 4 , 0 ) } + } +>> +@end lilypond + + +The placement of grace notes is synchronized between different staves. +In the following example, there are two sixteenth grace notes for +every eighth grace note + +@lilypond[quote,raggedright,relative=2,verbatim,fragment] +<< \new Staff { e4 \grace { c16[ d e f] } e4 } + \new Staff { c4 \grace { g8[ b] } c4 } >> +@end lilypond + + + +If you want to end a note with a grace, use the @code{\afterGrace} +command. It takes two arguments: the main note, and the grace notes +following the main note. + +@lilypond[raggedright, verbatim,relative=2,fragment] +c1 \afterGrace d1 { c16[ d] } c4 +@end lilypond + +This will put the grace notes after a ``space'' lasting 3/4 of the +length of the main note. The fraction 3/4 can be changed by setting +@code{afterGraceFraction}, ie. + +@example +afterGraceFraction = #(cons 7 8) +@end example + +@noindent +will put the grace note at 7/8 of the main note. + + +The same effect can be achieved manually by doing + + +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +\context Voice { + << { d1^\trill_( } + { s2 \grace { c16[ d] } } >> + c4) +} +@end lilypond + +@noindent +By adjusting the duration of the skip note (here it is a half-note), +the space between the main-note and the grace is adjusted. + + + + +A @code{\grace} section will introduce special typesetting settings, +for example, to produce smaller type, and set directions. Hence, when +introducing layout tweaks, they should be inside the grace section, +for example, +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +\new Voice { + \acciaccatura { + \stemDown + f16-> + \stemNeutral + } + g4 +} +@end lilypond + +@noindent +The overrides should also be reverted inside the grace section. + +The layout of grace sections can be changed throughout the music using +the function @code{add-grace-property}. The following example +undefines the Stem direction for this grace, so stems do not always +point up. + +@example +\new Staff @{ + #(add-grace-property 'Voice 'Stem 'direction '()) + @dots{} +@} +@end example + +@noindent +Another option is to change the variables @code{startGraceMusic}, +@code{stopGraceMusic}, @code{startAcciaccaturaMusic}, +@code{stopAcciaccaturaMusic}, @code{startAppoggiaturaMusic}, +@code{stopAppoggiaturaMusic}. More information is in the file +@file{ly/@/grace@/-init@/.ly}. + + +@seealso + +Program reference: @internalsref{GraceMusic}. + +@refbugs + +A score that starts with a @code{\grace} section needs an explicit +@code{\context Voice} declaration, otherwise the main note and the grace +note end up on different staves. + +Grace note synchronization can also lead to surprises. Staff notation, +such as key signatures, bar lines, etc., are also synchronized. Take +care when you mix staves with grace notes and staves without, for example, + +@lilypond[quote,raggedright,relative=2,verbatim,fragment] +<< \new Staff { e4 \bar "|:" \grace c16 d4 } + \new Staff { c4 \bar "|:" d4 } >> +@end lilypond + +@noindent +This can be remedied by inserting grace skips, for the above example + +@example +\new Staff @{ c4 \bar "|:" \grace s16 d4 @} +@end example + +Grace sections should only be used within sequential music +expressions. Nesting or juxtaposing grace sections is not supported, +and might produce crashes or other errors. + + +@node Glissando +@subsection Glissando +@cindex Glissando + +@cindex @code{\glissando} + +A glissando is a smooth change in pitch. It is denoted by a line or a +wavy line between two notes. It is requested by attaching +@code{\glissando} to a note + +@lilypond[quote,raggedright,fragment,relative=2,verbatim] +c\glissando c' +@end lilypond + +@seealso + +Program reference: @internalsref{Glissando}, and @internalsref{GlissandoEvent}. + +Example files: @file{input/@/regression/@/glissando@/.ly}. + + + +@refbugs + +Printing text over the line (such as @emph{gliss.}) is not supported. + + +@node Dynamics +@subsection Dynamics +@cindex Dynamics + + + +@cindex @code{\ppp} +@cindex @code{\pp} +@cindex @code{\p} +@cindex @code{\mp} +@cindex @code{\mf} +@cindex @code{\f} +@cindex @code{\ff} +@cindex @code{\fff} +@cindex @code{\ffff} +@cindex @code{\fp} +@cindex @code{\sf} +@cindex @code{\sff} +@cindex @code{\sp} +@cindex @code{\spp} +@cindex @code{\sfz} +@cindex @code{\rfz} + + +Absolute dynamic marks are specified using a command after a note +@code{c4\ff}. The available dynamic marks are @code{\ppp}, +@code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff}, +@code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff}, +@code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz} + +@lilypond[quote,verbatim,raggedright,fragment,relative=2] +c\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff +c2\fp c\sf c\sff c\sp c\spp c\sfz c\rfz +@end lilypond + +@cindex @code{\<} +@cindex @code{\>} +@cindex @code{\"!} + + + +A crescendo mark is started with @code{\<} and terminated with +@code{\!}. A decrescendo is started with @code{\>} and also terminated +with @code{\!}. Because these marks are bound to notes, you must +use spacer notes if multiple marks are needed during one note + +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +c\< c\! d\> e\! +<< f1 { s4 s4\< s4\! \> s4\! } >> +@end lilypond +This may give rise to very short hairpins. Use @code{minimum-length} +in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for +example + +@example +\override Staff.Hairpin #'minimum-length = #5 +@end example + +You can also use a text saying @emph{cresc.} instead of hairpins. Here +is an example how to do it + +@lilypond[quote,raggedright,fragment,relative=2,verbatim] +\setTextCresc +c\< d e f\! +\setHairpinCresc +e\> d c b\! +\setTextDecresc +c\> d e f\! +\setTextDim +e\> d c b\! +@end lilypond + +@cindex crescendo +@cindex decrescendo + +You can also supply your own texts +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +\set crescendoText = \markup { \italic "cresc. poco" } +\set crescendoSpanner = #'dashed-line +a'2\< a a a\!\mf +@end lilypond + +@cindex diminuendo + +To create new dynamic marks or text that should be aligned +with dynamics, see @ref{New dynamic marks}. + + +@refcommands + +@cindex @code{\dynamicUp} +@code{\dynamicUp}, +@cindex @code{\dynamicDown} +@code{\dynamicDown}, +@cindex @code{\dynamicNeutral} +@code{\dynamicNeutral}. + +@cindex direction, of dynamics + +@seealso + +Program reference: @internalsref{CrescendoEvent}, +@internalsref{DecrescendoEvent}, and +@internalsref{AbsoluteDynamicEvent}. + +Dynamics are @internalsref{DynamicText} and @internalsref{Hairpin} +objects. Vertical positioning of these symbols is handled by the +@internalsref{DynamicLineSpanner} object. diff --git a/Documentation/user/instrument-notation.itely b/Documentation/user/instrument-notation.itely index 897ac2b5b4..573c653296 100644 --- a/Documentation/user/instrument-notation.itely +++ b/Documentation/user/instrument-notation.itely @@ -1,6 +1,3842 @@ @c -*- coding: latin-1; 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 Instrument-specific notation @chapter Instrument-specific notation -This is a placeholder for very-near future reorganization of the manual. +This chapter explains how to use notation for specific instruments. + +@menu +* Rhythmic music:: +* Piano music:: +* Vocal music:: +* Other instrument specific notation:: +* Tablatures:: +* Popular music:: +* Ancient notation:: +@end menu + + +@node Rhythmic music +@section Rhythmic music + +Rhythmic music is primarily used for percussion and drum notation, but it can +also be used to show the rhythms of melodies. + +@menu +* Showing melody rhythms:: +* Entering percussion:: +* Percussion staves:: +@end menu + + +@node Showing melody rhythms +@subsection Showing melody rhythms + +Sometimes you might want to show only the rhythm of a melody. This +can be done with the rhythmic staff. All pitches of notes on such a +staff are squashed, and the staff itself has a single line + +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +\context RhythmicStaff { + \time 4/4 + c4 e8 f g2 | r4 g r2 | g1:32 | r1 | +} +@end lilypond + +@seealso + +Program reference: @internalsref{RhythmicStaff}. + +Examples: @inputfileref{input/@/regression,rhythmic@/-staff@/.ly}. + + +@node Entering percussion +@subsection Entering percussion + +@cindex percussion +@cindex drums + + +Percussion notes may be entered in @code{\drummode} mode, which is +similar to the standard mode for entering notes. Each piece of +percussion has a full name and an abbreviated name, and both can be used +in input files + +@lilypond[quote,raggedright,verbatim] +\drums { + hihat hh bassdrum bd +} +@end lilypond + +The complete list of drum names is in the init file +@file{ly/@/drumpitch@/-init@/.ly}. +@c TODO: properly document this. + +@seealso + +Program reference: @internalsref{DrumNoteEvent}. + +@node Percussion staves +@subsection Percussion staves +@cindex percussion +@cindex drums + +A percussion part for more than one instrument typically uses a +multiline staff where each position in the staff refers to one piece +of percussion. + + +To typeset the music, the notes must be interpreted in a +@internalsref{DrumStaff} and @internalsref{DrumVoice} contexts + +@lilypond[quote,raggedright,verbatim] +up = \drummode { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat } +down = \drummode { bassdrum4 snare8 bd r bd sn4 } + \new DrumStaff << + \new DrumVoice { \voiceOne \up } + \new DrumVoice { \voiceTwo \down } + >> +@end lilypond + +The above example shows verbose polyphonic notation. The short +polyphonic notation, described in @ref{Polyphony}, can also be used if +the @internalsref{DrumVoices} are instantiated by hand first. For example, + +@lilypond[quote,raggedright,fragment,verbatim] +\new DrumStaff << + \context DrumVoice = "1" { s1 *2 } + \context DrumVoice = "2" { s1 *2 } + \drummode { + bd4 sn4 bd4 sn4 + << + { \repeat unfold 16 hh16 } + \\ + { bd4 sn4 bd4 sn4 } + >> + } +>> +@end lilypond + + +There are also other layout possibilities. To use these, set the +property @code{drumStyleTable} in context @internalsref{DrumVoice}. +The following variables have been predefined + +@table @code +@item drums-style +This is the default. It typesets a typical drum kit on a five-line staff + +@lilypond[quote,linewidth=10.0\cm] +nam = \lyricmode { + cymc cyms cymr hh hhc hho hhho hhp + cb hc bd sn ss tomh tommh tomml toml tomfh tomfl } +mus = \drummode { + cymc cyms cymr hh hhc hho hhho hhp \break + cb hc bd sn ss tomh tommh tomml toml tomfh tomfl s16 } +\score { + << \new DrumStaff \with { + \remove Bar_engraver + \remove Time_signature_engraver + \override Stem #'transparent = ##t + \override Stem #'Y-extent-callback = ##f + minimumVerticalExtent = #'(-4.0 . 5.0) + } \mus + \context Lyrics \nam + >> + \layout { + \context { + \Score + \override LyricText #'font-family = #'typewriter + \override BarNumber #'transparent =##T + } + } +} +@end lilypond + +The drum scheme supports six different toms. When there are fewer toms, +simply select the toms that produce the desired result, i.e., to get toms +on the three middle lines you use @code{tommh}, @code{tomml}, and +@code{tomfh}. + +@item timbales-style +This typesets timbales on a two line staff + +@lilypond[quote,raggedright] +nam = \lyricmode { timh ssh timl ssl cb } +mus = \drummode { timh ssh timl ssl cb s16 } + +<< + \context DrumStaff \with { + \remove Bar_engraver + \remove Time_signature_engraver + \override Stem #'transparent = ##t + \override Stem #'Y-extent-callback = ##f + \override StaffSymbol #'line-count = #2 + \override StaffSymbol #'staff-space = #2 + minimumVerticalExtent = #'(-3.0 . 4.0) + drumStyleTable = #timbales-style + } \mus + \context Lyrics { + \override LyricText #'font-family = #'typewriter + \nam + } +>> +@end lilypond + +@item congas-style +This typesets congas on a two line staff + +@lilypond[quote,raggedright] +nam = \lyricmode { cgh cgho cghm ssh cgl cglo cglm ssl } +mus = \drummode { cgh cgho cghm ssh cgl cglo cglm ssl s16 } + +<< + \context DrumStaff \with { + \remove Bar_engraver + \remove Time_signature_engraver + drumStyleTable = #congas-style + \override StaffSymbol #'line-count = #2 + + %% this sucks; it will lengthen stems. + \override StaffSymbol #'staff-space = #2 + \override Stem #'transparent = ##t + \override Stem #'Y-extent-callback = ##f + } \mus + \context Lyrics { + \override LyricText #'font-family = #'typewriter + \nam + } +>> +@end lilypond + +@item bongos-style +This typesets bongos on a two line staff + +@lilypond[quote,raggedright] +nam = \lyricmode { boh boho bohm ssh bol bolo bolm ssl } +mus = \drummode { boh boho bohm ssh bol bolo bolm ssl s16 } + +<< + \context DrumStaff\with { + \remove Bar_engraver + \remove Time_signature_engraver + \override StaffSymbol #'line-count = #2 + drumStyleTable = #bongos-style + + %% this sucks; it will lengthen stems. + \override StaffSymbol #'staff-space = #2 + \override Stem #'transparent = ##t + \override Stem #'Y-extent-callback = ##f + } \mus + \context Lyrics { + \override LyricText #'font-family = #'typewriter + \nam + } +>> +@end lilypond + +@item percussion-style +To typeset all kinds of simple percussion on one line staves. + +@lilypond[quote,raggedright] +nam = \lyricmode { tri trio trim gui guis guil cb cl tamb cab mar hc } +mus = \drummode { tri trio trim gui guis guil cb cl tamb cab mar hc s16 } + +<< + \context DrumStaff\with{ + \remove Bar_engraver + drumStyleTable = #percussion-style + \override StaffSymbol #'line-count = #1 + \remove Time_signature_engraver + \override Stem #'transparent = ##t + \override Stem #'Y-extent-callback = ##f + } \mus + \context Lyrics { + \override LyricText #'font-family = #'typewriter + \nam + } +>> +@end lilypond +@end table + +If you do not like any of the predefined lists you can define your own +list at the top of your file + +@lilypond[quote,raggedright,verbatim] +#(define mydrums '( + (bassdrum default #f -1) + (snare default #f 0) + (hihat cross #f 1) + (pedalhihat xcircle "stopped" 2) + (lowtom diamond #f 3))) +up = \drummode { hh8 hh hh hh hhp4 hhp } +down = \drummode { bd4 sn bd toml8 toml } + +\new DrumStaff << + \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums) + \new DrumVoice { \voiceOne \up } + \new DrumVoice { \voiceTwo \down } +>> +@end lilypond + + +@seealso + +Init files: @file{ly/@/drumpitch@/-init@/.ly}. + +Program reference: @internalsref{DrumStaff}, @internalsref{DrumVoice}. + +@refbugs + +Because general MIDI does not contain rim shots, the sidestick is used +for this purpose instead. + + +@node Piano music +@section Piano music + +Piano staves are two normal staves coupled with a brace. The staves +are largely independent, but sometimes voices can cross between the +two staves. The same notation is also used for harps and other key +@c Is this `harp' or `harpsichord'? +instruments. The @internalsref{PianoStaff} is especially built to +handle this cross-staffing behavior. In this section we discuss the +@internalsref{PianoStaff} and some other pianistic peculiarities. + + +@menu +* Automatic staff changes:: +* Manual staff switches:: +* Pedals:: +* Arpeggio:: +* Staff switch lines:: +* Cross staff stems:: +@end menu + +@refbugs + +Dynamics are not centered, but workarounds do exist. See the +``piano centered dynamics'' template in @ref{Piano templates}. + +@cindex cross staff stem +@cindex stem, cross staff +@cindex distance between staves in piano music + +The distance between the two staves is the same for all systems in the +score. It is possible to override this per system, but it does require +an arcane command incantation. See +@inputfileref{input/@/test,piano@/-staff@/-distance@/.ly}. + + +@node Automatic staff changes +@subsection Automatic staff changes +@cindex Automatic staff changes + +Voices can be made to switch automatically between the top and the bottom +staff. The syntax for this is + +@quotation +@example +\autochange @dots{}@var{music}@dots{} +@end example +@end quotation + +@noindent +This will create two staves inside the current PianoStaff, called +@code{up} and @code{down}. The lower staff will be in bass clef by +default. + +A @code{\relative} section that is outside of @code{\autochange} has +no effect on the pitches of @var{music}, so, if necessary, put +@code{\relative} inside @code{\autochange} like + +@quotation +@example +\autochange \relative @dots{} @dots{} +@end example +@end quotation + + +The autochanger switches on basis of the pitch (middle C is the turning +point), and it looks ahead skipping over rests to switch in +advance. Here is a practical example + +@lilypond[quote,verbatim,raggedright] +\context PianoStaff + \autochange \relative c' + { + g4 a b c d r4 a g + } +@end lilypond + + +@seealso + +In this manual: @ref{Manual staff switches}. + +Program reference: @internalsref{AutoChangeMusic}. + + + +@refbugs + +The staff switches may not end up in optimal places. For high +quality output, staff switches should be specified manually. + + +@code{\autochange} cannot be inside @code{\times}. + +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 Manual staff switches +@subsection Manual staff switches + +@cindex manual staff switches +@cindex staff switch, manual + +Voices can be switched between staves manually, using the command +@example +\change Staff = @var{staffname} @var{music} +@end example + +@noindent +The string @var{staffname} is the name of the staff. It switches the +current voice from its current staff to the Staff called +@var{staffname}. Typically @var{staffname} is @code{"up"} or +@code{"down"}. The @context{Staff} referred to must already exist, so +usually the setup for a score will start with a setup of the staves, + +@example +<< + \context Staff = up @{ + \skip 1 * 10 % @emph{keep staff alive} + @} + \context Staff = down @{ + \skip 1 * 10 % @emph{idem} + @} +>> +@end example + + +and the @context{Voice} is inserted afterwards + +@example +\context Staff = down + \new Voice @{ @dots{} \change Staff = up @dots{} @} +@end example + + +@node Pedals +@subsection Pedals +@cindex Pedals + +Pianos have pedals that alter the way sound is produced. Generally, a +piano has three pedals, sustain, una corda, and sostenuto. + + +Piano pedal instruction can be expressed by attaching +@code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda}, +@code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp} to a +note or chord + +@lilypond[quote,raggedright,fragment,verbatim] +c'4\sustainDown c'4\sustainUp +@end lilypond + +What is printed can be modified by setting @code{pedal@var{X}Strings}, +where @var{X} is one of the pedal types: @code{Sustain}, +@code{Sostenuto} or @code{UnaCorda}. Refer to +@internalsref{SustainPedal} in the program reference for more +information. + +Pedals can also be indicated by a sequence of brackets, by setting the +@code{pedalSustainStyle} property to bracket objects + +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +\set Staff.pedalSustainStyle = #'bracket +c\sustainDown d e +b\sustainUp\sustainDown +b g \sustainUp a \sustainDown \bar "|." +@end lilypond + +A third style of pedal notation is a mixture of text and brackets, +obtained by setting the @code{pedalSustainStyle} property to +@code{mixed} + +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +\set Staff.pedalSustainStyle = #'mixed +c\sustainDown d e +b\sustainUp\sustainDown +b g \sustainUp a \sustainDown \bar "|." +@end lilypond + +The default `*Ped.' style for sustain and damper pedals corresponds to +style @code{#'text}. The sostenuto pedal uses @code{mixed} style by +default. + +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +c\sostenutoDown d e c, f g a\sostenutoUp +@end lilypond + +For fine-tuning the appearance of a pedal bracket, the properties +@code{edge-width}, @code{edge-height}, and @code{shorten-pair} of +@code{PianoPedalBracket} objects (see +@internalsref{PianoPedalBracket} in the Program reference) can be +modified. For example, the bracket may be extended to the right edge +of the note head + +@lilypond[quote,raggedright,fragment,verbatim,relative=2] +\override Staff.PianoPedalBracket #'shorten-pair = #'(0 . -1.0) +c\sostenutoDown d e c, f g a\sostenutoUp +@end lilypond + +@node Arpeggio +@subsection Arpeggio +@cindex Arpeggio + +@cindex broken chord +@cindex @code{\arpeggio} + +You can specify an arpeggio sign (also known as broken chord) on a +chord by attaching an @code{\arpeggio} to a chord + + +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +\arpeggio +@end lilypond + +When an arpeggio crosses staves, you attach an arpeggio to the chords +in both staves, and set +@internalsref{PianoStaff}.@code{connectArpeggios} + +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +\context PianoStaff << + \set PianoStaff.connectArpeggios = ##t + \new Staff { \arpeggio } + \new Staff { \clef bass \arpeggio } +>> +@end lilypond + +The direction of the arpeggio is sometimes denoted by adding an +arrowhead to the wiggly line + +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +\context Voice { + \arpeggioUp + \arpeggio + \arpeggioDown + \arpeggio +} +@end lilypond + +A square bracket on the left indicates that the player should not +arpeggiate the chord + +@c todo: ugh, lousy typography. Look for real example. --hwn + +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +\arpeggioBracket +\arpeggio +@end lilypond + +@refcommands + +@cindex @code{\arpeggio} +@code{\arpeggio}, +@cindex @code{\arpeggioUp} +@code{\arpeggioUp}, +@cindex @code{\arpeggioDown} +@code{\arpeggioDown}, +@cindex @code{\arpeggioNeutral} +@code{\arpeggioNeutral}, +@cindex @code{\arpeggioBracket} +@code{\arpeggioBracket}. + +@seealso + +Notation manual: @ref{Ties}, for writing out arpeggios. + +Program reference: @internalsref{ArpeggioEvent}, +@internalsref{Arpeggio}. + + + +@refbugs + +It is not possible to mix connected arpeggios and unconnected +arpeggios in one @internalsref{PianoStaff} at the same point in time. + +@node Staff switch lines +@subsection Staff switch lines + + +@cindex follow voice +@cindex staff switching +@cindex cross staff + +@cindex @code{followVoice} + +Whenever a voice switches to another staff, a line connecting the notes +can be printed automatically. This is switched on by setting +@code{followVoice} to true + +@lilypond[quote,raggedright,fragment,relative=1,verbatim] +\context PianoStaff << + \set followVoice = ##t + \context Staff \context Voice { + c1 + \change Staff=two + b2 a + } + \context Staff=two { \clef bass \skip 1*2 } +>> +@end lilypond + +@seealso + +Program reference: @internalsref{VoiceFollower}. + +@refcommands + +@cindex @code{\showStaffSwitch} +@code{\showStaffSwitch}, +@cindex @code{\hideStaffSwitch} +@code{\hideStaffSwitch}. + + +@node Cross staff stems +@subsection Cross staff stems + +Chords that cross staves may be produced by increasing the length +of the stem in the lower staff, so it reaches the stem in the upper +staff, or vice versa. + +@lilypond[raggedright,verbatim,quote] +stemExtend = \once \override Stem #'length = #22 +noFlag = \once \override Stem #'flag-style = #'no-flag +\context PianoStaff << + \new Staff { + \stemDown \stemExtend + f'4 + \stemExtend \noFlag + f'8 + } + \new Staff { + \clef bass + a4 a8 + } +>> +@end lilypond + + +@node Vocal music +@section Vocal music + +There are three different issues when printing vocal music + +@itemize @bullet +@item +Song texts must be entered as text, not notes. For example, the +input@tie{}@code{d} should be interpreted as a one letter syllable, not the +note@tie{}D. + +@item +Song texts must be printed as text, not as notes. + +@item +Song texts must be aligned with the notes of their melody. +@end itemize + +The simplest solution for printing music uses the @code{\addlyrics} +function to solve all these problems at once. However, these +three functions can be controlled separately, which is necessary +for complex vocal music. + + +@menu +* Setting simple songs:: +* Entering lyrics:: +* Hyphens and extenders:: +* The Lyrics context:: +* Flexibility in alignment:: +* More stanzas:: +* Ambitus:: +* Other vocal issues:: +@end menu + +@node Setting simple songs +@subsection Setting simple songs + +The easiest way to add lyrics to a melody is to append +@cindex \addlyrics +@example +\addlyrics @{ @var{the lyrics} @} +@end example + +@noindent +to a melody. Here is an example, + +@lilypond[raggedright,verbatim,fragment,quote] +\time 3/4 +\relative { c2 e4 g2. } +\addlyrics { play the game } +@end lilypond + +More stanzas can be added by adding more +@code{\addlyrics} sections + +@lilypond[raggedright,verbatim,fragment,quote] +\time 3/4 +\relative { c2 e4 g2. } +\addlyrics { play the game } +\addlyrics { speel het spel } +\addlyrics { joue le jeu } +@end lilypond + +@c TODO - this isn't such a great place for this note, but I can't +@c find a better place without rearranging a lot of lyric stuff. +@c It's yet another thing to look at post-3.0. + +The @code{\addlyrics} command is actually just a convienient way +to write a more complicated LilyPond structure that sets up the +lyrics. You should use @code{\addlyrics} unless you need to do +fancy things, in which case you should investigate +@code{\lyricsto} or @code{\lyricmode}. + +@example +@{ MUSIC @} +\addlyrics @{ LYRICS @} +@end example + +@noindent +is the same as + +@example +\context Voice = blah @{ music @} +\lyricsto "blah" \new lyrics @{ LYRICS @} +@end example + +@refbugs + +@code{\addlyrics} cannot handle polyphony. + + +@node Entering lyrics +@subsection Entering lyrics + + +@cindex lyrics +@cindex @code{\lyricmode} +@cindex punctuation + +Lyrics are entered in a special input mode. This mode is introduced +by the keyword @code{\lyricmode}, or by using @code{addlyrics} or +@code{lyricsto}. In this mode you can enter lyrics, +with punctuation and accents, and the input @code{d} is not parsed as +a pitch, but rather as a one letter syllable. Syllables are entered +like notes, but with pitches replaced by text. For example, +@example +\lyricmode @{ Twin-4 kle4 twin- kle litt- le star2 @} +@end example + + +A word lyrics mode begins with an alphabetic character, and ends with +any space or digit. The following characters can be any character +that is not a digit or white space. One important consequence of this +is that a word can end with @code{@}}. The following example is +usually a mistake in the input file. The syllable includes a @code{@}}, so the +opening brace is not balanced +@example +\lyricmode @{ twinkle@} +@end example + +@cindex @code{\property}, in @code{\lyricmode} +@noindent +Similarly, a period which follows an alphabetic sequence is included in +the resulting string. As a consequence, spaces must be inserted around +property commands +@example +\override Score . LyricText #'font-shape = #'italic +@end example + +@cindex @code{_} +@cindex spaces, in lyrics +@cindex quotes, in lyrics + +Any @code{_} character that appears in an unquoted word is converted +to a space. This provides a mechanism for introducing spaces into words +without using quotes. Quoted words can also be used in Lyrics mode to +specify words that cannot be written with the above rules. The +following example incorporates double quotes + +@example +\lyricmode @{ He said: "\"Let" my peo ple "go\"" @} +@end example + +This example is slightly academic, since it gives better looking +results using single quotes, @code{``} and @code{''} +@example +\lyricmode @{ He said: ``Let my peo ple go'' @} +@end example + + +The full definition of a word start in Lyrics mode is somewhat more +complex. + +A word in Lyrics mode begins with: an alphabetic character, @code{_}, +@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A} +through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^}, +any 8-bit character with ASCII code over 127, or a two-character +combination of a backslash followed by one of @code{`}, @code{'}, +@code{"}, or @code{^}. + + + +@seealso + +Program reference: events @internalsref{LyricEvent}, and +@internalsref{LyricText}. + +@refbugs + +The definition of lyrics mode is too complex. + +@node Hyphens and extenders +@subsection Hyphens and extenders + +@cindex hyphens + +Centered hyphens are entered as `@code{-}@code{-}' between syllables. +The hyphen will have variable length depending on the space between +the syllables and it will be centered between the syllables. + +@cindex melisma +@cindex extender + +When a lyric is sung over many notes (this is called a melisma), this is +indicated with a horizontal line centered between a syllable and the +next one. Such a line is called an extender line, and it is entered as +@code{__}. + +@ignore +FIXME: check that this compiles and displays correctly. I don't want +to commit this part blindly. + +In tighly engraved music, hyphens can be removed. In some languages +(e.g. German and Hungarian), hyphens should not disappear, since +spelling depends on hyphenation. For that purpose, hyphens can be +forced to remain by overriding @code{minimum-length} of +the @code{LyricHyphen} grob. + +(code from 2.2) +\score { +<< \notes \new Staff \relative c'' { \time 1/4 c16[ c c c] +\time 1/4 +c16[ c c c] +\time 1/4 +c16[ c c c] + +} + \lyrics \new Lyrics \with { + % Otherwise lyrics are so far apart that hyphens don't disappear + \override SeparationItem #'padding = #0.0 + }{ bla -- bla -- bla -- bla -- + bla -- bla -- bla -- bla -- + + \override LyricHyphen #'minimum-length = #0.7 + \override LyricHyphen #'spacing-procedure = + #Hyphen_spanner::set_spacing_rods + + bla -- bla -- bla -- bla + }>> + \paper { + indent = 0.0 \cm + linewidth = 3.4 \cm + + \context { + \StaffContext \remove "Time_signature_engraver" + } + + } + +} +@end ignore + + +@seealso + +Program reference: @internalsref{HyphenEvent}, +@internalsref{ExtenderEvent}, @internalsref{LyricHyphen}, and +@internalsref{LyricExtender} + + + +@node The Lyrics context +@subsection The Lyrics context + + +Lyrics are printed by interpreting them in a @internalsref{Lyrics} context +@example +\context Lyrics \lyricmode @dots{} +@end example + +@cindex automatic syllable durations +@cindex @code{\lyricsto} +@cindex lyrics and melodies + +This will place the lyrics according to the durations that were +entered. The lyrics can also be aligned under a given melody +automatically. In this case, it is no longer necessary to enter the +correct duration for each syllable. This is achieved by combining the +melody and the lyrics with the @code{\lyricsto} expression +@example +\lyricsto @var{name} \new Lyrics @dots{} +@end example + +This aligns the lyrics to the +notes of the @internalsref{Voice} context called @var{name}, which has +to exist. Therefore, normally the @code{Voice} is specified first, and +then the lyrics are specified with @code{\lyricsto}. The command +@code{\lyricsto} switches to @code{\lyricmode} mode automatically, so the +@code{\lyricmode} keyword may be omitted. + +For different or more complex orderings, the best way is to setup the +hierarchy of staves and lyrics first, e.g., +@example +\context ChoirStaff << + \context Lyrics = sopranoLyrics @{ s1 @} + \context Voice = soprano @{ @emph{music} @} + \context Lyrics = tenorLyrics @{ s1 @} + \context Voice = tenor @{ @emph{music} @} +>> +@end example +and then combine the appropriate melodies and lyric lines +@example +\lyricsto "soprano" \context Lyrics = sopranoLyrics + @emph{the lyrics} +@end example + +@noindent +The final input would resemble + +@example +<<\context ChoirStaff << @emph{setup the music} >> + \lyricsto "soprano" @emph{etc} + \lyricsto "alto" @emph{etc} + @emph{etc} +>> +@end example + + +The @code{\lyricsto} command detects melismata: it only puts one +syllable under a tied or slurred group of notes. If you want to force +an unslurred group of notes to be a melisma, insert @code{\melisma} +after the first note of the group, and @code{\melismaEnd} after the +last one, e.g., + +@lilypond[quote,relative=2,raggedright,fragment,verbatim] +<< + \context Voice = "lala" { + \time 3/4 + f4 g8 + \melisma + f e f + \melismaEnd + e2 + } + \lyricsto "lala" \new Lyrics { + la di __ daah + } +>> +@end lilypond + +In addition, notes are considered a melisma if they are manually +beamed, and automatic beaming (see @ref{Setting automatic beam +behavior}) is switched off. + +@ignore + +@c nonformation: + +The criteria for deciding melismata can +be tuned with the property @code{melismaBusyProperties}. See +@internalsref{Melisma_translator} in the program reference for more +information. + +@end ignore + +Lyrics can also be entered without @code{\lyricsto}. In this case the +duration of each syllable must be entered explicitly, for example, + +@example +play2 the4 game2. +sink2 or4 swim2. +@end example + +The alignment to a melody can be specified with the +@code{associatedVoice} property, + +@example +\set associatedVoice = #"lala" +@end example + +@noindent +The value of the property (here: @code{"lala"}) should be the name of +a @internalsref{Voice} context. Without this setting, extender lines +will not be formatted properly. + +Here is an example demonstrating manual lyric durations, + +@lilypond[relative=1,raggedright,verbatim,fragment,quote] +<< \context Voice = melody { + \time 3/4 + c2 e4 g2. + } + \new Lyrics \lyricmode { + \set associatedVoice = #"melody" + play2 the4 game2. + } >> +@end lilypond + +@cindex SATB +@cindex choral score + +A complete example of a SATB score setup is in section +@ref{Vocal ensembles}. + + +@refcommands + +@code{\melisma}, @code{\melismaEnd} +@cindex @code{\melismaEnd} +@cindex @code{\melisma} + +@seealso + +Program reference: @internalsref{LyricCombineMusic}, +@internalsref{Lyrics}, @internalsref{Melisma_translator}. + + +@inputfileref{input/@/regression,lyric@/-combine@/-new@/.ly}. +@c TODO: make separate section for melismata + +@refbugs + +Melismata are not detected automatically, and extender lines must be +inserted by hand. + + +@c TODO: document \new Staff << Voice \lyricsto >> bug + +@node Flexibility in alignment +@subsection Flexibility in alignment + + +Often, different stanzas of one song are put to one melody in slightly +differing ways. Such variations can still be captured with +@code{\lyricsto}. + +One possibility is that the text has a melisma in one stanza, but +multiple syllables in another one. One solution is to make the faster +voice ignore the melisma. This is done by setting +@code{ignoreMelismata} in the Lyrics context. + +There has one tricky aspect. The setting for @code{ignoreMelismata} +must be set one syllable @emph{before} the non-melismatic syllable +in the text, as shown here, + +@lilypond[verbatim,raggedright,quote] +<< + \relative \context Voice = "lahlah" { + \set Staff.autoBeaming = ##f + c4 + \slurDotted + f8.[( g16]) + a4 + } + \new Lyrics \lyricsto "lahlah" { + more slow -- ly + } + \new Lyrics \lyricsto "lahlah" { + \set ignoreMelismata = ##t % applies to "fas" + go fas -- ter + \unset ignoreMelismata + still + } +>> +@end lilypond + + +The @code{ignoreMelismata} applies to the syllable ``fas'', so it +should be entered before ``go''. + +The reverse is also possible: making a lyric line slower than the +standard. This can be achieved by insert @code{\skip}s into the +lyrics. For every @code{\skip}, the text will be delayed another note. +For example, + +@lilypond[verbatim,raggedright,quote] +\relative { c c g' } +\addlyrics { + twin -- \skip 4 + kle +} +@end lilypond + +More complex variations in text underlay are possible. It is possible +to switch the melody for a line of lyrics during the text. This is +done by setting the @code{associatedVoice} property. In the example + +@lilypond[raggedright,quote] +<< + \relative \context Voice = "lahlah" { + \set Staff.autoBeaming = ##f + c4 + << + \context Voice = alternative { + \voiceOne + \times 2/3 { + % show associations clearly. + \override NoteColumn #'force-hshift = #-3 + f8 f g + } + } + { + \voiceTwo + f8.[ g16] + \oneVoice + } >> + a8( b) c + } + \new Lyrics \lyricsto "lahlah" { + Ju -- ras -- sic Park + } + \new Lyrics \lyricsto "lahlah" { + % Tricky: need to set associatedVoice + % one syllable too soon! + \set associatedVoice = alternative % applies to "ran" + Ty -- + ran -- + no -- + \set associatedVoice = lahlah % applies to "rus" + sau -- rus Rex + } >> +@end lilypond + +@noindent +the text for the first stanza is set to a melody called ``lahlah'', + +@example +\new Lyrics \lyricsto "lahlah" @{ + Ju -- ras -- sic Park +@} +@end example + + +The second stanza initially is set to the @code{lahlah} context, but +for the syllable ``ran'', it switches to a different melody. +This is achieved with +@example +\set associatedVoice = alternative +@end example + +@noindent +Here, @code{alternative} is the name of the @code{Voice} context +containing the triplet. + +Again, the command must be one syllable too early, before ``Ty'' in +this case. + +@example +\new Lyrics \lyricsto "lahlah" @{ + \set associatedVoice = alternative % applies to "ran" + Ty -- + ran -- + no -- + \set associatedVoice = lahlah % applies to "rus" + sau -- rus Rex +@} +@end example + +@noindent +The underlay is switched back to the starting situation by assigning +@code{lahlah} to @code{associatedVoice}. + + + + +@node More stanzas +@subsection More stanzas + +@cindex phrasing, in lyrics + + +@cindex stanza number +@cindex singer's names +@cindex name of singer + +Stanza numbers can be added by setting @code{stanza}, e.g., + +@lilypond[quote,raggedright,verbatim,relative=2,fragment] +\new Voice { + \time 3/4 g2 e4 a2 f4 g2. +} \addlyrics { + \set stanza = "1. " + Hi, my name is Bert. +} \addlyrics { + \set stanza = "2. " + Oh, che -- ri, je t'aime +} +@end lilypond + +These numbers are put just before the start of first syllable. + +Names of singers can also be added. They are printed at the start of +the line, just like instrument names. They are created by setting +@code{vocalName}. A short version may be entered as @code{vocNam}. + + +@lilypond[fragment,raggedright,quote,verbatim,relative=2] +\new Voice { + \time 3/4 g2 e4 a2 f4 g2. +} \addlyrics { + \set vocalName = "Bert " + Hi, my name is Bert. +} \addlyrics { + \set vocalName = "Ernie " + Oh, che -- ri, je t'aime +} +@end lilypond + +@seealso + +Program reference: Layout objects @internalsref{LyricText} and +@internalsref{VocalName}. Music expressions +@internalsref{LyricEvent}. + + + +@node Ambitus +@subsection Ambitus +@cindex ambitus + +The term @emph{ambitus} denotes a range of pitches for a given voice +in a part of music. It may also denote the pitch range that a musical +instrument is capable of playing. Ambits are printed on vocal parts, +so performers can easily determine it meets their capabilities. + +Ambits are denoted at the beginning of a piece near the initial clef. +The range is graphically specified by two note heads that represent the +minimum and maximum pitch. To print such ambits, add the +@internalsref{Ambitus_engraver} to the @internalsref{Voice} context, +for example, + +@example +\layout @{ + \context @{ + \Voice + \consists Ambitus_engraver + @} +@} +@end example + +This results in the following output + +@lilypond[quote,raggedright] +\layout { + \context { + \Staff + \consists Ambitus_engraver + } +} + +\relative \new Staff { + as'' c e2 cis,2 +} +@end lilypond + +If you have multiple voices in a single staff and you want a single +ambitus per staff rather than per each voice, add the +@internalsref{Ambitus_engraver} to the @internalsref{Staff} context +rather than to the @internalsref{Voice} context. Here is an example, + +@lilypond[verbatim,raggedright,quote] +\new Staff \with { + \consists "Ambitus_engraver" +} +<< + \new Voice \with { + \remove "Ambitus_engraver" + } \relative c'' { + \override Ambitus #'X-offset-callbacks + = #(list (lambda (grob axis) -1.0)) + \voiceOne + c4 a d e f2 + } + \new Voice \with { + \remove "Ambitus_engraver" + } \relative c' { + \voiceTwo + es4 f g as b2 + } +>> +@end lilypond + +@noindent +This example uses one advanced feature, + +@example +\override Ambitus #'X-offset-callbacks + = #(list (lambda (grob axis) -1.0)) +@end example + +@noindent +This code moves the ambitus to the left. The same effect could have +been achieved with @code{extra-offset}, but then the formatting system +would not reserve space for the moved object. + +@seealso + +Program reference: @internalsref{Ambitus}, +@internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead}, +@internalsref{AmbitusAccidental}. + +Examples: @inputfileref{input/@/regression,ambitus@/.ly}. + +@refbugs + +There is no collision handling in the case of multiple per-voice +ambitus. + +@node Other vocal issues +@subsection Other vocal issue + +@ignore +yeah, I'm giving up somewhat by stuffing a bunch of things in +here. But at least they're in the manual now; it's easier to +move them around in the manual once they're already here. + +Besides, if users complain about everything stuffed in here, I +can ask them for specific instructions about where to move these +examples, and that might get them more involved in the docs. -gp +@end ignore + +You can display alternate (or divisi) lyrics by naming voice +contexts and attaching lyrics to those specific contexts. + +@lilypond[verbatim,raggedright,quote] +\score{ << + \context Voice = "melody" { + \relative c' { + c4 + << + { \voiceOne c8 e } + \context Voice = splitpart { \voiceTwo c4 } + >> + \oneVoice c4 c | c + } + } + \new Lyrics \lyricsto "melody" { we shall not o- ver- come } + \new Lyrics \lyricsto "splitpart" { shall } +>> } +@end lilypond + + +You can use this trick to display different lyrics for a repeated +section. + +@lilypond[verbatim,raggedright,quote] +\score{ << + \context Voice = melody \relative c' { + c2 e | g e | c1 | + \context Voice = verse \repeat volta 2 {c4 d e f | g1 | } + a2 b | c1} + \lyricsto melody \context Lyrics = mainlyrics \lyricmode { + do mi sol mi do + la si do } + \lyricsto verse \context Lyrics = mainlyrics \lyricmode { + do re mi fa sol } + \lyricsto verse \context Lyrics = repeatlyrics \lyricmode { + dodo rere mimi fafa solsol } +>> +} +@end lilypond + + +@node Other instrument specific notation, Tablatures, Vocal music, Notation manual +@section Other instrument specific notation + +This section includes extra information for writing string music, and may +include extra information for other instruments in the future. + +@menu +* Harmonic notes:: +@end menu + +@node Harmonic notes, , Other instrument specific notation, Other instrument specific notation +@subsection Harmonic notes + +@cindex artificial harmonics +@cindex harmonics + +Artificial harmonics are notated with a different notehead style. They +are entered by marking the harmonic pitch with @code{\harmonic}. + +@lilypond[raggedright,verbatim,quote,fragment] +4 +@end lilypond + + +@node Tablatures, Popular music, Other instrument specific notation, Notation manual +@section Tablatures + +@cindex tablature +@cindex guitar tablature + +Tablature notation is used for notating music for plucked string +instruments. Pitches are not denoted with note heads, but by +indicating on which string and fret a note must be played. LilyPond +offers limited support for tablature. + +@menu +* Tablatures basic:: +* Non-guitar tablatures:: +@end menu + +@node Tablatures basic, Non-guitar tablatures, Tablatures, Tablatures +@subsection Tablatures basic +@cindex Tablatures basic + +The string number associated to a note is given as a backslash +followed by a number, e.g., @code{c4\3} for a C quarter on the third +string. By default, string 1 is the highest one, and the tuning +defaults to the standard guitar tuning (with 6 strings). The notes +are printed as tablature, by using @internalsref{TabStaff} and +@internalsref{TabVoice} contexts + +@lilypond[quote,raggedright,fragment,verbatim] +\context TabStaff { + a,4\5 c'\2 a\3 e'\1 + e\4 c'\2 a\3 e'\1 +} +@end lilypond + +@cindex @code{minimumFret} +@cindex fret + +When no string is specified, the first string that does not give a +fret number less than @code{minimumFret} is selected. The default +value for @code{minimumFret} is 0 + + +@example +e16 fis gis a b4 +\set TabStaff.minimumFret = #8 +e16 fis gis a b4 +@end example +@lilypond[quote,raggedright] +frag = { + \key e \major + e16 fis gis a b4 + \set TabStaff.minimumFret = #8 + e16 fis gis a b4 +} + \context StaffGroup << + \context Staff { \clef "G_8" \frag } + \context TabStaff { \frag } + >> +@end lilypond + +@seealso + +Program reference: @internalsref{TabStaff}, @internalsref{TabVoice}, and +@internalsref{StringNumberEvent}. + +@refbugs + +Chords are not handled in a special way, and hence the automatic +string selector may easily select the same string to two notes in a +chord. + + +@node Non-guitar tablatures, , Tablatures basic, Tablatures +@subsection Non-guitar tablatures +@cindex Non-guitar tablatures + +You can change the number of strings, by setting the number of lines +in the @internalsref{TabStaff}. + +You can change the tuning of the strings. A string tuning is given as +a Scheme list with one integer number for each string, the number +being the pitch (measured in semitones relative to middle C) of an +open string. The numbers specified for @code{stringTuning} are the +numbers of semitones to subtract or add, starting the specified pitch +by default middle C, in string order. In the next example, +@code{stringTunings} is set for the pitches e, a, d, and g + +@lilypond[quote,raggedright,fragment,verbatim] +\context TabStaff << + \set TabStaff.stringTunings = #'(-5 -10 -15 -20) + { + a,4 c' a e' e c' a e' + } +>> +@end lilypond + +@refbugs + +No guitar special effects have been implemented. + +@seealso + +Program reference: @internalsref{Tab_note_heads_engraver}. + + +@node Popular music, Orchestral music, Tablatures, Notation manual +@section Popular music + +This section discusses issues that arise when writing popular music. + +@menu +* Chord names:: +* Chords mode:: +* Printing chord names:: +* Fret diagrams:: +@end menu + +@node Chord names, Chords mode, Popular music, Popular music +@subsection Chord names +@cindex Chords + +LilyPond has support for printing chord names. Chords may be entered +in musical chord notation, i.e., @code{< .. >}, but they can also be +entered by name. Internally, the chords are represented as a set of +pitches, so they can be transposed + + +@lilypond[quote,raggedright,verbatim,raggedright] +twoWays = \transpose c c' { + \chordmode { + c1 f:sus4 bes/f + } + + + +} + +<< \context ChordNames \twoWays + \context Voice \twoWays >> +@end lilypond + +This example also shows that the chord printing routines do not try to +be intelligent. The last chord (@code{f bes d}) is not interpreted as +an inversion. + +@c this menu isn't needed. +@ignore +@menu +* Chords mode:: +* Printing chord names:: +@end menu +@end ignore + +@node Chords mode +@subsection Chords mode +@cindex Chords mode + +In chord mode sets of pitches (chords) are entered with normal note +names. A chord is entered by the root, which is entered like a +normal pitch + +@lilypond[quote,raggedright,fragment,verbatim] +\chordmode { es4. d8 c2 } +@end lilypond + +@noindent +The mode is introduced by the keyword @code{\chordmode}. + +@cindex chord entry +@cindex chord mode + +Other chords may be entered by suffixing a colon and introducing a +modifier (which may include a number if desired) +@lilypond[quote,fragment,verbatim] +\chordmode { e1:m e1:7 e1:m7 } +@end lilypond +The first number following the root is taken to be the `type' of the +chord, thirds are added to the root until it reaches the specified +number +@lilypond[quote,fragment,verbatim] +\chordmode { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11 } +@end lilypond + +@cindex root of chord +@cindex additions, in chords +@cindex removals, in chords + +More complex chords may also be constructed adding separate steps +to a chord. Additions are added after the number following +the colon and are separated by dots +@lilypond[quote,verbatim,fragment] +\chordmode { c:5.6 c:3.7.8 c:3.6.13 } +@end lilypond +Chord steps can be altered by suffixing a @code{-} or @code{+} sign +to the number +@lilypond[quote,verbatim,fragment] +\chordmode { c:7+ c:5+.3- c:3-.5-.7- } +@end lilypond +Removals are specified similarly and are introduced by a caret. They +must come after the additions +@lilypond[quote,verbatim,fragment] +\chordmode { c^3 c:7^5 c:9^3.5 } +@end lilypond + +Modifiers can be used to change pitches. The following modifiers are +supported + +@table @code +@item m +The minor chord. This modifier lowers the 3rd and (if present) the 7th step. + +@item dim +The diminished chord. This modifier lowers the 3rd, 5th and (if present) +the 7th step. + +@item aug +The augmented chord. This modifier raises the 5th step. + +@item maj +The major 7th chord. This modifier raises the 7th step if present. + +@item sus +The suspended 4th or 2nd. This modifier removes the 3rd +step. Append either @code{2} or @code{4} to add the 2nd or 4th step to +the chord. +@end table + +Modifiers can be mixed with additions +@lilypond[quote,verbatim,fragment] + \chordmode { c:sus4 c:7sus4 c:dim7 c:m6 } +@end lilypond + +@cindex modifiers, in chords. +@cindex @code{aug} +@cindex @code{dim} +@cindex @code{maj} +@cindex @code{sus} +@cindex @code{m} + +Since an unaltered 11 does not sound good when combined with an +unaltered 3, the 11 is removed in this case (unless it is added +explicitly) +@lilypond[quote,raggedright,fragment,verbatim] +\chordmode { c:13 c:13.11 c:m13 } +@end lilypond + +@cindex @code{/} + +An inversion (putting one pitch of the chord on the bottom), as well +as bass notes, can be specified by appending +@code{/}@var{pitch} to the chord +@lilypond[quote,raggedright,fragment,verbatim] +\chordmode { c1 c/g c/f } +@end lilypond +@cindex @code{/+} + +A bass note can be added instead transposed out of the chord, +by using @code{/+}@var{pitch}. + +@lilypond[quote,raggedright,fragment,verbatim] +\chordmode { c1 c/+g c/+f } +@end lilypond + +Chords is a mode similar to @code{\lyricmode}, etc. Most +of the commands continue to work, for example, @code{r} and +@code{\skip} can be used to insert rests and spaces, and property +commands may be used to change various settings. + + + +@refbugs + +Each step can only be present in a chord once. The following +simply produces the augmented chord, since @code{5+} is interpreted +last +@cindex clusters +@lilypond[quote,raggedright,verbatim,fragment] +\chordmode { c:5.5-.5+ } +@end lilypond + + +@node Printing chord names +@subsection Printing chord names + +@cindex printing chord names +@cindex chord names +@cindex chords + +For displaying printed chord names, use the @internalsref{ChordNames} context. +The chords may be entered either using the notation +described above, or directly using @code{<} and @code{>} + +@lilypond[quote,verbatim,raggedright] +harmonies = { + \chordmode {a1 b c} +} +<< + \context ChordNames \harmonies + \context Staff \harmonies +>> +@end lilypond + +You can make the chord changes stand out by setting +@internalsref{ChordNames}.@code{chordChanges} to true. This will only +display chord names when there is a change in the chords scheme and at +the start of a new line + +@lilypond[quote,verbatim,raggedright] +harmonies = \chordmode { + c1:m c:m \break c:m c:m d +} +<< + \context ChordNames { + \set chordChanges = ##t + \harmonies } + \context Staff \transpose c c' \harmonies +>> +@end lilypond + +The previous examples all show chords over a staff. This is not +necessary. Chords may also be printed separately. It may be necessary +to add @internalsref{Volta_engraver} and @internalsref{Bar_engraver} +for showing repeats. + +@lilypond[raggedright,verbatim] +\new ChordNames \with { + \override BarLine #'bar-size = #4 + voltaOnThisStaff = ##t + \consists Bar_engraver + \consists "Volta_engraver" +} +\repeat volta 2 \chordmode { + f1:maj f:7 bes:7 + c:maj +} \alternative { + es e +} +@end lilypond + + +The default chord name layout is a system for Jazz music, proposed by +Klaus Ignatzek (see @ref{Literature list}). It can be tuned through the +following properties + +@table @code +@cindex @code{chordNameExceptions} +@item chordNameExceptions +This is a list that contains the chords that have special formatting. + +The exceptions list should be encoded as +@example +@{ 1 \markup @{ \super "7" "wahh" @} @} +@end example + +To get this information into @code{chordNameExceptions} takes a little +manoeuvring. The following code transforms @code{chExceptionMusic} +(which is a sequential music) into a list of exceptions. +@example +(sequential-music-to-chord-exceptions chExceptionMusic #t) +@end example +Then, +@example +(append + (sequential-music-to-chord-exceptions chExceptionMusic #t) + ignatzekExceptions) +@end example +adds the new exceptions to the default ones, which are defined in +@file{ly/@/chord@/-modifier@/-init@/.ly}. + +For an example of tuning this property, see also +@inputfileref{input/@/regression,chord@/-name@/-exceptions@/.ly}. +@cindex exceptions, chord names. + + +@cindex @code{majorSevenSymbol} +@item majorSevenSymbol +This property contains the markup object used for the 7th step, when +it is major. Predefined options are @code{whiteTriangleMarkup} and +@code{blackTriangleMarkup}. See +@inputfileref{input/@/regression,chord@/-name@/-major7@/.ly} for an example. + +@cindex @code{chordNameSeparator} +@item chordNameSeparator +Different parts of a chord name are normally separated by a +slash. By setting @code{chordNameSeparator}, you can specify other +separators, e.g., +@lilypond[quote,raggedright,fragment,verbatim] +\context ChordNames \chordmode { + c:7sus4 + \set chordNameSeparator + = \markup { \typewriter "|" } + c:7sus4 +} +@end lilypond + +@cindex @code{chordRootNamer} +@item chordRootNamer +The root of a chord is usually printed as a letter with an optional +alteration. The transformation from pitch to letter is done by this +function. Special note names (for example, the German ``H'' for a +B-chord) can be produced by storing a new function in this property. + +@cindex @code{chordNoteNamer} +@item chordNoteNamer +The default is to print single pitch, e.g., the bass note, using the +@code{chordRootNamer}. The @code{chordNoteNamer} property can be set +to a specialized function to change this behavior. For example, the +base can be printed in lower case. + +@end table + +The predefined variables @code{\germanChords}, +@code{\semiGermanChords} set these variables. The effect is +demonstrated here, + +@lilypondfile[raggedright]{chord-names-german.ly} + +There are also two other chord name schemes implemented: an alternate +Jazz chord notation, and a systematic scheme called Banter chords. The +alternate Jazz notation is also shown on the chart in @ref{Chord name +chart}. Turning on these styles is described in the input file +@inputfileref{input/@/test,chord@/-names@/-jazz@/.ly}. + +@cindex Banter +@cindex jazz chords +@cindex chords, jazz + + +@refcommands + +@cindex @code{\germanChords} +@code{\germanChords}, +@cindex @code{\semiGermanChords} +@code{\semiGermanChords}. + + + + +@seealso + +Examples: @inputfileref{input/@/regression,chord@/-name@/-major7@/.ly}, +@inputfileref{input/@/regression,chord@/-name@/-exceptions@/.ly}, +@inputfileref{input/@/test,chord@/-names@/-jazz@/.ly}. + + +Init files: @file{scm/@/chords@/-ignatzek@/.scm}, and +@file{scm/@/chord@/-entry@/.scm}. + + +@refbugs + +Chord names are determined solely from the list of pitches. Chord +inversions are not identified, and neither are added bass notes. This +may result in strange chord names when chords are entered with the +@code{< .. >} syntax. + + +@node Fret diagrams +@subsection Fret diagrams +@cindex fret diagrams +@cindex chord diagrams + +Fret diagrams can be added to music as a markup to the desired note. The +markup contains information about the desired fret diagram, as shown in the +following example + +@lilypond[verbatim, raggedright, quote] +\context Voice { + d' ^\markup \fret-diagram #"6-x;5-x;4-o;3-2;2-3;1-2;" + d' d' d' + fis' ^\markup \override #'(size . 0.75) { + \override #'(finger-code . below-string) { + \fret-diagram-verbose #'((place-fret 6 2 1) (barre 6 1 2) + (place-fret 5 4 3) (place-fret 4 4 4) + (place-fret 3 3 2) (place-fret 2 2 1) + (place-fret 1 2 1)) + } + } + fis' fis' fis' + c' ^\markup \override #'(dot-radius . 0.35) { + \override #'(finger-code . in-dot) { + \override #'(dot-color . white) { + \fret-diagram-terse #"x;3-1-(;5-2;5-3;5-4;3-1-);" + } + } + } + c' c' c' +} +@end lilypond + + +There are three different fret-diagram markup interfaces: standard, terse, +and verbose. The three interfaces produce equivalent markups, but have +varying amounts of information in the markup string. Details about the +markup interfaces are found at @ref{Overview of text markup commands}. + +You can set a number of graphical properties according to your preference. +Details about the property interface to fret diagrams are found at +@internalsref{fret-diagram-interface}. + + +@seealso + +Examples: @inputfileref{input/@/test,fret@/-diagram@/.ly} + + + +@node Ancient notation +@section Ancient notation + +@cindex Vaticana, Editio +@cindex Medicaea, Editio +@cindex hufnagel +@cindex Petrucci +@cindex mensural + +Support for ancient notation includes features for mensural notation +and Gregorian Chant notation. There is also limited support for +figured bass notation. + +Many graphical objects provide a @code{style} property, see +@itemize @bullet +@item +@ref{Ancient note heads}, +@item +@ref{Ancient accidentals}, +@item +@ref{Ancient rests}, +@item +@ref{Ancient clefs}, +@item +@ref{Ancient flags}, +@item +@ref{Ancient time signatures}. +@end itemize + +By manipulating such a grob property, the typographical appearance of +the affected graphical objects can be accommodated for a specific +notation flavor without the need for introducing any new notational +concept. + +In addition to the standard articulation signs described in section +@ref{Articulations}, specific articulation signs for ancient notation +are provided. + +@itemize @bullet +@item +@ref{Ancient articulations} +@end itemize + +Other aspects of ancient notation can not that easily be expressed +in terms of just changing a style property of a graphical object or +adding articulation signs. Some notational concepts are introduced +specifically for ancient notation, + +@itemize @bullet +@item +@ref{Custodes}, +@item +@ref{Divisiones}, +@item +@ref{Ligatures}. +@end itemize + +If this all is too much of documentation for you, and you just want to +dive into typesetting without worrying too much about the details on +how to customize a context, you may have a look at the predefined +contexts. Use them to set up predefined style-specific voice and +staff contexts, and directly go ahead with the note entry, + +@itemize @bullet +@item +@ref{Gregorian Chant contexts}, +@item +@ref{Mensural contexts}. +@end itemize + +There is limited support for figured bass notation which came +up during the baroque period. + +@itemize @bullet +@item +@ref{Figured bass} +@end itemize + +Here are all suptopics at a glance: + +@menu +* Ancient note heads:: +* Ancient accidentals:: +* Ancient rests:: +* Ancient clefs:: +* Ancient flags:: +* Ancient time signatures:: +* Ancient articulations:: +* Custodes:: +* Divisiones:: +* Ligatures:: +* Gregorian Chant contexts:: +* Mensural contexts:: +* Figured bass:: +@end menu + + +@node Ancient note heads +@subsection Ancient note heads + +@cindex note heads + + +For ancient notation, a note head style other than the @code{default} +style may be chosen. This is accomplished by setting the @code{style} +property of the @internalsref{NoteHead} object to @code{baroque}, +@code{neomensural} or @code{mensural}. The @code{baroque} style +differs from the @code{default} style only in using a square shape +for @code{\breve} note heads. The @code{neomensural} style differs from +the @code{baroque} style in that it uses rhomboidal heads for whole notes +and all smaller durations. Stems are centered on the note heads. +This style is particularly useful when transcribing mensural music, +e.g., for the incipit. The @code{mensural} style finally produces note +heads that mimic the look of note heads in historic printings of the +16th century. + +The following example demonstrates the @code{neomensural} style + +@lilypond[quote,fragment,raggedright,verbatim] +\set Score.skipBars = ##t +\override NoteHead #'style = #'neomensural +a'\longa a'\breve a'1 a'2 a'4 a'8 a'16 +@end lilypond + +When typesetting a piece in Gregorian Chant notation, the +@internalsref{Gregorian_ligature_engraver} will automatically select +the proper note heads, so there is no need to explicitly set the +note head style. Still, the note head style can be set, e.g., to +@code{vaticana_punctum} to produce punctum neumes. Similarly, a +@internalsref{Mensural_ligature_engraver} is used to automatically +assemble mensural ligatures. See @ref{Ligatures} for how ligature +engravers work. + +@seealso + +Examples: @inputfileref{input/@/regression,note@/-head@/-style@/.ly} gives an +overview over all available note head styles. + + +@node Ancient accidentals +@subsection Ancient accidentals + +@cindex accidentals + + +Use the @code{style} property of grob @internalsref{Accidental} to +select ancient accidentals. Supported styles are +@code{mensural}, @code{vaticana}, @code{hufnagel}, and @code{medicaea}. + +@lilypond[quote,raggedright,staffsize=26] +\score { +{ + \fatText + s^\markup { + \column { + "vaticana" + \line { " " \musicglyph #"accidentals.vaticana-1" + " " \musicglyph #"accidentals.vaticana0" } + } + \column { + "medicaea" + \line { " " \musicglyph #"accidentals.medicaea-1" } + } + \column { + "hufnagel" + \line { " " \musicglyph #"accidentals.hufnagel-1" } + } + \column { + "mensural" + \line { " " \musicglyph #"accidentals.mensural-1" + " " \musicglyph #"accidentals.mensural1" } + } + } +} +\layout { + interscoreline = 1 + \context { \Score \remove "Bar_number_engraver" } + \context { \Staff + \remove "Clef_engraver" + \remove "Key_engraver" + \remove "Time_signature_engraver" + \remove "Staff_symbol_engraver" + minimumVerticalExtent = ##f + } + } +} +@end lilypond + +As shown, not all accidentals are supported by each style. When +trying to access an unsupported accidental, LilyPond will switch to a +different style, as demonstrated in +@inputfileref{input/@/test,ancient@/-accidentals@/.ly}. + +Similarly to local accidentals, the style of the key signature can be +controlled by the @code{style} property of the +@internalsref{KeySignature} grob. + +@seealso + +In this manual: @ref{Pitches}, @ref{Chromatic alterations} and +@ref{Accidentals} give a general introduction of the use of +accidentals. @ref{Key signature} gives a general introduction of +the use of key signatures. + +Program reference: @internalsref{KeySignature}. + +Examples: @inputfileref{input/@/test,ancient@/-accidentals@/.ly}. + +@node Ancient rests +@subsection Ancient rests + +@cindex rests + + +Use the @code{style} property of grob @internalsref{Rest} to select +ancient rests. Supported styles are @code{classical}, +@code{neomensural}, and @code{mensural}. @code{classical} differs +from the @code{default} style only in that the quarter rest looks like +a horizontally mirrored 8th rest. The @code{neomensural} style suits +well for, e.g., the incipit of a transcribed mensural piece of music. +The @code{mensural} style finally mimics the appearance of rests as +in historic prints of the 16th century. + +The following example demonstrates the @code{neomensural} style + +@lilypond[quote,fragment,raggedright,verbatim] +\set Score.skipBars = ##t +\override Rest #'style = #'neomensural +r\longa r\breve r1 r2 r4 r8 r16 +@end lilypond + +There are no 32th and 64th rests specifically for the mensural or +neo-mensural style. Instead, the rests from the default style will be +taken. See @inputfileref{input/@/test,rests@/.ly} for a chart of all +rests. + +There are no rests in Gregorian Chant notation; instead, it uses +@ref{Divisiones}. + +@seealso + +In this manual: @ref{Rests} gives a general introduction into the use of rests. + + +@node Ancient clefs +@subsection Ancient clefs + +@cindex clefs + + +LilyPond supports a variety of clefs, many of them ancient. + +The following table shows all ancient clefs that are supported via the +@code{\clef} command. Some of the clefs use the same glyph, but +differ only with respect to the line they are printed on. In such +cases, a trailing number in the name is used to enumerate these clefs. +Still, you can manually force a clef glyph to be typeset on an +arbitrary line, as described in @ref{Clef}. The note printed to the +right side of each clef in the example column denotes the @code{c'} +with respect to that clef. + +@multitable @columnfractions .4 .4 .2 +@item +@b{Description} +@tab +@b{Supported Clefs} +@tab +@b{Example} + +@item +modern style mensural C clef +@tab +@code{neomensural-c1}, @code{neomensural-c2},@* +@code{neomensural-c3}, @code{neomensural-c4} +@tab +@lilypond[fragment,relative=1,notime] + \clef "neomensural-c2" c +@end lilypond + +@item +petrucci style mensural C clefs, for use on different staff lines +(the examples show the 2nd staff line C clef) +@tab +@code{petrucci-c1}, @code{petrucci-c2},@* +@code{petrucci-c3}, @code{petrucci-c4},@* +@code{petrucci-c5} +@tab +@lilypond[fragment,relative=1,notime] + \clef "petrucci-c2" c +@end lilypond + +@item +petrucci style mensural F clef +@tab +@code{petrucci-f} +@tab +@lilypond[fragment,relative=1,notime] + \clef "petrucci-f" c +@end lilypond + +@item +petrucci style mensural G clef +@tab +@code{petrucci-g} +@tab +@lilypond[fragment,relative=1,notime] + \clef "petrucci-g" c +@end lilypond + +@item +historic style mensural C clef +@tab +@code{mensural-c1}, @code{mensural-c2},@* +@code{mensural-c3}, @code{mensural-c4} +@tab +@lilypond[fragment,relative=1,notime] + \clef "mensural-c2" c +@end lilypond + +@item +historic style mensural F clef +@tab +@code{mensural-f} +@tab +@lilypond[fragment,relative=1,notime] + \clef "mensural-f" c +@end lilypond + +@item +historic style mensural G clef +@tab +@code{mensural-g} +@tab +@lilypond[fragment,relative=1,notime] + \clef "mensural-g" c +@end lilypond + +@item +Editio Vaticana style do clef +@tab +@code{vaticana-do1}, @code{vaticana-do2},@* +@code{vaticana-do3} +@tab +@lilypond[fragment,relative=1,notime] + \override Staff.StaffSymbol #'line-count = #4 + \clef "vaticana-do2" c +@end lilypond + +@item +Editio Vaticana style fa clef +@tab +@code{vaticana-fa1}, @code{vaticana-fa2} +@tab +@lilypond[fragment,relative=1,notime] + \override Staff.StaffSymbol #'line-count = #4 + \clef "vaticana-fa2" c +@end lilypond + +@item +Editio Medicaea style do clef +@tab +@code{medicaea-do1}, @code{medicaea-do2},@* +@code{medicaea-do3} +@tab +@lilypond[fragment,relative=1,notime] + \override Staff.StaffSymbol #'line-count = #4 + \clef "medicaea-do2" c +@end lilypond + +@item +Editio Medicaea style fa clef +@tab +@code{medicaea-fa1}, @code{medicaea-fa2} +@tab +@lilypond[fragment,relative=1,notime] + \override Staff.StaffSymbol #'line-count = #4 + \clef "medicaea-fa2" c +@end lilypond + +@item +historic style hufnagel do clef +@tab +@code{hufnagel-do1}, @code{hufnagel-do2},@* +@code{hufnagel-do3} +@tab +@lilypond[fragment,relative=1,notime] + \override Staff.StaffSymbol #'line-count = #4 + \clef "hufnagel-do2" c +@end lilypond + +@item +historic style hufnagel fa clef +@tab +@code{hufnagel-fa1}, @code{hufnagel-fa2} +@tab +@lilypond[fragment,relative=1,notime] + \override Staff.StaffSymbol #'line-count = #4 + \clef "hufnagel-fa2" c +@end lilypond + +@item +historic style hufnagel combined do/fa clef +@tab +@code{hufnagel-do-fa} +@tab +@lilypond[fragment,relative=1,notime] + \clef "hufnagel-do-fa" c +@end lilypond +@end multitable + + + +@emph{Modern style} means ``as is typeset in contemporary editions of +transcribed mensural music''. + +@emph{Petrucci style} means ``inspired by printings published by the +famous engraver Petrucci (1466-1539)''. + +@emph{Historic style} means ``as was typeset or written in historic +editions (other than those of Petrucci)''. + +@emph{Editio XXX style} means ``as is/was printed in Editio XXX''. + +Petrucci used C clefs with differently balanced left-side vertical +beams, depending on which staff line it is printed. + +@seealso + +In this manual: see @ref{Clef}. + +@refbugs + +The mensural g clef is mapped to the Petrucci g clef. + + + +@node Ancient flags +@subsection Ancient flags + +@cindex flags + + +Use the @code{flag-style} property of grob @internalsref{Stem} to +select ancient flags. Besides the @code{default} flag style, +only the @code{mensural} style is supported + +@lilypond[quote,fragment,raggedright,verbatim] +\override Stem #'flag-style = #'mensural +\override Stem #'thickness = #1.0 +\override NoteHead #'style = #'mensural +\autoBeamOff +c'8 d'8 e'8 f'8 c'16 d'16 e'16 f'16 c'32 d'32 e'32 f'32 s8 +c''8 d''8 e''8 f''8 c''16 d''16 e''16 f''16 c''32 d''32 e''32 f''32 +@end lilypond + +Note that the innermost flare of each mensural flag always is +vertically aligned with a staff line. + +There is no particular flag style for neo-mensural notation. Hence, +when typesetting the incipit of a transcribed piece of mensural +music, the default flag style should be used. There are no flags in +Gregorian Chant notation. + +@refbugs + +The attachment of ancient flags to stems is slightly off due to a +change in early 2.3.x. + +Vertically aligning each flag with a staff line assumes that stems +always end either exactly on or exactly in the middle between two +staff lines. This may not always be true when using advanced layout +features of classical notation (which however are typically out of +scope for mensural notation). + +@node Ancient time signatures +@subsection Ancient time signatures + +@cindex time signatures + + +There is limited support for mensural time signatures. The +glyphs are hard-wired to particular time fractions. In other words, +to get a particular mensural signature glyph with the @code{\time n/m} +command, @code{n} and @code{m} have to be chosen according to the +following table + +@lilypond[quote,raggedright] +\layout { + indent = 0.0 + \context { \Staff + \remove Staff_symbol_engraver + \remove Clef_engraver + \remove Time_signature_engraver + } +} { + \set Score.timing = ##f + \set Score.barAlways = ##t + s_\markup { "\\time 4/4" } + ^\markup { " " \musicglyph #"timesig.neomensural44" } + s + s_\markup { "\\time 2/2" } + ^\markup { " " \musicglyph #"timesig.neomensural22" } + s + s_\markup { "\\time 6/4" } + ^\markup { " " \musicglyph #"timesig.neomensural64" } + s + s_\markup { "\\time 6/8" } + ^\markup { " " \musicglyph #"timesig.neomensural68" } + \break + s_\markup { "\\time 3/2" } + ^\markup { " " \musicglyph #"timesig.neomensural32" } + s + s_\markup { "\\time 3/4" } + ^\markup { " " \musicglyph #"timesig.neomensural34" } + s + s_\markup { "\\time 9/4" } + ^\markup { " " \musicglyph #"timesig.neomensural94" } + s + s_\markup { "\\time 9/8" } + ^\markup { " " \musicglyph #"timesig.neomensural98" } + \break + s_\markup { "\\time 4/8" } + ^\markup { " " \musicglyph #"timesig.neomensural48" } + s + s_\markup { "\\time 2/4" } + ^\markup { " " \musicglyph #"timesig.neomensural24" } +} +@end lilypond + +Use the @code{style} property of grob @internalsref{TimeSignature} to +select ancient time signatures. Supported styles are +@code{neomensural} and @code{mensural}. The above table uses the +@code{neomensural} style. This style is appropriate for the +incipit of transcriptions of mensural pieces. The @code{mensural} +style mimics the look of historical printings of the 16th century. + +The following examples show the differences in style, + +@lilypond[raggedright,fragment,relative=1,quote] +{ + \fatText + \time 2/2 + c1^\markup { \hspace #-2.0 \typewriter default } + + \override Staff.TimeSignature #'style = #'numbered + \time 2/2 + c1^\markup { \hspace #-2.0 \typewriter numbered } + + \override Staff.TimeSignature #'style = #'mensural + \time 2/2 + c1^\markup { \hspace #-2.0 \typewriter mensural } + + \override Staff.TimeSignature #'style = #'neomensural + \time 2/2 + c1^\markup { \hspace #-2.0 \typewriter neomensural } + \override Staff.TimeSignature #'style = #'single-digit + \time 2/2 + c1^\markup { \hspace #-2.0 \typewriter single-digit } +} +@end lilypond + +@seealso + +This manual: @ref{Time signature} gives a general introduction to +the use of time signatures. + +@refbugs + +Ratios of note durations do not change with the time signature. For +example, the ratio of 1 brevis = 3 semibrevis (tempus perfectum) must +be made by hand, by setting + +@example +breveTP = #(ly:make-duration -1 0 3 2) +@dots{} +@{ c\breveTP f1 @} +@end example + +@noindent +This sets @code{breveTP} to 3/2 times 2 = 3 times a whole note. + +The @code{old6/8alt} symbol (an alternate symbol for 6/8) is not +addressable with @code{\time}. Use a @code{\markup} instead + +@node Ancient articulations +@subsection Ancient articulations + +@cindex articulations + +In addition to the standard articulation signs described in section +@ref{Articulations}, articulation signs for ancient notation are +provided. These are specifically designed for use with notation in +Editio Vaticana style. + +@lilypond[quote,raggedright,verbatim] +\include "gregorian-init.ly" +\score { + \context VaticanaVoice { + \override TextScript #'font-family = #'typewriter + \override TextScript #'font-shape = #'upright + \override Script #'padding = #-0.1 + a4\ictus_"ictus" s1 + a4\circulus_"circulus" s1 + a4\semicirculus_"semicirculus" s1 s + a4\accentus_"accentus" s1 + \[ a4_"episem" \episemInitium \pes b \flexa a \episemFinis \] + } +} +@end lilypond + +@refbugs + +Some articulations are vertically placed too closely to the +correpsonding note heads. + +@node Custodes +@subsection Custodes + +@cindex custos +@cindex custodes + +A @emph{custos} (plural: @emph{custodes}; Latin word for `guard') is a +symbol that appears at the end of a staff. It anticipates the pitch +of the first note(s) of the following line thus helping the performer +to manage line breaks during performance. + +Custodes were frequently used in music notation until the 17th +century. Nowadays, they have survived only in a few particular forms +of musical notation such as contemporary editions of Gregorian chant +like the @emph{editio vaticana}. There are different custos glyphs +used in different flavors of notational style. + +For typesetting custodes, just put a @internalsref{Custos_engraver} into the +@internalsref{Staff} context when declaring the @code{\layout} block, +as shown in the following example + +@example +\layout @{ + \context @{ + \Staff + \consists Custos_engraver + Custos \override #'style = #'mensural + @} +@} +@end example + +The result looks like this + +@lilypond[quote,raggedright] +\score { +{ + a'1 + \override Staff.Custos #'style = #'mensural + \break + g' +} +\layout { + \context { \Staff \consists Custos_engraver } + } +} +@end lilypond + +The custos glyph is selected by the @code{style} property. The styles +supported are @code{vaticana}, @code{medicaea}, @code{hufnagel}, and +@code{mensural}. They are demonstrated in the following fragment + +@lilypond[quote,raggedright,fragment] +\new Lyrics \lyricmode { + \markup { \column { + \typewriter "vaticana" + \line { " " \musicglyph #"custodes.vaticana-u0" } + } } + \markup { \column { + \typewriter "medicaea" + \line { " " \musicglyph #"custodes.medicaea-u0" } + }} + \markup { \column { + \typewriter "hufnagel" + \line { " " \musicglyph #"custodes.hufnagel-u0" } + }} + \markup { \column { + \typewriter "mensural" + \line { " " \musicglyph #"custodes.mensural-u0" } + }} +} +@end lilypond + +@seealso + +Program reference: @internalsref{Custos}. + +Examples: @inputfileref{input/@/regression,custos@/.ly}. + + +@node Divisiones +@subsection Divisiones + +@cindex divisio +@cindex divisiones +@cindex finalis + +A @emph{divisio} (plural: @emph{divisiones}; Latin word for +`division') is a staff context symbol that is used to structure +Gregorian music into phrases and sections. The musical meaning of +@emph{divisio minima}, @emph{divisio maior}, and @emph{divisio maxima} +can be characterized as short, medium, and long pause, somewhat like +the breathmarks from @ref{Breath marks}. The @emph{finalis} sign not +only marks the end of a chant, but is also frequently used within a +single antiphonal/responsorial chant to mark the end of each section. + + +To use divisiones, include the file @file{gregorian@/-init@/.ly}. It +contains definitions that you can apply by just inserting +@code{\divisioMinima}, @code{\divisioMaior}, @code{\divisioMaxima}, +and @code{\finalis} at proper places in the input. Some editions use +@emph{virgula} or @emph{caesura} instead of divisio minima. +Therefore, @file{gregorian@/-init@/.ly} also defines @code{\virgula} and +@code{\caesura} + +@lilypondfile[quote,raggedright]{divisiones.ly} + +@refcommands + +@cindex @code{\virgula} +@code{\virgula}, +@cindex @code{\caesura} +@code{\caesura}, +@cindex @code{\divisioMinima} +@code{\divisioMinima}, +@cindex @code{\divisioMaior} +@code{\divisioMaior}, +@cindex @code{\divisioMaxima} +@code{\divisioMaxima}, +@cindex @code{\finalis} +@code{\finalis}. + +@seealso + +In this manual: @ref{Breath marks}. + +Program reference: @internalsref{BreathingSign}, @internalsref{BreathingSignEvent}. + +Examples: @inputfileref{input/@/test,divisiones@/.ly}. + +@node Ligatures +@subsection Ligatures + +@cindex Ligatures + +@c TODO: Should double check if I recalled things correctly when I wrote +@c down the following paragraph by heart. + +A ligature is a graphical symbol that represents at least two distinct +notes. Ligatures originally appeared in the manuscripts of Gregorian +chant notation to denote ascending or descending sequences of notes. + +Ligatures are entered by enclosing them in @code{\[} and @code{\]}. +Some ligature styles may need additional input syntax specific for +this particular type of ligature. By default, the +@internalsref{LigatureBracket} engraver just puts a square bracket +above the ligature + +@lilypond[quote,raggedright,verbatim] +\transpose c c' { + \[ g c a f d' \] + a g f + \[ e f a g \] +} +@end lilypond + +To select a specific style of ligatures, a proper ligature engraver +has to be added to the @internalsref{Voice} context, as explained in +the following subsections. Only white mensural ligatures +are supported with certain limitations. + + + +@refbugs + +Ligatures need special spacing that has not yet been implemented. As +a result, there is too much space between ligatures most of the time, +and line breaking often is unsatisfactory. Also, lyrics do not +correctly align with ligatures. + +Accidentals must not be printed within a ligature, but instead need to +be collected and printed in front of it. + +Augmentum dots within ligatures are not handled correctly. + + +@menu +* White mensural ligatures:: +* Gregorian square neumes ligatures:: +@end menu + +@node White mensural ligatures +@subsubsection White mensural ligatures + +@cindex Mensural ligatures +@cindex White mensural ligatures + +There is limited support for white mensural ligatures. + +To engrave white mensural ligatures, in the layout block put the +@internalsref{Mensural_ligature_engraver} into the +@internalsref{Voice} context, and remove the +@internalsref{Ligature_bracket_engraver}, like this + +@example +\layout @{ + \context @{ + \Voice + \remove Ligature_bracket_engraver + \consists Mensural_ligature_engraver + @} +@} +@end example + +There is no additional input language to describe the shape of a +white mensural ligature. The shape is rather determined solely from +the pitch and duration of the enclosed notes. While this approach may +take a new user a while to get accustomed to, it has the great advantage +that the full musical information of the ligature is known internally. +This is not only required for correct MIDI output, but also allows for +automatic transcription of the ligatures. + +For example, + +@example +\set Score.timing = ##f +\set Score.defaultBarType = "empty" +\override NoteHead #'style = #'neomensural +\override Staff.TimeSignature #'style = #'neomensural +\clef "petrucci-g" +\[ g\longa c\breve a\breve f\breve d'\longa \] +s4 +\[ e1 f1 a\breve g\longa \] +@end example +@lilypond[quote,raggedright] +\score { + \transpose c c' { + \set Score.timing = ##f + \set Score.defaultBarType = "empty" + \override NoteHead #'style = #'neomensural + \override Staff.TimeSignature #'style = #'neomensural + \clef "petrucci-g" + \[ g\longa c\breve a\breve f\breve d'\longa \] + s4 + \[ e1 f1 a\breve g\longa \] + } + \layout { + \context { + \Voice + \remove Ligature_bracket_engraver + \consists Mensural_ligature_engraver + } + } +} +@end lilypond + +Without replacing @internalsref{Ligature_bracket_engraver} with +@internalsref{Mensural_ligature_engraver}, the same music transcribes +to the following + +@lilypond[quote,raggedright] +\transpose c c' { + \set Score.timing = ##f + \set Score.defaultBarType = "empty" + \override NoteHead #'style = #'neomensural + \override Staff.TimeSignature #'style = #'neomensural + \clef "petrucci-g" + \[ g\longa c\breve a\breve f\breve d'\longa \] + s4 + \[ e1 f1 a\breve g\longa \] +} +@end lilypond + +@refbugs + +The implementation is experimental. It may output strange warnings, +incorrect results, and might even crash on more complex ligatures. + +@node Gregorian square neumes ligatures +@subsubsection Gregorian square neumes ligatures + +@cindex Square neumes ligatures +@cindex Gregorian square neumes ligatures + +There is limited support for Gregorian square neumes notation +(following the style of the Editio Vaticana). Core ligatures can +already be typeset, but essential issues for serious typesetting are +still lacking, such as (among others) horizontal alignment of multiple +ligatures, lyrics alignment and proper handling of accidentals. + + +The following table contains the extended neumes table of the 2nd +volume of the Antiphonale Romanum (@emph{Liber Hymnarius}), published +1983 by the monks of Solesmes. + +@multitable @columnfractions .4 .2 .2 .2 + +@item +@b{Neuma aut@* +Neumarum Elementa} +@tab +@b{Figurae@* +Rectae} +@tab +@b{Figurae@* +Liquescentes@* +Auctae} +@tab +@b{Figurae@* +Liquescentes@* +Deminutae} + +@c TODO: \layout block is identical in all of the below examples. +@c Therefore, it should somehow be included rather than duplicated all +@c the time. --jr + +@c why not make identifiers in ly/engraver-init.ly? --hwn + +@c Because it's just used to typeset plain notes without +@c a staff for demonstration purposes rather than something +@c special of Gregorian chant notation. --jr + +@item +@code{1. Punctum} +@tab +@lilypond[staffsize=26,linewidth=1.5\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Punctum + \[ b \] + \noBreak s^\markup {"a"} \noBreak + + % Punctum Inclinatum + \[ \inclinatum b \] + \noBreak s^\markup {"b"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=2.5\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Punctum Auctum Ascendens + \[ \auctum \ascendens b \] + \noBreak s^\markup {"c"} \noBreak + + % Punctum Auctum Descendens + \[ \auctum \descendens b \] + \noBreak s^\markup {"d"} \noBreak + + % Punctum Inclinatum Auctum + \[ \inclinatum \auctum b \] + \noBreak s^\markup {"e"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Punctum Inclinatum Parvum + \[ \inclinatum \deminutum b \] + \noBreak s^\markup {"f"} + } +\layout { \neumeDemoLayout }} +@end lilypond + +@item +@code{2. Virga} +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Virga + \[ \virga b \] + \noBreak s^\markup {"g"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@tab + +@item +@code{3. Apostropha vel Stropha} +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Stropha + \[ \stropha b \] + \noBreak s^\markup {"h"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Stropha Aucta + \[ \stropha \auctum b \] + \noBreak s^\markup {"i"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab + +@item +@code{4. Oriscus} +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Oriscus + \[ \oriscus b \] + \noBreak s^\markup {"j"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@tab + +@item +@code{5. Clivis vel Flexa} +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Clivis vel Flexa + \[ b \flexa g \] + s^\markup {"k"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=2.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Clivis Aucta Descendens + \[ b \flexa \auctum \descendens g \] + \noBreak s^\markup {"l"} \noBreak + + % Clivis Aucta Ascendens + \[ b \flexa \auctum \ascendens g \] + \noBreak s^\markup {"m"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Cephalicus + \[ b \flexa \deminutum g \] + s^\markup {"n"} + } +\layout { \neumeDemoLayout }} +@end lilypond + +@item +@code{6. Podatus vel Pes} +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Podatus vel Pes + \[ g \pes b \] + s^\markup {"o"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=2.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Pes Auctus Descendens + \[ g \pes \auctum \descendens b \] + \noBreak s^\markup {"p"} \noBreak + + % Pes Auctus Ascendens + \[ g \pes \auctum \ascendens b \] + \noBreak s^\markup {"q"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Epiphonus + \[ g \pes \deminutum b \] + s^\markup {"r"} + } +\layout { \neumeDemoLayout }} +@end lilypond + +@item +@code{7. Pes Quassus} +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Pes Quassus + \[ \oriscus g \pes \virga b \] + s^\markup {"s"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Pes Quassus Auctus Descendens + \[ \oriscus g \pes \auctum \descendens b \] + s^\markup {"t"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab + +@item +@code{8. Quilisma Pes} +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Quilisma Pes + \[ \quilisma g \pes b \] + s^\markup {"u"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Quilisma Pes Auctus Descendens + \[ \quilisma g \pes \auctum \descendens b \] + s^\markup {"v"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab + +@item +@code{9. Podatus Initio Debilis} +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Pes Initio Debilis + \[ \deminutum g \pes b \] + s^\markup {"w"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Pes Auctus Descendens Initio Debilis + \[ \deminutum g \pes \auctum \descendens b \] + s^\markup {"x"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab + +@item +@code{10. Torculus} +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Torculus + \[ a \pes b \flexa g \] + s^\markup {"y"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Torculus Auctus Descendens + \[ a \pes b \flexa \auctum \descendens g \] + s^\markup {"z"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Torculus Deminutus + \[ a \pes b \flexa \deminutum g \] + s^\markup {"A"} + } +\layout { \neumeDemoLayout }} +@end lilypond + +@item +@code{11. Torculus Initio Debilis} +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Torculus Initio Debilis + \[ \deminutum a \pes b \flexa g \] + s^\markup {"B"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Torculus Auctus Descendens Initio Debilis + \[ \deminutum a \pes b \flexa \auctum \descendens g \] + s^\markup {"C"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Torculus Deminutus Initio Debilis + \[ \deminutum a \pes b \flexa \deminutum g \] + s^\markup {"D"} + } +\layout { \neumeDemoLayout }} +@end lilypond + +@item +@code{12. Porrectus} +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Porrectus + \[ a \flexa g \pes b \] + s^\markup {"E"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Porrectus Auctus Descendens + \[ a \flexa g \pes \auctum \descendens b \] + s^\markup {"F"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Porrectus Deminutus + \[ a \flexa g \pes \deminutum b \] + s^\markup {"G"} + } +\layout { \neumeDemoLayout }} +@end lilypond + +@item +@code{13. Climacus} +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Climacus + \[ \virga b \inclinatum a \inclinatum g \] + s^\markup {"H"} + } + \layout { \neumeDemoLayout } +} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Climacus Auctus + \[ \virga b \inclinatum a \inclinatum \auctum g \] + s^\markup {"I"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Climacus Deminutus + \[ \virga b \inclinatum a \inclinatum \deminutum g \] + s^\markup {"J"} + } +\layout { \neumeDemoLayout }} +@end lilypond + +@item +@code{14. Scandicus} +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Scandicus + \[ g \pes a \virga b \] + s^\markup {"K"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Scandicus Auctus Descendens + \[ g \pes a \pes \auctum \descendens b \] + s^\markup {"L"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Scandicus Deminutus + \[ g \pes a \pes \deminutum b \] + s^\markup {"M"} + } +\layout { \neumeDemoLayout }} +@end lilypond + +@item +@code{15. Salicus} +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Salicus + \[ g \oriscus a \pes \virga b \] + s^\markup {"N"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Salicus Auctus Descendens + \[ g \oriscus a \pes \auctum \descendens b \] + s^\markup {"O"} + } +\layout { \neumeDemoLayout }} +@end lilypond +@tab + +@item +@code{16. Trigonus} +@tab +@lilypond[staffsize=26,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \transpose c c' { + % Trigonus + \[ \stropha b \stropha b \stropha a \] + s^\markup {"P"} + } + \layout { \neumeDemoLayout } +} +@end lilypond +@tab +@tab + +@end multitable + + +Unlike most other neumes notation systems, the input language for +neumes does not reflect the typographical appearance, but is designed +to focus on musical meaning. For example, @code{\[ a \pes b +\flexa g \]} produces a Torculus consisting of three Punctum heads, +while @code{\[ a \flexa g \pes b \]} produces a Porrectus with a +curved flexa shape and only a single Punctum head. There is no +command to explicitly typeset the curved flexa shape; the decision of +when to typeset a curved flexa shape is based on the musical +input. The idea of this approach is to separate the musical aspects +of the input from the notation style of the output. This way, the +same input can be reused to typeset the same music in a different +style of Gregorian chant notation. + +The following table shows the code fragments that produce the +ligatures in the above neumes table. The letter in the first column +in each line of the below table indicates to which ligature in the +above table it refers. The second column gives the name of the +ligature. The third column shows the code fragment that produces this +ligature, using @code{g}, @code{a}, and @code{b} as example pitches. + +@multitable @columnfractions .02 .31 .67 +@item +@b{#} +@tab +@b{Name} +@tab +@b{Input Language} + +@item +a +@tab +Punctum +@tab +@code{\[ b \]} + +@item +b +@tab +Punctum Inclinatum +@tab +@code{\[ \inclinatum b \]} + +@item +c +@tab +Punctum Auctum@* +Ascendens +@tab +@code{\[ \auctum \ascendens b \]} + +@item +d +@tab +Punctum Auctum@* +Descendens +@tab +@code{\[ \auctum \descendens b \]} + +@item +e +@tab +Punctum Inclinatum@* +Auctum +@tab +@code{\[ \inclinatum \auctum b \]} + +@item +f +@tab +Punctum Inclinatum@* +Parvum @tab +@code{\[ \inclinatum \deminutum b \]} + +@item +g +@tab +Virga +@tab +@code{\[ \virga b \]} + +@item +h +@tab +Stropha +@tab +@code{\[ \stropha b \]} + +@item +i +@tab +Stropha Aucta +@tab +@code{\[ \stropha \auctum b \]} + +@item +j +@tab +Oriscus +@tab +@code{\[ \oriscus b \]} + +@item +k +@tab +Clivis vel Flexa +@tab +@code{\[ b \flexa g \]} + +@item +l +@tab +Clivis Aucta@* +Descendens +@tab +@code{\[ b \flexa \auctum \descendens g \]} + +@item +m +@tab +Clivis Aucta@* +Ascendens +@tab +@code{\[ b \flexa \auctum \ascendens g \]} + +@item +n +@tab +Cephalicus +@tab +@code{\[ b \flexa \deminutum g \]} + +@item +o +@tab +Podatus vel Pes +@tab +@code{\[ g \pes b \]} + +@item +p +@tab +Pes Auctus@* +Descendens +@tab +@code{\[ g \pes \auctum \descendens b \]} + +@item +q +@tab +Pes Auctus@* +Ascendens +@tab +@code{\[ g \pes \auctum \ascendens b \]} + +@item +r +@tab +Epiphonus +@tab +@code{\[ g \pes \deminutum b \]} + +@item +s +@tab +Pes Quassus +@tab +@code{\[ \oriscus g \pes \virga b \]} + +@item +t +@tab +Pes Quassus@* +Auctus Descendens @tab +@code{\[ \oriscus g \pes \auctum \descendens b \]} + +@item +u +@tab +Quilisma Pes +@tab +@code{\[ \quilisma g \pes b \]} + +@item +v +@tab +Quilisma Pes@* +Auctus Descendens +@tab +@code{\[ \quilisma g \pes \auctum \descendens b \]} + +@item +w +@tab +Pes Initio Debilis +@tab +@code{\[ \deminutum g \pes b \]} + +@item +x +@tab +Pes Auctus Descendens@* +Initio Debilis +@tab +@code{\[ \deminutum g \pes \auctum \descendens b \]} + +@item +y +@tab +Torculus +@tab +@code{\[ a \pes b \flexa g \]} + +@item +z +@tab +Torculus Auctus@* +Descendens +@tab +@code{\[ a \pes b \flexa \auctum \descendens g \]} + +@item +A +@tab +Torculus Deminutus +@tab +@code{\[ a \pes b \flexa \deminutum g \]} + +@item +B +@tab +Torculus Initio Debilis +@tab +@code{\[ \deminutum a \pes b \flexa g \]} + +@item +C +@tab +Torculus Auctus@* +Descendens Initio Debilis +@tab +@code{\[ \deminutum a \pes b \flexa \auctum \descendens g \]} + +@item +D +@tab +Torculus Deminutus@* +Initio Debilis +@tab +@code{\[ \deminutum a \pes b \flexa \deminutum g \]} + +@item +E +@tab +Porrectus +@tab +@code{\[ a \flexa g \pes b \]} + +@item +F +@tab +Porrectus Auctus@* +Descendens +@tab +@code{\[ a \flexa g \pes \auctum \descendens b \]} + +@item +G +@tab +Porrectus Deminutus +@tab +@code{\[ a \flexa g \pes \deminutum b \]} + +@item +H +@tab +Climacus +@tab +@code{\[ \virga b \inclinatum a \inclinatum g \]} + +@item +I +@tab +Climacus Auctus +@tab +@code{\[ \virga b \inclinatum a \inclinatum \auctum g \]} + +@item +J +@tab +Climacus Deminutus +@tab +@code{\[ \virga b \inclinatum a \inclinatum \deminutum g \]} + +@item +K +@tab +Scandicus +@tab +@code{\[ g \pes a \virga b \]} + +@item +L +@tab +Scandicus Auctus@* +Descendens +@tab +@code{\[ g \pes a \pes \auctum \descendens b \]} + +@item +M +@tab +Scandicus Deminutus +@tab +@code{\[ g \pes a \pes \deminutum b \]} + +@item +N +@tab +Salicus +@tab +@code{\[ g \oriscus a \pes \virga b \]} + +@item +O +@tab +Salicus Auctus Descendens +@tab +@code{\[ g \oriscus a \pes \auctum \descendens b \]} + +@item +P +@tab +Trigonus +@tab +@code{\[ \stropha b \stropha b \stropha a \]} +@end multitable + +@refcommands + +The following head prefixes are supported + +@cindex @code{\virga} +@code{\virga}, +@cindex @code{\stropha} +@code{\stropha}, +@cindex @code{\inclinatum} +@code{\inclinatum}, +@cindex @code{\auctum} +@code{\auctum}, +@cindex @code{\descendens} +@code{\descendens}, +@cindex @code{\ascendens} +@code{\ascendens}, +@cindex @code{\oriscus} +@code{\oriscus}, +@cindex @code{\quilisma} +@code{\quilisma}, +@cindex @code{\deminutum} +@code{\deminutum}. + +Head prefixes can be accumulated, though restrictions apply. For +example, either @code{\descendens} or @code{\ascendens} can be applied +to a head, but not both to the same head. + +@cindex @code{\pes} +@cindex @code{\flexa} +Two adjacent heads can be tied together with the @code{\pes} and +@code{\flexa} infix commands for a rising and falling line of melody, +respectively. + + + +@node Gregorian Chant contexts +@subsection Gregorian Chant contexts + +@cindex VaticanaVoiceContext +@cindex VaticanaStaffContext + +The predefined @code{VaticanaVoiceContext} and +@code{VaticanaStaffContext} can be used to engrave a piece of +Gregorian Chant in the style of the Editio Vaticana. These contexts +initialize all relevant context properties and grob properties to +proper values, so you can immediately go ahead entering the chant, as +the following excerpt demonstrates + +@lilypond[quote,raggedright,verbatim] +\include "gregorian-init.ly" +\score { + << + \context VaticanaVoice = "cantus" { + \override Score.BarNumber #'transparent = ##t { + \[ c'\melisma c' \flexa a \] + \[ a \flexa \deminutum g\melismaEnd \] + f \divisioMinima + \[ f\melisma \pes a c' c' \pes d'\melismaEnd \] + c' \divisioMinima \break + \[ c'\melisma c' \flexa a \] + \[ a \flexa \deminutum g\melismaEnd \] f \divisioMinima + } + } + \lyricsto "cantus" \new Lyrics { + San- ctus, San- ctus, San- ctus + } + >> +} +@end lilypond + + +@node Mensural contexts +@subsection Mensural contexts + +@cindex MensuralVoiceContext +@cindex MensuralStaffContext + +The predefined @code{MensuralVoiceContext} and +@code{MensuralStaffContext} can be used to engrave a piece in mensural +style. These contexts initialize all relevant context properties and +grob properties to proper values, so you can immediately go ahead +entering the chant, as the following excerpt demonstrates + +@lilypond[quote,raggedright,verbatim] +\score { + << + \context MensuralVoice = "discantus" \transpose c c' { + \override Score.BarNumber #'transparent = ##t { + c'1\melisma bes a g\melismaEnd + f\breve + \[ f1\melisma a c'\breve d'\melismaEnd \] + c'\longa + c'\breve\melisma a1 g1\melismaEnd + fis\longa^\signumcongruentiae + } + } + \lyricsto "discantus" \new Lyrics { + San -- ctus, San -- ctus, San -- ctus + } + >> +} +@end lilypond + + +@node Figured bass +@subsection Figured bass + +@cindex Basso continuo + +@c TODO: musicological blurb about FB + + +LilyPond has limited support for figured bass + +@lilypond[quote,raggedright,verbatim,fragment] +<< + \context Voice { \clef bass dis4 c d ais g fis} + \context FiguredBass \figuremode { + < 6 >4 < 7 >8 < 6+ [_!] > + < 6 >4 <6 5 [3+] > + < _ >4 < 6 >4 + } +>> +@end lilypond + +The support for figured bass consists of two parts: there is an input +mode, introduced by @code{\figuremode}, where you can enter bass figures +as numbers, and there is a context called @internalsref{FiguredBass} that +takes care of making @internalsref{BassFigure} objects. + +In figures input mode, a group of bass figures is delimited by +@code{<} and @code{>}. The duration is entered after the @code{>} +@example +<4 6> +@end example +@lilypond[quote,raggedright,fragment] +\context FiguredBass +\figuremode { <4 6> } +@end lilypond + +Accidentals are added when you append @code{-}, @code{!}, and @code{+} +to the numbers + +@example +<4- 6+ 7!> +@end example +@lilypond[quote,raggedright,fragment] +\context FiguredBass +\figuremode { <4- 6+ 7!> } +@end lilypond + +Spaces or dashes may be inserted by using @code{_}. Brackets are +introduced with @code{[} and @code{]} + +@example +< [4 6] 8 [_! 12] > +@end example +@lilypond[quote,raggedright,fragment] +\context FiguredBass +\figuremode { < [4 6] 8 [_! 12] > } +@end lilypond + +Although the support for figured bass may superficially resemble chord +support, it works much simpler. The @code{\figuremode} mode simply +stores the numbers and @internalsref{FiguredBass} context prints +them as entered. There is no conversion to pitches and no +realizations of the bass are played in the MIDI file. + +Internally, the code produces markup texts. You can use any of the +markup text properties to override formatting. For example, the +vertical spacing of the figures may be set with @code{baseline-skip}. + +@seealso + +Program reference: @internalsref{BassFigureEvent} music, +@internalsref{BassFigure} object, and @internalsref{FiguredBass} context. + +@refbugs + +Slash notation for alterations is not supported. +