@chapter Reference Manual
This document describes GNU LilyPond and its input format. The last
-revision of this document was for LilyPond 1.3.138.
+revision of this document was for LilyPond 1.3.141.
@menu
* Page layout::
* Sound::
* Music entry::
+* Using LilyPond::
* Interpretation context::
* Syntactic details::
* Lexical details::
LilyPond is linked to GUILE, GNU's Scheme library for extension. The
Scheme library provides the glue that holds together the low-level
-routines and separate modules general, which are C++
+routines and separate modules general, which are C++.
When lilypond is run to typeset sheet music, the following happens:
@itemize @bullet
@example
\pitch @var{scmpitch}
@end example
-9
+
@var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}.
In Note and Chord mode, pitches may be designated by names. The default
@code{Voice.sparseTies} to true, resulting in a smaller number of
ties:
@lilypond[fragment,verbatim,center]
-%oops: core dump
-% \property Voice.sparseTies = ##t
+ \property Voice.sparseTies = ##t
<c' e' g'> ~ <c' e' g'>
@end lilypond
Skips the amount of time specified by @var{duration}. If no other music
is played, a gap will be left for the skipped time with no notes
-printed. The short hand is only available in Note and Chord mode.
+printed. The shorthand is only available in Note and Chord mode.
@menu
* Key signature::
+* Clef::
* Time signature::
* Unmetered music::
* Bar lines::
@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
\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}
\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
@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}
@code{Voice.noAutoBeaming} to true. You you may find this necessary for
a melody that goes with lyrics.
+@refbugs
+
+It is not possible to specify beaming for beams with mixed durations,
+that differs from the beaming of all separate durations, ie, you'll
+have to specify manual beams to get:
+@lilypond[fragment,singleline,relative]
+ \property Voice.autoBeamSettings
+ \override #'(end * * * *) = #(make-moment 3 8)
+ \time 12/8; c'8 c c c16 c c c c c [c c c c] c8 c c4
+@end lilypond
+
+
@c . {Manual beams}
@cindex Automatic beams
@subsection Manual beams
rests or bar lines, so if you want that, specify the begin and end point
manually using @code{[} and @code{]}:
-@quotation
@lilypond[fragment,relative,verbatim]
\context Staff {
r4 [r8 g'' a r8] r8 [g | a] r8
[f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
}
@end lilypond
-@end quotation
@cindex @code{stemRightBeamCount}
The beam symbol can be tweaked through @code{Voice.Beam}'s
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
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
Maybe reinclude other slur features and move back to tricks? Esp. the
second example, how to fix, can be very helpful.
-@quotation
@lilypond[fragment,relative,verbatim]
\property Voice.Slur \set #'direction = #1
\property Voice.Stem \set #'length = #5.5
\property Voice.Slur \set #'attachment = #'(stem . stem)
g8(g)g4
@end lilypond
-@end quotation
If a slur would strike through a stem or beam, the slur will be moved
away upward or downward. If this happens, attaching the slur to the
stems might look better:
-@quotation
@lilypond[fragment,relative,verbatim]
\property Voice.Stem \set #'direction = #1
\property Voice.Slur \set #'direction = #1
\property Voice.Slur \set #'attachment = #'(stem . stem)
d,32( d'4 )d8..
@end lilypond
-@end quotation
Similarly, the curvature of a slur is adjusted to stay clear of note
* Articulation::
* Text scripts::
* Grace notes::
+* Glissando ::
+* Dynamics::
@end menu
@c . {Articulation}
stem. This behavior can be controlled with the
@code{Stem}.@code{flag-style} property.
-@quotation
@lilypond[fragment,verbatim]
\relative c'' {
\grace c8 c4 \grace { [c16 c16] } c4
\grace { \property Grace.Stem \override #'flag-style = #'() c16 } c4
}
-
@end lilypond
-@end quotation
At present, nesting @code{\grace} notes is not supported. The following
@c . {Glissando}
@node Glissando
-@subsubsection Glissando
+@subsection Glissando
@cindex Glissando
@cindex @code{\glissando}
A glissando line can be requested by attaching a @code{\glissando} to a
note:
-@quotation
@lilypond[fragment,relative,verbatim]
c'' \glissando c'
@end lilypond
-@end quotation
@refbugs
@c . {Dynamics}
@node Dynamics
-@subsubsection Dynamics
+@subsection Dynamics
@cindex Dynamics
@code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
@code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
+@lilypond[verbatim,singleline,fragment,relative]
+ c''\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
+ c2\sf c\rfz
+@end lilypond
@cindex Crescendo and Decrescendo
@cindex crescendo
@end lilypond
With alternative endings:
-@quotation
@lilypond[fragment,verbatim]
c'1
\repeat volta 2 {c'4 d' e' f'}
\alternative { {d'2 d'} {f' f} }
@end lilypond
-@end quotation
Folded repeats look like this:@footnote{Folded repeats offer little
more over simultaneous music. However, it is to be expected that
more functionality -- especially for the MIDI backend -- will be
implemented at some point in the future.}
-@quotation
@lilypond[fragment,verbatim]
c'1
\repeat fold 2 {c'4 d' e' f'}
\alternative { {d'2 d'} {f' f} }
@end lilypond
-@end quotation
-
If you don't give enough alternatives for all of the repeats, then
the first alternative is assumed to be repeated often enough to equal
the specified number of repeats.
-@quotation
@lilypond[fragment,verbatim]
\context Staff {
\relative c' {
}
}
@end lilypond
-@end quotation
@refbugs
@code{\sustainDown}, @code{\sustainUp}, @code{\unaChorda},
@code{\treChorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
-These identifiers are short hands for spanner commands of the types
+These identifiers are shorthands for spanner commands of the types
@code{Sustain}, @code{UnaChorda} and @code{Sostenuto}:
@lilypond[fragment,verbatim]
@code{\arpeggio} to a note of the chord.
-@quotation
@lilypond[fragment,relative,verbatim]
\context Voice <c'\arpeggio e g c>
@end lilypond
-@end quotation
When an arpeggio crosses staffs in piano music, you attach an arpeggio
to the chords in both staffs, and set
@code{PianoStaff.connectArpeggios}.
-@quotation
@lilypond[fragment,relative,verbatim]
\context PianoStaff <
\property PianoStaff.connectArpeggios = ##t
\context Voice = other { \clef bass; <c,,\arpeggio e g>}
>
@end lilypond
-@end quotation
This command creates @code{Arpeggio} grobs.
can be printed automatically. This is enabled if the property
@code{PianoStaff.followVoice} is set to true:
-@quotation
@lilypond[fragment,relative,verbatim]
\context PianoStaff <
\property PianoStaff.followVoice = ##t
\context Staff=two {\clef bass; \skip 1*2;}
>
@end lilypond
-@end quotation
@c . {Lyrics}
Throughout these examples, chords have been shifted around the staff
using @code{\transpose}.
-
-@quotation
-
@lilypond[fragment,verbatim]
\transpose c'' {
\chords {
c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
}
}
-
@end lilypond
-@end quotation
@cindex @code{aug}
@cindex @code{dim}
`@code{maj}' which adds a raised 7th, and `@code{sus}'
which replaces the 5th with a 4th.
-@quotation
-
@lilypond[fragment,verbatim]
\transpose c'' {
\chords {
c1:m c:min7 c:maj c:aug c:dim c:sus
}
}
-
@end lilypond
-@end quotation
Chord subtractions are used to eliminate notes from a chord. The
The chords may be entered either using the notation described above, or
directly using simultaneous music.
-@quotation
@lilypond[verbatim,singleline]
scheme = \notes {
\chords {a1 b c} <d f g> <e g b>
>
}
@end lilypond
-@end quotation
You can make the chord changes stand out by setting property
@code{ChordNames.chordChanges} to true. This will only display chord
names when there's a change in the chords scheme and at the start of the
line.
-@quotation
@lilypond[verbatim]
scheme = \chords {
c1:m \break c:m c:m c:m d
\context Staff \transpose c'' \scheme
> }
@end lilypond
-@end quotation
LilyPond examines chords specified as lists of notes to determine a name
to give the chord. LilyPond will not try to identify chord inversions or
[base vs. bass ?]
-@quotation
@lilypond[verbatim,center,singleline]
scheme = \notes {
<c'1 e' g'>
>
}
@end lilypond
-@end quotation
By default LilyPond uses chord name system proposed by Harald Banter
a tone. The first version will print sharps and the second version
will print flats.
-@quotation
@lilypond[fragment,verbatim]
\context Staff {
\clef "F";
\transpose des'' { \key e \major; c d e f }
\transpose cis'' { \key e \major; c d e f }
}
-
@end lilypond
-@end quotation
If you want to use both @code{\transpose} and @code{\relative}, then
you must use @code{\transpose} first. @code{\relative} will have no
documentation. Look for @code{Thread_devnull_engraver}
@code{Voice_devnull_engraver} and @code{A2_engraver}.
+@refbugs
+
+In @code{soloADue} mode, when the two voices play the same notes on and
+off, the part combiner may typeset @code{a2} more than once in a
+measure.
+
+@lilypond[fragment,singleline]
+ \context Staff <
+ \context Voice=one \partcombine Voice
+ \context Thread=one \relative c'' {
+ c b c b c a c a
+ }
+ \context Thread=two \relative c'' {
+ b b b b f a f a
+ }
+ >
+@end lilypond
+
@cindex @code{Thread_devnull_engraver}
@cindex @code{Voice_engraver}
@cindex @code{A2_engraver}
thus helps the player or singer to manage line breaks during
performance, thus enhancing readability of a score.
-@quotation
@lilypond[verbatim]
\score {
\notes { c'1 d' e' d' \break c' d' e' d' }
}
}
@end lilypond
-@end quotation
Custodes were frequently used in music notation until the 16th century.
There were different appearences for different notation styles.
@refbugs
LilyPond will hang or crash if @var{value} contains cyclic references.
+The backend is not very strict in type-checking grob properties. If you
+@code{\revert} properties that are expected to be set by default,
+LilyPond may crash.
@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{}
@item @code{linewidth}
Sets the width of the lines.
-If set to a negative value, a single
- unjustified line is produced.
+If set to a negative value, a single unjustified line is produced.
+@c rename to singleLinePaper ?
+The shorthand @code{\singleLine} defines a default paper block that
+produces a single line.
@cindex @code{textheight}
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, beifore invoking server-start.
+init file, before invoking server-start.
@example
(setq load-path (cons "~/usr/share/emacs" load-path))
harmless, and can be ignored.
+@c . {Using LilyPond}
+@node Using LilyPond
+@section Using LilyPond
+@cindex Using LilyPond
+@cindex Generating output
+
+@c slaat dit ergens op?
+
+@c direct postscript?
+
+@table @code
+@item plain lilypond
+@example
+lilypond foo.ly
+@end example
+For more information on how to use lilypond see
+@ifnottex
+@ref{Invoking LilyPond}.
+@end ifnottex
+@iftex
+the online manual.
+@end iftex
+
+@item ly2dvi
+Ly2dvi produces titling from @code{\header} fields.
+@example
+ly2dvi foo.ly
+@end example
+For more information on how to use ly2dvi see
+@ifnottex
+@ref{ly2dvi}.
+@end ifnottex
+@iftex
+the online manual.
+@end iftex
+
+@item lilypond-book
+Lilypond-book supports interleaving text and music.
+@example
+lilypond-book foo.doc
+@end example
+For more information on how to use lilypond-book see
+@ifnottex
+@ref{lilypond-book}.
+@end ifnottex
+@iftex
+the online manual.
+@end iftex
+@end table
+
+
+An emacs mode for LilyPond is included with the source archive as
+@file{lilypond-mode.el} and @file{lilypond-font-lock.el}. If you have
+an RPM, it is in @file{/usr/share/doc/lilypond-X/}. You have to install
+it yourself.
+
+Add this to your ~/.emacs or ~/.emacs.el:
+@example
+ (load-library "lilypond-mode.el")
+ (setq auto-mode-alist
+ (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
+ (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
+@end example
+
+If you have the latest LilyPond-1.3.x Debian package, LilyPond-mode
+is automatically loaded, so you need not modify your ~/.emacs file.
+
+@menu
+* Pre-cooked makefile::
+@end menu
+
+@node Pre-cooked makefile
+@subsection Pre-cooked makefile
+
+@c waar deze info? is uiteindelijk wel handig, schat ik.
+[TODO: cut blabla]
+If you have a big music project, or just a lot of LilyPond input files,
+all generated output from LilyPond, @TeX{} and metafont will clutter
+your working directory. LilyPond comes with a one-size-fits-all
+pre-cooked makefile that helps you manage producing ouptut. It will
+produce all output in @file{out}, generate and track dependencies.
+Also, it helps in preparing your submission to the @ref{Mutopia
+project}.
+
+@file{make/ly.make}
+@example
+mkdir my-project
+cd my-project
+cp /usr/share/lilypond/make/ly.make GNUmakefile
+cp /usr/share/doc/lilypond/examples/input/tutorial/menuet.ly .
+make menuet
+[..]
+Generated out/menuet.ps for target menuet.
+@end example
+
+Type @samp{make help} to see possible targets.
+
+[TODO]
+@file{/usr/share/lilypond/doc/lilypond/examples/input/mutopia-header.ly}
+
+
@node Interpretation context
@section Interpretation context
of type @var{contexttype} and with name @var{contextname}. If this
context does not exist, it will be created.
-@quotation
-
@lilypond[verbatim,singleline]
\score {
\notes \relative c'' {
}
@end lilypond
-@end quotation
In this example, the @code{c} and @code{d} are printed on the
default staff. For the @code{e}, a context Staff called
such an identifier outside of @code{\score}, you must do
@quotation
-
@example
\paper @{
foo = \translator @{ @dots{} @}
projects / lilypond.git / commitdiff