From: Graham Percival Date: Wed, 19 Sep 2007 02:39:36 +0000 (-0700) Subject: Whoops, I got a bit carried away. Split Repeats, Simultaneous, Staff, and X-Git-Tag: release/2.11.35-1~46^2~151 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=ad15c8efb6b234d250f275ebc133ba41fda35c54;p=lilypond.git Whoops, I got a bit carried away. Split Repeats, Simultaneous, Staff, and Text. --- diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely index 2ad8bbadf8..c22db02de6 100644 --- a/Documentation/user/advanced-notation.itely +++ b/Documentation/user/advanced-notation.itely @@ -18,815 +18,11 @@ This chapter deals with rarely-used and advanced notation. @menu -* Text:: * Preparing parts:: -* Orchestral music:: -* Contemporary notation:: -* Educational use:: @end menu -@node Text -@section Text - -This section explains how to include text (with various formatting) in -your scores. - -@cindex Text, other languages -To write accented and special text (such as characters from other languages), -simply -insert the characters directly into the lilypond file. The file must be -saved as UTF-8. For more information, see @ref{Text encoding}. - -@lilypond[fragment,ragged-right,staffsize=16,quote] -c'4^\markup { bla \bold bla } -@end lilypond - -@lilypond[fragment,ragged-right,staffsize=16,quote] -c'4^\markup { bla \bold bla } -@end lilypond - -@lilypond[fragment,ragged-right,staffsize=16,quote] -c'4^\markup { bla \bold bla } -@end lilypond - -@lilypond[fragment,ragged-right,staffsize=16,quote] -c'4^\markup { bla \bold bla } -@end lilypond - -@menu -* Text scripts:: -* Text and line spanners:: -* Text spanners:: -* Text marks:: -* Text markup:: -* Nested scores:: -* Page wrapping text:: -* Overview of text markup commands:: -* Overview of text markup list commands:: -* Font selection:: -* New dynamic marks:: -@end menu - - -@anchor{Text scripts} -@unnumberedsubsubsec Text scripts - -@cindex Text scripts -@cindex text items, non-empty -@cindex non-empty texts - -It is possible to place arbitrary strings of text or @ref{Text markup}, -above or below notes by using a string @code{c^"text"}. By default, -these indications do not influence the note spacing, but by using the -command @code{\fatText}, the widths will be taken into account - -@lilypond[quote,fragment,ragged-right,verbatim,relative=1] -c4^"longtext" \fatText c4_"longlongtext" c4 -@end lilypond - -@noindent -To prevent text from influencing spacing, use @code{\emptyText}. - -More complex formatting may also be added to a note by using the -markup command, - -@lilypond[fragment,ragged-right,verbatim,quote] -c'4^\markup { bla \bold bla } -@end lilypond - -The @code{\markup} is described in more detail in -@ref{Text markup}. - - -@refcommands - -@funindex \fatText -@code{\fatText}, -@funindex \emptyText -@code{\emptyText}. - - -@commonprop - -Checking to make sure that text scripts and lyrics are within the margins is -a relatively large computational task. To speed up processing, lilypond does -not perform such calculations by default; to enable it, use - -@example -\override Score.PaperColumn #'keep-inside-line = ##t -@end example - - -@seealso - -In this manual: @ref{Text markup}. - -Program reference: @internalsref{TextScript}. - - -@anchor{Text and line spanners} -@unnumberedsubsubsec Text and line spanners - -Some performance indications, e.g., @i{rallentando} and -@i{accelerando} and @i{trills} are written as text and are extended -over many measures with lines, sometimes dotted or wavy. - -These all use the same routines as the glissando for drawing the texts -and the lines, and tuning their behavior is therefore also done in the -same way. It is done with a spanner, and the routine responsible for -drawing the spanners is @code{ly:line-interface::print}. This -routine determines the exact location of the two @i{span -points} and draws a line in between, in the style requested. - -Here is an example of the different line styles available, and how to -tune them. - -@lilypond[relative=2,ragged-right,verbatim,fragment] -d2 \glissando d'2 -\once \override Glissando #'dash-fraction = #0.5 -d,2 \glissando d'2 -\override Glissando #'style = #'dotted-line -d,2 \glissando d'2 -\override Glissando #'style = #'zigzag -d,2 \glissando d'2 -\override Glissando #'style = #'trill -d,2 \glissando d'2 -@end lilypond - -The information that determines the end-points is computed on-the-fly -for every graphic object, but it is possible to override these. - -@lilypond[relative=2,ragged-right,verbatim,fragment] -e2 \glissando f -\once \override Glissando #'bound-details #'right #'Y = #-2 -e2 \glissando f -@end lilypond - -The @code{Glissando} object, like any other using the -@code{ly:line-interface::print} routine, carries a nested -association list. In the above statement, the value for @code{Y} -is set to @code{-2} for the association list corresponding to the right -end point. Of course, it is also possible to adjust the left side with -@code{left} instead of @code{right}. - -If @code{Y} is not set, the value is computed from the vertical -position of right attachment point of the spanner. - -In case of a line break, the values for the span-points are extended -with contents of the @code{left-broken} and @code{right-broken} -sublists, for example - -@lilypond[relative=2,ragged-right,verbatim,fragment] -\override Glissando #'breakable = ##T -\override Glissando #'bound-details #'right-broken #'Y = #-3 -c1 \glissando \break -f1 -@end lilypond - -The following properties can be used for the - -@table @code -@item Y -This sets the Y-coordinate of the end point, in staff space. By -default, it is the center of the bound object, so for a glissando it -points to the vertical center of the note head. - -For horizontal spanners, such as text spanner and trill spanners, it -is hardcoded to 0. - -@item attach-dir -This determines where the line starts and ends in X-direction, -relative to the bound object. So, a value of @code{-1} (or -@code{LEFT}) makes the line start/end at the left side of the note -head it is attached to. - -@item X -This is the absolute coordinate of the end point. It is usually -computed on the fly, and there is little use in overriding it. - -@item stencil -Line spanners may have symbols at the beginning or end, which is -contained in this sub-property. This is for internal use, it is -recommended to use @code{text}. - -@item text -This is a markup that is evaluated to yield stencil. It is -used to put @i{cresc.} and @i{tr} on horizontal spanners. - -@lilypond[quote,ragged-right,fragment,relative=2,verbatim] -\override TextSpanner #'bound-details #'left #'text - = \markup { \small \bold Slower } -c2\startTextSpan b c a\stopTextSpan -@end lilypond - -@item stencil-align-dir-y -@item stencil-offset -Without setting this, the stencil is simply put there at the -end-point, as defined by the @code{X} and @code{Y} sub properties. -Setting either @code{stencil-align-dir-y} or @code{stencil-offset} -will move the symbol at the edge relative to the end point of the line - -@lilypond[relative=1,fragment,verbatim] -\override TextSpanner #'bound-details #'left #'stencil-align-dir-y = #DOWN -\override TextSpanner #'bound-details #'right #'stencil-align-dir-y = #UP - -\override TextSpanner #'bound-details #'left #'text = #"gggg" -\override TextSpanner #'bound-details #'right #'text = #"hhhh" -c4^\startTextSpan c c c \stopTextSpan -@end lilypond - -@item arrow -Setting this sub property to @code{#t} produce an arrowhead at the end -of the line. - -@item padding -This sub property controls the space between the specified end-point -of the line and the actual end. Without padding, a glissando would -start and end in the center of each note head. - -@end table - -@seealso - -Program reference: @internalsref{TextSpanner}, -@internalsref{Glissando}, @internalsref{VoiceFollower}, -@internalsref{TrillSpanner}, @internalsref{line-spanner-interface}. - -Examples: @lsr{expressive,line-styles.ly}, @lsr{expressive,line-arrows.ly} - - -@anchor{Text spanners} -@unnumberedsubsubsec Text spanners - -@cindex Text spanners - -Some performance indications, e.g., @i{rallentando} or @i{accelerando}, -are written as text and are extended over many measures with dotted -lines. Such texts are created using text spanners; attach -@code{\startTextSpan} and @code{\stopTextSpan} to the first and last -notes of the spanner. - -The string to be printed, as well as the style, is set through object -properties - -@lilypond[quote,ragged-right,fragment,relative=1,verbatim] -c1 -\textSpannerDown -\override TextSpanner #'bound-details #'left #'text = - \markup { \upright "rall" } -c2\startTextSpan b c\stopTextSpan a -\break -\textSpannerUp -\override TextSpanner #'bound-details #'left #'text = - \markup { \italic "rit" } -c2\startTextSpan b c\stopTextSpan a -@end lilypond - -@refcommands - -@funindex textSpannerUp -@code{\textSpannerUp}, -@funindex textSpannerDown -@code{\textSpannerDown}, -@funindex textSpannerNeutral -@code{\textSpannerNeutral}. - - -@commonprop - -To print a solid line, use - -@example -\override TextSpanner #'dash-fraction = #'() -@end example - - -@seealso - -Program reference: @internalsref{TextSpanner}. - - -@anchor{Text marks} -@unnumberedsubsubsec Text marks - -@cindex coda on bar line -@cindex segno on bar line -@cindex fermata on bar line -@cindex bar lines, symbols on -@funindex \mark - -The @code{\mark} command is primarily used for -@ref{Rehearsal marks}, -but it can also be used to put signs like coda, -segno, and fermata on a bar line. Use @code{\markup} to -access the appropriate symbol (symbols are listed in -@ref{The Feta font}). - -@lilypond[fragment,quote,ragged-right,verbatim,relative=2] -c1 \mark \markup { \musicglyph #"scripts.ufermata" } -c1 -@end lilypond - -@noindent -@code{\mark} is only typeset above the top stave of the score. If -you specify the @code{\mark} command at a bar line, the resulting -mark is placed above the bar line. If you specify it in the middle -of a bar, the resulting mark is positioned between notes. If it is -specified before the beginning of a score line, it is placed -before the first note of the line. Finally, if the mark occurs at -a line break, the mark will be printed at the -beginning of the next line. -@c IMO this is a bug; hopefully it'll be fixed soon, so I can -@c delete this sentence. -gp -If there is no next line, then the mark will not be printed at all. - - -@commonprop - -To print the mark at the end of the current line, use - -@example -\override Score.RehearsalMark - #'break-visibility = #begin-of-line-invisible -@end example - -@code{\mark} is often useful for adding text to the end of bar. In -such cases, changing the @code{#'self-alignment} is very useful - -@lilypond[fragment,quote,ragged-right,verbatim,relative=2] -\override Score.RehearsalMark - #'break-visibility = #begin-of-line-invisible -c1 c c c4 c c c -\once \override Score.RehearsalMark #'self-alignment-X = #right -\mark "D.S. al Fine " -@end lilypond - -Text marks may be aligned with notation objects other than -bar lines, - -@lilypond[fragment,quote,ragged-right,verbatim,relative=2] -\relative { - c1 - \key cis \major - \clef alto - \override Score.RehearsalMark #'break-align-symbols = #'(key-signature) - \mark "on key" - cis - \key ces \major - \override Score.RehearsalMark #'break-align-symbols = #'(clef) - \clef treble - \mark "on clef" - ces - \override Score.RehearsalMark #'break-align-symbols = #'(time-signature) - \key d \minor - \clef tenor - \time 3/4 - \mark "on time" - c -} -@end lilypond - -Possible symbols for the @code{break-align-symbols} list are -@code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos}, -@code{staff-bar}, @code{left-edge}, @code{key-cancellation}, -@code{key-signature}, and @code{time-signature}. - -The text marks will, by default, be aligned with the middle of the notation -object, but this can be changed by overriding the -@code{break-align-anchor-alignment} and -@code{break-align-anchor} properties for the appropriate grob. - -@lilypond[fragment,quote,ragged-right,verbatim] -{ - \override Score.RehearsalMark #'break-align-symbols = #'(key-signature) - c1 - \key cis \major - - % the RehearsalMark will be aligned with the left edge of the KeySignature - \once \override Staff.KeySignature #'break-align-anchor-alignment = #LEFT - \mark \default - cis1 - \key ces \major - - % the RehearsalMark will be aligned with the right edge of the KeySignature - \once \override Staff.KeySignature #'break-align-anchor-alignment = #RIGHT - \mark \default - ces1 - \key cis \major - - % the RehearsalMark will be aligned with the left edge of the KeySignature - % and then shifted right by 2 units. - \once \override Staff.KeySignature #'break-align-anchor = #2 - \mark \default - ces1 -} -@end lilypond - -Although text marks are normally only printed above the topmost -staff, you may alter this to print them on every staff, - -@lilypond[quote,ragged-right,verbatim,relative=2] -{ - \new Score \with { - \remove "Mark_engraver" - } - << - \new Staff \with { - \consists "Mark_engraver" - } - { c''1 \mark "foo" c'' } - \new Staff \with { - \consists "Mark_engraver" - } - { c'1 \mark "foo" c' } - >> -} -@end lilypond - - -@seealso - -Program reference: @internalsref{RehearsalMark}. - - -@anchor{Text markup} -@unnumberedsubsubsec Text markup - -@cindex markup -@cindex text markup -@cindex markup text -@cindex typeset text - -Use @code{\markup} to typeset text. Commands are entered with the -backslash @code{\}. To enter @code{\} and @code{#}, use double -quotation marks. - -@lilypond[quote,verbatim,fragment,relative=1] -c1^\markup { hello } -c1_\markup { hi there } -c1^\markup { hi \bold there, is \italic {anyone home?} } -c1_\markup { "\special {weird} #characters" } -@end lilypond - -@noindent -See @ref{Overview of text markup commands}, for a list of all -commands. - -@code{\markup} is primarily used for @internalsref{TextScript}s, -but it can also be used anywhere text is called in lilypond - -@lilypond[quote,verbatim] -\header{ title = \markup{ \bold { foo \italic { bar! } } } } -\score{ - \relative c'' { - \override Score.RehearsalMark - #'break-visibility = #begin-of-line-invisible - \override Score.RehearsalMark #'self-alignment-X = #right - - \set Staff.instrumentName = \markup{ \column{ Alto solo } } - c2^\markup{ don't be \flat } - \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit } - b2\startTextSpan - a2\mark \markup{ \large \bold Fine } - r2\stopTextSpan - \bar "||" - } - \addlyrics { bar, foo \markup{ \italic bar! } } -} -@end lilypond - -A @code{\markup} command can also be placed on its own, away from any -@code{\score} block, see @ref{Multiple scores in a book}. - -@lilypond[quote,ragged-right,verbatim] -\markup{ Here is some text. } -@end lilypond - -@cindex font switching - -The markup in the example demonstrates font switching commands. The -command @code{\bold} and @code{\italic} apply to the first following -word only; to apply a command to more than one word, enclose the -words with braces, - -@example -\markup @{ \bold @{ hi there @} @} -@end example - -@noindent -For clarity, you can also do this for single arguments, e.g., - -@example -\markup @{ is \italic @{ anyone @} home @} -@end example - -In markup mode you can compose expressions, similar to mathematical -expressions, XML documents, and music expressions. You can stack -expressions grouped vertically with the command @code{\column}. -Similarly, @code{\center-align} aligns texts by their center lines: - -@lilypond[quote,verbatim,fragment,relative=1] -c1^\markup { \column { a bbbb \line { c d } } } -c1^\markup { \center-align { a bbbb c } } -c1^\markup { \line { a b c } } -@end lilypond - -Lists with no previous command are not kept distinct. The expression - -@example -\center-align @{ @{ a b @} @{ c d @} @} -@end example - -@noindent - -is equivalent to - -@example -\center-align @{ a b c d @} -@end example - -@noindent - -To keep lists of words distinct, please use quotes @code{"} or -the @code{\line} command - -@lilypond[quote,verbatim,fragment,relative=1] -\fatText -c4^\markup{ \center-align { on three lines } } -c4^\markup{ \center-align { "all one line" } } -c4^\markup{ \center-align { { on three lines } } } -c4^\markup{ \center-align { \line { on one line } } } -@end lilypond - -Markups can be stored in variables and these variables -may be attached to notes, like -@example -allegro = \markup @{ \bold \large @{ Allegro @} @} - @{ a^\allegro b c d @} -@end example - -Some objects have alignment procedures of their own, which cancel out -any effects of alignments applied to their markup arguments as a -whole. For example, the @internalsref{RehearsalMark} is horizontally -centered, so using @code{\mark \markup @{ \left-align .. @}} has no -effect. - -In addition, vertical placement is performed after creating the -text markup object. If you wish to move an entire piece of markup, -you need to use the #'padding property or create an @q{anchor} point -inside the markup (generally with @code{\hspace #0}). - -@lilypond[quote,verbatim,fragment,relative=1] -\fatText -c'4^\markup{ \raise #5 "not raised" } -\once \override TextScript #'padding = #3 -c'4^\markup{ raised } -c'4^\markup{ \hspace #0 \raise #1.5 raised } -@end lilypond - -Some situations (such as dynamic marks) have preset font-related -properties. If you are creating text in such situations, it -is advisable to cancel those properties with -@code{normal-text}. See @ref{Overview of text markup commands}, -for more details. - - -@seealso - -This manual: @ref{Overview of text markup commands}. - -Program reference: @internalsref{TextScript}. - -Init files: @file{scm/@/new@/-markup@/.scm}. - - -@refbugs - -Kerning or generation of ligatures is only done when the @TeX{} -backend is used. In this case, LilyPond does not account for them so -texts will be spaced slightly too wide. - -Syntax errors for markup mode are confusing. - - -@anchor{Nested scores} -@unnumberedsubsubsec Nested scores - -It is possible to nest music inside markups, by adding a @code{\score} -block to a markup expression. Such a score must contain a @code{\layout} -block. - -@lilypond[quote,verbatim,ragged-right] -\relative { - c4 d^\markup { - \score { - \relative { c4 d e f } - \layout { } - } - } - e f -} -@end lilypond - -@anchor{Page wrapping text} -@unnumberedsubsubsec Page wrapping text -Whereas @code{\markup} is used to enter a non-breakable block of text, -@code{\markuplines} can be used at top-level to enter lines of text that -can spread over multiple pages: - -@verbatim -\markuplines { - \justified-lines { - A very long text of justified lines. - ... - } - \justified-lines { - An other very long paragraph. - ... - } - ... -} -@end verbatim - -@code{\markuplines} accepts a list of markup, that is either the result -of a markup list command, or a list of markups or of markup lists. The -built-in markup list commands are described in -@ref{Overview of text markup list commands}. - -@seealso - -This manual: @ref{Overview of text markup list commands}, -@ref{New markup list command definition}. - -@refcommands - -@funindex \markuplines -@code{\markuplines} - -@anchor{Overview of text markup commands} -@unnumberedsubsubsec Overview of text markup commands - -The following commands can all be used inside @code{\markup @{ @}}. - -@include markup-commands.tely - -@anchor{Overview of text markup list commands} -@unnumberedsubsubsec Overview of text markup list commands - -The following commands can all be used with @code{\markuplines}. - -@include markup-list-commands.tely - -@anchor{Font selection} -@unnumberedsubsubsec Font selection - -@cindex font selection -@cindex font magnification -@funindex font-interface - -By setting the object properties described below, you can select a -font from the preconfigured font families. LilyPond has default -support for the feta music fonts. Text fonts are selected through -Pango/FontConfig. The serif font defaults to New Century Schoolbook, -the sans and typewriter to whatever the Pango installation defaults -to. - - -@itemize @bullet -@item @code{font-encoding} -is a symbol that sets layout of the glyphs. This should only be set to -select different types of non-text fonts, e.g. - -@code{fetaBraces} for piano staff braces, @code{fetaMusic} the -standard music font, including ancient glyphs, @code{fetaDynamic} for -dynamic signs and @code{fetaNumber} for the number font. - -@item @code{font-family} -is a symbol indicating the general class of the typeface. Supported are -@code{roman} (Computer Modern), @code{sans}, and @code{typewriter}. - -@item @code{font-shape} -is a symbol indicating the shape of the font. There are typically -several font shapes available for each font family. Choices are -@code{italic}, @code{caps}, and @code{upright}. - -@item @code{font-series} -is a symbol indicating the series of the font. There are typically -several font series for each font family and shape. Choices are -@code{medium} and @code{bold}. - -@end itemize - -Fonts selected in the way sketched above come from a predefined style -sheet. If you want to use a font from outside the style sheet, -then set the -@code{font-name} property, - -@lilypond[fragment,verbatim] -{ - \override Staff.TimeSignature #'font-name = #"Charter" - \override Staff.TimeSignature #'font-size = #2 - \time 3/4 - c'1_\markup { - \override #'(font-name . "Vera Bold") - { This text is in Vera Bold } - } -} -@end lilypond - -@noindent -Any font can be used, as long as it is available to Pango/FontConfig. -To get a full list of all available fonts, run the command -@example -lilypond -dshow-available-fonts blabla -@end example -(the last argument of the command can be anything, but has to be present). - - -The size of the font may be set with the @code{font-size} -property. The resulting size is taken relative to the -@code{text-font-size} as defined in the @code{\paper} block. - -@cindex font size -@cindex font magnification - - -It is also possible to change the default font family for the entire -document. This is done by calling the @code{make-pango-font-tree} from -within the @code{\paper} block. The function takes names for the font -families to use for roman, sans serif and monospaced text. For -example, - -@cindex font families, setting -@cindex Pango - - -@lilypond[verbatim] -\paper { - myStaffSize = #20 - - #(define fonts - (make-pango-font-tree "Times New Roman" - "Nimbus Sans" - "Luxi Mono" - (/ myStaffSize 20))) -} - -{ - c'^\markup { roman: foo \sans bla \typewriter bar } -} -@end lilypond - -@c we don't do Helvetica / Courier, since GS incorrectly loads -@c Apple TTF fonts - - - -@seealso - -Examples: @lsr{text,font@/-family@/-override.ly}. - - -@anchor{New dynamic marks} -@unnumberedsubsubsec New dynamic marks - -It is possible to print new dynamic marks or text that should be aligned -with dynamics. Use @code{make-dynamic-script} to create these -marks. Note that the dynamic font only contains the characters -@code{f,m,p,r,s} and @code{z}. - -Some situations (such as dynamic marks) have preset font-related -properties. If you are creating text in such situations, it -is advisable to cancel those properties with -@code{normal-text}. See @ref{Overview of text markup commands}, -for more details. - -@cindex make-dynamic-script - -@lilypond[quote,verbatim,ragged-right] -sfzp = #(make-dynamic-script "sfzp") -\relative c' { - c4 c c\sfzp c -} -@end lilypond - -@cindex Dynamics, editorial -@cindex Dynamics, parenthesis - -It is also possible to print dynamics in round parenthesis or square -brackets. These are often used for adding editorial dynamics. - -@lilypond[quote,verbatim,ragged-right] -rndf = \markup{ \center-align {\line { \bold{\italic (} - \dynamic f \bold{\italic )} }} } -boxf = \markup{ \bracket { \dynamic f } } -{ c'1_\rndf c'1_\boxf } -@end lilypond - - - @node Preparing parts @section Preparing parts @@ -845,169 +41,6 @@ individual parts. @end menu -@anchor{Metronome marks} -@unnumberedsubsubsec Metronome marks - -@cindex Tempo -@cindex beats per minute -@cindex metronome marking - -Metronome settings can be entered as follows -@example -\tempo @var{duration} = @var{per-minute} -@end example - -In the MIDI output, they are interpreted as a tempo change. In the -layout output, a metronome marking is printed -@funindex \tempo -@lilypond[quote,ragged-right,verbatim,fragment] -\tempo 8.=120 c''1 -@end lilypond - - -@commonprop - -To change the tempo in the MIDI output without printing anything, make -the metronome marking invisible -@example -\once \override Score.MetronomeMark #'transparent = ##t -@end example - -To print other metronome markings, use these markup commands -@lilypond[quote,ragged-right,verbatim,relative,fragment] -c4^\markup { - ( - \smaller \general-align #Y #DOWN \note #"16." #1 - = - \smaller \general-align #Y #DOWN \note #"8" #1 - ) } -@end lilypond - -@noindent -See @ref{Text markup}, for more details. - - -@seealso - -Program reference: @internalsref{MetronomeMark}. - - -@refbugs - -Collisions are not checked. If you have notes above the top line of -the staff (or notes with articulations, slurs, text, etc), then the -metronome marking may be printed on top of musical symbols. If this -occurs, increase the padding of the metronome mark to place it -further away from the staff. - -@example -\override Score.MetronomeMark #'padding = #2.5 -@end example - - -@anchor{Instrument names} -@unnumberedsubsubsec Instrument names - -In an orchestral score, instrument names are printed at the left side -of the staves. - -This can be achieved by setting @internalsref{Staff}.@code{instrumentName} -and @internalsref{Staff}.@code{shortInstrumentName}, or -@internalsref{PianoStaff}.@code{instrumentName} and -@internalsref{PianoStaff}.@code{shortInstrumentName}. This will -print text before -the start of the staff. For the first staff, @code{instrumentName} is -used, for the following ones, @code{shortInstrumentName} is used. - -@lilypond[quote,verbatim,ragged-right,relative=1,fragment] -\set Staff.instrumentName = "Ploink " -\set Staff.shortInstrumentName = "Plk " -c1 -\break -c'' -@end lilypond - -You can also use markup texts to construct more complicated instrument -names, for example - -@lilypond[quote,fragment,verbatim,ragged-right] -\set Staff.instrumentName = \markup { - \column { "Clarinetti" - \line { "in B" \smaller \flat } } } -c''1 -@end lilypond - -If you wish to center the instrument names, you must center all of them - -@lilypond[quote,verbatim,ragged-right] -{ << -\new Staff { - \set Staff.instrumentName = \markup { - \center-align { "Clarinetti" - \line { "in B" \smaller \flat } } } - c''1 -} -\new Staff { - \set Staff.instrumentName = \markup{ \center-align { Vibraphone }} - c''1 -} ->> -} -@end lilypond - -For longer instrument names, it may be useful to increase the -@code{indent} setting in the @code{\layout} block. - -To center instrument names while leaving extra space to the right, - -@lilypond[quote,verbatim,ragged-right] -\new StaffGroup \relative -<< - \new Staff { - \set Staff.instrumentName = \markup { \hcenter-in #10 "blabla" } - c1 c1 - } - \new Staff { - \set Staff.instrumentName = \markup { \hcenter-in #10 "blo" } - c1 c1 - } ->> -@end lilypond - -To add instrument names to other contexts (such as @code{GrandStaff}, -@code{ChoirStaff}, or @code{StaffGroup}), the engraver must -be added to that context. - -@example -\layout@{ - \context @{\GrandStaff \consists "Instrument_name_engraver"@} -@} -@end example - -@noindent -More information about adding and removing engravers can -be found in @ref{Modifying context plug-ins}. - -Instrument names may be changed in the middle of a piece, - -@lilypond[quote,fragment,verbatim,ragged-right] -\set Staff.instrumentName = "First" -\set Staff.shortInstrumentName = "one" -c1 c c c \break -c1 c c c \break -\set Staff.instrumentName = "Second" -\set Staff.shortInstrumentName = "two" -c1 c c c \break -c1 c c c \break -@end lilypond - - -@seealso - -Program reference: @internalsref{InstrumentName}. - - - @anchor{Different editions from one source} @unnumberedsubsubsec Different editions from one source @@ -1082,746 +115,3 @@ Examples: @lsr{parts,tag@/-filter@/.ly} Multiple rests are not merged if you create the score with both tagged sections. - - -@node Orchestral music -@section Orchestral music - -Orchestral music involves some special notation, both in the full -score and the individual parts. This section explains how to tackle -some common problems in orchestral music. - -@menu -* Automatic part combining:: -* Hiding staves:: -* Quoting other voices:: -* Formatting cue notes:: -* Aligning to cadenzas:: -@end menu - - -@anchor{Hiding staves} -@unnumberedsubsubsec Hiding staves - -@cindex Frenched scores -@cindex Hiding staves - -In orchestral scores, staff lines that only have rests are usually -removed; this saves some space. This style is called @q{French Score}. -For @internalsref{Lyrics}, -@internalsref{ChordNames} and @internalsref{FiguredBass}, this is -switched on by default. When the lines of these contexts turn out -empty after the line-breaking process, they are removed. - -For normal staves, a specialized @internalsref{Staff} context is -available, which does the same: staves containing nothing (or only -multi-measure rests) are removed. The context definition is stored in -@code{\RemoveEmptyStaffContext} variable. Observe how the second staff -in this example disappears in the second line - -@lilypond[quote,ragged-right,verbatim] -\layout { - \context { \RemoveEmptyStaffContext } -} - -{ - \relative c' << - \new Staff { e4 f g a \break c1 } - \new Staff { c4 d e f \break R1 } - >> -} -@end lilypond - -The first system shows all staves in full. If empty staves should be -removed from the first system too, set @code{remove-first} to true in -@internalsref{VerticalAxisGroup}. - -@example -\override Score.VerticalAxisGroup #'remove-first = ##t -@end example - -To remove other types of contexts, use @code{\AncientRemoveEmptyStaffContext} -or @code{\RemoveEmptyRhythmicStaffContext}. - -Another application is making ossia sections, i.e., alternative -melodies on a separate piece of staff, with help of a Frenched -staff. - - -@anchor{Quoting other voices} -@unnumberedsubsubsec Quoting other voices - -@cindex cues - -With quotations, fragments of other parts can be inserted into a part -directly. Before a part can be quoted, it must be marked especially as -quotable. This is done with the @code{\addQuote} command. - -@example -\addQuote @var{name} @var{music} -@end example - - -@noindent -Here, @var{name} is an identifying string. The @var{music} is any kind -of music. Here is an example of @code{\addQuote} - -@example -\addQuote clarinet \relative c' @{ - f4 fis g gis -@} -@end example - -This command must be entered at toplevel, i.e., outside any music -blocks. - -After calling @code{\addQuote}, the quotation may then be done with -@code{\quoteDuring} or @code{\cueDuring}, - -@example -\quoteDuring #@var{name} @var{music} -@end example - -During a part, a piece of music can be quoted with the @code{\quoteDuring} -command. - -@example -\quoteDuring #"clarinet" @{ s2. @} -@end example - -This would cite three quarter notes (the duration of @code{s2.}) of -the previously added @code{clarinet} voice. - - -More precisely, it takes the current time-step of the part being -printed, and extracts the notes at the corresponding point of the -@code{\addQuote}d voice. Therefore, the argument to @code{\addQuote} -should be the entire part of the voice to be quoted, including any -rests at the beginning. - -Quotations take into account the transposition of both source and target -instruments, if they are specified using the @code{\transposition} command. - -@lilypond[quote,ragged-right,verbatim] -\addQuote clarinet \relative c' { - \transposition bes - f4 fis g gis -} - -{ - e'8 f'8 \quoteDuring #"clarinet" { s2 } -} -@end lilypond - -The type of events that are present in cue notes can be trimmed with -the @code{quotedEventTypes} property. The default value is -@code{(note-event rest-event)}, which means that only notes and -rests of the cued voice end up in the @code{\quoteDuring}. -Setting - -@example -\set Staff.quotedEventTypes = - #'(note-event articulation-event dynamic-event) -@end example - -@noindent -will quote notes (but no rests), together with scripts and dynamics. - -@refbugs - -Only the contents of the first @internalsref{Voice} occurring in an -@code{\addQuote} command will be considered for quotation, so -@var{music} can not contain @code{\new} and @code{\context Voice} -statements that would switch to a different Voice. - -Quoting grace notes is broken and can even cause LilyPond to crash. - -Quoting nested triplets may result in poor notation. - - -@seealso - -In this manual: @ref{Instrument transpositions}. - -Examples: @lsr{parts,quote.ly}, @lsr{parts,quote-transportation.ly} - -Program reference: @internalsref{QuoteMusic}. - - -@anchor{Formatting cue notes} -@unnumberedsubsubsec Formatting cue notes - -@cindex cues, formatting - -The previous section deals with inserting notes from another voice. -There is a more advanced music function called @code{\cueDuring}, -which makes formatting cue notes easier. - -The syntax is - -@example - \cueDuring #@var{name} #@var{updown} @var{music} -@end example - -This will insert notes from the part @var{name} into a -@internalsref{Voice} called @code{cue}. This happens simultaneously -with @var{music}, which usually is a rest. When the cue notes start, -the staff in effect becomes polyphonic for a moment. The argument -@var{updown} determines whether the cue notes should be notated as a -first or second voice. - - -@lilypond[verbatim,ragged-right] -smaller = { - \set fontSize = #-2 - \override Stem #'length-fraction = #0.8 - \override Beam #'thickness = #0.384 - \override Beam #'length-fraction = #0.8 -} - -\addQuote clarinet \relative { - R1*20 - r2 r8 c' f f -} - -\new Staff \relative << - - % setup a context for cue notes. - \new Voice = "cue" { \smaller \skip 1*21 } - - \set Score.skipBars = ##t - - \new Voice { - R1*20 - \cueDuring #"clarinet" #UP { - R1 - } - g4 g2. - } ->> -@end lilypond - - -Here are a couple of hints for successful cue notes - -@itemize @bullet -@item -Cue notes have smaller font sizes. -@item - the cued part is marked with the instrument playing the cue. -@item - when the original part takes over again, this should be marked with - the name of the original instrument. - -@c really? Are you sure about that last point? I'll check after 3.0 -gp - -@c Yes, this is good practice. Otherwise, the start of the original -@c part can only be seen from the font size. This is not good enough -@c for sight-reading. It is possilbe to use other -@c markers (e.g. a big close-bracket over the staff) to indicate the cue -@c notes are -@c finished. -@c -hwn - - -Any other changes introduced by the cued part should also be -undone. For example, if the cued instrument plays in a different clef, -the original clef should be stated once again. - -@end itemize - -The macro @code{\transposedCueDuring} is -useful to add cues to instruments which use a completely different -octave range (for example, having a cue of a piccolo flute within -a contra bassoon part). - -@lilypond[verbatim,ragged-right,quote] -picc = \relative c''' { - \clef "treble^8" - R1 | - c8 c c e g2 | - a4 g g2 | -} -\addQuote "picc" { \picc } - -cbsn = \relative c, { - \clef "bass_8" - c4 r g r - \transposedCueDuring #"picc" #UP c,, { R1 } | - c4 r g r | -} - -<< - \context Staff = "picc" \picc - \context Staff = "cbsn" \cbsn ->> -@end lilypond - - - - - -@node Contemporary notation -@section Contemporary notation - -In the 20th century, composers have greatly expanded the musical -vocabulary. With this expansion, many innovations in musical notation -have been tried. The book @q{Music Notation in the 20th century} by -Kurt Stone gives a comprehensive overview (see @ref{Literature -list}). - -This section describes notation that does -not fit into traditional notation categories, such as pitches, -tuplet beams, and articulation. For contemporary notation -that fits into traditional notation categories, such as -microtones, nested tuplet beams, and unusual fermatas, please -see those sections of the documentation. - -@menu -* Polymetric notation:: -* Time administration:: -* Proportional notation (introduction):: -* Clusters:: -* Special noteheads:: -* Feathered beams:: -* Improvisation:: -* Selecting notation font size:: -@end menu - - - -@anchor{Special noteheads} -@unnumberedsubsubsec Special noteheads - -@cindex note heads, special - -Different noteheads are used by various instruments for various -meanings -- crosses are used for @q{parlato} with vocalists, stopped -notes on guitar; diamonds are used for harmonics on string instruments, -etc. There is a shorthand (@code{\harmonic}) for diamond shapes; the -other notehead styles are produced by tweaking the property - -@lilypond[ragged-right,relative=1,fragment,verbatim,quote] -c4 d -\override NoteHead #'style = #'cross -e f -\revert NoteHead #'style -e d -@end lilypond - -@noindent -To see all notehead styles, please see -@ref{Note head styles}. - - -@seealso - -Program reference: @internalsref{NoteHead}. - - -@anchor{Improvisation} -@unnumberedsubsubsec Improvisation - -Improvisation is sometimes denoted with slashed note heads. Such note -heads can be created by adding a @internalsref{Pitch_squash_engraver} -to the @internalsref{Voice} context. Then, the -following command - -@example -\set squashedPosition = #0 -\override NoteHead #'style = #'slash -@end example - -@noindent -switches on the slashes. - -There are shortcuts @code{\improvisationOn} (and an accompanying -@code{\improvisationOff}) for this command sequence. They are used in -the following example - -@lilypond[verbatim,ragged-right,quote] -\new Voice \with { - \consists Pitch_squash_engraver -} \transpose c c' { - e8 e g a a16(bes)(a8) g \improvisationOn - e8 - ~e2~e8 f4 fis8 - ~fis2 \improvisationOff a16(bes) a8 g e -} -@end lilypond - - -@anchor{Selecting notation font size} -@unnumberedsubsubsec Selecting notation font size - -The easiest method of setting the font size of any context is by -setting the @code{fontSize} property. - -@lilypond[quote,fragment,relative=1,verbatim] -c8 -\set fontSize = #-4 -c f -\set fontSize = #3 -g -@end lilypond - -@noindent -It does not change the size of variable symbols, such as beams or -slurs. - -Internally, the @code{fontSize} context property will cause the -@code{font-size} property to be set in all layout objects. The value -of @code{font-size} is a number indicating the size relative to the -standard size for the current staff height. Each step up is an -increase of approximately 12% of the font size. Six steps is exactly a -factor two. The Scheme function @code{magstep} converts a -@code{font-size} number to a scaling factor. The @code{font-size} -property can also be set directly, so that only certain layout objects are -affected. - -@lilypond[quote,fragment,relative=1,verbatim] -c8 -\override NoteHead #'font-size = #-4 -c f -\override NoteHead #'font-size = #3 -g -@end lilypond - -Font size changes are achieved by scaling the design size that is -closest to the desired size. The standard font size (for -@code{font-size} equals 0), depends on the standard staff height. For -a 20pt staff, a 10pt font is selected. - -The @code{font-size} property can only be set on layout objects that -use fonts. These are the ones supporting the -@internalsref{font-interface} layout interface. - -@refcommands - -The following commands set @code{fontSize} for the current voice: - -@funindex \tiny -@code{\tiny}, -@funindex \small -@code{\small}, -@funindex \normalsize -@code{\normalsize}. - - - -@node Educational use -@section Educational use - -With the amount of control that LilyPond offers, one can make great -teaching tools in addition to great musical scores. - -@menu -* Balloon help:: -* Blank music sheet:: -* Hidden notes:: -* Shape note heads:: -* Easy Notation note heads:: -* Analysis brackets:: -* Coloring objects:: -* Parentheses:: -* Grid lines:: -@end menu - -@anchor{Balloon help} -@unnumberedsubsubsec Balloon help - -Elements of notation can be marked and named with the help of a square -balloon. The primary purpose of this feature is to explain notation. - -The following example demonstrates its use. - -@lilypond[quote,verbatim,fragment,ragged-right,relative=2] -\new Voice \with { \consists "Balloon_engraver" } -{ - \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" } - 8 -} -@end lilypond - -@noindent -There are two music functions, @code{balloonText} and -@code{balloonGrobText}. The latter takes the name of the grob to -adorn, while the former may be used as an articulation on a note. -The other arguments are the offset and the text of the label. - -@cindex balloon -@cindex notation, explaining - -@seealso - -Program reference: @internalsref{text-balloon-interface}. - - - - -@anchor{Blank music sheet} -@unnumberedsubsubsec Blank music sheet - -@cindex Sheet music, empty -@cindex Staves, blank sheet - -A blank music sheet can be produced also by using invisible notes, and -removing @code{Bar_number_engraver}. - - -@lilypond[quote,verbatim] -\layout{ indent = #0 } -emptymusic = { - \repeat unfold 2 % Change this for more lines. - { s1\break } - \bar "|." -} -\new Score \with { - \override TimeSignature #'transparent = ##t -% un-comment this line if desired -% \override Clef #'transparent = ##t - defaultBarType = #"" - \remove Bar_number_engraver -} << - -% modify these to get the staves you want - \new Staff \emptymusic - \new TabStaff \emptymusic ->> -@end lilypond - - -@anchor{Hidden notes} -@unnumberedsubsubsec Hidden notes - -@cindex Hidden notes -@cindex Invisible notes -@cindex Transparent notes - -@funindex \hideNotes -@funindex \unHideNotes -Hidden (or invisible or transparent) notes can be useful in preparing theory -or composition exercises. - -@lilypond[quote,ragged-right,verbatim,relative=2,fragment] -c4 d4 -\hideNotes -e4 f4 -\unHideNotes -g4 a -@end lilypond - - -@anchor{Shape note heads} -@unnumberedsubsubsec Shape note heads - -@cindex note heads, shape - -In shape note head notation, the shape of the note head corresponds -to the harmonic function of a note in the scale. This notation was -popular in the 19th century American song books. - -Shape note heads can be produced by setting @code{\aikenHeads} or -@code{\sacredHarpHeads}, depending on the style desired. - -@lilypond[verbatim,relative=1,fragment] - \aikenHeads - c8 d4 e8 a2 g1 - \sacredHarpHeads - c8 d4. e8 a2 g1 -@end lilypond - -Shapes are determined on the step in the scale, where the base of the -scale is determined by the @code{\key} command - -@funindex \key -@funindex shapeNoteStyles -@funindex \aikenHeads -@funindex \sacredHarpHeads - -Shape note heads are implemented through the @code{shapeNoteStyles} -property. Its value is a vector of symbols. The k-th element indicates -the style to use for the k-th step of the scale. Arbitrary -combinations are possible, e.g. - -@lilypond[verbatim,relative=1,fragment] - \set shapeNoteStyles = ##(cross triangle fa #f mensural xcircle diamond) - c8 d4. e8 a2 g1 -@end lilypond - - -@anchor{Easy Notation note heads} -@unnumberedsubsubsec Easy Notation note heads - -@cindex note heads, practice -@cindex note heads, easy notation -@cindex easy notation -@cindex Hal Leonard - -The @q{easy play} note head includes a note name inside the head. It is -used in music for beginners - -@lilypond[quote,ragged-right,verbatim,fragment,staffsize=26] - \setEasyHeads - c'2 e'4 f' | g'1 -@end lilypond - -The command @code{\setEasyHeads} overrides settings for the -@internalsref{NoteHead} object. To make the letters readable, it has -to be printed in a large font size. To print with a larger font, see -@ref{Setting the staff size}. - -@refcommands - -@funindex \setEasyHeads -@code{\setEasyHeads} - - -@anchor{Coloring objects} -@unnumberedsubsubsec Coloring objects - -Individual objects may be assigned colors. You may use the -color names listed in the @ref{List of colors}. - -@lilypond[quote,ragged-right,verbatim,fragment,relative=1] -\override NoteHead #'color = #red -c4 c -\override NoteHead #'color = #(x11-color 'LimeGreen) -d -\override Stem #'color = #blue -e -@end lilypond - -The full range of colors defined for X11 can be accessed by using the -Scheme function x11-color. The function takes one argument that can be a -symbol - -@example -\override Beam #'color = #(x11-color 'MediumTurquoise) -@end example - -or a string - -@example -\override Beam #'color = #(x11-color "MediumTurquoise") -@end example - -The first form is quicker to write and is more efficient. However, using -the second form it is possible to access X11 colors by the multi-word -form of its name - -@example -\override Beam #'color = #(x11-color "medium turquoise") -@end example - -If x11-color cannot make sense of the parameter then the color returned -defaults to black. It should be obvious from the final score that -something is wrong. - -This example illustrates the use of x11-color. Notice that the stem -color remains black after being set to (x11-color 'Boggle), which is -deliberate nonsense. - -@lilypond[quote,ragged-right,verbatim] -{ - \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2) - \set Staff.instrumentName = \markup { - \with-color #(x11-color 'navy) "Clarinet" - } - \time 2/4 - gis''8 a'' - \override Beam #'color = #(x11-color "medium turquoise") - gis'' a'' - \override NoteHead #'color = #(x11-color "LimeGreen") - gis'' a'' - \override Stem #'color = #(x11-color 'Boggle) - gis'' a'' -} -@end lilypond - - -@seealso - -Appendix: @ref{List of colors}. - - -@refbugs -Not all x11 colors are distinguishable in a web browser. For web use -normal colors are recommended. - -An x11 color is not necessarily exactly the same shade as a similarly -named normal color. - -Notes in a chord cannot be colored with @code{\override}; use -@code{\tweak} instead. See @ref{Objects connected to the input}, -for details. - - -@anchor{Parentheses} -@unnumberedsubsubsec Parentheses - -@cindex ghost notes -@cindex notes, ghost -@cindex notes, parenthesized - -Objects may be parenthesized by prefixing @code{\parenthesize} to the music -event, - -@lilypond[relative=2,fragment,verbatim,ragged-right] -< - c - \parenthesize d - g ->4-\parenthesize -. -@end lilypond - -This only functions inside chords, even for single notes - -@example -< \parenthesize NOTE> -@end example - - -@anchor{Grid lines} -@unnumberedsubsubsec Grid lines - -Vertical lines can be drawn between staves synchronized with -the notes. - -@lilypond[ragged-right,quote,verbatim] -\layout { - \context { - \Staff - \consists "Grid_point_engraver" %% sets of grid - gridInterval = #(ly:make-moment 1 4) - } -} - -\new Score \with { - \consists "Grid_line_span_engraver" - %% centers grid lines horizontally below noteheads - \override NoteColumn #'X-offset = #-0.5 -} - -\new ChoirStaff << - \new Staff { - \stemUp - \relative { - c'4. d8 e8 f g4 - } - } - \new Staff { - %% centers grid lines vertically - \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 ) - \stemDown - \clef bass - \relative c { - c4 g' f e - } - } ->> -@end lilypond - -Examples: @lsrdir{education} - - diff --git a/Documentation/user/educational.itely b/Documentation/user/educational.itely new file mode 100644 index 0000000000..8c0cbc1810 --- /dev/null +++ b/Documentation/user/educational.itely @@ -0,0 +1,620 @@ +@c -*- coding: utf-8; mode: texinfo; -*- + +@node Educational use +@section Educational use + +@menu +* Note heads:: +* Inside the staff:: +* Outside the staff:: +@end menu + + +@node Note heads +@subsection Note heads + +@anchor{Easy notation note heads} +@unnumberedsubsubsec Easy notation note heads + +@cindex note heads, practice +@cindex note heads, easy notation +@cindex easy notation +@cindex Hal Leonard + +The @q{easy play} note head includes a note name inside the head. It is +used in music for beginners + +@lilypond[quote,ragged-right,verbatim,fragment,staffsize=26] + \setEasyHeads + c'2 e'4 f' | g'1 +@end lilypond + +The command @code{\setEasyHeads} overrides settings for the +@internalsref{NoteHead} object. To make the letters readable, it has +to be printed in a large font size. To print with a larger font, see +@ref{Setting the staff size}. + +@refcommands + +@funindex \setEasyHeads +@code{\setEasyHeads} + + +@anchor{Shape note heads} +@unnumberedsubsubsec Shape note heads + +@cindex note heads, shape + +In shape note head notation, the shape of the note head corresponds +to the harmonic function of a note in the scale. This notation was +popular in the 19th century American song books. + +Shape note heads can be produced by setting @code{\aikenHeads} or +@code{\sacredHarpHeads}, depending on the style desired. + +@lilypond[verbatim,relative=1,fragment] + \aikenHeads + c8 d4 e8 a2 g1 + \sacredHarpHeads + c8 d4. e8 a2 g1 +@end lilypond + +Shapes are determined on the step in the scale, where the base of the +scale is determined by the @code{\key} command + +@funindex \key +@funindex shapeNoteStyles +@funindex \aikenHeads +@funindex \sacredHarpHeads + +Shape note heads are implemented through the @code{shapeNoteStyles} +property. Its value is a vector of symbols. The k-th element indicates +the style to use for the k-th step of the scale. Arbitrary +combinations are possible, e.g. + +@lilypond[verbatim,relative=1,fragment] + \set shapeNoteStyles = ##(cross triangle fa #f mensural xcircle diamond) + c8 d4. e8 a2 g1 +@end lilypond + + +@anchor{Improvisation} +@unnumberedsubsubsec Improvisation + +Improvisation is sometimes denoted with slashed note heads. Such note +heads can be created by adding a @internalsref{Pitch_squash_engraver} +to the @internalsref{Voice} context. Then, the +following command + +@example +\set squashedPosition = #0 +\override NoteHead #'style = #'slash +@end example + +@noindent +switches on the slashes. + +There are shortcuts @code{\improvisationOn} (and an accompanying +@code{\improvisationOff}) for this command sequence. They are used in +the following example + +@lilypond[verbatim,ragged-right,quote] +\new Voice \with { + \consists Pitch_squash_engraver +} \transpose c c' { + e8 e g a a16(bes)(a8) g \improvisationOn + e8 + ~e2~e8 f4 fis8 + ~fis2 \improvisationOff a16(bes) a8 g e +} +@end lilypond + + +@anchor{Special noteheads} +@unnumberedsubsubsec Special noteheads + +@cindex note heads, special + +Different noteheads are used by various instruments for various +meanings -- crosses are used for @q{parlato} with vocalists, stopped +notes on guitar; diamonds are used for harmonics on string instruments, +etc. There is a shorthand (@code{\harmonic}) for diamond shapes; the +other notehead styles are produced by tweaking the property + +@lilypond[ragged-right,relative=1,fragment,verbatim,quote] +c4 d +\override NoteHead #'style = #'cross +e f +\revert NoteHead #'style +e d +@end lilypond + +@noindent +To see all notehead styles, please see +@ref{Note head styles}. + + +@seealso + +Program reference: @internalsref{NoteHead}. + + + +@node Inside the staff +@subsection Inside the staff + + +@anchor{Selecting notation font size} +@unnumberedsubsubsec Selecting notation font size + +The easiest method of setting the font size of any context is by +setting the @code{fontSize} property. + +@lilypond[quote,fragment,relative=1,verbatim] +c8 +\set fontSize = #-4 +c f +\set fontSize = #3 +g +@end lilypond + +@noindent +It does not change the size of variable symbols, such as beams or +slurs. + +Internally, the @code{fontSize} context property will cause the +@code{font-size} property to be set in all layout objects. The value +of @code{font-size} is a number indicating the size relative to the +standard size for the current staff height. Each step up is an +increase of approximately 12% of the font size. Six steps is exactly a +factor two. The Scheme function @code{magstep} converts a +@code{font-size} number to a scaling factor. The @code{font-size} +property can also be set directly, so that only certain layout objects are +affected. + +@lilypond[quote,fragment,relative=1,verbatim] +c8 +\override NoteHead #'font-size = #-4 +c f +\override NoteHead #'font-size = #3 +g +@end lilypond + +Font size changes are achieved by scaling the design size that is +closest to the desired size. The standard font size (for +@code{font-size} equals 0), depends on the standard staff height. For +a 20pt staff, a 10pt font is selected. + +The @code{font-size} property can only be set on layout objects that +use fonts. These are the ones supporting the +@internalsref{font-interface} layout interface. + +@refcommands + +The following commands set @code{fontSize} for the current voice: + +@funindex \tiny +@code{\tiny}, +@funindex \small +@code{\small}, +@funindex \normalsize +@code{\normalsize}. + + +@anchor{Fingering instructions} +@unnumberedsubsubsec Fingering instructions + +@cindex fingering +@cindex finger change + +Fingering instructions can be entered using +@example +@var{note}-@var{digit} +@end example +For finger changes, use markup texts + +@lilypond[quote,verbatim,ragged-right,fragment,relative=1] +c4-1 c-2 c-3 c-4 +c^\markup { \finger "2 - 3" } +@end lilypond + +You can use the thumb-script to indicate that a note should be +played with the thumb (e.g., in cello music) +@lilypond[quote,verbatim,ragged-right,fragment,relative=2] +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,ragged-right,fragment,relative=2] +< c-1 e-2 g-3 b-5 >4 +@end lilypond + + +@commonprop + +You may exercise greater control over fingering chords by +setting @code{fingeringOrientations} + +@lilypond[quote,verbatim,ragged-right,fragment,relative=1] +\set fingeringOrientations = #'(left down) + 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,ragged-right,quote,fragment] +\set fingeringOrientations = #'(right) +4 +@end lilypond + + +@seealso + +Program reference: @internalsref{Fingering}. + +Examples: @lsr{expressive,fingering-chords.ly} + + + +@anchor{Hidden notes} +@unnumberedsubsubsec Hidden notes + +@cindex Hidden notes +@cindex Invisible notes +@cindex Transparent notes + +@funindex \hideNotes +@funindex \unHideNotes +Hidden (or invisible or transparent) notes can be useful in preparing theory +or composition exercises. + +@lilypond[quote,ragged-right,verbatim,relative=2,fragment] +c4 d4 +\hideNotes +e4 f4 +\unHideNotes +g4 a +@end lilypond + + +@anchor{Coloring objects} +@unnumberedsubsubsec Coloring objects + +Individual objects may be assigned colors. You may use the +color names listed in the @ref{List of colors}. + +@lilypond[quote,ragged-right,verbatim,fragment,relative=1] +\override NoteHead #'color = #red +c4 c +\override NoteHead #'color = #(x11-color 'LimeGreen) +d +\override Stem #'color = #blue +e +@end lilypond + +The full range of colors defined for X11 can be accessed by using the +Scheme function x11-color. The function takes one argument that can be a +symbol + +@example +\override Beam #'color = #(x11-color 'MediumTurquoise) +@end example + +or a string + +@example +\override Beam #'color = #(x11-color "MediumTurquoise") +@end example + +The first form is quicker to write and is more efficient. However, using +the second form it is possible to access X11 colors by the multi-word +form of its name + +@example +\override Beam #'color = #(x11-color "medium turquoise") +@end example + +If x11-color cannot make sense of the parameter then the color returned +defaults to black. It should be obvious from the final score that +something is wrong. + +This example illustrates the use of x11-color. Notice that the stem +color remains black after being set to (x11-color 'Boggle), which is +deliberate nonsense. + +@lilypond[quote,ragged-right,verbatim] +{ + \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2) + \set Staff.instrumentName = \markup { + \with-color #(x11-color 'navy) "Clarinet" + } + \time 2/4 + gis''8 a'' + \override Beam #'color = #(x11-color "medium turquoise") + gis'' a'' + \override NoteHead #'color = #(x11-color "LimeGreen") + gis'' a'' + \override Stem #'color = #(x11-color 'Boggle) + gis'' a'' +} +@end lilypond + + +@seealso + +Appendix: @ref{List of colors}. + + +@refbugs +Not all x11 colors are distinguishable in a web browser. For web use +normal colors are recommended. + +An x11 color is not necessarily exactly the same shade as a similarly +named normal color. + +Notes in a chord cannot be colored with @code{\override}; use +@code{\tweak} instead. See @ref{Objects connected to the input}, +for details. + + +@anchor{Parentheses} +@unnumberedsubsubsec Parentheses + +@cindex ghost notes +@cindex notes, ghost +@cindex notes, parenthesized + +Objects may be parenthesized by prefixing @code{\parenthesize} to the music +event, + +@lilypond[relative=2,fragment,verbatim,ragged-right] +< + c + \parenthesize d + g +>4-\parenthesize -. +@end lilypond + +This only functions inside chords, even for single notes + +@example +< \parenthesize NOTE> +@end example + + +@anchor{Ambitus} +@unnumberedsubsubsec Ambitus +@cindex ambitus + +The term @emph{ambitus} denotes a range of pitches for a given voice +in a part of music. It may also denote the pitch range that a musical +instrument is capable of playing. Ambits are printed on vocal parts, +so performers can easily determine it meets their capabilities. + +Ambits are denoted at the beginning of a piece near the initial clef. +The range is graphically specified by two note heads that represent the +minimum and maximum pitch. To print such ambits, add the +@internalsref{Ambitus_engraver} to the @internalsref{Voice} context, +for example, + +@example +\layout @{ + \context @{ + \Voice + \consists Ambitus_engraver + @} +@} +@end example + +This results in the following output + +@lilypond[quote,ragged-right] +\layout { + \context { + \Staff + \consists Ambitus_engraver + } +} + +\relative \new Staff { + as'' c e2 cis,2 +} +@end lilypond + +If you have multiple voices in a single staff and you want a single +ambitus per staff rather than per each voice, add the +@internalsref{Ambitus_engraver} to the @internalsref{Staff} context +rather than to the @internalsref{Voice} context. Here is an example, + +@lilypond[verbatim,ragged-right,quote] +\new Staff \with { + \consists "Ambitus_engraver" +} +<< + \new Voice \with { + \remove "Ambitus_engraver" + } \relative c'' { + \override Ambitus #'X-offset = #-1.0 + \voiceOne + c4 a d e f2 + } + \new Voice \with { + \remove "Ambitus_engraver" + } \relative c' { + \voiceTwo + es4 f g as b2 + } +>> +@end lilypond + +@noindent +This example uses one advanced feature, + +@example +\override Ambitus #'X-offset = #-1.0 +@end example + +@noindent +This code moves the ambitus to the left. The same effect could have +been achieved with @code{extra-offset}, but then the formatting system +would not reserve space for the moved object. + +@seealso + +Program reference: @internalsref{Ambitus}, +@internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead}, +@internalsref{AmbitusAccidental}. + +Examples: +@lsr{vocal,ambitus@/.ly}. + +@refbugs + +There is no collision handling in the case of multiple per-voice +ambitus. + + +@anchor{Stems} +@unnumberedsubsubsec Stems + +Whenever a note is found, a @internalsref{Stem} object is created +automatically. For whole notes and rests, they are also created but +made invisible. + +@refcommands + +@funindex \stemUp +@code{\stemUp}, +@funindex \stemDown +@code{\stemDown}, +@funindex \stemNeutral +@code{\stemNeutral}. + + +@commonprop + +To change the direction of stems in the middle of the staff, use + +@lilypond[quote,ragged-right,fragment,relative=2,verbatim] +a4 b c b +\override Stem #'neutral-direction = #up +a4 b c b +\override Stem #'neutral-direction = #down +a4 b c b +@end lilypond + + +@node Outside the staff +@subsection Outside the staff + + +@anchor{Balloon help} +@unnumberedsubsubsec Balloon help + +Elements of notation can be marked and named with the help of a square +balloon. The primary purpose of this feature is to explain notation. + +The following example demonstrates its use. + +@lilypond[quote,verbatim,fragment,ragged-right,relative=2] +\new Voice \with { \consists "Balloon_engraver" } +{ + \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" } + 8 +} +@end lilypond + +@noindent +There are two music functions, @code{balloonText} and +@code{balloonGrobText}. The latter takes the name of the grob to +adorn, while the former may be used as an articulation on a note. +The other arguments are the offset and the text of the label. + +@cindex balloon +@cindex notation, explaining + +@seealso + +Program reference: @internalsref{text-balloon-interface}. + + +@anchor{Grid lines} +@unnumberedsubsubsec Grid lines + +Vertical lines can be drawn between staves synchronized with +the notes. + +@lilypond[ragged-right,quote,verbatim] +\layout { + \context { + \Staff + \consists "Grid_point_engraver" %% sets of grid + gridInterval = #(ly:make-moment 1 4) + } +} + +\new Score \with { + \consists "Grid_line_span_engraver" + %% centers grid lines horizontally below noteheads + \override NoteColumn #'X-offset = #-0.5 +} + +\new ChoirStaff << + \new Staff { + \stemUp + \relative { + c'4. d8 e8 f g4 + } + } + \new Staff { + %% centers grid lines vertically + \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 ) + \stemDown + \clef bass + \relative c { + c4 g' f e + } + } +>> +@end lilypond + +Examples: @lsrdir{education} + + +@anchor{Blank music sheet} +@unnumberedsubsubsec Blank music sheet + +@cindex Sheet music, empty +@cindex Staves, blank sheet + +A blank music sheet can be produced also by using invisible notes, and +removing @code{Bar_number_engraver}. + + +@lilypond[quote,verbatim] +\layout{ indent = #0 } +emptymusic = { + \repeat unfold 2 % Change this for more lines. + { s1\break } + \bar "|." +} +\new Score \with { + \override TimeSignature #'transparent = ##t +% un-comment this line if desired +% \override Clef #'transparent = ##t + defaultBarType = #"" + \remove Bar_number_engraver +} << + +% modify these to get the staves you want + \new Staff \emptymusic + \new TabStaff \emptymusic +>> +@end lilypond + + + diff --git a/Documentation/user/instrument-notation.itely b/Documentation/user/instrument-notation.itely index 6141b6cea7..e84dffe7a3 100644 --- a/Documentation/user/instrument-notation.itely +++ b/Documentation/user/instrument-notation.itely @@ -1697,98 +1697,6 @@ Program reference: @internalsref{LyricText}, @internalsref{StanzaNumber}, -@anchor{Ambitus} -@unnumberedsubsubsec Ambitus -@cindex ambitus - -The term @emph{ambitus} denotes a range of pitches for a given voice -in a part of music. It may also denote the pitch range that a musical -instrument is capable of playing. Ambits are printed on vocal parts, -so performers can easily determine it meets their capabilities. - -Ambits are denoted at the beginning of a piece near the initial clef. -The range is graphically specified by two note heads that represent the -minimum and maximum pitch. To print such ambits, add the -@internalsref{Ambitus_engraver} to the @internalsref{Voice} context, -for example, - -@example -\layout @{ - \context @{ - \Voice - \consists Ambitus_engraver - @} -@} -@end example - -This results in the following output - -@lilypond[quote,ragged-right] -\layout { - \context { - \Staff - \consists Ambitus_engraver - } -} - -\relative \new Staff { - as'' c e2 cis,2 -} -@end lilypond - -If you have multiple voices in a single staff and you want a single -ambitus per staff rather than per each voice, add the -@internalsref{Ambitus_engraver} to the @internalsref{Staff} context -rather than to the @internalsref{Voice} context. Here is an example, - -@lilypond[verbatim,ragged-right,quote] -\new Staff \with { - \consists "Ambitus_engraver" -} -<< - \new Voice \with { - \remove "Ambitus_engraver" - } \relative c'' { - \override Ambitus #'X-offset = #-1.0 - \voiceOne - c4 a d e f2 - } - \new Voice \with { - \remove "Ambitus_engraver" - } \relative c' { - \voiceTwo - es4 f g as b2 - } ->> -@end lilypond - -@noindent -This example uses one advanced feature, - -@example -\override Ambitus #'X-offset = #-1.0 -@end example - -@noindent -This code moves the ambitus to the left. The same effect could have -been achieved with @code{extra-offset}, but then the formatting system -would not reserve space for the moved object. - -@seealso - -Program reference: @internalsref{Ambitus}, -@internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead}, -@internalsref{AmbitusAccidental}. - -Examples: -@lsr{vocal,ambitus@/.ly}. - -@refbugs - -There is no collision handling in the case of multiple per-voice -ambitus. - - @anchor{Other vocal issues} @unnumberedsubsubsec Other vocal issues diff --git a/Documentation/user/lilypond.tely b/Documentation/user/lilypond.tely index 4d0b20826c..dee04c6746 100644 --- a/Documentation/user/lilypond.tely +++ b/Documentation/user/lilypond.tely @@ -161,7 +161,6 @@ of this and other documentation. * Musical notation:: Musical notation. old stuff -* Basic notation:: * Instrument-specific notation:: * Advanced notation:: @@ -190,7 +189,6 @@ Appendices @include notation.itely -@include basic-notation.itely @include instrument-notation.itely @include advanced-notation.itely @include changing-defaults.itely diff --git a/Documentation/user/notation.itely b/Documentation/user/notation.itely index 579854a4fd..249871344b 100644 --- a/Documentation/user/notation.itely +++ b/Documentation/user/notation.itely @@ -11,6 +11,9 @@ This chapter explains how to create musical notation. * Expressive marks:: Adding expression to notes. * Repeats:: Repeat music. * Simultaneous notes:: More than one note at once. +* Staff notation:: Displaying staves. +* Educational use:: Special notation to increase legibility. +* Text:: Adding text to scores. @end menu @include pitch.itely @@ -18,5 +21,8 @@ This chapter explains how to create musical notation. @include expressive.itely @include repeats.itely @include simultaneous.itely +@include staff.itely +@include educational.itely +@include text.itely diff --git a/Documentation/user/repeats.itely b/Documentation/user/repeats.itely new file mode 100644 index 0000000000..2bce1bc200 --- /dev/null +++ b/Documentation/user/repeats.itely @@ -0,0 +1,391 @@ +@c -*- coding: utf-8; mode: texinfo; -*- + +@node Repeats +@section Repeats + +Repetition is a central concept in music, and multiple notations exist +for repetitions. + +@menu +* Writing repeats:: +* Other repeats:: +@end menu + +@node Writing repeats +@subsection Writing repeats + +@anchor{Repeat types} +@unnumberedsubsubsec Repeat types + +@cindex repeats + +The following types of repetition are supported + +@table @code +@item unfold +Repeated music is fully written (played) out. This is useful when +entering repetitious music. This is the only kind of repeat that +is included in MIDI output. + +@item volta +Repeats are not written out, but alternative endings (volte) are +printed, left to right with brackets. This is the standard notation +for repeats with alternatives. These are not played in MIDI output by +default. + + +@item tremolo +Make tremolo beams. These are not played in MIDI output by default. + +@item percent +Make beat or measure repeats. These look like percent signs. These +are not played in MIDI output by default. Percent repeats must be +declared within a @code{Voice} context. + +@end table + + +@anchor{Repeat syntax} +@unnumberedsubsubsec Repeat syntax + +@cindex volta +@cindex prima volta +@cindex seconda volta +@funindex \repeat + +LilyPond has one syntactic construct for specifying different types of +repeats. The syntax is + +@example +\repeat @var{variant} @var{repeatcount} @var{repeatbody} +@end example + +If you have alternative endings, you may add +@funindex \alternative +@example +\alternative @{ + @var{alternative1} + @var{alternative2} + @var{alternative3} + @dots{} +@} +@end example + +@noindent +where each @var{alternative} is a music expression. If you do not +give enough alternatives for all of the repeats, the first alternative +is assumed to be played more than once. + +Standard repeats are used like this + +@lilypond[quote,ragged-right,fragment,verbatim,relative=2] +c1 +\repeat volta 2 { c4 d e f } +\repeat volta 2 { f e d c } +@end lilypond + +With alternative endings + +@lilypond[quote,ragged-right,fragment,verbatim,relative=2] +c1 +\repeat volta 2 {c4 d e f} +\alternative { {d2 d} {f f,} } +@end lilypond + +Repeats with upbeats may be created. + +@lilypond[quote,ragged-right,fragment,verbatim,relative=2] +\new Staff { + \partial 4 e | + \repeat volta 4 { c2 d2 | e2 f2 | } + \alternative { { g4 g g e } { a a a a | b2. } } +} +@end lilypond + +@noindent +or + +@lilypond[quote,ragged-right,fragment,verbatim,relative=2] +\new Staff { + \partial 4 + \repeat volta 4 { e | c2 d2 | e2 f2 | } + \alternative { { \partial 4*3 g4 g g } { a a a a | b2. } } +} +@end lilypond + + + +@funindex \repeatTie + +Ties may be added to a second ending, + +@lilypond[quote,ragged-right,fragment,verbatim,relative=2] +c1 +\repeat volta 2 {c4 d e f ~ } +\alternative { {f2 d} {f\repeatTie f,} } +@end lilypond + +It is possible to shorten volta brackets +by setting @code{voltaSpannerDuration}. In the next example, the +bracket only lasts one measure, which is a duration of 3/4. + +@lilypond[verbatim,ragged-right,quote] +\relative c''{ + \time 3/4 + c c c + \set Score.voltaSpannerDuration = #(ly:make-moment 3 4) + \repeat volta 5 { d d d } + \alternative { { e e e f f f } + { g g g } } +} +@end lilypond + +If you want to start a repeat at the beginning of a line and have a +double bar at the end of the previous line, use +@example +@dots{} \bar "||:" \break +\repeat volta 2 @{ @dots{} +@end example +see @ref{Bar lines} for more information. + +@seealso + +Program reference: @internalsref{VoltaBracket}, +@internalsref{RepeatedMusic}, +@internalsref{VoltaRepeatedMusic}, and +@internalsref{UnfoldedRepeatedMusic}. + +Examples: + +Brackets for the repeat are normally only printed over the topmost +staff. This can be adjusted by moving @code{Volta_engraver} to the +Staff context where you want the brackets to appear; +see @ref{Modifying context plug-ins} and + +@lsr{repeats,volta@/-multi@/-staff@/.ly}. + + +@refbugs + +@cindex repeat, ambiguous + +A nested repeat like + +@example +\repeat @dots{} +\repeat @dots{} +\alternative +@end example + +@noindent +is ambiguous, since it is is not clear to which @code{\repeat} the +@code{\alternative} belongs. This ambiguity is resolved by always +having the @code{\alternative} belong to the inner @code{\repeat}. +For clarity, it is advisable to use braces in such situations. + +Timing information is not remembered at the start of an alternative, +so after a repeat timing information must be reset by hand; for +example, by setting @code{Score.measurePosition} or entering +@code{\partial}. Similarly, slurs or ties are also not repeated. + + +@anchor{Manual repeat commands} +@unnumberedsubsubsec Manual repeat commands + +@funindex repeatCommands + +The property @code{repeatCommands} can be used to control the layout of +repeats. Its value is a Scheme list of repeat commands. + +@table @asis +@item @code{start-repeat} +Print a @code{|:} bar line. + +@item @code{end-repeat} +Print a @code{:|} bar line. + +@item @code{(volta @var{text})} +Print a volta bracket saying @var{text}: The text can be specified as +a text string or as a markup text, see @ref{Text markup}. Do not +forget to change the font, as the default number font does not contain +alphabetic characters; + +@item @code{(volta #f)} +Stop a running volta bracket. +@end table + +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +c4 + \set Score.repeatCommands = #'((volta "93") end-repeat) +c4 c4 + \set Score.repeatCommands = #'((volta #f)) +c4 c4 +@end lilypond + + +@seealso + +Program reference: @internalsref{VoltaBracket}, +@internalsref{RepeatedMusic}, +@internalsref{VoltaRepeatedMusic}, and +@internalsref{UnfoldedRepeatedMusic}. + +@anchor{Repeats and MIDI} +@unnumberedsubsubsec Repeats and MIDI + +@cindex expanding repeats +@funindex \unfoldRepeats + +With a little bit of tweaking, all types of repeats can be present +in the MIDI output. This is achieved by applying the +@code{\unfoldRepeats} music function. This function changes all +repeats to unfold repeats. + +@lilypond[quote,verbatim,fragment,line-width=8.0\cm] +\unfoldRepeats { + \repeat tremolo 8 {c'32 e' } + \repeat percent 2 { c''8 d'' } + \repeat volta 2 {c'4 d' e' f'} + \alternative { + { g' a' a' g' } + {f' e' d' c' } + } +} +\bar "|." +@end lilypond + +When creating a score file using @code{\unfoldRepeats} for MIDI, +it is necessary to make two @code{\score} blocks: one for MIDI (with +unfolded repeats) and one for notation (with volta, tremolo, and +percent repeats). For example, + +@example +\score @{ + @var{..music..} + \layout @{ .. @} +@} +\score @{ + \unfoldRepeats @var{..music..} + \midi @{ .. @} +@} +@end example + + +@node Other repeats +@subsection Other repeats + +@anchor{Tremolo repeats} +@unnumberedsubsubsec Tremolo repeats + +@cindex tremolo beams + +To place tremolo marks between notes, use @code{\repeat} with tremolo +style +@lilypond[quote,verbatim,ragged-right] +\new Voice \relative c' { + \repeat tremolo 8 { c16 d16 } + \repeat tremolo 4 { c16 d16 } + \repeat tremolo 2 { c16 d16 } +} +@end lilypond + +Tremolo marks can also be put on a single note. In this case, the +note should not be surrounded by braces. +@lilypond[quote,verbatim,ragged-right] +\repeat tremolo 4 c'16 +@end lilypond + +Similar output is obtained using the tremolo subdivision, described in +@ref{Tremolo subdivisions}. + + +@seealso + +In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}. + +Program reference: @internalsref{Beam}, @internalsref{StemTremolo}. + + +@anchor{Tremolo subdivisions} +@unnumberedsubsubsec Tremolo subdivisions + +@cindex tremolo marks +@funindex tremoloFlags + +Tremolo marks can be printed on a single note by adding +@q{@code{:}[@var{number}]} after the note. The number indicates the +duration of the subdivision, and it must be at least 8. A +@var{length} value of 8 gives one line across the note stem. If the +length is omitted, the last value (stored in @code{tremoloFlags}) is +used + +@lilypond[quote,ragged-right,verbatim,fragment] +c'2:8 c':32 | c': c': | +@end lilypond + + +@refbugs + +Tremolos entered in this way do not carry over into the MIDI output. + + +@seealso + +In this manual: @ref{Tremolo repeats}. + +Elsewhere: @internalsref{StemTremolo}. + + +@anchor{Measure repeats} +@unnumberedsubsubsec Measure repeats + +@cindex percent repeats +@cindex measure repeats + +In the @code{percent} style, a note pattern can be repeated. It is +printed once, and then the pattern is replaced with a special sign. +Patterns of one and two measures are replaced by percent-like signs, +patterns that divide the measure length are replaced by slashes. +Percent repeats must be declared within a @code{Voice} context. + +@lilypond[quote,verbatim,ragged-right] +\new Voice \relative c' { + \repeat percent 4 { c4 } + \repeat percent 2 { c2 es2 f4 fis4 g4 c4 } +} +@end lilypond + +Measure repeats of more than 2 measures get a counter, if you switch +on the @code{countPercentRepeats} property, + +@lilypond[relative=2,fragment,quote,verbatim,ragged-right] +\new Voice { +\set countPercentRepeats = ##t + \repeat percent 4 { c1 } +} +@end lilypond + + + +Isolated percents can also be printed. This is done by putting a +multi-measure rest with a different print function, + +@lilypond[fragment,verbatim,quote] +\override MultiMeasureRest #'stencil + = #ly:multi-measure-rest::percent +R1 +@end lilypond + + + + +@seealso + +Program reference: @internalsref{RepeatSlash}, +@internalsref{PercentRepeat}, @internalsref{DoublePercentRepeat}, +@internalsref{DoublePercentRepeatCounter}, +@internalsref{PercentRepeatCounter}, +@internalsref{PercentRepeatedMusic}. + + + diff --git a/Documentation/user/simultaneous.itely b/Documentation/user/simultaneous.itely index 9af8f61c8e..0f9c4f185c 100644 --- a/Documentation/user/simultaneous.itely +++ b/Documentation/user/simultaneous.itely @@ -32,38 +32,6 @@ articulations, just like simple notes For more information about chords, see @ref{Chord names}. -@c I don't like having this here, but I can't think of -@c anywhere else to put it. :( -gp -@anchor{Stems} -@unnumberedsubsubsec Stems - -Whenever a note is found, a @internalsref{Stem} object is created -automatically. For whole notes and rests, they are also created but -made invisible. - -@refcommands - -@funindex \stemUp -@code{\stemUp}, -@funindex \stemDown -@code{\stemDown}, -@funindex \stemNeutral -@code{\stemNeutral}. - - -@commonprop - -To change the direction of stems in the middle of the staff, use - -@lilypond[quote,ragged-right,fragment,relative=2,verbatim] -a4 b c b -\override Stem #'neutral-direction = #up -a4 b c b -\override Stem #'neutral-direction = #down -a4 b c b -@end lilypond - - @anchor{Clusters} @unnumberedsubsubsec Clusters diff --git a/Documentation/user/staff.itely b/Documentation/user/staff.itely new file mode 100644 index 0000000000..9d0a757506 --- /dev/null +++ b/Documentation/user/staff.itely @@ -0,0 +1,579 @@ +@c -*- coding: utf-8; mode: texinfo; -*- + +@node Staff notation +@section Staff notation + +staff = singular, staves = plural + +@menu +* Displaying staves:: +* Writing parts:: +@end menu + + +@node Displaying staves +@subsection Displaying staves + +@anchor{System start delimiters} +@unnumberedsubsubsec System start delimiters + +@cindex start of system +@cindex Staff, multiple +@cindex bracket, vertical +@cindex brace, vertical +@cindex grand staff +@cindex staff group +@cindex staff, choir + +Many scores consist of more than one staff. These staves can be +joined in four different ways + +@itemize @bullet +@item The group is started with a brace at the left, and bar lines are +connected. This is done with the @internalsref{GrandStaff} context. + +@lilypond[verbatim,ragged-right,quote] +\new GrandStaff +\relative << + \new Staff { c1 c } + \new Staff { c c } +>> +@end lilypond + +@item The group is started with a bracket, and bar lines are connected. +This is done with the +@internalsref{StaffGroup} context + +@lilypond[verbatim,ragged-right,quote] +\new StaffGroup +\relative << + \new Staff { c1 c } + \new Staff { c c } +>> +@end lilypond + +@item The group is started with a bracket, but bar lines are not +connected. This is done with the @internalsref{ChoirStaff} context. + +@lilypond[verbatim,ragged-right,quote] +\new ChoirStaff +\relative << + \new Staff { c1 c } + \new Staff { c c } +>> +@end lilypond + +@item The group is started with a vertical line. Bar lines are not +connected. This is the default for the score. + +@lilypond[verbatim,ragged-right,quote] +\relative << + \new Staff { c1 c } + \new Staff { c c } +>> +@end lilypond +@end itemize + + +@seealso + +The bar lines at the start of each system are +@internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and +@internalsref{SystemStartBracket}. Only one of these types is created +in every context, and that type is determined by the property +@code{systemStartDelimiter}. + + +@commonprop + +System start delimiters may be deeply nested, + +@lilypond[quote,ragged-right,verbatim] +\new StaffGroup +\relative << + \set StaffGroup.systemStartDelimiterHierarchy + = #'(SystemStartSquare (SystemStartBracket a (SystemStartSquare b)) d) + \new Staff { c1 } + \new Staff { c1 } + \new Staff { c1 } + \new Staff { c1 } + \new Staff { c1 } +>> +@end lilypond + + +@anchor{Staff symbol} +@unnumberedsubsubsec Staff symbol + +@cindex adjusting staff symbol + +Notes, dynamic signs, etc., are grouped +with a set of horizontal lines, called a staff (plural @q{staves}). In +LilyPond, these lines are drawn using a separate layout object called +@code{staff symbol}. + +The staff symbol may be tuned in the number, thickness and distance +of lines, using properties. This is demonstrated in the example files +@lsr{staff,changing-the-number-of-lines-in-a-staff.ly} and +@lsr{staff,changing-the-staff-size.ly}. + +In addition, staves may be started and stopped at will. This is done +with @code{\startStaff} and @code{\stopStaff}. + +@lilypond[verbatim,relative=2,fragment] +b4 b +\override Staff.StaffSymbol #'line-count = 2 +\stopStaff \startStaff +b b +\revert Staff.StaffSymbol #'line-count +\stopStaff \startStaff +b b +@end lilypond + +In combination with Frenched staves, this may be used to typeset ossia +sections. An example is shown here + +@cindex ossia + +@lilypondfile{ossia.ly} + +@cindex staff lines, setting number of +@cindex staff lines, setting thickness of +@cindex thickness of staff lines, setting +@cindex number of staff lines, setting + +@seealso + +Program reference: @internalsref{StaffSymbol}. + +Examples: @lsrdir{staff} + + +@anchor{Hiding staves} +@unnumberedsubsubsec Hiding staves + +@cindex Frenched scores +@cindex Hiding staves + +In orchestral scores, staff lines that only have rests are usually +removed; this saves some space. This style is called @q{French Score}. +For @internalsref{Lyrics}, +@internalsref{ChordNames} and @internalsref{FiguredBass}, this is +switched on by default. When the lines of these contexts turn out +empty after the line-breaking process, they are removed. + +For normal staves, a specialized @internalsref{Staff} context is +available, which does the same: staves containing nothing (or only +multi-measure rests) are removed. The context definition is stored in +@code{\RemoveEmptyStaffContext} variable. Observe how the second staff +in this example disappears in the second line + +@lilypond[quote,ragged-right,verbatim] +\layout { + \context { \RemoveEmptyStaffContext } +} + +{ + \relative c' << + \new Staff { e4 f g a \break c1 } + \new Staff { c4 d e f \break R1 } + >> +} +@end lilypond + +The first system shows all staves in full. If empty staves should be +removed from the first system too, set @code{remove-first} to true in +@internalsref{VerticalAxisGroup}. + +@example +\override Score.VerticalAxisGroup #'remove-first = ##t +@end example + +To remove other types of contexts, use @code{\AncientRemoveEmptyStaffContext} +or @code{\RemoveEmptyRhythmicStaffContext}. + +Another application is making ossia sections, i.e., alternative +melodies on a separate piece of staff, with help of a Frenched +staff. + + + +@node Writing parts +@subsection Writing parts + +@anchor{Metronome marks} +@unnumberedsubsubsec Metronome marks + +@cindex Tempo +@cindex beats per minute +@cindex metronome marking + +Metronome settings can be entered as follows +@example +\tempo @var{duration} = @var{per-minute} +@end example + +In the MIDI output, they are interpreted as a tempo change. In the +layout output, a metronome marking is printed +@funindex \tempo +@lilypond[quote,ragged-right,verbatim,fragment] +\tempo 8.=120 c''1 +@end lilypond + + +@commonprop + +To change the tempo in the MIDI output without printing anything, make +the metronome marking invisible +@example +\once \override Score.MetronomeMark #'transparent = ##t +@end example + +To print other metronome markings, use these markup commands +@lilypond[quote,ragged-right,verbatim,relative,fragment] +c4^\markup { + ( + \smaller \general-align #Y #DOWN \note #"16." #1 + = + \smaller \general-align #Y #DOWN \note #"8" #1 + ) } +@end lilypond + +@noindent +See @ref{Text markup}, for more details. + + +@seealso + +Program reference: @internalsref{MetronomeMark}. + + +@refbugs + +Collisions are not checked. If you have notes above the top line of +the staff (or notes with articulations, slurs, text, etc), then the +metronome marking may be printed on top of musical symbols. If this +occurs, increase the padding of the metronome mark to place it +further away from the staff. + +@example +\override Score.MetronomeMark #'padding = #2.5 +@end example + + +@anchor{Instrument names} +@unnumberedsubsubsec Instrument names + +In an orchestral score, instrument names are printed at the left side +of the staves. + +This can be achieved by setting @internalsref{Staff}.@code{instrumentName} +and @internalsref{Staff}.@code{shortInstrumentName}, or +@internalsref{PianoStaff}.@code{instrumentName} and +@internalsref{PianoStaff}.@code{shortInstrumentName}. This will +print text before +the start of the staff. For the first staff, @code{instrumentName} is +used, for the following ones, @code{shortInstrumentName} is used. + +@lilypond[quote,verbatim,ragged-right,relative=1,fragment] +\set Staff.instrumentName = "Ploink " +\set Staff.shortInstrumentName = "Plk " +c1 +\break +c'' +@end lilypond + +You can also use markup texts to construct more complicated instrument +names, for example + +@lilypond[quote,fragment,verbatim,ragged-right] +\set Staff.instrumentName = \markup { + \column { "Clarinetti" + \line { "in B" \smaller \flat } } } +c''1 +@end lilypond + +If you wish to center the instrument names, you must center all of them + +@lilypond[quote,verbatim,ragged-right] +{ << +\new Staff { + \set Staff.instrumentName = \markup { + \center-align { "Clarinetti" + \line { "in B" \smaller \flat } } } + c''1 +} +\new Staff { + \set Staff.instrumentName = \markup{ \center-align { Vibraphone }} + c''1 +} +>> +} +@end lilypond + +For longer instrument names, it may be useful to increase the +@code{indent} setting in the @code{\layout} block. + +To center instrument names while leaving extra space to the right, + +@lilypond[quote,verbatim,ragged-right] +\new StaffGroup \relative +<< + \new Staff { + \set Staff.instrumentName = \markup { \hcenter-in #10 "blabla" } + c1 c1 + } + \new Staff { + \set Staff.instrumentName = \markup { \hcenter-in #10 "blo" } + c1 c1 + } +>> +@end lilypond + +To add instrument names to other contexts (such as @code{GrandStaff}, +@code{ChoirStaff}, or @code{StaffGroup}), the engraver must +be added to that context. + +@example +\layout@{ + \context @{\GrandStaff \consists "Instrument_name_engraver"@} +@} +@end example + +@noindent +More information about adding and removing engravers can +be found in @ref{Modifying context plug-ins}. + +Instrument names may be changed in the middle of a piece, + +@lilypond[quote,fragment,verbatim,ragged-right] +\set Staff.instrumentName = "First" +\set Staff.shortInstrumentName = "one" +c1 c c c \break +c1 c c c \break +\set Staff.instrumentName = "Second" +\set Staff.shortInstrumentName = "two" +c1 c c c \break +c1 c c c \break +@end lilypond + + +@seealso + +Program reference: @internalsref{InstrumentName}. + + +@anchor{Quoting other voices} +@unnumberedsubsubsec Quoting other voices + +@cindex cues + +With quotations, fragments of other parts can be inserted into a part +directly. Before a part can be quoted, it must be marked especially as +quotable. This is done with the @code{\addQuote} command. + +@example +\addQuote @var{name} @var{music} +@end example + + +@noindent +Here, @var{name} is an identifying string. The @var{music} is any kind +of music. Here is an example of @code{\addQuote} + +@example +\addQuote clarinet \relative c' @{ + f4 fis g gis +@} +@end example + +This command must be entered at toplevel, i.e., outside any music +blocks. + +After calling @code{\addQuote}, the quotation may then be done with +@code{\quoteDuring} or @code{\cueDuring}, + +@example +\quoteDuring #@var{name} @var{music} +@end example + +During a part, a piece of music can be quoted with the @code{\quoteDuring} +command. + +@example +\quoteDuring #"clarinet" @{ s2. @} +@end example + +This would cite three quarter notes (the duration of @code{s2.}) of +the previously added @code{clarinet} voice. + + +More precisely, it takes the current time-step of the part being +printed, and extracts the notes at the corresponding point of the +@code{\addQuote}d voice. Therefore, the argument to @code{\addQuote} +should be the entire part of the voice to be quoted, including any +rests at the beginning. + +Quotations take into account the transposition of both source and target +instruments, if they are specified using the @code{\transposition} command. + +@lilypond[quote,ragged-right,verbatim] +\addQuote clarinet \relative c' { + \transposition bes + f4 fis g gis +} + +{ + e'8 f'8 \quoteDuring #"clarinet" { s2 } +} +@end lilypond + +The type of events that are present in cue notes can be trimmed with +the @code{quotedEventTypes} property. The default value is +@code{(note-event rest-event)}, which means that only notes and +rests of the cued voice end up in the @code{\quoteDuring}. +Setting + +@example +\set Staff.quotedEventTypes = + #'(note-event articulation-event dynamic-event) +@end example + +@noindent +will quote notes (but no rests), together with scripts and dynamics. + +@refbugs + +Only the contents of the first @internalsref{Voice} occurring in an +@code{\addQuote} command will be considered for quotation, so +@var{music} can not contain @code{\new} and @code{\context Voice} +statements that would switch to a different Voice. + +Quoting grace notes is broken and can even cause LilyPond to crash. + +Quoting nested triplets may result in poor notation. + + +@seealso + +In this manual: @ref{Instrument transpositions}. + +Examples: @lsr{parts,quote.ly}, @lsr{parts,quote-transportation.ly} + +Program reference: @internalsref{QuoteMusic}. + + +@anchor{Formatting cue notes} +@unnumberedsubsubsec Formatting cue notes + +@cindex cues, formatting + +The previous section deals with inserting notes from another voice. +There is a more advanced music function called @code{\cueDuring}, +which makes formatting cue notes easier. + +The syntax is + +@example + \cueDuring #@var{name} #@var{updown} @var{music} +@end example + +This will insert notes from the part @var{name} into a +@internalsref{Voice} called @code{cue}. This happens simultaneously +with @var{music}, which usually is a rest. When the cue notes start, +the staff in effect becomes polyphonic for a moment. The argument +@var{updown} determines whether the cue notes should be notated as a +first or second voice. + + +@lilypond[verbatim,ragged-right] +smaller = { + \set fontSize = #-2 + \override Stem #'length-fraction = #0.8 + \override Beam #'thickness = #0.384 + \override Beam #'length-fraction = #0.8 +} + +\addQuote clarinet \relative { + R1*20 + r2 r8 c' f f +} + +\new Staff \relative << + + % setup a context for cue notes. + \new Voice = "cue" { \smaller \skip 1*21 } + + \set Score.skipBars = ##t + + \new Voice { + R1*20 + \cueDuring #"clarinet" #UP { + R1 + } + g4 g2. + } +>> +@end lilypond + + +Here are a couple of hints for successful cue notes + +@itemize @bullet +@item +Cue notes have smaller font sizes. +@item + the cued part is marked with the instrument playing the cue. +@item + when the original part takes over again, this should be marked with + the name of the original instrument. + +@c really? Are you sure about that last point? I'll check after 3.0 -gp + +@c Yes, this is good practice. Otherwise, the start of the original +@c part can only be seen from the font size. This is not good enough +@c for sight-reading. It is possilbe to use other +@c markers (e.g. a big close-bracket over the staff) to indicate the cue +@c notes are +@c finished. +@c -hwn + + +Any other changes introduced by the cued part should also be +undone. For example, if the cued instrument plays in a different clef, +the original clef should be stated once again. + +@end itemize + +The macro @code{\transposedCueDuring} is +useful to add cues to instruments which use a completely different +octave range (for example, having a cue of a piccolo flute within +a contra bassoon part). + +@lilypond[verbatim,ragged-right,quote] +picc = \relative c''' { + \clef "treble^8" + R1 | + c8 c c e g2 | + a4 g g2 | +} +\addQuote "picc" { \picc } + +cbsn = \relative c, { + \clef "bass_8" + c4 r g r + \transposedCueDuring #"picc" #UP c,, { R1 } | + c4 r g r | +} + +<< + \context Staff = "picc" \picc + \context Staff = "cbsn" \cbsn +>> +@end lilypond + + + + + + diff --git a/Documentation/user/text.itely b/Documentation/user/text.itely new file mode 100644 index 0000000000..40d2edfb00 --- /dev/null +++ b/Documentation/user/text.itely @@ -0,0 +1,802 @@ +@c -*- coding: utf-8; mode: texinfo; -*- + +@node Text +@section Text + +This section explains how to include text (with various formatting) in +your scores. + +@cindex Text, other languages +To write accented and special text (such as characters from other languages), +simply +insert the characters directly into the lilypond file. The file must be +saved as UTF-8. For more information, see @ref{Text encoding}. + +@lilypond[fragment,ragged-right,staffsize=16,quote] +c'4^\markup { bla \bold bla } +@end lilypond + +@lilypond[fragment,ragged-right,staffsize=16,quote] +c'4^\markup { bla \bold bla } +@end lilypond + +@lilypond[fragment,ragged-right,staffsize=16,quote] +c'4^\markup { bla \bold bla } +@end lilypond + +@lilypond[fragment,ragged-right,staffsize=16,quote] +c'4^\markup { bla \bold bla } +@end lilypond + +@menu +* Writing text:: +* Text markup:: +@end menu + + +@node Writing text +@subsection Writing text + +@anchor{Text scripts} +@unnumberedsubsubsec Text scripts + +@cindex Text scripts +@cindex text items, non-empty +@cindex non-empty texts + +It is possible to place arbitrary strings of text or @ref{Text markup}, +above or below notes by using a string @code{c^"text"}. By default, +these indications do not influence the note spacing, but by using the +command @code{\fatText}, the widths will be taken into account + +@lilypond[quote,fragment,ragged-right,verbatim,relative=1] +c4^"longtext" \fatText c4_"longlongtext" c4 +@end lilypond + +@noindent +To prevent text from influencing spacing, use @code{\emptyText}. + +More complex formatting may also be added to a note by using the +markup command, + +@lilypond[fragment,ragged-right,verbatim,quote] +c'4^\markup { bla \bold bla } +@end lilypond + +The @code{\markup} is described in more detail in +@ref{Text markup}. + + +@refcommands + +@funindex \fatText +@code{\fatText}, +@funindex \emptyText +@code{\emptyText}. + + +@commonprop + +Checking to make sure that text scripts and lyrics are within the margins is +a relatively large computational task. To speed up processing, lilypond does +not perform such calculations by default; to enable it, use + +@example +\override Score.PaperColumn #'keep-inside-line = ##t +@end example + + +@seealso + +In this manual: @ref{Text markup}. + +Program reference: @internalsref{TextScript}. + + +@anchor{Text and line spanners} +@unnumberedsubsubsec Text and line spanners + +Some performance indications, e.g., @i{rallentando} and +@i{accelerando} and @i{trills} are written as text and are extended +over many measures with lines, sometimes dotted or wavy. + +These all use the same routines as the glissando for drawing the texts +and the lines, and tuning their behavior is therefore also done in the +same way. It is done with a spanner, and the routine responsible for +drawing the spanners is @code{ly:line-interface::print}. This +routine determines the exact location of the two @i{span +points} and draws a line in between, in the style requested. + +Here is an example of the different line styles available, and how to +tune them. + +@lilypond[relative=2,ragged-right,verbatim,fragment] +d2 \glissando d'2 +\once \override Glissando #'dash-fraction = #0.5 +d,2 \glissando d'2 +\override Glissando #'style = #'dotted-line +d,2 \glissando d'2 +\override Glissando #'style = #'zigzag +d,2 \glissando d'2 +\override Glissando #'style = #'trill +d,2 \glissando d'2 +@end lilypond + +The information that determines the end-points is computed on-the-fly +for every graphic object, but it is possible to override these. + +@lilypond[relative=2,ragged-right,verbatim,fragment] +e2 \glissando f +\once \override Glissando #'bound-details #'right #'Y = #-2 +e2 \glissando f +@end lilypond + +The @code{Glissando} object, like any other using the +@code{ly:line-interface::print} routine, carries a nested +association list. In the above statement, the value for @code{Y} +is set to @code{-2} for the association list corresponding to the right +end point. Of course, it is also possible to adjust the left side with +@code{left} instead of @code{right}. + +If @code{Y} is not set, the value is computed from the vertical +position of right attachment point of the spanner. + +In case of a line break, the values for the span-points are extended +with contents of the @code{left-broken} and @code{right-broken} +sublists, for example + +@lilypond[relative=2,ragged-right,verbatim,fragment] +\override Glissando #'breakable = ##T +\override Glissando #'bound-details #'right-broken #'Y = #-3 +c1 \glissando \break +f1 +@end lilypond + +The following properties can be used for the + +@table @code +@item Y +This sets the Y-coordinate of the end point, in staff space. By +default, it is the center of the bound object, so for a glissando it +points to the vertical center of the note head. + +For horizontal spanners, such as text spanner and trill spanners, it +is hardcoded to 0. + +@item attach-dir +This determines where the line starts and ends in X-direction, +relative to the bound object. So, a value of @code{-1} (or +@code{LEFT}) makes the line start/end at the left side of the note +head it is attached to. + +@item X +This is the absolute coordinate of the end point. It is usually +computed on the fly, and there is little use in overriding it. + +@item stencil +Line spanners may have symbols at the beginning or end, which is +contained in this sub-property. This is for internal use, it is +recommended to use @code{text}. + +@item text +This is a markup that is evaluated to yield stencil. It is +used to put @i{cresc.} and @i{tr} on horizontal spanners. + +@lilypond[quote,ragged-right,fragment,relative=2,verbatim] +\override TextSpanner #'bound-details #'left #'text + = \markup { \small \bold Slower } +c2\startTextSpan b c a\stopTextSpan +@end lilypond + +@item stencil-align-dir-y +@item stencil-offset +Without setting this, the stencil is simply put there at the +end-point, as defined by the @code{X} and @code{Y} sub properties. +Setting either @code{stencil-align-dir-y} or @code{stencil-offset} +will move the symbol at the edge relative to the end point of the line + +@lilypond[relative=1,fragment,verbatim] +\override TextSpanner #'bound-details #'left #'stencil-align-dir-y = #DOWN +\override TextSpanner #'bound-details #'right #'stencil-align-dir-y = #UP + +\override TextSpanner #'bound-details #'left #'text = #"gggg" +\override TextSpanner #'bound-details #'right #'text = #"hhhh" +c4^\startTextSpan c c c \stopTextSpan +@end lilypond + +@item arrow +Setting this sub property to @code{#t} produce an arrowhead at the end +of the line. + +@item padding +This sub property controls the space between the specified end-point +of the line and the actual end. Without padding, a glissando would +start and end in the center of each note head. + +@end table + +@seealso + +Program reference: @internalsref{TextSpanner}, +@internalsref{Glissando}, @internalsref{VoiceFollower}, +@internalsref{TrillSpanner}, @internalsref{line-spanner-interface}. + +Examples: @lsr{expressive,line-styles.ly}, @lsr{expressive,line-arrows.ly} + + +@anchor{Text spanners} +@unnumberedsubsubsec Text spanners + +@cindex Text spanners + +Some performance indications, e.g., @i{rallentando} or @i{accelerando}, +are written as text and are extended over many measures with dotted +lines. Such texts are created using text spanners; attach +@code{\startTextSpan} and @code{\stopTextSpan} to the first and last +notes of the spanner. + +The string to be printed, as well as the style, is set through object +properties + +@lilypond[quote,ragged-right,fragment,relative=1,verbatim] +c1 +\textSpannerDown +\override TextSpanner #'bound-details #'left #'text = + \markup { \upright "rall" } +c2\startTextSpan b c\stopTextSpan a +\break +\textSpannerUp +\override TextSpanner #'bound-details #'left #'text = + \markup { \italic "rit" } +c2\startTextSpan b c\stopTextSpan a +@end lilypond + +@refcommands + +@funindex textSpannerUp +@code{\textSpannerUp}, +@funindex textSpannerDown +@code{\textSpannerDown}, +@funindex textSpannerNeutral +@code{\textSpannerNeutral}. + + +@commonprop + +To print a solid line, use + +@example +\override TextSpanner #'dash-fraction = #'() +@end example + + +@seealso + +Program reference: @internalsref{TextSpanner}. + + +@anchor{Text marks} +@unnumberedsubsubsec Text marks + +@cindex coda on bar line +@cindex segno on bar line +@cindex fermata on bar line +@cindex bar lines, symbols on +@funindex \mark + +The @code{\mark} command is primarily used for +@ref{Rehearsal marks}, +but it can also be used to put signs like coda, +segno, and fermata on a bar line. Use @code{\markup} to +access the appropriate symbol (symbols are listed in +@ref{The Feta font}). + +@lilypond[fragment,quote,ragged-right,verbatim,relative=2] +c1 \mark \markup { \musicglyph #"scripts.ufermata" } +c1 +@end lilypond + +@noindent +@code{\mark} is only typeset above the top stave of the score. If +you specify the @code{\mark} command at a bar line, the resulting +mark is placed above the bar line. If you specify it in the middle +of a bar, the resulting mark is positioned between notes. If it is +specified before the beginning of a score line, it is placed +before the first note of the line. Finally, if the mark occurs at +a line break, the mark will be printed at the +beginning of the next line. +@c IMO this is a bug; hopefully it'll be fixed soon, so I can +@c delete this sentence. -gp +If there is no next line, then the mark will not be printed at all. + + +@commonprop + +To print the mark at the end of the current line, use + +@example +\override Score.RehearsalMark + #'break-visibility = #begin-of-line-invisible +@end example + +@code{\mark} is often useful for adding text to the end of bar. In +such cases, changing the @code{#'self-alignment} is very useful + +@lilypond[fragment,quote,ragged-right,verbatim,relative=2] +\override Score.RehearsalMark + #'break-visibility = #begin-of-line-invisible +c1 c c c4 c c c +\once \override Score.RehearsalMark #'self-alignment-X = #right +\mark "D.S. al Fine " +@end lilypond + +Text marks may be aligned with notation objects other than +bar lines, + +@lilypond[fragment,quote,ragged-right,verbatim,relative=2] +\relative { + c1 + \key cis \major + \clef alto + \override Score.RehearsalMark #'break-align-symbols = #'(key-signature) + \mark "on key" + cis + \key ces \major + \override Score.RehearsalMark #'break-align-symbols = #'(clef) + \clef treble + \mark "on clef" + ces + \override Score.RehearsalMark #'break-align-symbols = #'(time-signature) + \key d \minor + \clef tenor + \time 3/4 + \mark "on time" + c +} +@end lilypond + +Possible symbols for the @code{break-align-symbols} list are +@code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos}, +@code{staff-bar}, @code{left-edge}, @code{key-cancellation}, +@code{key-signature}, and @code{time-signature}. + +The text marks will, by default, be aligned with the middle of the notation +object, but this can be changed by overriding the +@code{break-align-anchor-alignment} and +@code{break-align-anchor} properties for the appropriate grob. + +@lilypond[fragment,quote,ragged-right,verbatim] +{ + \override Score.RehearsalMark #'break-align-symbols = #'(key-signature) + c1 + \key cis \major + + % the RehearsalMark will be aligned with the left edge of the KeySignature + \once \override Staff.KeySignature #'break-align-anchor-alignment = #LEFT + \mark \default + cis1 + \key ces \major + + % the RehearsalMark will be aligned with the right edge of the KeySignature + \once \override Staff.KeySignature #'break-align-anchor-alignment = #RIGHT + \mark \default + ces1 + \key cis \major + + % the RehearsalMark will be aligned with the left edge of the KeySignature + % and then shifted right by 2 units. + \once \override Staff.KeySignature #'break-align-anchor = #2 + \mark \default + ces1 +} +@end lilypond + +Although text marks are normally only printed above the topmost +staff, you may alter this to print them on every staff, + +@lilypond[quote,ragged-right,verbatim,relative=2] +{ + \new Score \with { + \remove "Mark_engraver" + } + << + \new Staff \with { + \consists "Mark_engraver" + } + { c''1 \mark "foo" c'' } + \new Staff \with { + \consists "Mark_engraver" + } + { c'1 \mark "foo" c' } + >> +} +@end lilypond + + +@seealso + +Program reference: @internalsref{RehearsalMark}. + + + +@anchor{New dynamic marks} +@unnumberedsubsubsec New dynamic marks + +It is possible to print new dynamic marks or text that should be aligned +with dynamics. Use @code{make-dynamic-script} to create these +marks. Note that the dynamic font only contains the characters +@code{f,m,p,r,s} and @code{z}. + +Some situations (such as dynamic marks) have preset font-related +properties. If you are creating text in such situations, it +is advisable to cancel those properties with +@code{normal-text}. See @ref{Overview of text markup commands}, +for more details. + +@cindex make-dynamic-script + +@lilypond[quote,verbatim,ragged-right] +sfzp = #(make-dynamic-script "sfzp") +\relative c' { + c4 c c\sfzp c +} +@end lilypond + +@cindex Dynamics, editorial +@cindex Dynamics, parenthesis + +It is also possible to print dynamics in round parenthesis or square +brackets. These are often used for adding editorial dynamics. + +@lilypond[quote,verbatim,ragged-right] +rndf = \markup{ \center-align {\line { \bold{\italic (} + \dynamic f \bold{\italic )} }} } +boxf = \markup{ \bracket { \dynamic f } } +{ c'1_\rndf c'1_\boxf } +@end lilypond + + + +@node Text markup +@subsection Text markup + +@anchor{Text markup introduction} +@unnumberedsubsubsec Text markup introduction + +@cindex markup +@cindex text markup +@cindex markup text +@cindex typeset text + +Use @code{\markup} to typeset text. Commands are entered with the +backslash @code{\}. To enter @code{\} and @code{#}, use double +quotation marks. + +@lilypond[quote,verbatim,fragment,relative=1] +c1^\markup { hello } +c1_\markup { hi there } +c1^\markup { hi \bold there, is \italic {anyone home?} } +c1_\markup { "\special {weird} #characters" } +@end lilypond + +@noindent +See @ref{Overview of text markup commands}, for a list of all +commands. + +@code{\markup} is primarily used for @internalsref{TextScript}s, +but it can also be used anywhere text is called in lilypond + +@lilypond[quote,verbatim] +\header{ title = \markup{ \bold { foo \italic { bar! } } } } +\score{ + \relative c'' { + \override Score.RehearsalMark + #'break-visibility = #begin-of-line-invisible + \override Score.RehearsalMark #'self-alignment-X = #right + + \set Staff.instrumentName = \markup{ \column{ Alto solo } } + c2^\markup{ don't be \flat } + \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit } + b2\startTextSpan + a2\mark \markup{ \large \bold Fine } + r2\stopTextSpan + \bar "||" + } + \addlyrics { bar, foo \markup{ \italic bar! } } +} +@end lilypond + +A @code{\markup} command can also be placed on its own, away from any +@code{\score} block, see @ref{Multiple scores in a book}. + +@lilypond[quote,ragged-right,verbatim] +\markup{ Here is some text. } +@end lilypond + +@cindex font switching + +The markup in the example demonstrates font switching commands. The +command @code{\bold} and @code{\italic} apply to the first following +word only; to apply a command to more than one word, enclose the +words with braces, + +@example +\markup @{ \bold @{ hi there @} @} +@end example + +@noindent +For clarity, you can also do this for single arguments, e.g., + +@example +\markup @{ is \italic @{ anyone @} home @} +@end example + +In markup mode you can compose expressions, similar to mathematical +expressions, XML documents, and music expressions. You can stack +expressions grouped vertically with the command @code{\column}. +Similarly, @code{\center-align} aligns texts by their center lines: + +@lilypond[quote,verbatim,fragment,relative=1] +c1^\markup { \column { a bbbb \line { c d } } } +c1^\markup { \center-align { a bbbb c } } +c1^\markup { \line { a b c } } +@end lilypond + +Lists with no previous command are not kept distinct. The expression + +@example +\center-align @{ @{ a b @} @{ c d @} @} +@end example + +@noindent + +is equivalent to + +@example +\center-align @{ a b c d @} +@end example + +@noindent + +To keep lists of words distinct, please use quotes @code{"} or +the @code{\line} command + +@lilypond[quote,verbatim,fragment,relative=1] +\fatText +c4^\markup{ \center-align { on three lines } } +c4^\markup{ \center-align { "all one line" } } +c4^\markup{ \center-align { { on three lines } } } +c4^\markup{ \center-align { \line { on one line } } } +@end lilypond + +Markups can be stored in variables and these variables +may be attached to notes, like +@example +allegro = \markup @{ \bold \large @{ Allegro @} @} + @{ a^\allegro b c d @} +@end example + +Some objects have alignment procedures of their own, which cancel out +any effects of alignments applied to their markup arguments as a +whole. For example, the @internalsref{RehearsalMark} is horizontally +centered, so using @code{\mark \markup @{ \left-align .. @}} has no +effect. + +In addition, vertical placement is performed after creating the +text markup object. If you wish to move an entire piece of markup, +you need to use the #'padding property or create an @q{anchor} point +inside the markup (generally with @code{\hspace #0}). + +@lilypond[quote,verbatim,fragment,relative=1] +\fatText +c'4^\markup{ \raise #5 "not raised" } +\once \override TextScript #'padding = #3 +c'4^\markup{ raised } +c'4^\markup{ \hspace #0 \raise #1.5 raised } +@end lilypond + +Some situations (such as dynamic marks) have preset font-related +properties. If you are creating text in such situations, it +is advisable to cancel those properties with +@code{normal-text}. See @ref{Overview of text markup commands}, +for more details. + + +@seealso + +This manual: @ref{Overview of text markup commands}. + +Program reference: @internalsref{TextScript}. + +Init files: @file{scm/@/new@/-markup@/.scm}. + + +@refbugs + +Kerning or generation of ligatures is only done when the @TeX{} +backend is used. In this case, LilyPond does not account for them so +texts will be spaced slightly too wide. + +Syntax errors for markup mode are confusing. + + +@anchor{Nested scores} +@unnumberedsubsubsec Nested scores + +It is possible to nest music inside markups, by adding a @code{\score} +block to a markup expression. Such a score must contain a @code{\layout} +block. + +@lilypond[quote,verbatim,ragged-right] +\relative { + c4 d^\markup { + \score { + \relative { c4 d e f } + \layout { } + } + } + e f +} +@end lilypond + +@anchor{Page wrapping text} +@unnumberedsubsubsec Page wrapping text +Whereas @code{\markup} is used to enter a non-breakable block of text, +@code{\markuplines} can be used at top-level to enter lines of text that +can spread over multiple pages: + +@verbatim +\markuplines { + \justified-lines { + A very long text of justified lines. + ... + } + \justified-lines { + An other very long paragraph. + ... + } + ... +} +@end verbatim + +@code{\markuplines} accepts a list of markup, that is either the result +of a markup list command, or a list of markups or of markup lists. The +built-in markup list commands are described in +@ref{Overview of text markup list commands}. + +@seealso + +This manual: @ref{Overview of text markup list commands}, +@ref{New markup list command definition}. + +@refcommands + +@funindex \markuplines +@code{\markuplines} + +@anchor{Overview of text markup commands} +@unnumberedsubsubsec Overview of text markup commands + +The following commands can all be used inside @code{\markup @{ @}}. + +@include markup-commands.tely + +@anchor{Overview of text markup list commands} +@unnumberedsubsubsec Overview of text markup list commands + +The following commands can all be used with @code{\markuplines}. + +@include markup-list-commands.tely + +@anchor{Font selection} +@unnumberedsubsubsec Font selection + +@cindex font selection +@cindex font magnification +@funindex font-interface + +By setting the object properties described below, you can select a +font from the preconfigured font families. LilyPond has default +support for the feta music fonts. Text fonts are selected through +Pango/FontConfig. The serif font defaults to New Century Schoolbook, +the sans and typewriter to whatever the Pango installation defaults +to. + + +@itemize @bullet +@item @code{font-encoding} +is a symbol that sets layout of the glyphs. This should only be set to +select different types of non-text fonts, e.g. + +@code{fetaBraces} for piano staff braces, @code{fetaMusic} the +standard music font, including ancient glyphs, @code{fetaDynamic} for +dynamic signs and @code{fetaNumber} for the number font. + +@item @code{font-family} +is a symbol indicating the general class of the typeface. Supported are +@code{roman} (Computer Modern), @code{sans}, and @code{typewriter}. + +@item @code{font-shape} +is a symbol indicating the shape of the font. There are typically +several font shapes available for each font family. Choices are +@code{italic}, @code{caps}, and @code{upright}. + +@item @code{font-series} +is a symbol indicating the series of the font. There are typically +several font series for each font family and shape. Choices are +@code{medium} and @code{bold}. + +@end itemize + +Fonts selected in the way sketched above come from a predefined style +sheet. If you want to use a font from outside the style sheet, +then set the +@code{font-name} property, + +@lilypond[fragment,verbatim] +{ + \override Staff.TimeSignature #'font-name = #"Charter" + \override Staff.TimeSignature #'font-size = #2 + \time 3/4 + c'1_\markup { + \override #'(font-name . "Vera Bold") + { This text is in Vera Bold } + } +} +@end lilypond + +@noindent +Any font can be used, as long as it is available to Pango/FontConfig. +To get a full list of all available fonts, run the command +@example +lilypond -dshow-available-fonts blabla +@end example +(the last argument of the command can be anything, but has to be present). + + +The size of the font may be set with the @code{font-size} +property. The resulting size is taken relative to the +@code{text-font-size} as defined in the @code{\paper} block. + +@cindex font size +@cindex font magnification + + +It is also possible to change the default font family for the entire +document. This is done by calling the @code{make-pango-font-tree} from +within the @code{\paper} block. The function takes names for the font +families to use for roman, sans serif and monospaced text. For +example, + +@cindex font families, setting +@cindex Pango + + +@lilypond[verbatim] +\paper { + myStaffSize = #20 + + #(define fonts + (make-pango-font-tree "Times New Roman" + "Nimbus Sans" + "Luxi Mono" + (/ myStaffSize 20))) +} + +{ + c'^\markup { roman: foo \sans bla \typewriter bar } +} +@end lilypond + +@c we don't do Helvetica / Courier, since GS incorrectly loads +@c Apple TTF fonts + + + +@seealso + +Examples: @lsr{text,font@/-family@/-override.ly}. + + + +