@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
@c A menu is needed before every deeper *section nesting of @node's; run
@c M-x texinfo-all-menus-update
your scores.
@cindex Text, other languages
-To write non-ascii text (such as characters from other languages), simply
+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}.
@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
@cindex text items, non-empty
@cindex non-empty texts
-It is possible to place arbitrary strings of text or @ref{Text markup}
+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
Program reference: @internalsref{TextScript}.
+@node Text and line spanners
+@subsection 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}
+
+
@node Text spanners
@subsection Text spanners
@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
c1
\textSpannerDown
-\override TextSpanner #'edge-text = #'("rall " . "")
+\override TextSpanner #'bound-details #'left #'text =
+ \markup { \upright "rall" }
c2\startTextSpan b c\stopTextSpan a
\break
\textSpannerUp
-\override TextSpanner #'edge-text = #(cons (markup #:italic "rit" ) "")
+\override TextSpanner #'bound-details #'left #'text =
+ \markup { \italic "rit" }
c2\startTextSpan b c\stopTextSpan a
@end lilypond
@refcommands
-@cindex textSpannerUp
-@code{textSpannerUp},
-@cindex textSpannerDown
-@code{textSpannerDown},
-@cindex textSpannerNeutral
-@code{textSpannerNeutral}.
+@funindex textSpannerUp
+@code{\textSpannerUp},
+@funindex textSpannerDown
+@code{\textSpannerDown},
+@funindex textSpannerNeutral
+@code{\textSpannerNeutral}.
@commonprop
Program reference: @internalsref{TextSpanner}.
-Examples: @inputfileref{input/@/regression,text@/-spanner@/.ly}.
-
@node Text marks
@subsection Text 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})
+@ref{The Feta font}).
@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
c1 \mark \markup { \musicglyph #"scripts.ufermata" }
@end lilypond
@noindent
-See @ref{Overview of text markup commands} for a list of all
+See @ref{Overview of text markup commands}, for a list of all
commands.
@code{\markup} is primarily used for @internalsref{TextScript}s,
\set Staff.instrumentName = \markup{ \column{ Alto solo } }
c2^\markup{ don't be \flat }
- \override TextSpanner #'edge-text = #(cons (markup #:italic "rit" ) "")
+ \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
b2\startTextSpan
a2\mark \markup{ \large \bold Fine }
r2\stopTextSpan
In addition, vertical placement is performed after creating the
text markup object. If you wish to move an entire piece of markup,
-you need to use the #'padding property or create an "anchor" point
+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]
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}
+@code{normal-text}. See @ref{Overview of text markup commands},
for more details.
}
@end lilypond
+@node Page wrapping text
+@subsection 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}
@node Overview of text markup commands
@subsection Overview of text markup commands
@include markup-commands.tely
+@node Overview of text markup list commands
+@subsection Overview of text markup list commands
+
+The following commands can all be used with @code{\markuplines}.
+
+@include markup-list-commands.tely
@node Font selection
@subsection Font selection
@seealso
-Examples: @inputfileref{input/@/regression,font@/-family@/-override.ly}.
+Examples: @lsr{text,font@/-family@/-override.ly}.
@node New dynamic marks
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}
+@code{normal-text}. See @ref{Overview of text markup commands},
for more details.
@cindex make-dynamic-script
@cindex whole rests for a full measure
@funindex R
-Rests for one full measure (or many bars) are entered using `@code{R}'. It
+Rests for one full measure (or many bars) are entered using @samp{R}. It
is specifically meant for full bar rests and for entering parts: the rest
can expand to fill a score with rests, or it can be printed as a single
multi-measure rest. This expansion is controlled by the property
An @code{R} spanning a single measure is printed as either a whole rest
or a breve, centered in the measure regardless of the time signature.
-If there are only a few measures of rest, LilyPond prints ``church rests''
+If there are only a few measures of rest, LilyPond prints @q{church rests}
(a series of rectangles) in the staff. To replace that with a simple
rest, use @code{MultiMeasureRest.expand-limit}.
@end lilypond
@noindent
-See @ref{Text markup} for more details.
+See @ref{Text markup}, for more details.
@seealso
@end lilypond
@noindent
-The letter@tie{}`I' is skipped in accordance with engraving traditions.
-If you wish to include the letter `I', then use
+The letter@tie{}@q{I} is skipped in accordance with engraving traditions.
+If you wish to include the letter @q{I}, then use
@example
\set Score.markFormatter = #format-mark-alphabet
@end lilypond
@noindent
-See @ref{The Feta font} for a list of symbols which may be
+See @ref{The Feta font}, for a list of symbols which may be
printed with @code{\musicglyph}.
The horizontal location of rehearsal marks can be adjusted by
@code{format-mark-letters}. They can be used as inspiration for other
formatting functions.
-Examples: @inputfileref{input/@/regression,rehearsal@/-mark@/-letter@/.ly},
-
-@inputfileref{input/@/regression,rehearsal@/-mark@/-number@/.ly}.
+Examples: @lsr{parts,rehearsal-mark-numbers.ly}
@node Bar numbers
Bar numbers can be typeset at regular intervals instead of at the
beginning of each line. This is illustrated in the following example,
whose source is available as
-@inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}
+@lsr{staff,making-bar-numbers-appear-at-regular-intervals.ly}.
@lilypondfile[ragged-right,quote]{bar-number-regular-interval.ly}
Program reference: @internalsref{BarNumber}.
-Examples:
-@inputfileref{input/@/test,bar@/-number@/-every@/-five@/-reset@/.ly},
-and @inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}.
+Examples: @lsrdir{staff}
@refbugs
@node Ottava brackets
@subsection Ottava brackets
-`Ottava' brackets introduce an extra transposition of an octave for
+@q{Ottava} brackets introduce an extra transposition of an octave for
the staff. They are created by invoking the function
@code{set-octavation}
Program reference: @internalsref{OttavaBracket}.
-Examples: @inputfileref{input/@/regression,ottava@/.ly},
-@inputfileref{input/@/regression,ottava@/-broken@/.ly}.
-
@refbugs
@seealso
-Examples: @inputfileref{input/@/regression,tag@/-filter@/.ly}.
+Examples: @lsr{parts,tag@/-filter@/.ly}
@refbugs
specified twice (once in each part). Stem, slur, and tie directions are
set automatically, depending whether there is a solo or unisono. The
first part (with context called @code{one}) always gets up stems, and
-`Solo', while the second (called @code{two}) always gets down stems and
-`Solo II'.
+@q{Solo}, while the second (called @code{two}) always gets down stems and
+@q{Solo II}.
If you just want the merging parts, and not the textual markings, you
may set the property @code{printPartCombineTexts} to false
@cindex Hiding staves
In orchestral scores, staff lines that only have rests are usually
-removed; this saves some space. This style is called `French Score'.
+removed; this saves some space. This style is called @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
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.
+quotable. This is done with the @code{\addQuote} command.
@example
-\addquote @var{name} @var{music}
+\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}
+of music. Here is an example of @code{\addQuote}
@example
-\addquote clarinet \relative c' @{
+\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
+After calling @code{\addQuote}, the quotation may then be done with
@code{\quoteDuring} or @code{\cueDuring},
@example
More precisely, it takes the current time-step of the part being
printed, and extracts the notes at the corresponding point of the
-@code{\addquote}d voice. Therefore, the argument to @code{\addquote}
+@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.
instruments, if they are specified using the @code{\transposition} command.
@lilypond[quote,ragged-right,verbatim]
-\addquote clarinet \relative c' {
+\addQuote clarinet \relative c' {
\transposition bes
f4 fis g gis
}
@refbugs
Only the contents of the first @internalsref{Voice} occurring in an
-@code{\addquote} command will be considered for quotation, so
+@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: @inputfileref{input/@/regression,quote@/.ly}
-@inputfileref{input/@/regression,quote@/-transposition@/.ly}
+Examples: @lsr{parts,quote.ly}, @lsr{parts,quote-transportation.ly}
Program reference: @internalsref{QuoteMusic}.
\override Beam #'length-fraction = #0.8
}
-\addquote clarinet \relative {
+\addQuote clarinet \relative {
R1*20
- r2 r8 c f f
+ r2 r8 c' f f
}
\new Staff \relative <<
- % setup a context for cue notes.
+ % setup a context for cue notes.
\new Voice = "cue" { \smaller \skip 1*21 }
\set Score.skipBars = ##t
\new Voice {
R1*20
- \cueDuring #"clarinet" #1 {
+ \cueDuring #"clarinet" #UP {
R1
}
g4 g2.
c8 c c e g2 |
a4 g g2 |
}
-\addquote "picc" { \picc }
+\addQuote "picc" { \picc }
cbsn = \relative c, {
\clef "bass_8"
In the 20th century, composers have greatly expanded the musical
vocabulary. With this expansion, many innovations in musical notation
-have been tried. The book ``Music Notation in the 20th century'' by
+have been tried. The book @q{Music Notation in the 20th century} by
Kurt Stone gives a comprehensive overview (see @ref{Literature
list}).
@menu
* Polymetric notation::
* Time administration::
-* Proportional notation::
+* Proportional notation (introduction)::
* Clusters::
* Special noteheads::
* Feathered beams::
@node Polymetric notation
@subsection Polymetric notation
+@cindex double time signatures
+@cindex signatures, polymetric
+@cindex polymetric signatures
+@cindex meter, polymetric
+
Double time signatures are not supported explicitly, but they can be
faked. In the next example, the markup for the time signature is
created with a markup text. This markup text is inserted in the
@internalsref{TimeSignature} grob. See also
-@inputfileref{input/@/test,compound@/-time@/.ly}).
+@lsr{contemporary,compound-time-signature}.
@lilypond[verbatim,ragged-right]
% create 2/4 + 5/8
tsMarkup =\markup {
\override #'(baseline-skip . 2) \number {
\column { "2" "4" }
- \lower #1 "+"
+ \vcenter "+"
\bracket \column { "5" "8" }
}
}
seven sixteenths notes.
-@node Proportional notation
-@subsection Proportional notation
+@node Proportional notation (introduction)
+@subsection Proportional notation (introduction)
@cindex Proportional notation
+See @ref{Proportional notation}.
+
+
+TODO: remove all this stuff?
+
Notes can be spaced proportionally to their time-difference by
assigning a duration to @code{proportionalNotationDuration}
@seealso
-@inputfileref{input/@/regression,spacing-proportional/.ly}
-@inputfileref{input/@/regression,spacing-strict-notespacing/.ly}
-@inputfileref{input/@/regression,spacing-strict-spacing-grace/.ly}
+Examples: @lsr{spacing,proportional@/-spacing@/.ly},
+@lsr{spacing,proportional@/-strict@/-grace@/-notes@/.ly}, and
+@lsr{spacing,proportional@/-strict@/-notespacing@/.ly}
An example of strict proportional notation is in the
example file @file{input/proportional.ly}.
\makeClusters { <c e > <b f'> }
@end lilypond
-The following example (from
-@inputfileref{input/@/regression,cluster@/.ly}) shows what the result
-looks like
-
-@lilypondfile[ragged-right,quote]{cluster.ly}
-
Ordinary notes and clusters can be put together in the same staff,
even simultaneously. In such a case no attempt is made to
automatically avoid collisions between ordinary notes and clusters.
@internalsref{ClusterSpannerBeacon},
@internalsref{Cluster_spanner_engraver}.
-Examples: @inputfileref{input/@/regression,cluster@/.ly}.
+Examples: @lsr{contemporary,cluster@/.ly}.
@refbugs
@cindex note heads, special
Different noteheads are used by various instruments for various
-meanings -- crosses are used for ``parlato'' with vocalists, stopped
+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
@noindent
To see all notehead styles, please see
-@inputfileref{input/@/regression,note@/-head@/-style@/.ly}.
+@ref{Note head styles}.
@seealso
Improvisation is sometimes denoted with slashed note heads. Such note
heads can be created by adding a @internalsref{Pitch_squash_engraver}
-to the @internalsref{Staff} or @internalsref{Voice} context. Then, the
+to the @internalsref{Voice} context. Then, the
following command
@example
the following example
@lilypond[verbatim,ragged-right,quote]
-\new Staff \with {
+\new Voice \with {
\consists Pitch_squash_engraver
} \transpose c c' {
e8 e g a a16(bes)(a8) g \improvisationOn
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.
+@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
Program reference: @internalsref{text-balloon-interface}.
-Examples: @inputfileref{input/@/regression,balloon@/.ly}.
-
@cindex easy notation
@cindex Hal Leonard
-The `easy play' note head includes a note name inside the head. It is
+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]
Program reference: @internalsref{HorizontalBracket}.
-Examples: @inputfileref{input/@/regression,note@/-group@/-bracket@/.ly}.
-
@node Coloring objects
@subsection Coloring objects
named normal color.
Notes in a chord cannot be colored with @code{\override}; use
-@code{\tweak} instead. See @ref{Objects connected to the input}
+@code{\tweak} instead. See @ref{Objects connected to the input},
for details.
Vertical lines can be drawn between staves synchronized with
the notes.
-Examples: @inputfileref{input/@/regression,grid@/-lines@/.ly}.
+@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}
+