* Writing parts::
* Ancient notation ::
* Tuning output::
-* Page layout::
-* Output formats::
+* Global layout::
* Sound::
@end menu
@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
moving the tie-engraver into the Thread context and turning on and off
ties per Thread.
+Switching staffs 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}.
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
+
+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.
-In the emacs startup file (usually @file{~/.emacs}), add the following
+@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} grob. This grob 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
Auto knee beams can not be used together with hara kiri staffs.
+[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 ::
@end menu
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
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
@internalsref{Voice} context.
@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 }
}
staffs, 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 grob property @code{flag-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}.
+
@lilypond[fragment,verbatim]
\relative c'' \context Voice {
}
@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
+
+
@refbugs
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.
-@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
@end lilypond
Tremolo beams are @internalsref{Beam} grobs. Single stem tremolos are
-@internalsref{StemTremolo}.
+@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
-
@node Non-guitar tablatures
@subsection Non-guitar tablatures
@cindex Non-guitar tablatures
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
c1 \mark \default
c1 \mark "12"
c1 \mark \default
- c1 \mark #'(music "scripts-segno")
c1
}
@end lilypond
@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
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
* Tuning per grob ::
* Font selection::
* Text markup::
-* Spacing::
@end menu
@node Tuning groups of grobs
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 grob
@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}.
-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:
+@cindex cue notes
+@cindex font size
+@cindex size
+
+The font used for printing a grob 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 grob properties described below, you can select a different font.
+All three mechanisms work for every grob 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-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, 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 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}. 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
@code{font-magnification}. For example, @code{2.0} blows up all
The markup is broken down and converted into a list of grob properties,
which are prepended to the property list. The @var{key}-@var{value}
pair is a grob property. A list of properties available is included in
-the generated documentation for @rint{Text_interface}.
+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
-
-S
-
-TODO: Move this section.
-
-@refbugs
-
+LilyPond does not do kerning, and there generally spaces texts
+slightly too wide.
-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
+iline 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
+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
+@cindex vertical spacing
+@cindex distance between staffs
+@cindex staff distance
+@cindex between staves, distance
-where each of the items is one of
+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 staffs closer together, and thus
+put more systems onto one page.
-@itemize @bullet
- @item An assignment.
-
- @item A context definition. See @ref{Interpretation context} for
- more information on context definitions.
-@end itemize
-
-@c . {Paper variables}
-@node Paper variables
-@subsection Paper variables
-@cindex Paper variables
-
-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} grob, which lives at
+@internalsref{Score} level.
+
+The piano staffs 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}
+grob, created in @internalsref{PianoStaff}, but a forced distance is
+set. This is done with the grob 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 staffs 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}, grob 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} grob 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{lilypond-book: integrating text and music} 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