@c before saving changes
-@ignore
- TODO:
-
- fix all FIXMEs
-
- Rhythm staff (clef, x-notehead)
-
-@end ignore
-
-
@macro refbugs
@unnumberedsubsec Bugs
+
@end macro
@chapter Reference Manual
This document describes GNU LilyPond and its input format. The last
-revision of this document was for LilyPond 1.3.136.
+revision of this document was for LilyPond 1.3.138.
@menu
* Expressive marks::
* Ornaments::
* Repeats::
+* Rhythmic music::
* Piano music::
* Lyrics::
* Chords::
* Notes::
* Easy Notation note heads ::
* Tie::
+* Tuplets::
* Rests::
* Skip::
* Note mode::
@end lilypond
If you dislike the amount of ties created for a chord, you set
-@code{Thread.sparseTies} to true, resulting in a smaller number of
+@code{Voice.sparseTies} to true, resulting in a smaller number of
ties:
@lilypond[fragment,verbatim,center]
- \property Thread.sparseTies = ##t
+ \property Voice.sparseTies = ##t
<c' e' g'> ~ <c' e' g'>
@end lilypond
context and turning off ties per Thread.
-@c . {Tuplets}
-@menu
-* Tuplets::
-@end menu
-
@node Tuplets
-@subsubsection Tuplets
-@cindex Tuplets
-@cindex Times
+@subsection Tuplets
+
+@cindex tuplets
+@cindex triplets
+@cindex @code{\times}
Tuplets are made out of a music expression by multiplying their duration
with a fraction.
g'4 \times 2/3 {c'4 c' c'} d'4 d'4
@end lilypond
-[todo: document tupletSpannerDuration]
-
-
+The property @code{tupletSpannerDuration} specifies how long brackets
+should last. With this, you can make lots of tuplets while typing
+@code{\times} only once. This saves typing work when you must make lots
+of tuplets.
+@lilypond[fragment, relative, singleline, verbatim]
+\property Voice.tupletSpannerDuration = #(make-moment 1 4)
+\times 2/3 { c''8 c c c c c }
+@end lilypond
@c . {Rests}
@node Rests
@menu
* Key signature::
+* Clef::
* Time signature::
+* Unmetered music::
* Bar lines::
@end menu
@cindex @code{keySignature}
@c . {Clef}
-@subsection Clef changes
+@node Clef
+@subsection Clef
@cindex @code{\clef}
@example
\clef @var{clefname} @code{;}
@end example
-Short-cut for
+Shortcut for
@example
\property Staff.clefGlyph = @var{glyph associated with clefname}
@example
\time @var{numerator}@code{/}@var{denominator} @code{;}
@end example
-Internally, this is a short-cut for doing
+Internally, this is a shortcut for doing
@example
\property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
@end example
[TODO: discuss options for layout]
@c . {Partial}
-@subsubsection Partial
+@subsection Partial
@cindex Partial
@cindex anacrusis
@cindex upstep
\partial @var{duration} @code{;}
@end example
-Internally, this is a short cut for
+Internally, this is a shortcut for
@example
\property Score.measurePosition = -@var{length of duration}
@end example
@cindex @code{|}
+
+@node Unmetered music
+@subsection Unmetered music
+
+Bar lines and bar numbers are calculated automatically. For unmetered
+music (e.g. cadenzas), this is not desirable. The property
+@code{Score.timing} can be used to switch off this automatic timing
+
+@lilypond[fragment,relative,singleline,verbatim]
+c'2.
+\property Score.timing = ##f
+c4 c4 c4
+\property Score.timing = ##t
+c4 c4 c4
+@end lilypond
+
+The identifiers @code{\cadenzaOn} and @code{\cadenzaOff} can be used to
+achieve the same effect.
+
+
+
@c . {Bar lines}
@node Bar lines
@subsection Bar lines
\bar @var{bartype};
@end example
-This is a short-cut for doing
+This is a shortcut for doing
@example
\property Score.whichBar = @var{bartype}
@end example
@cindex Polyphony
[TODO: collisions, rest-collisinos, voiceX identifiers, how to
-which contexts to instantiate.]
+which contexts to instantiate. some small examples? ]
@table @code
@code{\slurBoth},
@code{\slurDown},
@code{\slurUp}.
-@cindex @code{\slurBoth}
-@cindex @code{\slurDown}
-@cindex @code{\slurUp}
-Aand for ties use
+
+@cindex @code{\tieBoth}
+@cindex @code{\tieDown}
+@cindex @code{\tieUp}
+For ties use
@code{\tieBoth},
@code{\tieDown},
@code{\tieUp}.
+@cindex @code{\dynacmicBoth}
+@cindex @code{\dynamicDown}
+@cindex @code{\dynamicUp}
+For dynamics use
+@code{\dynamicBoth},
+@code{\dynamicDown},
+@code{\dynamicUp}.
+
+@c text scripts? articulation scripts? fingering?
+
+@cindex @code{\voiceOne}
+@cindex @code{\voiceTwo}
+@cindex @code{\voiceThree}
+@cindex @code{\voiceFour}
+@cindex @code{\oneVoice}
+@cindex @code{\shiftOn}
+@cindex @code{\shiftOff}
+
+If two voices sharing one staff have the same stem directions, their
+note heads may collide. You can shift the note heads of one voice by
+setting @code{\shiftOn}. This can be undone by setting
+@code{\shiftOff}.
+
+For simple polyphonic music, shorthands are available that combine
+directions and shift settings: @code{\voiceOne}, @code{\voiceTwo},
+@code{\voiceThree}, @code{\voiceFour} and @code{\oneVoice}.
+
@node Beaming
@section Beaming
@c . {Manual beams}
@cindex Automatic beams
-@subsubsection Manual beams
+@subsection Manual beams
@cindex beams, manual
@cindex @code{]}
@cindex @code{[}
@end quotation
@cindex @code{stemRightBeamCount}
+The beam symbol can be tweaked through @code{Voice.Beam}'s
+grob-properties @code{height} and @code{staff-position},
+in staff-spaces.
+
+Set @code{height} to zero, to get horizontal beams:
+
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \property Voice.Beam \set #'direction = #1
+ \property Voice.Beam \set #'height = #0
+ [a''8 e' d c]
+@end lilypond
+@end quotation
-[FIXME: explain common tweaks.]
+Here's how you'd specify a weird looking beam that instead of being
+horizontal, falls two staff spaces:
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \property Voice.Beam \set #'staff-position = #2
+ \property Voice.Beam \set #'height = #-2
+ [c'8 c]
+@end lilypond
+@end quotation
+@cindex @code{default-neutral-direction}
@node Expressive marks
@section Expressive marks
* Slur ::
* Phrasing slur::
* Breath marks::
+* Tempo::
+* Text spanner::
@end menu
@node Slur
stem end. If you want to override this layout you can do this through
@code{Voice.Slur}'s grob-property @code{attachment}:
-[TODO: remove this section]
Maybe reinclude other slur features and move back to tricks? Esp. the
second example, how to fix, can be very helpful.
Similarly, the curvature of a slur is adjusted to stay clear of note
heads and stems. When that would increase the curvature too much, the
slur is reverted to its default shape. The threshold for this decision
-is in @code{Voice.Slur}'s grob-property @code{beautiful}. In some
-cases, you may prefer curved slurs to vertically moved ones. You can
+is in @code{Voice.Slur}'s grob-property @code{beautiful}. It is loosely
+related to the enclosed area between the slur and the notes. Usually,
+the default setting works well, but in some cases you may prefer a
+curved slur when LilyPond decides for a vertically moved one. You can
express this by increasing the @code{beautiful} value:
-[hoe gedefd?? wat betekent beautiful = X?]
+@lilypond[verbatim,singleline,relative]
+ \property Voice.Beam \override #'direction = #-1
+ \property Voice.Slur \override #'direction = #1
+ c'16( a' f' a a f a, )c,
+ c( a' f' a a f d, )c
+ \property Voice.Slur \override #'beautiful = #5.0
+ c( a' f' a a f d, )c
+@end lilypond
-[dit voorbeeld is te lang: junken, of inkorten]
+@refbugs
-@quotation
-@lilypond[verbatim,singleline]
-\score {
- \notes \context PianoStaff <
- \time 6/4;
- \context Staff=up { s1 * 6/4 }
- \context Staff=down <
- \clef bass;
- \autochange Staff \context Voice
- \notes \relative c {
- d,8( a' d f a d f d a f d )a
- }
- >
- >
- \paper {
- \translator {
- \VoiceContext
- Slur \override #'beautiful = #5.0
- Slur \override #'direction = #1
- Stem \override #'direction = #-1
- autoBeamSettings \override #'(end * * * *)
- = #(make-moment 1 2)
- }
- \translator {
- \PianoStaffContext
- VerticalAlignment \override #'threshold = #'(5 . 5)
- }
- }
-}
-@end lilypond
-@end quotation
+The definition for @code{beautiful} is vague, the default setting is
+experimental computer science.
@cindex Adusting slurs
-
-@c . {Text spanner}
-@menu
-* Text spanner::
-@end menu
-
@node Text spanner
-@subsubsection Text spanner
+@subsection Text spanner
@cindex Text spanner
Some textual indications, e.g. rallentando, accelerando, often extend
influence, spacing, but setting @code{Voice.textNonEmpty} to true will
take the widths into account. The identifier @code{\fattext} is defined
in the standard includes.
-@lilypond[fragment,singleline]
+@lilypond[fragment,singleline,verbatim]
\relative c' { c4^"longtext" \fatText c4_"longlongtext" c4 }
@end lilypond
@lilypond[fragment,verbatim]
\relative c'' {
\grace c8 c4 \grace { [c16 c16] } c4
- \grace { \property Grace.Stem \override #'flag-style = ##f c16 } c4
+ \grace { \property Grace.Stem \override #'flag-style = #'() c16 } c4
}
@end lilypond
At present, only repeats of whole measures are supported.
+@node Rhythmic music
+@section Rhythmic music
+
+
+@menu
+* Rhythmic staffs::
+@end menu
+
+@node Rhythmic staffs
+@subsection Rhythmic staffs
+
+Some times you might want to show only the rhythm of a melody. This can
+be done with the rhythmic staff. All pitches of notes on such a staff
+are squashed, and the staff itself looks has a single staff line:
+
+@lilypond[fragment,relative ]
+ \context RhythmicStaff {
+ \time 4/4;
+ c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
+ }
+@end lilypond
+
+
@c . {Piano music}
@node Piano music
@section Piano music
* Manual staff switches::
* Pedals::
* Arpeggio::
-* Follow Thread::
+* VoiceFollower::
@end menu
connected arpeggios and unconnected arpeggios at the same time.
-@c . {Follow Thread}
-@node Follow Thread
-@subsection Follow Thread
+@c . {VoiceFollower}
+@node VoiceFollower
+@subsection VoiceFollower
-@cindex follow thread
+@cindex follow voice
@cindex staff switching
@cindex cross staff
-[todo: figure out different name, eg. voice line, switch indicator ? ]
-
-@cindex @code{followThread}
+@cindex @code{followVoice}
Whenever a voice switches to another staff a line connecting the notes
can be printed automatically. This is enabled if the property
-@code{PianoStaff.followThread} is set to true:
+@code{PianoStaff.followVoice} is set to true:
@quotation
@lilypond[fragment,relative,verbatim]
\context PianoStaff <
- \property PianoStaff.followThread = ##t
+ \property PianoStaff.followVoice = ##t
\context Staff \context Voice {
c'1
\translator Staff=two
staff in an intelligent way. It is aimed primarily at typesetting Hymns
and orchestral scores. When the two parts are identical for a period of
time, only one is shown. In places where the two parts differ, stem
-directions are set automatically. Also, soli and @`{a} due parts can be
+directions are set automatically. Also, soli and @emph{a due} parts can be
identified and marke.
The syntax for part combining is
@lilypond[verbatim,singleline,fragment]
\context Staff <
\context Voice=one \partcombine Voice
- \context Thread=one \notes\relative c'' {
- g g a b r2
+ \context Thread=one \relative c'' {
+ g a b r
}
- \context Thread=two \notes\relative c'' {
- g g r2 g4 f4
+ \context Thread=two \relative c'' {
+ g r2 f4
}
>
@end lilypond
Notice that the first @code{g} appears only once, although it was
specified twice (once in each Thread). Also note that stem, slur and tie
directions are set automatically, depending whether there is a solo or
-unisono.
-
-There is actually a third engraver involved in part combining; the
-@code{Voice_devnull_engraver}. This one takes care of removing
-redundant spanners such as beams, slurs, ties, crescendi, etc. Note that
-the Thread called one always gets up stems, and "solo", while @code{two}
-always gets down stems and "Solo II".
+unisono. The Thread called @code{one} always gets up stems, and "solo",
+while @code{two} always gets down stems and "Solo II".
If you just want the splitting of Threads and setting of directions, and
not the textual markings, you may set the property @var{soloADue} to
-false. There are a number of other properties that you can use to tweak
+false. This mode can be used to set hymns:
+
+@lilypond[verbatim,singleline,fragment]
+ \context Staff <
+ \property Staff.soloADue = ##f
+ \context Voice=one \partcombine Voice
+ \context Thread=one \relative c'' {
+ b4 a c g
+ }
+ \context Thread=two \relative c'' {
+ d,2 a4 g'
+ }
+ >
+@end lilypond
+
+There are a number of other properties that you can use to tweak
the behavior of part combining, refer to the automatically generated
documentation. Look for @code{Thread_devnull_engraver}
-@code{Voice_engraver} and @code{A2_engraver}.
+@code{Voice_devnull_engraver} and @code{A2_engraver}.
@cindex @code{Thread_devnull_engraver}
@cindex @code{Voice_engraver}
@node Hara-kiri staffs
@subsection Hara-kiri staffs
+In orchestral scores, staffs that only have rests are usually removed.
+This saves some space. LilyPond also supports this through the
+hara-kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide
+of the Japanese Samourai warriors.} staff. This staff commits suicide
+when it finds itself to be empty after the line-breaking process---note
+that it will not disappear when it contains normal rests, you must use
+multi measure rests.
+
+The hara kiri staff is specialized version of the Staff context. It is
+available as the context identifier @code{\HaraKiriStaffContext}.
+Observe how the second staff in this example disappears in the second
+line.
-[TODO]@footnote{Harakiri, also called Seppuku, is the ritual suicide of
-the Japanese Samourai warriors.}
+@lilypond[verbatim]
+\score {
+ \notes \relative c' <
+ \context Staff = SA { e4 f g a \break c1 }
+ \context Staff = SB { c4 d e f \break R1 }
+ >
+ \paper {
+ linewidth = 6.\cm ;
+ \translator { \HaraKiriStaffContext }
+ }
+}
+@end lilypond
direction, length and thickness.
-
The most common way of tuning the output is to alter the values of these
-properties. There are two ways of doing that: first, you can
-specifically select a set of grobs at one point, and set properties as
-you wish, or secondly, you can (temporarily) modify the definition of a
-grob, thereby affecting an entire group of grobs.
-
-[Todo: onduidelijk]
+properties. There are two ways of doing that: first, you can temporarily
+change the definition of a certain type of grob, thus affecting a whole
+set of objects. Second, you can select one specific object, and set a
+grob property.
@menu
* Tuning groups of grobs ::
* Tuning per grob ::
* What to tune?::
+* Font selection::
* Text markup::
@end menu
overview of the context, listing which grob types are created there.
+@node Font selection
+@subsection Font selection
+
+Most graphics in LilyPond are composed of characters of fonts. You can
+alter the characteristics of the font by setting certain grob
+properties. The mechanism that is used for this resembles LaTeX's New
+Font Selection Scheme. Within this scheme, a font is entirely
+characterized by its font name.
+
+For each grob that uses fonts (in other words, each grob that supports
+@code{font-interface}) a font-name must be selected before it can be
+printed. The font name is selected by looking at a number of grob
+properties:
+
+@table @code
+@item font-family
+ The general class of the typeface. Supported are roman (Computer
+Modern), braces (for piano staff braces), music (the standard music
+font), dynamic (font for dynamic signs) and typewriter
+
+@item font-shape
+ A symbol indicating the shape of the font, a finer gradation than
+ font-family. Choices are italic and upright
+@item font-series
+ Symbol indicating the serie of the font. Series form a finer gradation
+ than font-shape. Choices are medium and bold.
+
+@item font-relative-size
+ A number indicating the size relative the standard size. For example,
+ with 20pt staff height, relative size -1 corresponds to 16pt staff
+ height, and relative size +1 corresponds to 23 pt staff height.
+
+@item font-design-size
+A number indicating the design size of the font.
+
+This is a feature of the Computer Modern Font: each point size has a
+slightly different design. Smaller design sizes are relatively wider,
+which enhances readability. Scalable type faces such TrueType and Adobe
+Type1 usually come as ``one design fits all sizes''.
+
+@item font-name
+ The name of the font, without the design size, eg. @code{cmr},
+@code{cmti}, etc. Setting this overrides font-family, font-shape and
+font-series.
+
+@end table
+
+The font is selected by taking the first font that satisfies all
+qualifiers specified. You can override any of these fields through
+@code{\override} and @code{\revert}. The special value @code{*} matches
+any value for that qualifier.
+
+@example
+ \property Lyrics.LyricText \override #'font-series = #'bold
+ \property Lyrics.LyricText \override #'font-shape = #'*
+@end example
+
+@cindex @code{font-style}
+
+There are also pre-cooked font selection qualifiers. These are selected
+through the grob property @code{font-style}. For example, the style
+@code{finger} selects family @code{number} and relative size @code{-3}.
+Styles available include: volta, finger, tuplet, timesig, mmrest,
+script, large, Large and dynamic.
+
+The style sheets and tables for selecting fonts are located in
+@file{scm/font.scm}. Refer to this file for more information.
+
+@refbugs
+
+Relative size is not linked to any real size. There is no mechanism to
+select magnifications of fonts, meaning that you can not scale fonts
+continuoussly. There is no style sheet provided for other fonts besides
+the @TeX{} family.
+
+@cindex font selection
+@cindex font magnification
+@cindex @code{font-interface}
+
+@refbugs
+
@node Text markup
@subsection Text markup
form text markup expressions by composing scheme expressions
in the following way.
-
-[BUG]
-
@lilypond[verbatim, singleline]
\relative c' {
- b_#"italic"
- c^#'(upright "upright")
- c_#'((bold upright) "bold")
- d^#'(lines "one" ((bold upright) "two"))
- e_#'(music (named "noteheads-2" "flags-u3"))
+ \fatText
+ a^#"upright"
+ b_#'(bold "bold")
+ c^#'(italic "italic")
+ d_#'((bold italic) "ff")
+ e^#'(dynamic "ff")
+ f_#'(lines "one" (bold "two"))
+ g^#'(music "noteheads-2" "flags-u3")
}
@end lilypond
@example
text: string | (head? text+)
head: markup | (markup+)
-markup-item: property | abbrev | @var{fontstyle}
+markup-item: property | abbrev
property: (@var{key} . @var{value})
abbrev: @code{rows lines roman music bold italic named super sub text}
+ @code{finger volta timesig mmrest mark script large Large dynamic}
@end example
The markup is broken down and converted into a list of grob properties,
which are prepended to the property list. The @var{key}-@var{value}
pair is a grob property.
-The following abbreviations are currently
-defined:
+The following abbreviations are currently defined:
@table @code
@item rows
superscript
@item sub
subscript
+@item finger
+ select fingering number fontstyle
+@item volta
+ select volta number fontstyle
+@item timesig
+ select time signature number fontstyle
+@item mmrest
+ select multi measure rest number fontstyle
+@item mark
+ select mark number fontstyle
+@item script
+ select scriptsize roman fontstyle
+@item large
+ select large roman fontstyle
+@item Large
+ select Large roman fontstyle
+@item dynamic
+ select dynamics fontstyle
@end table
-@var{fontstyle} may be any of @code{finger volta timesig mmrest mark
-script large Large dynamic}
-
-[wat is het verschil tussen fontstyle en abbrev?]
-
-
It is possible to use @TeX{} commands in the strings, but this should be
avoided because this makes it impossible for LilyPond to compute the
exact length of the string, which may lead to collisions. Also, @TeX{}
@end example
See @file{scm/font.scm} for details of @var{alist}.
-@item an \elementdescriptions declaration.
+ @item an \elementdescriptions declaration.
@example
\elementdescriptions @var{alist}
@end example
interesting effects, such as swing, articulation, slurring, tieing,
etc., but it is good enough for proof-hearing the music you enter.
-Dynamics and tempo changes are interpreted. [TODO: mention volume
-control/Instrument Equaliser]
+Dynamics and tempo changes are interpreted.
+
+[TODO: mention volume control/Instrument Equaliser]
@refbugs
The MIDI instrument name is set by the @code{Staff.midiInstrument}
property or, if that property is not set, the @code{Staff.instrument}
property. The instrument name should be chosen from the list in
-@ref{MIDI Instrument}.
+@ref{MIDI instruments}.
@refbugs
* Point and click::
@end menu
-
+One of the applications of LilyPond is to enter music from existing
+written or printed material. When you're doing this kind of copying
+work, you can easily make mistakes. This section deals with tricks and
+features that help you enter music, and find and correct mistakes.
@c . {Relative}
@node Relative
@code{fisis} following a @code{ceses} will be put above the
@code{ceses}.
-Entering scales is straightforward in relative mode.
-
-@lilypond[fragment,verbatim,center]
+Entering music that changes octave frequently is easy in relative mode.
+@lilypond[fragment,singleline,verbatim,center]
\relative c'' {
- g a b c d e f g g, g
+ b c d c b c bes a
}
@end lilypond
And octave changing marks are used for intervals greater than a fourth.
-
@lilypond[fragment,verbatim,center]
\relative c'' {
c g c f, c' a, e'' }
@node Point and click
@subsection Point and click
-[todo]
+Point and click lets you find notes in the input by clicking on them in
+the Xdvi window. This makes it very easy to find input that causes some
+error in the sheet music.
+
+To use it, you need the following software
+
+@itemize
+@item
+@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain
+Xdvi} version 22.36 or newer.
+
+ Note that most @TeX{} distributions ship with xdvik, which is a
+ different and less well maintained program. To find out which xdvi you
+ are running, try @code{xdvi --version} or @code{xdvi.bin --version}.
+@item emacs
+@end itemize
+
+
+Add one these lines to the top of your .ly file. The first one is for
+line location only. The second one is more convenient, but requires
+patching @code{emacsclient}.
+
+@example
+#(set! point-and-click line-location)
+#(set! point-and-click line-column-location)
+@end example
+
+In the emacs startup file (usually @file{~/.emacs}), add the following
+@example
+(server-start)
+@end example
+
+If you want emacs to jump to the exact spot (and not just the line) on a
+click, you must enable column positioning. To do so, you need to patch
+emacsclient. Apply @file{emacsclient.patch} (included with the source
+package) to @file{emacsclient.c} and @file{server.el} from the emacs
+source code. Recompile and stick the recompiled emacsclient into a bin
+directory, and put @file{server.el} into a elisp directory
+(eg. @file{~/usr/share/emacs/}). Add the following to your @file{.emacs}
+init file, before invoking server-start.
+
+@example
+ (setq load-path (cons "~/usr/share/emacs" load-path))
+@end example
+
+
+Xdvi must be configured to use the emacs editor. Before starting, set
+the environment variable @code{XEDITOR} to
+@example
+emacsclient --no-wait +%c:%l %f
+@end example
+Xdvi also must be configured to find the fonts. Refer to the
+xdvi documentation for more information.
+
+When viewing, control-mousebutton 1 will take you to the originating
+line and column. Control-mousebutton 2 will show all clickable boxes.
+
+@refbugs
+
+When you convert the TeX file to PostScript using dvips, dvips
+will complain about not finding @code{src:X:Y} files. Those complaints are
+harmless, and can be ignored.
+
@node Interpretation context
@section Interpretation context
@cindex notation contexts
Notation contexts are objects that only exist during a run of LilyPond.
-During the interpretation phase of LilyPond (when lily prints
-"interpreting music"), music a @code{\score} block is interpreted in
-time order, i.e. in much the same order that humans read, play, and
-write music.
+During the interpretation phase of LilyPond (when it prints
+"interpreting music"), the music expresiion in a @code{\score} block is
+interpreted in time order. This is the same order that humans hear and
+play music.
-During this reading, the notation context is holds the state
-for the current point within the music. It contains information like
+During this interpretation, the notation context is holds the state for
+the current point within the music. It contains information like
@itemize @bullet
@item What notes are playing at this point?
There are some quirks that you must keep in mind when dealing with
defaults:
-Every top-level music is interpreted by the Score context, in other
+First, every top-level music is interpreted by the Score context, in other
words, you may think of @code{\score} working like
@example
\score @{
@}
@end example
-Sequential music follows the contexts of its "children". Take this example
+Second, sequential music follows the contexts of its
+``children''. Consider the following example.
+
@lilypond[verbatim, singleline]
\score { \context Score \notes { c'4 ( d' )e' } }
@end lilypond
@var{context-identifier}
@} @}
@end example
-Then you can add engravers, remove engravers and set context
-properties. The syntax for these operations are respectively
+Then you can add engravers, remove engravers.
+The syntax for these operations are respectively
@example
\remove @var{engravername}
\consists @var{engravername}
- @var{propname} = @var{value}
@end example
+
Here @var{engravername} is a string, the name of an engraver in the
-system. @var{propname} is a string and @var{value} is a Scheme
-expression.
+system.
+@example
+ @var{propname} = @var{value}
+@end example
+
@lilypond[verbatim,singleline]
\score { \notes {
c'4 c'4 }
\paper {
\translator { \StaffContext
- \consists Instrument_name_engraver;
- instrument = #"foo"
\remove Clef_engraver;
} } }
@end lilypond
@cindex engraver
-These type of property assignments happen before interpretation starts,
-so a @code{\property} expression will override any predefined settings.
+You can also set properties in a translator definition. The syntax is as
+follows:
-Engravers are the actual C++ modules that do the work in the
-interpretation phase.
-
-
-There are some pre-defined identifiers to simplify editing translators,
-they are defined in @file{ly/engraver.ly}. These pre-defined
-identifiers are:
-
-@table @code
-@cindex @code{StaffContext}
- @item @code{StaffContext}
- Default Staff context.
-@cindex @code{RhythmicStaffContext}
-
- @item @code{RhythmicStaffContext}
- Default RhythmicStaff context.
-@cindex @code{VoiceContext}
+@var{propname} is a string and @var{value} is a Scheme
+expression.
+@example
+ @var{propname} = @var{value}
+ @var{propname} \set @var{symbol} = @var{value}
+ @var{propname} \override @var{symbol} = @var{value}
+ @var{propname} \revert @var{symbol}
- @item @code{VoiceContext}
- Default Voice context.
-@cindex @code{ScoreContext}
+@end example
- @item @code{ScoreContext}
- Default Score context.
+These type of property assignments happen before interpretation starts,
+so a @code{\property} expression will override any predefined settings.
-@cindex @code{HaraKiriStaffContext}
- @item @code{HaraKiriStaffContext}
- Staff context that does not print if it only contains rests. See
-@ref{Hara-kiri staffs}.
-@end table
+ To simplify editing translators, all standard contexts have standard
+identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
+@code{VoiceContext}.
@node Defining new contexts
@subsection Defining new contexts
@itemize @bullet
@item A name, specified by @code{\name @var{contextname};}.
- @item A cooperation engraver. This is specified by @code{\type
+ @item A cooperation module. This is specified by @code{\type
@var{typename};}.
@end itemize
-
-A context definition has this syntax:
-
+This is an example:
@example
-
- \translator @code{@{}
- @var{translatorinit} @var{translatormodifierlist}
- @code{@}}
-@end example
-
-@var{translatorinit} can be an identifier or
-@example
-
+\translator @code{
+ \type "Engraver_group_engraver";
+ \name "SimpleStaff";
+ \alias "Staff";
+ \consists "Staff_symbol_engraver";
+ \consists "Note_head_engraver";
+ \consistsend "Axis_group_engraver";
+}@
@end example
-where @var{typename} is one of
-The cooperation engraver groups other engravers, and specifies how they
-should cooperate. Choices are:
+Basic building blocks of translation are called engravers; they are
+special C++ classes.
+The argument of @code{\type} is the name for a special engraver that
+handles cooperation between simple engravers such as
+@code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives
+for this engraver are the following:
@table @code
@cindex @code{Engraver_group_engraver}
@item @code{Engraver_group_engraver}
`miniscore'.
@end table
-@var{translatormodifierlist} is a list of items where each item is
-one of
+Other modifiers are
@itemize @bullet
- @item @code{\consists} @var{engravername} @code{;}
- Add @var{engravername} to the list of modules in this context.
- The order of engravers added with @code{\consists} is
- significant.
-
+ @item @code{\alias} @var{alternate-name} @code{;}
+ This specifies a different name. In the above example,
+@code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
+
@item @code{\consistsend} @var{engravername} @code{;}
Analogous to @code{\consists}, but makes sure that
@var{engravername} is always added to the end of the list of
completeness, but is never used in practice.
- @item @code{\remove} @var{engravername} @code{;}
- Remove a previously added (with @code{\consists}) engraver.
-
@item @code{\name} @var{contextname} @code{;}
This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
the name is not specified, the translator won't do anything.
-
- @item @var{propname} @code{=} @var{value} @code{;}
- A property assignment.
@end itemize
In the @code{\paper} block, it is also possible to define translator
- Properties can be preset within the @code{\translator} block
-corresponding to the appropriate context. In this case, the syntax
-is
-
-@example
- @var{propname} @code{=} @var{value}
-@end example
-
-The property settings are used during the interpretation phase. They
-are read by the LilyPond modules where interpretation contexts are
-built of. These modules are called @emph{translators}. Translators for
-notation are called @emph{engravers}, and translators for sound are
-called @emph{performers}.
-
-
@c . {Syntactic details}
@node Syntactic details
@section Syntactic details
@cindex Syntactic details
+
+This section describes details that were too boring to be put elsewhere.
+
@menu
* Top level::
* Identifiers::
\score @{ @var{musicexpr} @var{outputdefs} @}
@end example
-@var{outputdefs} are zero or more output definitions. If no output
-definition is supplied, the default @code{\paper} block will be added.
+@var{outputdefs} are zero or more output definitions. If none is
+supplied, the default @code{\paper} block will be added.
@cindex Header
@cindex @code{\header}
-The syntax is
+A header describes bibilographic information of the file's contents. It
+can also appear in a @code{\score} block. Tools like @code{ly2dvi} can
+use this information for generating titles. Key values that are used by
+@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
+metre, arranger, piece and tagline.
+
+@cindex @code{ly2dvi}
+
+The syntax is
@example
\header @{ @var{key1} = @var{val1};
-@cindex @code{ly2dvi}
@var{key2} = @var{val2}; @dots{} @}
@end example
-
-A header describes the file's contents. It can also appear in a
-@code{\score} block. Tools like @code{ly2dvi} can use this
-information for generating titles. Key values that are used by
-@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
-metre, arranger, piece and tagline.
-
It is customary to put the @code{\header} at the top of the file.
@subsubsection Default output
Music in LilyPond is entered as a music expression. Notes, rests, lyric
syllables are music expressions, and you can combine music expressions
to form new ones, for example by enclosing a list of expressions in
-@code{\sequential @{ @}} or @code{< >}. In this example, a compound
-expression is formed out of the quarter note @code{c} and a quarter note
-@code{d}:
+@code{\sequential @{ @}} or @code{< >}. In the following example, a
+compound expression is formed out of the quarter note @code{c} and a
+quarter note @code{d}:
@example
\sequential @{ c4 d4 @}
@node Lexical details
@section Lexical details
+Even more boring details, now on lexical side of the input parser.
+
@menu
* Comments::
* Direct Scheme::
A real constant can be followed by one of the dimension keywords:
@code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
points, inches and centimeters, respectively. This converts the number
-to a real that is the internal representation of dimensions.
+a number that is the internal representation of that dimension.
@node Strings
projects / lilypond.git / blobdiff