@macro refbugs
@strong{BUGS}
-
@end macro
@end html
This document describes GNU LilyPond and its input format. The last
-revision of this document was made for LilyPond 1.4.1. It supposes a
-passing familiarity with how LilyPond input works. New users are
-encouraged to study the tutorial first.
+revision of this document was made for LilyPond 1.6.2. It assumes
+that you already know a little bit about LilyPond input (how to
+make an input file, how to create sheet music from that input file,
+etc). New users are encouraged to study the tutorial before reading
+this manual.
@menu
* Ancient notation ::
* Tuning output::
* Global layout::
-* Output formats::
* Sound::
@end menu
@section Note entry
@cindex Note entry
-The most basic forms of music are notes. Notes on their own don't
-form valid input, but for the sake of brevity we omit @code{\score}
-blocks and @code{\paper} declarations.
+Notes constitute the most basic elements of LilyPond input, but they do
+not form valid input on their own without a @code{\score} block. However,
+for the sake of brevity and simplicity we will generally omit
+@code{\score} blocks and @code{\paper} declarations in this manual.
@menu
@subsection Notes
-A note is printed by specifying its pitch, and then its duration.
+A note is printed by specifying its pitch and then its duration.
@lilypond[fragment,verbatim]
cis'4 d'8 e'16 c'16
@end lilypond
\pitch @var{scmpitch}
@end example
-@var{scmpitch} is a pitch scheme object.
+where @var{scmpitch} is a pitch scheme object.
In Note and Chord mode, pitches may be designated by names. The default
names are the Dutch note names. The notes are specified by the letters
-@code{a} through @code{g} (where the octave is formed by notes ranging
-from @code{c} to @code{b}). The pitch @code{c} is an octave below
-middle C and the letters span the octave above that C.
+@code{a} through @code{g}, while the octave is formed with notes ranging
+from @code{c} to @code{b}. The pitch @code{c} is an octave below
+middle C and the letters span the octave above that C. Here's an example
+which should make things more clear:
+
+@lilypond[fragment,verbatim]
+\clef bass
+ a,4 b, c d e f g a b c' d' e' \clef treble f' g' a' b' c''
+@end lilypond
@cindex note names, Dutch
In Dutch, a sharp is formed by adding @code{-is} to the end of a pitch
-name and a flat is formed by adding @code{-es}. Double sharps and double
+name and a flat is formed by adding @code{-es}. Double sharps and double
flats are obtained by adding @code{-isis} or @code{-eses}. @code{aes}
and @code{ees} are contracted to @code{as} and @code{es} in Dutch, but
both forms are accepted.
LilyPond has predefined sets of note names for various other languages.
To use them, simply include the language specific init file. For
example: @code{\include "english.ly"}. The available language files and
-the names they define are:
+the note names they define are:
+@anchor{note name}
+@anchor{note names}
@example
Note Names sharp flat
nederlands.ly c d e f g a bes b -is -es
@node Chromatic alterations
@subsection Chromatic alterations
-Normally, accidentals are printed automatically, but you may force
-accidentals in the following ways: A reminder accidental
+Normally accidentals are printed automatically, but you may also
+print them manually. A reminder accidental
@cindex reminder accidental
@cindex @code{?}
-can be forced by adding an exclamation mark @code{!} after the pitch. A
-cautionary accidental,
+can be forced by adding an exclamation mark @code{!}
+after the pitch. A cautionary accidental
@cindex cautionary accidental
@cindex parenthesized accidental
-i.e., an accidental within parentheses can be obtained by adding the
+(an accidental within parentheses) can be obtained by adding the
question mark `@code{?}' after the pitch.
+@lilypond[fragment,verbatim]
+ cis' cis' cis'! cis'?
+@end lilypond
+
+
The automatic production of accidentals can be tuned in many
-ways. Refer to @ref{Accidentals} for more information.
+ways. For more information, refer to @ref{Accidentals}.
@c . {Rests}
@node Rests
@subsection Rests
@cindex Rests
-A rest is entered like a note, with note name `@code{r}':
+Rests are entered like notes, with a ``note name'' of `@code{r}':
@lilypond[singleline,verbatim]
r1 r2 r4 r8
@end lilypond
-Whole bar rests centered in the bar are specified using @code{R}, see
-@ref{Multi measure rests}. See also @seeinternals{Rest}.
+Whole bar rests, centered in middle of the bar, are specified using
+@code{R} (capital R); see @ref{Multi measure rests}. See also
+@seeinternals{Rest}.
-For polyphonic music, it can be convenient to specify the rest position
-directly. You can do that by entering a note, with the keyword
-@code{\rest} appended, e.g. Rest collisions will leave these rests alone.
+For some music, you may wish to explicitly specify the rest's vertical
+position. This can be achieved by entering a note with the @code{\rest}
+keyword appended. Rest collision testing will leave these rests alone.
@lilypond[singleline,verbatim]
a'4\rest d'4\rest
@cindex Invisible rest
@cindex Space note
-An invisible rest, or skip, can be entered like a note with note name
-@code{s}, or with @code{\skip @var{duration}}:
+An invisible rest (also called a `skip') can be entered like a note
+with note name `@code{s}' or with @code{\skip @var{duration}}:
@lilypond[singleline,verbatim]
a2 s4 a4 \skip 1 a4
@end lilypond
-The @code{s} syntax is only available in Note mode and Chord mode.
-In other situations, you should use the @code{\skip} command, and it is
-only available in Note mode and Chord mode.
-
-@c FIXME: in lyrics mode, we have " " and _
+@c FIXME: in Lyrics mode, we have " " and _
-In Lyrics mode, you can use `@code{" "}' and `@code{_}':
+In Lyrics mode, invisible rests are entered using either `@code{" "}'
+or `@code{_}':
@lilypond[singleline,verbatim]
<
\context Lyrics \lyrics { lah2 di4 " " dah2 _4 di }
>
@end lilypond
-The unabbreviated `@code{\skip} @var{duration}' also works outside of
-note mode:
+Note that the @code{s} syntax is only available in Note mode and Chord
+mode. In other situations, you should use the @code{\skip} command,
+which will work outside of those two modes:
@lilypond[singleline,verbatim]
\score {
}
@end lilypond
-The skip command is merely a empty musical placeholder. It does not
+The skip command is merely an empty musical placeholder. It doesn't
produce any output, not even transparent output.
+
@c . {Durations}
@node Durations
@subsection Durations
@cindex @code{\duration}
-In Note, Chord, and Lyrics mode, durations may be designated by numbers
-and dots: durations are entered as their reciprocal values. For notes
+In Note, Chord, and Lyrics mode, durations are designated by numbers
+and dots: durations are entered as their reciprocal values. For example,
+a quarter note is entered using a @code{4} (since it's a 1/4 note), while
+a half note is entered using a @code{2} (since it's a 1/2 note). For notes
longer than a whole you must use identifiers.
+@c FIXME: what's an identifier? I don't think it's been introduced yet.
+@c and if it has, I obviously skipped that part. - Graham
@example
- c'\breve
+c'\breve
c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
r\longa r\breve
r1 r2 r4 r8 r16 r32 r64 r64
@end example
-
-@lilypond[]
+@lilypond[noindent,noquote]
\score {
\notes \relative c'' {
a\breve \autoBeamOff
@end lilypond
-If the duration is omitted then it is set to the previous duration
-entered. At the start of parsing a quarter note is assumed. The
-duration can be followed by dots (`@code{.}') to obtain dotted note
-lengths.
+If the duration is omitted then it is set to the previously entered
+duration. At the start of parsing, a quarter note is assumed. The
+duration can be followed by dots (`@code{.}') in order to obtain dotted
+note lengths:
@cindex @code{.}
@lilypond[fragment,verbatim,center]
- a'4. b'4.. c'8.
+ a' b' c''8 b' a'4 a'4. b'4.. c'8.
@end lilypond
@cindex @code{r}
@cindex @code{s}
-You can alter the length of duration by a fraction @var{N/M} by
+You can alter the length of duration by a fraction @var{N/M}
appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
-will not affect the appearance of the notes or rests produced.
+won't affect the appearance of the notes or rests produced.
+
+@lilypond[fragment,verbatim]
+ a'2*2 b'4*2 a'8*4 a'4*3/2 gis'4*3/2 a'4*3/2 a'4
+@end lilypond
Durations can also be produced through GUILE extension mechanism.
@lilypond[verbatim,fragment]
- c\duration #(make-duration 2 1)
+ c'\duration #(ly:make-duration 2 1)
+@end lilypond
+
+
+@refbugs
+
+Dot placement for chords is not perfect. In some cases, dots overlap:
+@lilypond[]
+ <<f, c'' d e f>>4.
@end lilypond
@cindex @code{~}
A tie connects two adjacent note heads of the same pitch. The tie in
-effect extends the length of a note. A tie is entered with @code{~}.
+effect extends the length of a note. Ties should not be confused with
+slurs, which indicate articulation, or phrasing slurs, which indicate
+musical phrasing. A tie is entered using the tilde symbol `@code{~}'.
@lilypond[fragment,verbatim,center]
- e' ~ e' <c' e' g'> ~ <c' e' g'>
+ e' ~ e' <<c' e' g'>> ~ <<c' e' g'>>
@end lilypond
-When ties are used with chords, all note heads whose pitches match are
-connected. Ties are indicated using the tilde symbol `@code{~}'. If
-you try to tie together chords which have no common pitches then no
-ties will be created.
+When a tie is applied to a chord, all note heads (whose pitches match) are
+connected. If you try to tie together chords that have no common pitches,
+no ties will be created.
-If you want less ties created for a chord, you can set
-@code{Voice.sparseTies} to true. In this case, a single tie is used
+If you want less ties created for a chord, you can set
+@code{Voice.sparseTies} to true. In this case, a single tie is used
for every tied chord.
@lilypond[fragment,verbatim,center]
\property Voice.sparseTies = ##t
- <c' e' g'> ~ <c' e' g'>
+ <<c' e' g'>> ~ <<c' e' g'>>
@end lilypond
In its meaning a tie is just a way of extending a note duration, similar
@lilypond[fragment, singleline]
\time 3/4 c'2. c'2 ~ c'4
@end lilypond
-Ties should not be confused with slurs, which indicate articulation,
-and phrasing slurs, which indicate musical phrasing.
+If you need to tie notes over bars, it may be easier to use
+@ref{Automatic note splitting}.
-See also @seeinternals{Tie}.
+See also @seeinternals{Tie}.
@refbugs
At present, the tie is represented as a separate event, temporally
-located in between the notes. Tieing only a subset of the note heads
+located in between the notes. Tying only a subset of the note heads
of a chord is not supported in a simple way. It can be achieved by
moving the tie-engraver into the Thread context and turning on and off
ties per Thread.
+Switching staves when a tie is active will not work.
+
@node Automatic note splitting
@subsection Automatic note splitting
@c FIXME: This subsection doesn't belong in @ref{Note entry}.
-There is a facility for automatically converting long notes to tied
-notes. This is done by replacing the @code{Note_heads_engraver} by the
+LilyPond can automatically converting long notes to tied notes. This
+is done by replacing the @code{Note_heads_engraver} by the
@code{Completion_heads_engraver}.
-@lilypond[verbatim,center]
+@lilypond[verbatim,noindent,noquote]
\score{
\notes\relative c'{ \time 2/4
c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2
@end lilypond
This engraver splits all running notes at the bar line, and inserts
-ties. One of its uses is to debug complex scores: if the measures are
+ties. One of its uses is to debug complex scores: if the measures are
not entirely filled, then the ties exactly show how much each measure
is off.
@cindex triplets
@cindex @code{\times}
-Tuplets are made out of a music expression by multiplying all duration
+Tuplets are made out of a music expression by multiplying all durations
with a fraction.
@cindex @code{\times}
@end example
The duration of @var{musicexpr} will be multiplied by the fraction.
-In print, the fraction's denominator will be printed over the notes,
-optionally with a bracket. The most common tuplet is the triplet in
-which 3 notes have the length of 2, so the notes are 2/3 of
-their written length:
+In the sheet music, the fraction's denominator will be printed over
+the notes, optionally with a bracket. The most common tuplet is the
+triplet in which 3 notes have the length of 2, so the notes are 2/3
+of their written length:
@lilypond[fragment,verbatim,center]
g'4 \times 2/3 {c'4 c' c'} d'4 d'4
The property @code{tupletSpannerDuration} specifies how long each bracket
should last. With this, you can make lots of tuplets while typing
-@code{\times} only once, thus saving typing work.
+@code{\times} only once, saving you lots of typing.
@lilypond[fragment, relative, singleline, verbatim]
-\property Voice.tupletSpannerDuration = #(make-moment 1 4)
+\property Voice.tupletSpannerDuration = #(ly:make-moment 1 4)
\times 2/3 { c'8 c c c c c }
@end lilypond
The format of the number is determined by the property
-@code{tupletNumberFormatFunction}. The default prints only the
+@code{tupletNumberFormatFunction}. The default prints only the
denominator, but if you set it to the Scheme function
@code{fraction-tuplet-formatter}, Lilypond will print @var{num}:@var{den}
instead.
@refbugs
-Nested tuplets are not formatted automatically. In this case, outer
+Nested tuplets are not formatted automatically. In this case, outer
tuplet brackets should be moved automatically.
@node Easy Notation note heads
A entirely different type of note head is the "easyplay" note head: a
note head that includes a note name. It is used in some publications by
-Hal-Leonard Inc. music publishers.
+Hal-Leonard Inc. music publishers.
@lilypond[singleline,verbatim,26pt]
\score {
@end lilypond
Note that @code{EasyNotation} overrides a @internalsref{Score} context. You
-probably will want to print it with magnification or a large font size to make it more
-readable.
+probably will want to print it with magnification or a large font size to
+make it more readable. To print with magnification, you must create a dvi
+(with @file{ly2dvi}) and then enlarge it with something like @file{dvips -x
+2000 file.dvi}. See @file{man dvips} for details. To print with a larger
+font, see @ref{Font Size}.
@cindex Xdvi
@cindex ghostscript
If you view the result with Xdvi, then staff lines will show through
-the letters. Printing the postscript file obtained with ly2dvi does
+the letters. Printing the PostScript file obtained with ly2dvi does
produce the correct result.
@section Easier music entry
@cindex Music entry
@menu
+* Graphical interfaces::
* Relative octaves::
* Bar check::
* Point and click::
section deals with tricks and features that help you enter music, and
find and correct mistakes.
+@node Graphical interfaces
+@subsection Graphical interfaces
+
+@cindex GUI
+@cindex graphical interface
+@cindex sequencer
+@cindex RoseGarden
+@cindex Denemo
+@cindex NoteEdit
+@cindex MIDI
+
+One way to avoid entering notes using the keyboard is to use a
+graphical user interface. The following programs are known to have
+a lilypond export option:
+
+@itemize @bullet
+@item
+Denemo was once intended as
+a LilyPond graphical user interface. It run on Gnome/GTK.
+
+@quotation
+@uref{http://denemo.sourceforge.net/}
+@end quotation
+
+@item
+ Noteedit, a graphical score editor that runs under KDE/Qt.
+@quotation
+@uref{http://rnvs.informatik.tu-chemnitz.de/~jan/noteedit/noteedit.html,}
+@end quotation
+
+@item
+RoseGarden was once the inspiration for naming LilyPond. Nowadays it
+has been rewritten from scratch and supports LilyPond export as of
+version 0.1.6.
+
+@quotation
+@uref{http://rosegarden.sf.net/}
+@end quotation
+@end itemize
+
+Another option is to enter the music using your favorite MIDI
+sequencer, and then import it using midi2ly. midi2ly is described in
+@ref{Invoking midi2ly}.
+
+
@c . {Relative}
@node Relative octaves
@subsection Relative octaves
@lilypond[fragment,verbatim,center]
\relative c' {
- c <c e g>
- <c' e g>
- <c, e' g>
+ c <<c e g>>
+ <<c' e g>>
+ <<c, e' g>>
}
@end lilypond
@cindex @code{\notes}
additional @code{\relative} inside the @code{\transpose}.
-@c . {Bar check}
+@c . {Bar check}
@node Bar check
@subsection Bar check
@cindex Bar check
error in the sheet music.
To use it, you need the following software
-
@itemize @bullet
-@item
-@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain
-Xdvi} version 22.36 or newer.
+@item A dvi viewer that supports src specials.
+@itemize @bullet
+@item Xdvi, version 22.36 or newer. Available from
+@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,ftp.math.berkeley.edu}.
+
+ Note that most @TeX{} distributions ship with xdvik, which is always
+ a few versions behind the official Xdvi. To find out which xdvi you
+ are running, try @code{xdvi -version} or @code{xdvi.bin -version}.
+@item KDVI. A dvi viewer for KDE. You need KDVI from KDE 3.0 or
+newer. Enable option @emph{Inverse search} in the menu @emph{Settings}.
- 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}.
+@cindex Xdvi
+@cindex KDVI
+@cindex KDE
+
+
+
+@end itemize
+@item An editor with a client/server interface (or a lightweight GUI
+editor).
+
+@cindex editor
-@item An editor with a client/server interface (or a lightweight GUI editor).
@itemize @bullet
@item Emacs. Emacs is an extensible text-editor. It is available from
@uref{http://www.gnu.org/software/emacs/}. You need version 21 to use
column location.
-@item GVim. GVim is a lightweight GUI variant of VIM, the popular VI
+
+@c move this elsewhere?
+
+LilyPond also comes with support files for emacs: lilypond-mode for
+emacs provides indentation, syntax coloring and handy compile
+short-cuts. If lilypond-mode is not installed on your platform, then
+refer to the installation instructions for more information
+
+@cindex emacs
+@cindex emacs mode
+@cindex lilypond-mode for emacs
+@cindex syntax coloring
+
+@item XEmacs. Xemacs is very similar to emacs.
+
+@cindex XEmacs
+
+@item NEdit. NEdit runs under Windows, and Unix.
+ It is available from @uref{http://www.nedit.org}.
+
+@cindex NEdit
+
+@item GVim. GVim is a GUI variant of VIM, the popular VI
clone. It is available from @uref{http://www.vim.org}.
-@item NEdit. NEdit is a somewhat Windows like editor, that has recently
-become Free Software. It is available from @uref{http://www.nedit.org}.
+
+@cindex GVim
+@cindex Vim
+
@end itemize
+@end itemize
+
Xdvi must be configured to find the @TeX{} fonts and music
fonts. Refer to the Xdvi documentation for more information.
To use point-and-click, add one of these lines to the top of your .ly
file.
@example
-#(set! point-and-click line-location)
+#(ly:set-point-and-click 'line)
@end example
@cindex line-location
spot in the @file{.ly} file. Control-Mousebutton 2 will show all
clickable boxes.
-@subsubsec Emacs
+If you correct large files with point-and-click, be sure to start
+correcting at the end of the file. When you start at the top, and
+insert one line, all following locations will be off by a line.
+
@cindex Emacs
-In your emacs startup file (usually @file{~/.emacs}), add the following
+For using point-and-click with emacs, add the following
+In your emacs startup file (usually @file{~/.emacs}),
@example
(server-start)
@end example
-Make sure that the environment variable @code{XEDITOR} is set to
+Make sure that the environment variable @var{XEDITOR} is set to
@example
emacsclient --no-wait +%l %f
@end example
-@cindex XEDITOR
-
-If you use Emacs version 21, you can make emacs jump to the exact spot
-(and not just the line) on a click. To use this feature, you must
-enable column positioning. At the top of the @code{ly} file, replace
-the @code{set!} line with the following line
-@example
-#(set! point-and-click line-column-location)
-@end example
-@cindex line-colomn-location
-Set @var{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}, or
-use this argument with xdvi's @file{-editor} option.
+@cindex @var{XEDITOR}
+If you use xemacs instead of emacs, you use @code{(gnuserve-start)} in
+your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f}
-If you correct large files with point-and-click, be sure to start
-correcting at the end of the file. When you start at the top, and
-insert one line, all following locations will be off by a line.
-
-@subsubsec GVim
-@cindex GVIM
-Set @var{XEDITOR} to @code{gvim +%l %f}, or
+For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or
use this argument with xdvi's @code{-editor} option.
-@subsubsec NEdit
@cindex NEdit
-Set @var{XEDITOR} to @code{nc -noask +%l %f}, or
+For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or
use this argument with xdvi's @code{-editor} option.
+If can also make your editor jump to the exact location of the note
+you clicked. This is only supported on Emacs and VIM. Users of Emacs version
+20 must apply the patch @file{emacsclient.patch}. Users of version 21
+must apply @file{server.el.patch} (version 21.2 and earlier). At the
+top of the @code{ly} file, replace the @code{set-point-and-click} line
+with the following line,
+@example
+#(ly:set-point-and-click 'line-column)
+@end example
+@cindex line-colomn-location
+and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}. Vim
+users can set @var{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}.
+
+
@refbugs
@cindex Staff notation
@menu
+* Staff symbol::
* Key signature::
* Clef::
* Time signature::
* Bar lines::
@end menu
+@node Staff symbol
+@subsection Staff symbol
+
+
+@cindex adjusting staff symbol
+@cindex StaffSymbol, using \property
+@cindex staff lines, setting number of
+
+
+The lines of the staff symbol are formed by the
+@internalsref{StaffSymbol} object. This object is created at the moment
+that their context is created. You can not change the appearance of
+the staff symbol by using @code{\override} or @code{\set}. At the
+moment that @code{\property Staff} is interpreted, a Staff context is
+made, and the StaffSymbol is created before any @code{\override} is
+effective. You can deal with this either overriding properties in a
+@code{\translator} definition, or by using @code{\outputproperty}.
+
+
+@refbugs
+
+If you end a staff half way a piece, the staff symbol may not end
+exactly on the barline.
+
+
@c . {Key}
@node Key signature
@subsection Key signature
Non-standard key signatures can be specified by setting this property
directly.
-The printed signature is a @internalsref{KeySignature} grob, typically
+The printed signature is a @internalsref{KeySignature} object, typically
created in @internalsref{Staff} context.
@cindex @code{keySignature}
\clef "G_8"
@end example
-The grob for this symbol is @internalsref{Clef}.
+The object for this symbol is @internalsref{Clef}.
This command is equivalent to setting @code{clefGlyph},
2/2 time.
-The grob for this symbol is @internalsref{TimeSignature}. There are
+The object for this symbol is @internalsref{TimeSignature}. There are
many more options for its layout. They are selected through the
-@code{style} grob property. See @file{input/test/time.ly} for more
+@code{style} object property. See @file{input/test/time.ly} for more
examples.
This command sets the property @code{timeSignatureFraction},
-@code{beatLength} and @code{measureLength}. The property
+@code{beatLength} and @code{measureLength} in the @code{Timing}
+context, which is normally aliased to @internalsref{Score}. The property
@code{timeSignatureFraction} determine where bar lines should be
inserted, and how automatic beams should be generated. Changing the
value of @code{timeSignatureFraction} also causes a time signature
symbol to be printed.
+More options are available through the Scheme function
+@code{set-time-signature}. In combination with the
+@internalsref{Measure_grouping_engraver}, it will create
+@internalsref{MeasureGrouping} signs. Such signs ease reading
+rhythmically complex modern music. In the following example, the 9/8
+measure is subdivided in 2, 2, 2 and 3. This is passed to
+@code{set-time-signature} as the third argument @code{(2 2 2 3)}.
+
+@lilypond[verbatim]
+\score { \notes \relative c'' {
+ #(set-time-signature 9 8 '(2 2 2 3))
+ g8 g d d g g a8-[-( bes g-]-) |
+ #(set-time-signature 5 8 '(3 2))
+ a4. g4
+ }
+ \paper {
+ linewidth = -1.0
+ \translator { \StaffContext
+ \consists "Measure_grouping_engraver"
+ }}}
+@end lilypond
+
@c . {Partial}
@subsection Partial
@cindex Partial
@end example
This is internally translated into
@example
- \property Score.measurePosition = -@var{length of duration}
+ \property Timing.measurePosition = -@var{length of duration}
@end example
@cindex @code{|}
The property @code{measurePosition} contains a rational number
You are encouraged to use @code{\repeat} for repetitions. See
@ref{Repeats}.
-In scores with many staffs, the barlines are automatically placed at
-top level, and they are connected between different staffs of a
+In scores with many staves, the barlines are automatically placed at
+top level, and they are connected between different staves of a
@internalsref{StaffGroup}:
@lilypond[fragment, verbatim]
< \context StaffGroup <
\context Staff = pedal { \clef bass c2 c2 } >
@end lilypond
-The grobs that are created at @internalsref{Staff} level. The name is
+The objects that are created at @internalsref{Staff} level. The name is
@internalsref{BarLine}.
The command @code{\bar @var{bartype}} is a short cut for
Normally, note heads with a different number of dots are not merged, but
-if you set the grob property @code{merge-differently-dotted}, they are:
+if you set the object property @code{merge-differently-dotted}, they are:
@lilypond[verbatim,fragment,singleline]
\context Voice < {
g'8 g'8
Resolving collisions is a very intricate subject, and LilyPond only
handles a few situations. When it can not cope, you are advised to use
-@code{force-hshift} of the @internalsref{NoteColumn} grob and pitched
+@code{force-hshift} of the @internalsref{NoteColumn} object and pitched
rests to override typesetting decisions.
@node Beaming
\property Voice.subdivideBeams = ##t
[c16 c c c c c c c]
[c32 c c c c c c c c c c c c c c c]
-\property Score.beatLength = #(make-moment 1 8)
+\property Score.beatLength = #(ly:make-moment 1 8)
[c32 c c c c c c c c c c c c c c c]
@end example
-@lilypond[]
+@lilypond[noindent,noquote]
\score {
\notes \relative c' {
[c16 c c c c c c c]
\property Voice.subdivideBeams = ##t
[c16 c c c c c c c]
[c32 c c c c c c c c c c c c c c c]
- \property Score.beatLength = #(make-moment 1 8)
+ \property Score.beatLength = #(ly:make-moment 1 8)
[c32 c c c c c c c c c c c c c c c]
}
}
Kneed beams are inserted automatically, when a large gap between two
adjacent beamed notes is detected. This behavior can be tuned through
-the grob property @code{auto-knee-gap}.
+the object property @code{auto-knee-gap}.
@cindex beams, kneed
@cindex kneed beams
@refbugs
-Auto knee beams can not be used together with hara kiri staffs.
+Auto knee beams can not be used together with hara kiri staves.
+
+[TODO from bugs]
+
+The Automatic beamer does not put @strong{unfinished} beams on the
+last notes of a score.
+
+Formatting of ties is a difficult subject. LilyPond often does not
+give optimal results.
@menu
* Setting automatic beam behavior ::
you can use the following:
@example
\property Voice.autoBeamSettings \override
- #'(end * * * *) = #(make-moment 1 4)
+ #'(end * * * *) = #(ly:make-moment 1 4)
@end example
Since the duration of a quarter note is 1/4 of a whole note, it is
-entered as @code{(make-moment 1 4)}.
+entered as @code{(ly:make-moment 1 4)}.
The same syntax can be used to specify beam starting points. In this
example, automatic beams can only end on a dotted quarter note.
@example
\property Voice.autoBeamSettings \override
- #'(end * * * *) = #(make-moment 3 8)
+ #'(end * * * *) = #(ly:make-moment 3 8)
@end example
In 4/4 time signature, this means that automatic beams could end only on
3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
It is not possible to specify beaming parameters for beams with mixed
durations, that differ from the beaming parameters of all separate
durations, i.e., you'll have to specify manual beams to get:
-@lilypond[fragment,singleline,relative]
+
+@lilypond[singleline,fragment,relative,noverbatim]
\property Voice.autoBeamSettings
- \override #'(end * * * *) = #(make-moment 3 8)
+ \override #'(end * * * *) = #(ly: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
-
It is not possible to specify beaming parameters that act differently in
different parts of a measure. This means that it is not possible to use
automatic beaming in irregular meters such as @code{5/8}.
@file{ly/property-init.ly}.
@cindex @file{property-init.ly}
-The normal way of using the macros is to enter the macro name right after the
+The macros operate on the ``Current'' context (see @ref{Context properties}). This
+means that the macros shuold normally be invoked right after the
creation of the context in which the accidental typesetting described
by the macro is to take effect. I.e. if you want to use
piano-accidentals in a pianostaff then you issue
@lilypond[singleline,fragment,verbatim]
\property Staff.autoAccidentals = #'( Staff (any-octave . 0) )
-cis'4 <c'' c'> r2 | cis'4 <c' c''> r2 | <cis' c''> r | <c'' cis'> r |
+cis'4 <<c'' c'>> r2 | cis'4 <<c' c''>> r2 | <<cis' c''>> r | <<c'' cis'>> r |
@end lilypond
The only solution is to manually insert the problematic
* Breath marks::
* Tempo::
* Text spanners::
+* Analysis brackets::
@end menu
@node Slurs
Slurs avoid crossing stems, and are generally attached to note heads.
However, in some situations with beams, slurs may be attached to stem
ends. If you want to override this layout you can do this through the
-grob-property @code{attachment} of @internalsref{Slur} in
+object property @code{attachment} of @internalsref{Slur} in
@internalsref{Voice} context It's value is a pair of symbols, specifying
the attachment type of the left and right end points.
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 @internalsref{Slur}'s grob-property @code{beautiful}.
+decision is in @internalsref{Slur}'s object 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
@end lilypond
Typographically, the phrasing slur behaves almost exactly like a normal
-slur. See also @seeinternals{PhrasingSlur}.
+slur. See also @seeinternals{PhrasingSlur}. But although they behave
+similarily to normal slurs, phrasing slurs count as different objects.
+A @code{\slurUp} will have no effect on a phrasing slur; instead, you
+should use @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and
+@code{\phrasingSlurBoth}.
+Note that the commands
+@code{\slurUp}, @code{\slurDown}, and @code{\slurBoth} will only affect
+normal slurs and not phrasing slurs.
@node Breath marks
@subsection Breath marks
dotted line. You can create such texts using text spanners. The syntax
is as follows:
@example
-\spanrequest \start "text"
-\spanrequest \stop "text"
+ \startTextSpan
+ \stopTextSpan
@end example
-LilyPond will respond by creating a @internalsref{TextSpanner} grob (typically
+LilyPond will respond by creating a @internalsref{TextSpanner} object (typically
in @internalsref{Voice} context). The string to be printed, as well as the
-style is set through grob properties.
+style is set through object properties.
An application---or rather, a hack---is to fake octavation indications.
@lilypond[fragment,relative,verbatim]
\property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
\property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
\property Staff.centralCPosition = #-13
- a\spanrequest \start "text" b c a \spanrequest \stop "text" }
+ a\startTextSpan b c a \stopTextSpan }
@end lilypond
+@node Analysis brackets
+@subsection Analysis brackets
+@cindex brackets
+@cindex phrasing brackets
+@cindex musicological analysis
+@cindex note grouping bracket
+
+Brackets are used in musical analysis to indicate structure in musical
+pieces. LilyPond supports a simple form of nested horizontal brackets.
+To use this, add the @internalsref{Horizontal_bracket_engraver} to
+@internalsref{Staff} context. A bracket is started with
+@code{\groupOpen} and closed with @code{\groupClose}. This produces
+@internalsref{HorizontalBracket} objects.
+
+@lilypond[singleline,verbatim]
+\score { \notes \relative c'' {
+ c4-\groupOpen-\groupOpen
+ c4-\groupClose
+ c4-\groupOpen
+ c4-\groupClose-\groupClose
+ }
+ \paper { \translator {
+ \StaffContext \consists "Horizontal_bracket_engraver"
+ }}}
+@end lilypond
+
@c . {Ornaments}
@node Ornaments
@section Ornaments
c''4-|_"c-|" s4
c''4->_"c->" s4
c''4-^_"c-\\^{ }" s4
+ c''4-__"c-\_" s4
}
}
@end lilypond
@cindex staccatissimo
@cindex fermata
@cindex stopped
-@cindex staccato
+@cindex staccato
+@cindex portato
@cindex tenuto
@cindex upbow
@cindex downbow
\property Score.LyricText \override #'font-shape = #'upright
\context Staff \notes {
c''-\accent c''-\marcato c''-\staccatissimo c''^\fermata
- c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
+ c''-\stopped c''-\staccato c''-\tenuto c''-\portato
+ c''-\upbow
c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
c''-\rtoe c''-\turn c''-\open c''-\flageolet
c''-\reverseturn c''-\trill c''-\prall c''-\mordent
}
\context Lyrics \lyrics {
accent__ marcato__ staccatissimo__ fermata
- stopped__ staccato__ tenuto__ upbow
+ stopped__ staccato__ tenuto__ portato
+ upbow
downbow__ lheel__ rheel__ ltoe
rtoe__ turn__ open__ flageolet
reverseturn__ trill__ prall__ mordent
}
>
\paper {
- linewidth = 5.875\in
- indent = 0.0
+ linewidth = 5.1\in
+ indent = 0.0\mm
}
}
@end lilypond
@end lilypond
-@cindex @code{\script}
@cindex scripts
@cindex superscript
@cindex subscript
It is possible to use @TeX{} commands in the strings, but this should be
avoided because it makes it impossible for LilyPond to compute the
exact length of the string, which may lead to collisions. Also, @TeX{}
-commands won't work with direct PostScript output (see @ref{PostScript
-output}).
+commands won't work with direct PostScript output.
+@c (see @ref{PostScript output}).
-Text scripts are created in form of @internalsref{TextScript} grobs, in
+Text scripts are created in form of @internalsref{TextScript} objects, in
@internalsref{Voice} context.
@ref{Text markup} describes how to change the font or access
@cindex ornaments
@cindex grace notes
-Grace notes are ornaments are written out ornaments
-@lilypond[relative=2,verbatim,ifragment]
- c4 \grace c16 c4 \grace { [c16 d16] } c4
+Grace notes are ornaments that are written out
+@lilypond[relative=2,verbatim,ifragment] c4 \grace c16 c4 \grace {
+[c16 d16] } c4
@end lilypond
In normal notation, grace notes are supposed to take up no logical
@end lilypond
The placement of these grace notes is synchronized between different
-staffs, using this grace timing.
+staves, using this grace timing.
@lilypond[relative=2,verbatim,fragment]
< \context Staff = SA { e4 \grace { c16 d e f } e4 }
Unbeamed eighth notes and shorter by default have a slash through the
-stem. This can be controlled with grob property @code{flag-style} of
+stem. This can be controlled with object property @code{stroke-style} of
@internalsref{Stem}. The change in formatting is accomplished by
inserting @code{\startGraceMusic} before handling the grace notes, and
-@code{\stopGraceMusic} after finishing the grace notes. You can add to
-these definitions to globally change grace note formatting. The
-standard definitions are in @file{ly/grace-init.ly}.
+@code{\stopGraceMusic} after finishing the grace notes.
+You can add to these definitions to globally change grace note
+formatting. The standard definitions are in @file{ly/grace-init.ly}.
+[TODO discuss Scheme functionality.]
+
+
+Notice how the @code{\override} is carefully matched with a @code{\revert}.
+
+@cindex slash
+@cindex grace slash
@lilypond[fragment,verbatim]
\relative c'' \context Voice {
\grace c8 c4 \grace { [c16 c16] } c4
\grace {
- \property Voice.Stem \override #'flag-style = #'()
+ \property Voice.Stem \override #'stroke-style = #'()
c16
- \property Voice.Stem \revert #'flag-style
+ \property Voice.Stem \revert #'stroke-style
} c4
}
@end lilypond
+
+
+If you want to end a note with a grace note, then the standard trick
+is to put the grace notes before a phantom ``space note'', e.g.
+@lilypond[fragment,verbatim, relative=2]
+\context Voice {
+ < { d1^\trill ( }
+ { s2 \grace { [c16 d] } } >
+ )c4
+}
+@end lilypond
+
+A @code{\grace} section has some default values, and LilyPond will
+use those default values unless you specify otherwise inside the
+@code{\grace} section. For example, if you specify \slurUp
+@emph{before} your @code{\grace} section, a slur which starts inside
+the @code{\grace} won't be forced up, even if the slur ends outside
+of the @code{\grace}. Note the difference between the first and
+second bars in this example:
+
+@lilypond[fragment,verbatim]
+\relative c'' \context Voice {
+ \slurUp
+ \grace {
+ a4 ( }
+ ) a4 a4 () a2
+ \slurBoth
+
+ \grace {
+ \slurUp
+ a4 ( }
+ ) a4 a4 () a2
+ \slurBoth
+
+}
+@end lilypond
+
+
@refbugs
+Grace notes can not be used in the smallest size (@file{paper11.ly}).
+
Grace note synchronization can also lead to surprises. Staff notation,
such as key signatures, barlines, etc. are also synchronized. Take
-care when you mix staffs with grace notes and staffs without.
+care when you mix staves with grace notes and staves without.
@lilypond[relative=2,verbatim,fragment]
< \context Staff = SA { e4 \bar "|:" \grace c16 d4 }
grace section is not supported, and might produce crashes or other
errors.
-@menu
-* Glissando ::
-* Dynamics::
-@end menu
-
-
-@c . {Glissando}
@node Glissando
@subsection Glissando
@cindex Glissando
@cindex diminuendo
-Dynamics are grobs of @internalsref{DynamicText} and
+Dynamics are objects of @internalsref{DynamicText} and
@internalsref{Hairpin}. Vertical positioning of these symbols is
-handled by the @internalsref{DynamicLineSpanner} grob. If you want to
+handled by the @internalsref{DynamicLineSpanner} object. If you want to
adjust padding or vertical direction of the dynamics, you must set
-properties for the @internalsref{DynamicLineSpanner} grob. Predefined
+properties for the @internalsref{DynamicLineSpanner} object. Predefined
identifiers to set the vertical direction are \dynamicUp and
\dynamicDown.
@item 'end-repeat
Print a :| bar line
@item (volta . @var{text})
- Print a volta bracket saying @var{text}.
+ Print a volta bracket saying @var{text}.
@item (volta . #f)
- Stop a running volta bracket
+ Stop a running volta bracket
@end table
@lilypond[verbatim, fragment]
@end lilypond
-Repeats brackets are @internalsref{VoltaBracket} grobs.
+Repeats brackets are @internalsref{VoltaBracket} objects.
@node Tremolo repeats
@subsection Tremolo repeats
}
@end lilypond
-Tremolo beams are @internalsref{Beam} grobs. Single stem tremolos are
+Tremolo beams are @internalsref{Beam} objects. Single stem tremolos are
@internalsref{StemTremolo}. The single stem tremolo @emph{must} be
entered without @code{@{} and @code{@}}.
}
@end lilypond
-The signs are represented by these grobs: @internalsref{RepeatSlash} and
+The signs are represented by these objects: @internalsref{RepeatSlash} and
@internalsref{PercentRepeat} and @internalsref{DoublePercentRepeat}.
@refbugs
Currently the following lists are defined in @file{scm/drums.scm}:
@table @code
@item 'drums
-To typeset a typical drum kit on a five line staff.
-@lilypond[]
+To typeset a typical drum kit on a five-line staff.
+
+@lilypond[noindent]
\include "drumpitch-init.ly"
nam = \lyrics { cymc cyms cymr hh hhc hho hhho hhp cb hc
bd sn ss tomh tommh tomml toml tomfh tomfl }
\context Lyrics \nam
>
\paper {
+ linewidth = 100.0\mm
\translator {
\StaffContext
\remove Bar_engraver
}
}
@end lilypond
+
Notice that the scheme supports six different toms.
If you are using fewer toms then you simply select the toms that produce
the desired result - i.e. to get toms on the three middle lines you
@lilypond[singleline, verbatim]
#(define mydrums `(
- (bassdrum default #f ,(make-pitch -1 2 0))
- (snare default #f ,(make-pitch 0 1 0))
- (hihat cross #f ,(make-pitch 0 5 0))
- (pedalhihat xcircle "stopped" ,(make-pitch 0 5 0))
- (lowtom diamond #f ,(make-pitch -1 6 0))
+ (bassdrum default #f ,(ly:make-pitch -1 2 0))
+ (snare default #f ,(ly:make-pitch 0 1 0))
+ (hihat cross #f ,(ly:make-pitch 0 5 0))
+ (pedalhihat xcircle "stopped" ,(ly:make-pitch 0 5 0))
+ (lowtom diamond #f ,(ly:make-pitch -1 6 0))
))
\include "drumpitch-init.ly"
up = \notes { hh8 hh hh hh hhp4 hhp }
@example
#(define mydrums (append `(
- (bassdrum default #f ,(make-pitch -1 2 0))
- (lowtom diamond #f ,(make-pitch -1 6 0))
+ (bassdrum default #f ,(ly:make-pitch -1 2 0))
+ (lowtom diamond #f ,(ly:make-pitch -1 6 0))
) drums ))
@end example
up = \notes { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat }
down = \notes { bassdrum4 snare8 bd r bd sn4 }
\include "nederlands.ly"
-bass = \notes \transpose c, { a4. e8 r e g e }
+bass = \notes \transpose c c,, { a4. e8 r e g e }
\score {
<
\apply #(drums->paper 'drums) \context Staff = drums <
behavior. In this section we discuss the @internalsref{PianoStaff} and some
other pianistic peculiarities.
+
@menu
* Automatic staff changes::
* Manual staff switches::
* Voice follower lines::
@end menu
+@refbugs
+
+There is no support for putting chords across staves. You can get
+this result by increasing the length of the stem in the lower stave so
+it reaches the stem in the upper stave, or vice versa. An example is
+included with the distribution as @file{input/test/stem-cross-staff.ly}.
+
+@cindex cross staff stem
+@cindex stem, cross staff
+
+
+@c fixme: should have hyperlinks as well.
+
+
+
@c . {Automatic staff changes}
@node Automatic staff changes
@code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
@code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
-These identifiers are shorthands for spanner commands of the types
-@internalsref{Sustain}, @internalsref{UnaCorda} and @internalsref{Sostenuto}:
-
-@lilypond[fragment,verbatim]
-c''4 \spanrequest \start "Sustain" c''4
-c''4 \spanrequest \stop "Sustain"
-@end lilypond
-
The symbols that are printed can be modified by setting
@code{pedal@var{X}Strings}, where @var{X} is one of the pedal types:
Sustain, Sostenuto or UnaCorda. Refer to the generated documentation of
-@rgrob{SustainPedal}, for example, for more information.
+@internalsref{SustainPedal}, for example, for more information.
Pedals can also be indicated by a sequence of brackets, by setting the
-@code{pedal-type} property of SustainPedal grobs:
+@code{pedal-type} property of SustainPedal objects:
@lilypond[fragment,verbatim]
\property Staff.SustainPedal \override #'pedal-type = #'bracket
For fine-tuning of the appearance of a pedal bracket, the properties
@code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
-@code{PianoPedalBracket} grobs (see the detailed documentation of
+@code{PianoPedalBracket} objects (see the detailed documentation of
@rgrob{PianoPedalBracket}) can be modified. For example, the bracket
may be extended to the end of the note head.
f'4 g'4 a'4 \sostenutoUp
@end lilypond
-
-
-@c . {Arpeggio}
@node Arpeggio
@subsection Arpeggio
@cindex Arpeggio
@cindex @code{\arpeggio}
You can specify an arpeggio sign on a chord by attaching an
-@code{\arpeggio} to a note of the chord.
+@code{\arpeggio} to a chord.
@lilypond[fragment,relative,verbatim]
- \context Voice <c\arpeggio e g c>
+ <<c e g c>>-\arpeggio
@end lilypond
When an arpeggio crosses staves in piano music, you attach an arpeggio
@lilypond[fragment,relative,verbatim]
\context PianoStaff <
\property PianoStaff.connectArpeggios = ##t
- \context Voice = one { <c'\arpeggio e g c> }
- \context Voice = other { \clef bass <c,,\arpeggio e g>}
+ \context Voice = one { <<c' e g c>>-\arpeggio }
+ \context Voice = other { \clef bass <<c,, e g>>-\arpeggio}
>
@end lilypond
-This command creates @internalsref{Arpeggio} grobs. Cross staff arpeggios
+This command creates @internalsref{Arpeggio} objects. Cross staff arpeggios
are @code{PianoStaff.Arpeggio}.
To add an arrow head to explicitly specify the direction of the
-arpeggio, you should set the arpeggio grob property
+arpeggio, you should set the arpeggio object property
@code{arpeggio-direction}.
@lilypond[fragment,relative,verbatim]
\context Voice {
\property Voice.Arpeggio \set #'arpeggio-direction = #1
- <c\arpeggio e g c>
+ <<c e g c>>-\arpeggio
\property Voice.Arpeggio \set #'arpeggio-direction = #-1
- <c\arpeggio e g c>
+ <<c e g c>>-\arpeggio
}
@end lilypond
A square bracket on the left indicates that the player should not
arpeggiate the chord. To draw these brackets, set the
@code{molecule-callback} property of @code{Arpeggio} or
-@code{PianoStaff.Arpeggio} grobs to @code{\arpeggioBracket}, and use
+@code{PianoStaff.Arpeggio} objects to @code{\arpeggioBracket}, and use
@code{\arpeggio} statements within the chords as before.
@lilypond[fragment,relative,verbatim]
\property PianoStaff.connectArpeggios = ##t
\property PianoStaff.Arpeggio \override
#'molecule-callback = \arpeggioBracket
- \context Voice = one { <c'\arpeggio e g c> }
- \context Voice = other { \clef bass <c,,\arpeggio e g>}
+ \context Voice = one { <<c' e g c>>-\arpeggio }
+ \context Voice = other { \clef bass <<c,, e g>>-\arpeggio }
>
@end lilypond
>
@end lilypond
-The associated grob is @internalsref{VoiceFollower}.
+The associated object is @internalsref{VoiceFollower}.
@node Tablatures
@section Tablatures
-Tablature notation is used music for plucked string instruments. It
-notates pitches not by using note heads, but by indicating on which
-string and fret a note must be played. LilyPond offers limited
-support for tablature, by abusing the fingering system.
+Tablature notation is used for notating music for plucked string
+instruments. It notates pitches not by using note heads, but by
+indicating on which string and fret a note must be played. LilyPond
+offers limited support for tablature.
@menu
* Tablatures basic::
Tablature can be typeset with Lilypond by using the
@internalsref{TabStaff} and @internalsref{TabVoice} contexts. As
tablature is a recent feature in Lilypond, most of the guitar special
-effects such as hammer, pull, bend are not yet supported.
+effects such as bend are not yet supported.
With the @internalsref{TabStaff}, the string number associated to a note
-is given though the fingering mechanism, e.g. @code{c4-3} for a C
-quarter on the third string. The string 1 is the lowest one, and the
+is given as a backslash followed by the string number, e.g. @code{c4\3} for a C
+quarter on the third string. By default, string 1 is the highest one, and the
tuning defaults to the standard guitar tuning (with 6 strings).
@lilypond[fragment,verbatim]
\context TabStaff <
\notes {
- \property Staff.Stem \override #'direction = #1
-
- a,4-2 c'-5 a-4 e'-6
- e-3 c'-5 a-4 e'-6
+ a,4\5 c'\2 a\3 e'\1
+ e\4 c'\2 a\3 e'\1
}
>
@end lilypond
+If you do not specify a string number then lilypond automatically selects one.
+The selection is controlled by the translator property @code{minimumFret}. -- LilyPond
+simply selects the first string that does not give a fret number less than
+@code{minimumFret}. Default is 0.
+
+Notice that LilyPond does not handle chords in any special way, and hence
+the automatic string selector may easily select the same string to two notes in a chord.
+
+@example
+e8 fis gis a b cis' dis' e'
+\property TabStaff.minimumFret = #8
+e8 fis gis a b cis' dis' e'
+@end example
+@lilypond[noindent,noquote]
+frag = \notes {
+ \key e \major
+ e8 fis gis a b cis' dis' e'
+ \property TabStaff.minimumFret = #8
+ e8 fis gis a b cis' dis' e'
+}
+\score {
+ \context StaffGroup <
+ \context Staff { \clef "G_8" \frag }
+ \context TabStaff { \frag }
+ >
+}
+@end lilypond
@node Non-guitar tablatures
@subsection Non-guitar tablatures
There are many ways to customize Lilypond tablatures.
First you can change the number of strings, by setting the number of
-lines in the @internalsref{TabStaff}. You can change the strings
+lines in the @internalsref{TabStaff} (the @code{line-count} property
+of TabStaff can only be changed using @code{\outputproperty}, for more
+information, see @ref{Tuning per object}. You can change the strings
tuning. A string tuning is given as a Scheme list with one integer
number for each string, the number being the pitch of an open string.
+(The numbers specified for stringTuning are the numbers of semitons
+to subtract --- or add --- starting the specified pitch by default
+middle C, in string order: thus the notes are e, a, d & g)
+
+@lilypond[fragment,verbatim]
+ \context TabStaff <
+
+ \outputproperty #(make-type-checker 'staff-symbol-interface)
+ #'line-count = #4
+ \property TabStaff.stringTunings = #'(-5 -10 -15 -20)
+
+ \notes {
+ a,4 c' a e' e c' a e'
+ }
+ >
+@end lilypond
+
Finally, it is possible to change the Scheme function to format the
tablature note text. The default is @var{fret-number-tablature-format},
which uses the fret number, but for some instruments that may not use
the fingering information (which correspond to the string number) for
the standard staff.
-@lilypond[verbatim]
- part = \notes {
+@c FIXME
+@c @lily pond[verbatim]
+@example
+ part = \notes @{
a,4-2 c'-5 a-4 e'-6
e-3 c'-5 a-4 e'-6
- }
- \score{
+ @}
+ \score @{
\context StaffGroup <
\context Staff <
% Hide fingering number
\part
>
>
- }
-@end lilypond
-
+ @}
+@end example
+@c @end lilypond
@c . {Chords}
@node Chords
LilyPond has support for both entering and printing chords.
@lilypond[verbatim,singleline]
-twoWays = \notes \transpose c'' {
+twoWays = \notes \transpose c c' {
\chords {
c1 f:sus4 bes/f
}
- <c e g>
- <f bes c'>
- <f bes d'>
+ <<c e g>>
+ <<f bes c'>>
+ <<f bes d'>>
}
\score {
using @code{\transpose}.
@lilypond[fragment,verbatim]
-\transpose c'' {
+\transpose c c' {
\chords {
c1 c:3- c:7 c:8
c:9 c:9-.5+.7+ c:3-.5-
which replaces the 5th with a 4th.
@lilypond[fragment,verbatim]
-\transpose c'' {
+\transpose c c' {
\chords {
c1:m c:min7 c:maj c:aug c:dim c:sus
}
separated by dots.
@lilypond[fragment,verbatim,center]
- \transpose c'' {
+ \transpose c c' {
\chords {
c1^3 c:7^5.3 c:8^7
}
is not in the chord, a warning will be printed.
@lilypond[fragment,verbatim,center]
- \transpose c''' {
+ \transpose c c'' {
\chords {
c1 c/e c/g c:7/e
}
so it becomes the lowest note in the chord.
@lilypond[fragment,verbatim,center]
- \transpose c''' {
+ \transpose c c'' {
\chords {
c1 c/+c c/+g c:7/+b
}
@lilypond[verbatim,singleline]
scheme = \notes {
- \chords {a1 b c} <d f g> <e g b>
+ \chords {a1 b c} <<d f g>> <<e g b>>
}
\score {
\notes<
\context ChordNames \scheme
- \context Staff \transpose c'' \scheme
+ \context Staff \transpose c c' \scheme
>
}
@end lilypond
\context ChordNames {
\property ChordNames.chordChanges = ##t
\scheme }
- \context Staff \transpose c'' \scheme
+ \context Staff \transpose c c' \scheme
>
\paper{linewidth= 9.\cm}
}
@lilypond[verbatim,center,singleline]
scheme = \notes {
- <c'1 e' g'>
- <e' g' c''>
- <e e' g' c''>
+ <<c' e' g'>>1
+ <<e' g' c''>>
+ <<e e' g' c''>>
}
\score {
By default, a chord name system proposed by Harald Banter (See
@ref{Literature}) is used. The system is very regular and predictable.
Typical American style chord names may be selected by setting the
-@code{style} property of the @code{ChordNames.ChordName} grob to
+@code{style} property of the @code{ChordNames.ChordName} object to
@code{'american}. Similarly @code{'jazz} selects Jazz chordnames.
Routines that determine the names to be printed are written in Scheme,
@c too long?
@c maybe just junk verbatim option?
-@lilypond[verbatim,singleline]
+@lilypond[verbatim,singleline,noquote]
scheme = \chords {
c1 c:5^3 c:4^3 c:5+
c:m7+ c:m5-.7
\context ChordNames = jazz {
\property ChordNames.ChordName \override
#'style = #'jazz \scheme }
- \context Staff \transpose c'' \scheme
+ \context Staff \transpose c c' \scheme
>
}
@end lilypond
c1 \mark \default
c1 \mark "12"
c1 \mark \default
- c1 \mark #'(music "scripts-segno")
c1
}
@end lilypond
As you can see, the mark is incremented automatically if you use
@code{\mark \default}. The value to use is stored in the property
-@code{rehearsalMark} is used and automatically incremented. The grob
+@code{rehearsalMark} is used and automatically incremented. The object
is @internalsref{RehearsalMark} in @internalsref{Score} context. See
@code{input/test/boxed-molecule.ly} if you need boxes around the
marks.
+The @code{\mark} command can also be used to put signs like coda,
+segno and fermatas on a barline. The trick is to use the text markup
+mechanism to access the fermata symbol.
+@lilypond[fragment,verbatim,relative=1]
+ c1 \mark #'(music "scripts-ufermata")
+ c1
+@end lilypond
+
+The problem is that marks that occur at a line break are typeset only
+at the beginning of the next line, opposite to what you want for the
+fermata. This can be corrected by the following property setting
+@example
+\property Score.RehearsalMark \override
+ #'visibility-lambda = #begin-of-line-invisible
+@end example
+
+@cindex fermatas
+@cindex coda
+@cindex segno
+@cindex barlines, putting symbols on
+
+
@node Bar numbers
@subsection Bar numbers
Bar numbers are printed by default at the start of the line. The
number itself is a property that can be set by modifying the
-@code{currentBarNumber} property, i.e.
+@code{currentBarNumber} property, although that is usually not
+necessary, i.e.
@example
\property Score.currentBarNumber = #217
@end example
-If you want boxed bar numbers, see the example file
-@code{input/test/boxed-molecule.ly}.
+To typeset Bar Numbers at regular intervals instead of at the beginning of each line,
+you need to change the grob property @code{break-visibility} as well as the translator
+property @code{barNumberVisibility}, as illustrated in the following example which also
+adds a box around the bar numbers:
+@example
+\property Score.BarNumber \override #'break-visibility =
+ #end-of-line-invisible
+\property Score.barNumberVisibility = #(every-nth-bar-number-visible 5)
+\property Score.BarNumber \override #'molecule-callback =
+ #(make-molecule-boxer 0.1 0.25 0.25 Text_item::brew_molecule)
+\property Score.BarNumber \override #'font-relative-size = #0
+@end example
+@lilypond[noindent,noquote]
+\score {
+ \context Staff \notes \transpose c c'' {
+ \property Score.BarNumber \override #'break-visibility = #end-of-line-invisible
+ \property Score.barNumberVisibility = #(every-nth-bar-number-visible 5)
+ \property Score.BarNumber \override #'molecule-callback =
+ #(make-molecule-boxer 0.1 0.25 0.25 Text_item::brew_molecule)
+ \property Score.BarNumber \override #'font-relative-size = #0
+
+ \repeat unfold 16 c1 \bar "|."
+ }
+}
+@end lilypond
See also @seeinternals{BarNumber}.
@refbugs
-Printing bar numbers at regular intervals is not implemented.
Barnumbers can collide with the StaffGroup, if there is one at the
top. To solve this, You have to twiddle with the
@internalsref{padding} property of @internalsref{BarNumber} if your
A music expression can be transposed with @code{\transpose}. The syntax
is
@example
- \transpose @var{pitch} @var{musicexpr}
+ \transpose @var{from} @var{to} @var{musicexpr}
@end example
-This means that middle C in @var{musicexpr} is transposed to
-@var{pitch}.
+This means that @var{musicexpr} is transposed to by the interval
+between @var{from} is @var{to}.
@code{\transpose} distinguishes between enharmonic pitches: both
-@code{\transpose cis'} or @code{\transpose des'} will transpose up half
-a tone. The first version will print sharps and the second version
-will print flats.
+@code{\transpose c cis} or @code{\transpose c des} will transpose up
+half a tone. The first version will print sharps and the second
+version will print flats.
@lilypond[singleline, verbatim]
mus =\notes { \key d \major cis d fis g }
\score { \notes \context Staff {
\clef "F" \mus
\clef "G"
- \transpose g'' \mus
- \transpose f'' \mus
+ \transpose c g' \mus
+ \transpose c f' \mus
}}
@end lilypond
Multi measure rests are entered using `@code{R}'. It is specifically
meant for full bar rests and for entering parts: the rest can expand to
-fill a score with
-rests, or it can be printed as a single multimeasure rest This expansion
-is controlled by the property @code{Score.skipBars}. If this is set to true,
-Lily will not expand empty measures, and the appropriate number is added
-automatically.
+fill a score with rests, or it can be printed as a single multimeasure
+rest This expansion is controlled by the property
+@code{Score.skipBars}. If this is set to true, Lily will not expand
+empty measures, and the appropriate number is added automatically.
+
+@lilypond[fragment,verbatim]
+ \time 4/4 r1 | R1 | R1*2
+ \property Score.skipBars = ##t R1*17 R1*4
+@end lilypond
+
+The @code{1} in @code{R1} is similar to the duration notation used for
+notes. Hence, for time signatures other than 4/4, you must enter other
+durations. This can be done with augmentation dots, or with
+fractions:
@lilypond[fragment,verbatim]
- \time 3/4 r2. | R2. | R2.*2
- \property Score.skipBars = ##t R2.*17 R2.*4
+ \property Score.skipBars = ##t
+ \time 3/4
+ R2. | R2.*2
+ \time 13/8
+ R1*13/8
+ R1*13/8*12
@end lilypond
+Notice that a @code{R} spanning a single measure is printed as a whole
+rest centered in the measure, regardless of the time signature.
-Notice that the @code{R2.} is printed as a whole rest, centered in the
-measure.
+[ add note about breves.]
+
@cindex whole rests for a full measure
-The grob for this object is @internalsref{MultiMeasureRest}.
+The object for this object is @internalsref{MultiMeasureRest}, and
+@internalsref{MultiMeasureRestNumber}.
@refbugs
into a single multimeasure rest. Multi measure rests do not take part
in rest collisions.
+Multi-measure rests do not accept @var{note}-@code{text} syntax for
+putting texts and scripts on the rest. This has to be done by setting
+@code{#'text} in @internalsref{MultiMeasureRestNumber}. An identifier is
+provided for a fermata:
+
+@cindex text on multi-measure rest
+@cindex script on multi-measure rest
+@cindex fermata on multi-measure rest
+
+@lilypond[verbatim,fragment]
+ \time 3/4
+ \setMmRestFermata R2.
+@end lilypond
+
+
@cindex condensing rests
@node Automatic part combining
@node Ancient notation
@section Ancient notation
+@cindex Vaticana, Editio
+@cindex Medicaea, Editio
+@cindex hufnagel
+@cindex Petrucci
+@cindex mensural
+
@menu
* Ancient note heads::
-* Custodes::
* Ancient clefs ::
+* Custodes::
+* Ligatures::
* Figured bass::
@end menu
@node Ancient note heads
@subsection Ancient note heads
- To get a longa note head, you have to use mensural note heads. This
+To get a longa note head, you have to use mensural note heads. This
is accomplished by setting the @code{style} property of the
-NoteHead grob to @code{mensural}. There is also a note head style
+NoteHead object to @code{mensural}. There is also a note head style
@code{baroque} which gives mensural note heads for @code{\longa} and
@code{\breve} but standard note heads for shorter notes.
@lilypond[fragment,singleline,verbatim]
\property Voice.NoteHead \set #'style = #'mensural
- \property Voice.NoteHead \set #'font-family = #'ancient
a'\longa
@end lilypond
+@node Ancient clefs
+@subsection Ancient clefs
+
+LilyPond supports a variety of clefs, many of them ancient.
+
+For modern clefs, see section @ref{Clef}. For the percussion clef, see
+section @ref{Percussion staves}. For the @code{TAB} clef, see section
+@ref{Tablatures}.
+
+The following table shows all ancient clefs that are supported via the
+@code{\clef} command. Some of the clefs use the same glyph, but differ
+only with respect to the line they are printed on. In such cases, a
+trailing number in the name is used to enumerate these clefs. Still,
+you can manually force a clef glyph to be typeset on an arbitrary line,
+as described in section @ref{Clef}. The note printed to the right side
+of each clef denotes the @code{c'} with respect to the clef.
+
+@table @code
+
+@c --- This should go somewhere else: ---
+@c @item modern style G clef (glyph: @code{clefs-G})
+@c
+@c Supported clefs:
+@c @code{treble}, @code{violin}, @code{G}, @code{G2}, @code{french}
+@c
+@c @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "G" c'}
+@c
+@c @item modern style F clef (glyph: @code{clefs-F})
+@c
+@c Supported clefs:
+@c @code{varbaritone}, @code{bass}, @code{F}, @code{subbass}
+@c
+@c @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "F" c'}
+@c
+@c @item modern style C clef (glyph: @code{clefs-C})
+@c
+@c Supported clefs:
+@c @code{soprano}, @code{mezzosoprano}, @code{alto}, @code{C},
+@c @code{tenor}, @code{baritone}
+@c
+@c @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "C" c'}
+
+@item modern style mensural C clef (glyph: @code{clefs-neo_mensural_c'})
+
+Supported clefs:
+@code{neo_mensural_c1}, @code{neo_mensural_c2},
+@code{neo_mensural_c3}, @code{neo_mensural_c4}
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "neo_mensural_c2" c'}
+
+@item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c1})
+
+Supported clefs:
+@code{petrucci_c1}
+for 1st staffline
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c1" c'}
+
+@item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c2})
+
+Supported clefs:
+@code{petrucci_c2}
+for 2nd staffline
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c2" c'}
+
+@item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c3})
+
+Supported clefs:
+@code{petrucci_c3}
+for 3rd staffline
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c3" c'}
+
+@item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c4})
+
+Supported clefs:
+@code{petrucci_c4}
+for 4th staffline
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c4" c'}
+
+@item petrucci style mensural C clef (glyph: @code{clefs-petrucci_c5})
+
+Supported clefs:
+@code{petrucci_c5}
+for 5th staffline
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_c5" c'}
+
+@item petrucci style mensural F clef (glyph: @code{clefs-petrucci_f})
+
+Supported clefs:
+@code{petrucci_f}
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_f" c'}
+
+@item petrucci style mensural G clef (glyph: @code{clefs-petrucci_g})
+
+Supported clefs:
+@code{petrucci_g}
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "petrucci_g" c'}
+
+@item historic style mensural C clef (glyph: @code{clefs-mensural_c'})
+
+Supported clefs:
+@code{mensural_c1}, @code{mensural_c2}, @code{mensural_c3},
+@code{mensural_c4}
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "mensural_c2" c'}
+
+@item historic style mensural F clef (glyph: @code{clefs-mensural_f})
+
+Supported clefs:
+@code{mensural_f}
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "mensural_f" c'}
+
+@item historic style mensural G clef (glyph: @code{clefs-mensural_g})
+
+Supported clefs:
+@code{mensural_g}
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "mensural_g" c'}
+
+@item Editio Vaticana style do clef (glyph: @code{clefs-vaticana_do})
+
+Supported clefs:
+@code{vaticana_do1}, @code{vaticana_do2}, @code{vaticana_do3}
+
+@lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "vaticana_do2" c'}
+
+@item Editio Vaticana style fa clef (glyph: @code{clefs-vaticana_fa})
+
+Supported clefs:
+@code{vaticana_fa1}, @code{vaticana_fa2}
+
+@lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "vaticana_fa2" c'}
+
+@item Editio Medicaea style do clef (glyph: @code{clefs-medicaea_do})
+
+Supported clefs:
+@code{medicaea_do1}, @code{medicaea_do2}, @code{medicaea_do3}
+
+@lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "medicaea_do2" c'}
+
+@item Editio Medicaea style fa clef (glyph: @code{clefs-medicaea_fa})
+
+Supported clefs:
+@code{medicaea_fa1}, @code{medicaea_fa2}
+
+@lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "medicaea_fa2" c'}
+
+@item historic style hufnagel do clef (glyph: @code{clefs-hufnagel_do})
+
+Supported clefs:
+@code{hufnagel_do1}, @code{hufnagel_do2}, @code{hufnagel_do3}
+
+@lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "hufnagel_do2" c'}
+
+@item historic style hufnagel fa clef (glyph: @code{clefs-hufnagel_fa})
+
+Supported clefs:
+@code{hufnagel_fa1}, @code{hufnagel_fa2}
+
+@lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property Staff.TimeSignature \set #'transparent = ##t \clef "hufnagel_fa2" c'}
+
+@item historic style hufnagel combined do/fa clef (glyph: @code{clefs-hufnagel_do_fa})
+
+Supported clefs:
+@code{hufnagel_do_fa}
+
+@lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "hufnagel_do_fa" c'}
+
+@c --- This should go somewhere else: ---
+@c @item modern style percussion clef (glyph: @code{clefs-percussion})
+@c
+@c Supported clefs:
+@c @code{percussion}
+@c
+@c @lilypond[26pt]{\property Staff.TimeSignature \set #'transparent = ##t \clef "percussion" c'}
+@c
+@c @item modern style tab clef (glyph: @code{clefs-tab})
+@c
+@c Supported clefs:
+@c @code{tab}
+@c
+@c @lilypond[26pt]{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #6 \property Staff.TimeSignature \set #'transparent = ##t \clef "tab" c'}
+
+@end table
+
+@emph{Modern style} means ``as is typeset in current editions of
+transcribed mensural music''.
+
+@emph{Petrucci style} means ``inspired by printings published by the
+famous engraver Petrucci (1466-1539)''.
+
+@emph{Historic style} means ``as was typeset or written in contemporary
+historic editions (other than those of Petrucci)''.
+
+@emph{Editio XXX style} means ``as is/was printed in Editio XXX''.
+
+Petrucci used C clefs with differently balanced left-side vertical
+beams, depending on which staffline it was printed.
+
@node Custodes
@subsection Custodes
thus helps the player or singer to manage line breaks during
performance, thus enhancing readability of a score.
-@lilypond[verbatim]
+@lilypond[verbatim,noquote]
\score {
\notes { c'1 \break
\property Staff.Custos \set #'style = #'mensural
@}
@end example
-@node Ancient clefs
-@subsection Ancient clefs
+@node Ligatures
+@subsection Ligatures
+
+@cindex Ligatures
+
+@c TODO: Should double check if I recalled things correctly when I wrote
+@c down the following paragraph by heart.
+In musical terminology, a ligature is a coherent graphical symbol that
+represents at least two different notes. Ligatures originally appeared
+in the manuscripts of Gregorian chant notation roughly since the 9th
+century as an allusion to the accent symbols of greek lyric poetry to
+denote ascending or descending sequences of notes. Both, the shape and
+the exact meaning of ligatures changed tremendously during the following
+centuries: In early notation, ligatures where used for monophonic tunes
+(Gregorian chant) and very soon denoted also the way of performance in
+the sense of articulation. With upcoming multiphony, the need for a
+metric system arised, since multiple voices of a piece have to be
+synchronized some way. New notation systems were invented, that used
+the manifold shapes of ligatures to now denote rhythmical patterns
+(e.g. black mensural notation, mannered notation, ars nova). With the
+invention of the metric system of the white mensural notation, the need
+for ligatures to denote such patterns disappeared. Nevertheless,
+ligatures were still in use in the mensural system for a couple of
+decades until they finally disappeared during the late 16th / early 17th
+century. Still, ligatures have survived in contemporary editions of
+Gregorian chant such as the Editio Vaticana from 1905/08.
+
+Syntactically, ligatures are simply enclosed by @code{\[} and @code{\]}.
+Some ligature styles (such as Editio Vaticana) may need additional input
+syntax specific for this particular type of ligature. By default, the
+@internalsref{LigatureBracket} engraver just marks the start and end of
+a ligature by small square angles:
-LilyPond supports a variety of clefs, many of them ancient. These can
-be selected from the @code{ancient} font family, by setting
-@code{Staff.clefGlyph}) to one of the following values
+@lilypond[singleline,verbatim]
+\score {
+ \notes \transpose c c' {
+ \[ g c a f d' \]
+ a g f
+ \[ e f a g \]
+ }
+}
+@end lilypond
-@table @code
-@item clefs-C
- modern style C clef
-@item clefs-F
- modern style F clef
-@item clefs-G
- modern style G clef
-@item clefs-vaticana_do
- Editio Vaticana style do clef
-@item clefs-vaticana_fa
- Editio Vaticana style fa clef
-@item clefs-medicaea_do
- Editio Medicaea style do clef
-@item clefs-medicaea_fa
- Editio Medicaea style fa clef
-@item clefs-mensural1_c
- modern style mensural C clef
-@item clefs-mensural2_c
- historic style small mensural C clef
-@item clefs-mensural3_c
- historic style big mensural C clef
-@item clefs-mensural1_f
- historic style traditional mensural F clef
-@item clefs-mensural2_f
- historic style new mensural F clef
-@item clefs-mensural_g
- historic style mensural G clef
-@item clefs-hufnagel_do
- historic style hufnagel do clef
-@item clefs-hufnagel_fa
- historic style hufnagel fa clef
-@item clefs-hufnagel_do_fa
- historic style hufnagel combined do/fa clef
-@item clefs-percussion
- modern style percussion clef
-@end table
+To select a specific style of ligatures, a proper ligature engraver has
+to be added to the @internalsref{Voice} context, as explained in the
+following subsections. Currently, Lilypond only supports white mensural
+ligatures with certain limitations. Support for Editio Vaticana will be
+added in the future.
-@emph{Modern style} means ``as is typeset in current editions.''
-@emph{Historic style} means ``as was typeset or written in contemporary
-historic editions''. @emph{Editio XXX style} means ``as is/was printed in
-Editio XXX.''
+@menu
+* White mensural ligatures::
+@end menu
-@cindex Vaticana, Editio
-@cindex Medicaea, Editio
-@cindex hufnagel clefs
+@node White mensural ligatures
+@subsubsection White mensural ligatures
+
+@cindex Mensural ligatures
+@cindex White mensural ligatures
+
+Lilypond has limited support for white mensural ligatures. The
+implementation is still experimental; it currently may output strange
+warnings or even crash in some cases or produce weird results on more
+complex ligatures. To engrave white mensural ligatures, in the paper
+block the @internalsref{MensuralLigature} engraver has to be put into
+the @internalsref{Voice} context (and you probably want to remove the
+@internalsref{LigatureBracket} engraver). There is no additional input
+language to describe the shape of a white mensural ligature. The shape
+is rather determined solely from the pitch and duration of the enclosed
+notes. While this approach may take a new user quite a while to get
+accustomed, it has a great advantage: this way, lily has full musical
+information about the ligature. This is not only required for correct
+MIDI output, but also allows for automatic transcription of the
+ligatures.
+
+Example:
+@lilypond[singleline,verbatim]
+\score {
+ \notes \transpose c c' {
+ \property Score.timing = ##f
+ \property Score.defaultBarType = "empty"
+ \property Voice.NoteHead \set #'style = #'neo_mensural
+ \property Staff.TimeSignature \set #'style = #'neo_mensural
+ \clef "petrucci_g"
+ \[ g\longa c\breve a\breve f\breve d'\longa \]
+ s4
+ \[ e1 f1 a\breve g\longa \]
+ }
+ \paper {
+ \translator {
+ \VoiceContext
+ \remove Ligature_bracket_engraver
+ \consists Mensural_ligature_engraver
+ }
+ }
+}
+@end lilypond
+
+Without replacing @code{Ligature_bracket_engraver} with
+@code{Mensural_ligature_engraver}, the same music transcribes to the
+following:
+
+@lilypond[singleline,verbatim]
+\score {
+ \notes \transpose c c' {
+ \property Score.timing = ##f
+ \property Score.defaultBarType = "empty"
+ \property Voice.NoteHead \set #'style = #'neo_mensural
+ \property Staff.TimeSignature \set #'style = #'neo_mensural
+ \clef "petrucci_g"
+ \[ g\longa c\breve a\breve f\breve d'\longa \]
+ s4
+ \[ e1 f1 a\breve g\longa \]
+ }
+}
+@end lilypond
@node Figured bass
@subsection Figured bass
The support for figured bass consists of two parts: there is an input
mode, introduced by @code{\figures}, where you can enter bass figures
as numbers, and there is a context called @internalsref{FiguredBass}
-that takes care of making @internalsref{BassFigure} grobs.
+that takes care of making @internalsref{BassFigure} objects.
In figures input mode, a group of bass figures is delimited by
@code{<} and @code{>}. The duration is entered after the @code{>}.
where you want to override its decisions. In this section we discuss
ways to do just that.
-Formatting is internally done by manipulating so called grobs (graphic
-objects). Each grob carries with it a set of properties (grob
-properties) specific to that object. For example, a stem grob has
+Formatting is internally done by manipulating so called objects (graphic
+objects). Each object carries with it a set of properties (object
+properties) specific to that object. For example, a stem object has
properties that specify its direction, length and thickness.
The most direct way of tuning the output is by altering the values of
these properties. There are two ways of doing that: first, you can
-temporarily change the definition of a certain type of grob, thus
+temporarily change the definition of a certain type of object, thus
affecting a whole set of objects. Second, you can select one specific
-object, and set a grob property in that object.
+object, and set a object property in that object.
@menu
-* Tuning groups of grobs ::
-* Tuning per grob ::
+* Tuning groups of objects ::
+* Tuning per object ::
* Font selection::
* Text markup::
@end menu
-@node Tuning groups of grobs
-@subsection Tuning groups of grobs
-
-@cindex grob description
+@node Tuning groups of objects
+@subsection Tuning groups of objects
+@cindex object description
-
-A grob definition is a Scheme association list, that is stored in a
+A object definition is a Scheme association list, that is stored in a
context property. By assigning to that property (using plain
-@code{\property}), you can change the resulting grobs.
+@code{\property}), you can change the resulting objects.
@lilypond[verbatim, fragment]
c'4 \property Voice.Stem = #'()
@cindex \set
This mechanism is fairly crude, since you can only set, but not modify,
-the definition of a grob. For this reason, there is a more advanced
+the definition of a object. For this reason, there is a more advanced
mechanism.
-The definition of a grob is actually a list of default grob
-properties. For example, the definition of the Stem grob (available in
+The definition of a object is actually a list of default object
+properties. For example, the definition of the Stem object (available in
@file{scm/grob-description.scm}), defines the following values for
@internalsref{Stem}
\set \set \set \set @var{to default value}
@end example
-If there is no default (i.e. by default, the grob property is unset),
+If there is no default (i.e. by default, the object property is unset),
then you can use
@example
\set \set \set \revert
@end example
-For the digirati, the grob description is an Scheme association
+For the digirati, the object description is an Scheme association
list. Since a Scheme list is a singly linked list, we can treat it as a
stack, and @code{\override} and @code{\revert} are just push and pop
operations. This pushing and popping is also used for overriding
@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
+The backend is not very strict in type-checking object properties. If you
@code{\revert} properties that are expected to be set by default,
LilyPond may crash.
-@cindex adjusting staff symbol
-@cindex StaffSymbol, using \property
-@cindex staff lines, setting number of
-
-Some grobs are created at the moment that their context is created. An
-example of such a grob is the staff itself (i.e. the horizontal lines).
-You can not change the appearance of the staff symbol by manipulating
-@code{\property Staff.StaffSymbol}. At the moment that @code{\property
-Staff} is interpreted, a Staff context is made, and the StaffSymbol is
-created before any @code{\override} is effective. You can deal with this
-either overriding properties in a @code{\translator} definition, or by
-using @code{\outputproperty}.
-
+@node Tuning per object
+@subsection Tuning per object
-@node Tuning per grob
-@subsection Tuning per grob
+@cindex \once
+Tuning a single object is most often done with @code{\property}. The
+form,
+@example
+ \once \property @dots{}
+@end example
+@c
+applies a setting only during one moment in the score: notice how the
+original setting for stem thickness is restored automatically in the
+following example
+@c
+@lilypond[verbatim, fragment, relative=1]
+ c4
+ \once \property Voice.Stem \set #'thickness = #4
+ c4
+ c4
+@end lilypond
+@cindex \once
@cindex \outputproperty
-A second way of tuning grobs is the more arcane @code{\outputproperty}
+A second way of tuning objects is the more arcane @code{\outputproperty}
feature. The syntax is as follows:
@example
\outputproperty @var{predicate} @var{symbol} = @var{value}
@end example
-Here @code{predicate} is a Scheme function taking a grob argument, and
+Here @code{predicate} is a Scheme function taking a object argument, and
returning a boolean. This statement is processed by the
@code{Output_property_engraver}. It instructs the engraver to feed all
-grobs that it sees to @var{predicate}. Whenever the predicate returns
-true, the grob property @var{symbol} will be set to @var{value}.
+objects that it sees to @var{predicate}. Whenever the predicate returns
+true, the object property @var{symbol} will be set to @var{value}.
+
+This command is only single shot, in contrast to @code{\override} and
+@code{\set}.
You will need to combine this statement with @code{\context} to select
the appropriate context to apply this to.
-Here are some random examples.
-
-
In the following example, all note heads occurring at current staff
level, are shifted up and right by setting their @code{extra-offset}
property.
\context Staff \outputproperty
#(make-type-checker 'note-head-interface)
#'extra-offset = #'(0.5 . 0.75)
- <c8 e g> }
+ <<c e g>>8 }
@end lilypond
@cindex @code{extra-offset}
-In this example, the predicate checks the @code{text} grob property, to
+In this example, the predicate checks the @code{text} object property, to
shift only the `m.d.' text, but not the fingering instruction "2".
@lilypond[verbatim,singleline]
#(define (make-text-checker text)
- (lambda (grob) (equal? text (ly-get-grob-property grob 'text))))
+ (lambda (grob) (equal? text (ly:get-grob-property grob 'text))))
\score {
\notes\relative c''' {
@cindex cue notes
@cindex font size
@cindex size
+@cindex symbol size
+@cindex glyph size
-The font used for printing a grob can be selected by setting
+The font used for printing a object can be selected by setting
@code{font-name}, e.g.
@example
\property Staff.TimeSignature
fonts or fonts that do not belong to the Computer Modern font family.
Font selection for the standard fonts, @TeX{}'s Computer Modern fonts,
can also be adjusted with a more fine-grained mechanism. By setting
-the grob properties described below, you can select a different font.
-All three mechanisms work for every grob that supports
+the object properties described below, you can select a different font.
+All three mechanisms work for every object that supports
@code{font-interface}.
@table @code
@code{*}, entered as @code{#'*}), acts as a wildcard. This can be used
to override default setting, which are always present. For example:
@example
- \property Lyrics . LyricText \override #'font-series = #'bold
- \property Lyrics . LyricText \override #'font-family = #'typewriter
- \property Lyrics . LyricText \override #'font-shape = #'*
+ \property Lyrics.LyricText \override #'font-series = #'bold
+ \property Lyrics.LyricText \override #'font-family = #'typewriter
+ \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,
+selected through the object property @code{font-style}. For example,
the style @code{finger} selects family @code{number} and relative size
@code{-3}. Styles available include @code{volta}, @code{finger},
@code{tuplet}, @code{timesig}, @code{mmrest}, @code{script},
@cindex magnification
-The size of the font may be scaled with the grob property
+The size of the font may be scaled with the object property
@code{font-magnification}. For example, @code{2.0} blows up all
letters by a factor 2 in both directions.
@end lilypond
Normally, the Scheme markup text is stored in the @code{text} property
-of a grob. Formally, it is defined as follows:
+of a object. Formally, it is defined as follows:
@example
text: string | (head? text+)
@code{large Large dynamic}
@end example
-The markup is broken down and converted into a list of grob properties,
+The markup is broken down and converted into a list of object properties,
which are prepended to the property list. The @var{key}-@var{value}
-pair is a grob property. A list of properties available is included in
-the generated documentation for @rint{Text_interface}.
+pair is a object property. A list of properties available is included in
+the generated documentation for @internalsref{text-interface}.
The following abbreviations are defined:
@table @code
\score {
\notes\relative c'' {
- a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64")
+ a1^#`((columns (font-relative-size . -1))
+ ,dotted-eight-note " = 64")
}
\paper {
linewidth = -1.
The syntax and semantics of markup texts are not clean, and both
syntax and semantics are slated for a rewrite.
+LilyPond does not do kerning, and there generally spaces texts
+slightly too wide.
+
+
+
@node Global layout
@section Global layout
The global layout determined by three factors: the page layout, the
line breaks and the spacing. These all influence each other: The
choice of spacing determines how densely each system of music is set,
-whree line breaks breaks are chosen, and thus ultimately how many
+where line breaks breaks are chosen, and thus ultimately how many
pages a piece of music takes. In this section we will explain how the
lilypond spacing engine works, and how you can tune its results.
are chosen whenever the page gets full.
@menu
-* Spacing::
+* Vertical spacing::
+* Horizontal spacing::
* Font Size::
* Line breaking::
* Page layout::
@end menu
-@node Spacing
-@subsection Spacing
+
+@node Vertical spacing
+@subsection Vertical spacing
+
+@cindex vertical spacing
+@cindex distance between staves
+@cindex staff distance
+@cindex between staves, distance
+@cindex staffs per page
+
+
+The height of each system is determined automatically by lilypond, to
+keep systems from bumping into each other, some minimum distances are
+set. By changing these, you can put staves closer together, and thus
+put more systems onto one page.
+
+Normally staves are stacked vertically. To make
+staves maintain a distance, their vertical size is padded. This is
+done with the property @code{minimumVerticalExtent}. It takes a pair
+of numbers, so if you want to make it smaller from its, then you could
+set
+@example
+ \property Staff.minimumVerticalExtent = #'(-4 . 4)
+@end example
+This sets the vertical size of the current staff to 4 staff-space on
+either side of the center staff line. The argument of
+@code{minimumVerticalExtent} is interpreted as an interval, where the
+center line is the 0, so the first number is generally negative. you
+could also make the staff larger at the bottom by setting it to
+@code{(-6 . 4)}. The default value is @code{(-6 . 6)}.
+
+Vertical aligment of staves is handled by the
+@internalsref{VerticalAlignment} object, which lives at
+@internalsref{Score} level.
+
+The piano staves are handled a little differently: to make cross-staff
+beaming work correctly, it necessary that the distance between staves
+is fixed. This is also done with a @internalsref{VerticalAlignment}
+object, created in @internalsref{PianoStaff}, but a forced distance is
+set. This is done with the object property #'forced-distance. If you
+want to override this, use a @code{\translator} block as follows:
+@example
+ \translator @{
+ \PianoStaffContext
+ VerticalAlignment \override #'forced-distance = #9
+ @}
+@end example
+This would bring the staves together at a distance of 9 staff spaces,
+and again this is measured from the center line of each staff.
+
+
+
+@node Horizontal spacing
+@subsection Horizontal Spacing
The spacing engine translates differences in durations into
stretchable distances (``springs'') of differing lengths. Longer
@end lilypond
These two amounts of space are @code{shortest-duration-space}
-@code{spacing-increment}, grob properties of
+@code{spacing-increment}, object properties of
@internalsref{SpacingSpanner}. Normally @code{spacing-increment} is
set to 1.2, which is the width of a note head, and
@code{shortest-duration-space} is set to 2.0, meaning that the
In the introduction it was explained that stem directions influence
spacing. This is controlled with @code{stem-spacing-correction} in
-@internalsref{NoteSpacing}. The @code{StaffSpacing} grob contains the
+@internalsref{NoteSpacing}. The @code{StaffSpacing} object contains the
same property for controlling the stem/barline spacing. In the
following example shows these corrections, once with default settings,
and once with exaggerated corrections.
@lilypond
\score {
- \context PianoStaff \notes \transpose c''' <
+ \context PianoStaff \notes \transpose c c'' <
\context Staff = up { s1 }
- \context Staff = down { [c8 c \translator Staff=up <c d> c
+ \context Staff = down { [c8 c \translator Staff=up <<c d>> c
\translator Staff=down c c c] }
>
\paper { linewidth = -1 }
""}. Similarly, @code{\noBreak} forbids a line break at a certain
point.
+
+@cindex regular line breaks
+@cindex four bar music.
+
If you want linebreaks at regular intervals, you can use the following:
@example
< \repeat 7 unfold @{ s1 * 4 \break @}
@cindex @code{indent}
@cindex @code{linewidth}
-The most basic settings influencing the spacing are @code{linewidth}
-and @code{indent}, both set in the @code{\paper} block. They control
-the indentation of the first line of music, and the lengths of the
-lines. If @code{linewidth} set to a negative value, a single
+The most basic settings influencing the spacing are @code{indent} and
+@code{linewidth}. They are set in the @code{\paper} block. They
+control the indentation of the first line of music, and the lengths of
+the lines. If @code{linewidth} set to a negative value, a single
unjustified line is produced. A similar effect for scores that are
longer than one line, can be produced by setting @code{raggedright} to
true in the @code{\paper} block.
@cindex @code{interscoreline}
@cindex @code{interscorelinefill}
+If the variable @code{lastpagefill} is defined (that is, it gets any
+value assigned in the @code{\paper} block), systems are evenly
+distributed vertically on the last page. This might produce ugly
+results in case there are not enough systems on the last page. Note
+that @command{lilypond-book} ignores @code{lastpagefill}. See
+@ref{Integrating text and music with lilypond-book} for
+more information.
+
+@cindex @code{lastpagefill}
+
Page breaks are normally computed by @TeX{}, so they are not under
direct control of LilyPond. However, you can insert a commands into
the @file{.tex} output to instruct @TeX{} where to break pages. You
Both loudness controls are combined to produce the final MIDI volume.
-
-
@menu
* MIDI block::
* MIDI instrument names::
projects / lilypond.git / blobdiff