@macro refbugs
@strong{BUGS}
-
@end macro
* Writing parts::
* Ancient notation ::
* Tuning output::
-* Page layout::
-* Output formats::
+* Global layout::
* 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 form of music, but they do not form
+valid input on their own. Yet for the sake of brevity and simplicity,
+we'll generally omit @code{\score} blocks and @code{\paper} declarations.
@menu
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:
@example
Note Names sharp flat
@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 automatically printed, but you may force
+them in the following ways: a reminder accidental
@cindex reminder accidental
@cindex @code{?}
can be forced by adding an exclamation mark @code{!} after the pitch. A
question mark `@code{?}' after the pitch.
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 an `@code{r}' note name:
@lilypond[singleline,verbatim]
r1 r2 r4 r8
@end lilypond
-Whole bar rests centered in the bar are specified using @code{R}, see
+Whole bar rests, centered in the bar, are specified using @code{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 polyphonic music, it can be convenient 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
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
+also works 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
+In Note, Chord, and Lyrics mode, durations are designated by numbers
and dots: durations are entered as their reciprocal values. For notes
longer than a whole you must use identifiers.
@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]
@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.
Durations can also be produced through GUILE extension mechanism.
@lilypond[verbatim,fragment]
@end lilypond
+@refbugs
+
+Dot placement for chords is not perfect. In some cases, dots overlap:
+@lilypond[]
+ \context Voice { <f,4. c'' d e f> }
+@end lilypond
+
+
@node Ties
@subsection Ties
@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, and 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'>
@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
@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.
+And if you need to tie notes over bars, it may be easier to use
+@ref{Automatic note splitting}.
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
+There is a facility for automatically converting long notes to tied
notes. This is done by replacing the @code{Note_heads_engraver} by the
@code{Completion_heads_engraver}.
@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}
note head that includes a note name. It is used in some publications by
Hal-Leonard Inc. music publishers.
-@lilypond[singleline,verbatim]
-\include "paper23.ly"
+@lilypond[singleline,verbatim,26pt]
\score {
\notes { c'2 e'4 f' | g'1 }
\paper { \translator { \EasyNotation } }
@end lilypond
Note that @code{EasyNotation} overrides a @internalsref{Score} context. You
-probably will want to print it with magnification to make it more
+probably will want to print it with magnification or a large font size to make it more
readable.
@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
additional @code{\relative} inside the @code{\transpose}.
-@c . {Bar check}
+@c . {Bar check}
@node Bar check
@subsection Bar check
@cindex Bar check
@c . {Point and click}
@node Point and click
@subsection Point and click
+@cindex poind and click
Point and click lets you find notes in the input by clicking on them in
the Xdvi window. This makes it very easy to find input that causes some
error in the sheet music.
To use it, you need the following software
+@itemize @bullet
+@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}.
+
+@cindex Xdvi
+@cindex KDVI
+@cindex KDE
+
+
+
+@end itemize
+@item An editor with a client/server interface (or a lightweight GUI
+editor).
+
+@cindex editor
@itemize @bullet
-@item
-@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain
-Xdvi} version 22.36 or newer.
-
- Note that most @TeX{} distributions ship with xdvik, which is a
- different and less well maintained program. To find out which xdvi you
- are running, try @code{xdvi --version} or @code{xdvi.bin --version}.
-@item Emacs. Emacs is an extensible text-editor It is available from
-@uref{http://www.gnu.org/software/emacs/}. You need version 21 to use
+@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.
+
+@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}.
+
+@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)
+#(set-point-and-click! 'line)
@end example
+@cindex line-location
-In the emacs startup file (usually @file{~/.emacs}), add the following
+When viewing, Control-Mousebutton 1 will take you to the originating
+spot in the @file{.ly} file. Control-Mousebutton 2 will show all
+clickable boxes.
+
+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
+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
-
-When viewing, Control-Mousebutton 1 will take you to the originating
-spot in the @file{.ly} file. Control-Mousebutton 2 will show all
-clickable boxes.
-
-If you use Emacs version 21, then you can make emacs jump to the exact
-spot (and not just the line) on a click, you must enable column
-positioning. At the top of the @code{ly} file, replace the
-@code{set!} line with the following line
+@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}
+
+For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or use this
+argument with xdvi's @code{-editor} option.
+@cindex NEdit
+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. Users of 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!} line with the following
+line,
@example
-#(set! point-and-click line-column-location)
+#(set-point-and-click! 'line-column)
@end example
-Set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %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.
-
+@cindex line-colomn-location
+and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%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
@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
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 ::
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)
\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
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
\spanrequest \start "text"
\spanrequest \stop "text"
@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]
c''4-|_"c-|" s4
c''4->_"c->" s4
c''4-^_"c-\\^{ }" s4
+ c''4-__"c-\_" s4
}
}
@end lilypond
Other symbols can be added using the syntax
@var{note}@code{-\}@var{name}. Again, they can be forced up or down
using @code{^} and @code{_}.
+
+@cindex accent
+@cindex marcato
+@cindex staccatissimo
+@cindex fermata
+@cindex stopped
+@cindex staccato
+@cindex portato
+@cindex tenuto
+@cindex upbow
+@cindex downbow
+@cindex foot marks
+@cindex organ pedal marks
+@cindex turn
+@cindex open
+@cindex flageolet
+@cindex reverseturn
+@cindex trill
+@cindex prall
+@cindex mordent
+@cindex prallprall
+@cindex prallmordent
+@cindex prall, up
+@cindex prall, down
+@cindex mordent
+@cindex thumb marking
+@cindex segno
+@cindex coda
+
@lilypond[]
\score {
<
\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
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
@lilypond[]
\score { \notes \relative c''{
- c4^"(0,0)" \grace c16_"(1/4,-1/16)" c4^"(1/4,0)" \grace {
- [c16_"(2/4,-1/8)" d16^"(2/4,-1/16)" ] } c4_"(2/4,0)"
+ c4^"(0,0)" \grace c16_" "_"(1/4,-1/16)" c4^"(1/4,0)" \grace {
+ [c16_"(2/4,-1/8)" d16^"(2/4,-1/16)" ] } c4_" "_"(2/4,0)"
}
\paper { linewidth = 8.\cm }
}
@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 }
-\context Staff = SB { c4 \grace { g8 b } c4 }
+< \context Staff = SA { e4 \grace { c16 d e f } e4 }
+ \context Staff = SB { c4 \grace { g8 b } c4 } >
@end lilypond
-The syntax is as follows.
-@example
- \grace @var{musicexpr}
-@end example
-
Unbeamed eighth notes and shorter by default have a slash through the
-stem.
+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}.
+
+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,fragment]
+@lilypond[relative=2,verbatim,fragment]
< \context Staff = SA { e4 \bar "|:" \grace c16 d4 }
\context Staff = SB { c4 \bar "|:" d4 } >
@end lilypond
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
-@internalsref{StemTremolo}.
+Tremolo beams are @internalsref{Beam} objects. Single stem tremolos are
+@internalsref{StemTremolo}. The single stem tremolo @emph{must} be
+entered without @code{@{} and @code{@}}.
@refbugs
-Tremolo beams confuse the spacing engine.
+Only powers of two and undotted notes are supported repeat counts.
@node Tremolo subdivisions
@subsection Tremolo subdivisions
}
@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
@rgrob{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.
>
@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]
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]
>
@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
+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 (used for string number) for the "normal" staff
+ % Hide fingering number
\property Staff.Fingering \override #'transparent = ##t
\part
\part
>
>
- }
-@end lilypond
-
+ @}
+@end example
+@c @end lilypond
@c . {Chords}
@node Chords
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,
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
\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
+\score {
+ \context Staff \notes \transpose 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
will print flats.
@lilypond[singleline, verbatim]
-mus =\notes { \key e \major c d e f }
+mus =\notes { \key d \major cis d fis g }
\score { \notes \context Staff {
\clef "F" \mus
\clef "G"
- \transpose des'' \mus
- \transpose cis'' \mus
+ \transpose g'' \mus
+ \transpose f'' \mus
}}
@end lilypond
@cindex whole rests for a full measure
-The grob for this object is @internalsref{MultiMeasureRest}.
+The object for this object is @internalsref{MultiMeasureRest}.
@refbugs
@node Ancient notation
@section Ancient notation
+@cindex Vaticana, Editio
+@cindex Medicaea, Editio
+@cindex hufnagel
+@cindex Petrucci
+@cindex mensural
+
@menu
* Ancient note heads::
+* Ancient clefs::
* Custodes::
-* Ancient clefs ::
+* 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
@}
@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'' {
+ \[ 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'' {
+ \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'' {
+ \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::
-* Spacing::
@end menu
-@node Tuning groups of grobs
-@subsection Tuning groups of grobs
+@node Tuning groups of objects
+@subsection Tuning groups of objects
-@cindex grob description
+@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.
@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)
@node Font selection
@subsection Font selection
-Most graphics in LilyPond are composed of characters of fonts. You can
-alter the characteristics of the font by setting certain grob
-properties. The mechanism that is used for this resembles La@TeX{}'s New
-Font Selection Scheme. Within this scheme, a font is entirely
-characterized by its font name.
+The most common thing to change about the appearance of fonts is
+their size. The font size of a @internalsref{Voice},
+@internalsref{Staff} or @internalsref{Thread} context, can be easily
+changed by setting the @code{fontSize} property for that context:
+@lilypond[fragment,relative=1]
+ c4 c4 \property Voice.fontSize = #-1
+ f4 g4
+@end lilypond
+ This command will not change the size of variable symbols, such as
+beams or slurs. You can use this command to get smaller symbol for
+cue notes, but that involves some more subtleties. An elaborate
+example of those is in @file{input/test/cue-notes.ly}.
+
+@cindex cue notes
+@cindex font size
+@cindex size
-For each grob that uses fonts (in other words, each grob that supports
-@code{font-interface}) a font-name must be selected before it can be
-printed. The font name is selected by looking at a number of grob
-properties:
+The font used for printing a object can be selected by setting
+@code{font-name}, e.g.
+@example
+ \property Staff.TimeSignature
+ \set #'font-name = #"cmr17"
+@end example
+You may use any font which is available to @TeX{}, such as foreign
+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 object properties described below, you can select a different font.
+All three mechanisms work for every object that supports
+@code{font-interface}.
@table @code
@item font-family
@code{roman} (Computer Modern), @code{braces} (for piano staff
braces), @code{music} (the standard music font), @code{ancient} (the
ancient notation font) @code{dynamic} (font for dynamic signs) and
-@code{typewriter}
-
+@code{typewriter}.
+
@item font-shape
A symbol indicating the shape of the font, there are typically several
font shapes available for each font family. Choices are @code{italic},
This is a feature of the Computer Modern Font: each point size has a
slightly different design. Smaller design sizes are relatively wider,
which enhances readability.
-
-@item font-name
- The name of the font, as a string, e.g. @code{"cmr12"}. This overrides
-all other font-qualifiers.
-You may use this to use special fonts, which are not a part of the
-style sheet, or which have special encodings.
-
@end table
-
-The font is selected by taking the first font that satisfies all
-qualifiers specified. You can override any of these fields through
-@code{\override} and @code{\revert}. The special value @code{*} matches
-any value for that qualifier. The value @code{*} is needed to
-override default settings which are always present.
-
+For any of these properties, the value @code{*} (i.e. the @emph{symbol},
+@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-shape = #'*
+ \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, 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}, @code{large}, @code{Large}
-and @code{dynamic}.
+There are also pre-cooked font selection qualifiers. These are
+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},
+@code{large}, @code{Large} and @code{dynamic}. The style sheets and
+tables for selecting fonts are located in @file{scm/font.scm}. Refer
+to this file for more information.
-The style sheets and tables for selecting fonts are located in
-@file{scm/font.scm}. Refer to this file for more information.
+@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.
-@node Spacing
-@subsection Spacing
+LilyPond does not do kerning, and there generally spaces texts
+slightly too wide.
-S
-
-TODO: Move this section.
-
-@refbugs
-
-
-Generating optically pleasing spacing is black magic. LilyPond tries
-to deal with a number of frequent cases. Here is an example that is
-not handled correctly, due to the combination of chord collisions and
-kneed stems.
-@lilypond
-\score {
- \context PianoStaff \notes \transpose c''' <
- \context Staff = up { s1 }
- \context Staff = down { [c8 c \translator Staff=up <c d> c
-\translator Staff=down c c c] }
- >
- \paper { linewidth = -1 }
-}
-@end lilypond
-The spacing algorithm is global: it searches the entire score for the
-shortest notes. Pieces that have major changes in duration density
-(eg. due to meter changes) will be printed in a uniform density, which
-is undesirable
+@node Global layout
+@section Global layout
-@c . {Page layout}
-@node Page layout
-@section Page layout
-@cindex Page 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,
+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.
-The page layout is the combined product of LilyPond formatting notation,
-and (La)@TeX{} putting the notation on a page, including page breaks.
-The part of LilyPond is documented here.
+Globally spoken, this procedure happens in three steps: first,
+flexible distances (``springs'') are chosen, based on durations. All
+possible line breaking combination are tried, and the one with the
+best results---a layout that has uniform density and requires as
+little stretching or cramping as possible---is chosen. When the score
+is processed by @TeX{}, page are filled with systems, and page breaks
+are chosen whenever the page gets full.
@menu
-* Paper block::
-* Paper variables::
+* Vertical spacing::
+* Horizontal spacing::
* Font Size::
-* Paper size::
-* Line break::
-* Page break::
+* Line breaking::
+* Page layout::
@end menu
-@c . {Paper block}
-@node Paper block
-@subsection Paper block
-@cindex Paper block
-The most important output definition is the @code{\paper} block, for
-music notation. The syntax is
+@node Vertical spacing
+@subsection Vertical spacing
-@example
- @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
-@end example
-
-where each of the items is one of
-
-@itemize @bullet
- @item An assignment.
-
- @item A context definition. See @ref{Interpretation context} for
- more information on context definitions.
-@end itemize
+@cindex vertical spacing
+@cindex distance between staves
+@cindex staff distance
+@cindex between staves, distance
-@c . {Paper variables}
-@node Paper variables
-@subsection Paper variables
-@cindex Paper variables
+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.
-The paper block has some variables you may want to use or change:
+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.
-@table @code
-@cindex @code{indent}
- @item @code{indent}
- The indentation of the first line of music.
-@cindex @code{staffspace}
- @item @code{staffspace}
- The distance between two staff lines, calculated from the center
- of the lines.
-@cindex @code{linewidth}
- @item @code{linewidth}
- Sets the width of the lines.
+@node Horizontal spacing
+@subsection Horizontal Spacing
-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.
+The spacing engine translates differences in durations into
+stretchable distances (``springs'') of differing lengths. Longer
+durations get more space, shorter durations get less. The basis for
+assigning spaces to durations, is that the shortest durations get a
+fixed amount of space, and the longer durations get more: doubling a
+duration adds a fixed amount of space to the note.
-@cindex @code{textheight}
+For example, the following piece contains lots of half, quarter and
+8th notes, the eighth note is followed by 1 note head width. The The
+quarter note is followed by 2 NHW, the half by 3 NHW, etc.
+@lilypond[fragment, verbatim, relative=1]
+ c2 c4. c8 c4. c8 c4. c8 c8 c8 c4 c4 c4
+@end lilypond
- @item @code{textheight}
- Sets the total height of the music on each page. Only used by
-@code{ly2dvi}.
+These two amounts of space are @code{shortest-duration-space}
+@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
+shortest note gets 2 noteheads of space. For normal notes, this space
+is always counted from the left edge of the symbol, so the short notes
+in a score is generally followed by one note head width of space.
+
+If one would follow the above procedure exactly, then adding a single
+32th note to a score that uses 8th and 16th notes, would widen up the
+entire score a lot. The shortest note is no longer a 16th, but a 64th,
+thus adding 2 noteheads of space to every note. To prevent this, the
+shortest duration for spacing is not the shortest note in the score,
+but the most commonly found shortest note. Notes that are even
+shorter this are followed by a space that is proportonial to their
+duration relative to the common shortest note. So if we were to add
+only a few 16th notes to the example above, they would be followed by
+half a NHW:
+
+@lilypond[fragment, verbatim, relative=1]
+ c2 c4. c8 c4. [c16 c] c4. c8 c8 c8 c4 c4 c4
+@end lilypond
-@cindex @code{interscoreline}
+The most common shortest duration is determined as follows: in every
+measure, the shortest duration is determined. The most common short
+duration, is taken as the basis for the spacing, with the stipulation
+that this shortest duration should always be equal to or shorter than
+1/8th note. The shortest duration is printed when you run lilypond
+with @code{--verbose}. These durations may also be customized. If you
+set the @code{common-shortest-duration} in
+@internalsref{SpacingSpanner}, then this sets the base duration for
+spacing. The maximum duration for this base (normally 1/8th), is set
+through @code{base-shortest-duration}.
+
+@cindex @code{common-shortest-duration}
+@cindex @code{base-shortest-duration}
+@cindex @code{stem-spacing-correction}
+@cindex @code{spacing}
+
+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} 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.
- @item @code{interscoreline}
- Sets the spacing between systems. The default is 16pt.
-
-@cindex @code{interscorelinefill}
+@lilypond
+ \score { \notes {
+ c'4 e''4 e'4 b'4 |
+ b'4 e''4 b'4 e''4|
+ \property Staff.NoteSpacing \override #'stem-spacing-correction
+ = #1.5
+ \property Staff.StaffSpacing \override #'stem-spacing-correction
+ = #1.5
+ c'4 e''4 e'4 b'4 |
+ b'4 e''4 b'4 e''4|
+ }
+ \paper { linewidth = -1. } }
+@end lilypond
- @item @code{interscorelinefill}
- If set to a positive number, the distance between the score
- lines will stretch in order to fill the full page. In that
- case @code{interscoreline} specifies the minimum spacing.
- Not set by default.
+@refbugs
-@cindex @code{stafflinethickness}
+Spacing is determined on a score wide basis. If you have a score that
+changes its character (measured in durations) half way during the
+score, the part containing the longer durations will be spaced too
+widely.
- @item @code{stafflinethickness}
- Determines the thickness of staff lines, and also acts as a scaling
- parameter for other line thicknesses.
-@end table
+Generating optically pleasing spacing is black magic. LilyPond tries
+to deal with a number of frequent cases. Here is an example that is
+not handled correctly, due to the combination of chord collisions and
+kneed stems.
-You may enter these dimension using units (@code{cm}, @code{in},
-@code{mm}, @code{pt})
-@example
- linewidth = 20.0 * \staffspace
- indent = 0.5 \cm
-@end example
+@lilypond
+\score {
+ \context PianoStaff \notes \transpose c''' <
+ \context Staff = up { s1 }
+ \context Staff = down { [c8 c \translator Staff=up <c d> c
+\translator Staff=down c c c] }
+ >
+ \paper { linewidth = -1 }
+}
+@end lilypond
@c . {Font size}
@cindex staff size, setting
@cindex @code{paper} file
-The Feta font provides musical symbols at six different sizes. These
-fonts are 11 point, 13 point, 16 point, 20 point, 23 point, and 26
-point. The point size of a font is the height of the five lines in a
-staff when displayed in the font.
+The Feta font provides musical symbols at seven different sizes.
+These fonts are 11 point, 13 point, 16 point, 19 pt, 20 point, 23
+point, and 26 point. The point size of a font is the height of the
+five lines in a staff when displayed in the font.
Definitions for these sizes are the files @file{paperSZ.ly}, where
-@code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
-these files, the identifiers @code{paperEleven}, @code{paperThirteen},
-@code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
-@code{paperTwentysix} are defined respectively. The default
-@code{\paper} block is also set. These files should be imported at toplevel, i.e.
+@code{SZ} is one of 11, 13, 16, 19, 20, 23 and 26. If you include any
+of these files, the identifiers @code{paperEleven},
+@code{paperThirteen}, @code{paperSixteen}, @code{paperNineteen},
+@code{paperTwenty}, @code{paperTwentythree}, and @code{paperTwentysix}
+are defined respectively. The default @code{\paper} block is also
+set. These files should be imported at toplevel, i.e.
@example
\include "paper26.ly"
\score @{ ... @}
details, see the file @file{scm/font.scm}.
-
-@c . {Paper size}
-@node Paper size
-@subsection Paper size
-@cindex Paper size
-
-@cindex paper size
-@cindex page size
-@cindex @code{papersize}
-
-To change the paper size, you must first set the
-@code{papersize} paper variable variable. Set it to
-the strings @code{a4}, @code{letter}, or @code{legal}. After this
-specification, you must set the font as described above. If you want
-the default font, then use the 20 point font.
-
-@example
- \paper@{ papersize = "a4" @}
- \include "paper16.ly"
-@end example
-
-The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
-will set the paper variables @code{hsize} and @code{vsize} (used by
-Lilypond and @code{ly2dvi})
-
@c . {Line break}
-@node Line break
-@subsection Line break
+@node Line breaking
+@subsection Line breaking
@cindex line breaks
@cindex breaking lines
""}. 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 @}
This makes the following 28 measures (assuming 4/4 time) be broken every
4 measures.
-@c . {Page break}
-@node Page break
-@subsection Page break
+@node Page layout
+@subsection Page layout
@cindex page breaks
@cindex breaking pages
+@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
+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 page layout
+
+The page layout process happens outside lilypond. Ly2dvi sets page
+layout instructions. Ly2dvi responds to the following variables in the
+@code{\paper} block. The variable @code{textheight} sets the total
+height of the music on each page. The spacing between systems is
+controlled with @code{interscoreline}, its default is 16pt.
+The distance between the score lines will stretch in order to fill the
+full page @code{interscorelinefill} is set to a positive number. In
+that case @code{interscoreline} specifies the minimum spacing.
+
+@cindex @code{textheight}
+@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
setting the @code{between-systems-strings} on the
@internalsref{NonMusicalPaperColumn} where the system is broken.
+@cindex paper size
+@cindex page size
+@cindex @code{papersize}
-
-@refbugs
-
-There is no mechanism to select magnification of particular fonts,
-meaning that you don't have access to continuously scaled fonts.
-
-
-
-@c . {Output formats}
-@node Output formats
-@section Output formats
-
-LilyPond can output processed music in different output formats.
-
-@menu
-* @TeX{} output::
-* PostScript output::
-* Scheme output::
-* ASCIIScript output::
-* Sketch output::
-@end menu
-
-@node @TeX{} output
-@subsection @TeX{} output
-@cindex @TeX{} output
-
-LilyPond will use @TeX{} by default. Even if you want to produce
-PostScript output for viewing or printing, you should normally have
-LilyPond produce @TeX{} first. The .tex output must be processed by
-@TeX{} (@strong{not} La@TeX{}) to generate a .dvi. Then, @file{Dvips}
-is used to generate PostScript. Alternatively, @file{ly2dvi} can be
-used to generate the .dvi for you.
-
-@refbugs
-
-Titling is not generated unless you use @file{ly2dvi}.
-
-
-@node PostScript output
-@subsection PostScript output
-@cindex PostScript output
-@cindex direct PostScript output
-
-LilyPond can produce PostScript directly, without going through @TeX{}.
-Currently, this is mainly useful if you cannot use TeX, because direct
-PostScript output has some problems; see Bugs below.
-
-@example
-$ lilypond -fps foo.ly
-GNU LilyPond 1.3.144
-Now processing: `foo.ly'
-Parsing...
-Interpreting music...[3]
-Preprocessing elements...
-Calculating column positions...
-paper output to foo.ps...
-
-$ cat /usr/share/lilypond/pfa/feta20.pfa foo.ps | lpr
-@end example
-
-
-@refbugs
-
-Text font selection is broken.
-
-The .ps file does not contain the .pfa font files. To print a .ps
-created through direct postscript output, you should prepend the
-necessary .pfa files to LilyPond's .ps output, or upload them to the
-printer before printing.
-
-The line height calculation is broken, you must set @var{lineheight} in
-the paperblock if you have more than one staff in your score, e.g.
-
-@example
- ...
- \paper @{
- % Set line height to 40 staff spaces
- lineheight = 40
- @}
-@end example
-
-@node Scheme output
-@subsection Scheme output
-@cindex Scheme output
-
-In the typesetting stage, LilyPond builds a page description, which is
-then written to disk in postscript, @TeX{} or ASCII art. Before it is
-written, the page description is represented as Scheme expressions. You
-can also dump these Scheme expressions to a file, which may be
-convenient for debugging output routines. This is done with the Scheme
-output format
-
-@example
-$ lilypond -fscm foo.ly
-GNU LilyPond 1.3.144
-Now processing: `foo.ly'
-Parsing...
-Interpreting music...[3]
-Preprocessing elements...
-Calculating column positions...
-paper output to foo.scm...
-
-$ head -4 foo.scm
-;;; Usage: guile -s x.scm > x.tex
- (primitive-load-path 'standalone.scm)
-; (scm-tex-output)
- (scm-ps-output)
-
-$ guile -s foo.scm > foo.tex
-@end example
-
-
-@node ASCIIScript output
-@subsection ASCIIScript output
-@cindex ASCIIScript output
-@cindex ascii script
-@cindex ascii art
-
-LilyPond can output ASCII Art. This is a two step process, LilyPond
-produces an ASCII description file, dubbed ASCIIScript (extension
-@file{.as}). ASCIIScript has a small and simple command set that
-includes font selection, character and string printing and line drawing
-commands. The program @file{as2text} is used to translate an .as file
-to text.
-
-To produce ASCII Art, you must include an ASCII Art paper definition
-file in your .ly, one of:
-@example
-\include "paper-as5.ly"
-\include "paper-as9.ly"
-@end example
-
-Here's an example use for ASCII Art output (the example file
-@file{as-email.ly} is included in the LilyPond distribution), the staff
-symbol has been made invisible:
+To change the paper size, you must first set the
+@code{papersize} paper variable variable. Set it to
+the strings @code{a4}, @code{letter}, or @code{legal}. After this
+specification, you must set the font as described above. If you want
+the default font, then use the 20 point font.
@example
-$ lilypond -fas as-email.ly
-GNU LilyPond 1.3.144
-Now processing: `as-email.ly'
-Parsing...
-Interpreting music...[3]
-Preprocessing elements...
-Calculating column positions... [2]
-paper output to as-email.as...
-
-$ as2text as-email.as 2>/dev/null
- |\
- |/ |##|##| | | | | |
- /| | | | | |\ |\ |\ |\ |\ |
- / |_ 3 | | | | 5 | )| )| )| )| )|
- | /| \ 8 * * * | 8 * * * * * |
- \_|_/ | |
- *_|
-
- lily
+ \paper@{ papersize = "a4" @}
+ \include "paper16.ly"
@end example
+The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
+will set the paper variables @code{hsize} and @code{vsize} (used by
+Lilypond and @code{ly2dvi})
-@refbugs
-
-The ASCII Art fonts are far from complete and not very well designed.
-It's easy to change the glyphs, though; if you think you can do better,
-have a look at @file{mf/*.af}.
-
-Lots of resizable symbols such as slurs, ties and tuplets are missing.
-
-The poor looks of most ASCII Art output and its limited general
-usefulness gives ASCII Art output a low priority; it may be
-dropped in future versions.
-
-
-@node Sketch output
-@subsection Sketch output
-@uref{http://sketch.sourceforge.net,Sketch} is a Free vector drawing
-program. LilyPond includes bare bones output for Sketch version 0.7.
-@cindex Sketch
-@cindex vector drawing
-@cindex drawing program
@c . {Sound}
@node Sound
projects / lilypond.git / blobdiff