@cindex Program reference
The controls available for tuning are described in a separate
-document, the @internalsref{Program reference} manual. That manual
+document, the
+@iftex
+Program reference
+@end iftex
+@ifnottex
+@ref{Top,Program reference,,lilypond-internals}.
+@end ifnottex
+manual. That manual
lists all different variables, functions and options available in
LilyPond. It is written as a HTML document, which is available
-@uref{http://@/lilypond@/.org/@/doc/@/Documentation/@/user/@/out@/-www/@/lilypond@/-internals/,on@/-line},
+@uref{http://@/lilypond@/.org/@/doc/@/v2.5/@/Documentation/@/user/@/out@/-www/@/lilypond@/-internals/,on@/-line},
but is also included with the LilyPond documentation package.
There are three areas where the default settings may be changed:
@menu
* Interpretation contexts::
* The \override command::
-* Fonts::
-* Text markup::
-* Global layout::
-* File structure::
@end menu
* Modifying context plug-ins::
* Layout tunings within contexts::
* Changing context default settings::
-* Defining new contexts::
+* Defining new contexts::
@end menu
@node Creating contexts
setting lyrics the melody is in a named context
@example
-\CONtext Voice = "@b{tenor}" @var{music}
+\context Voice = "@b{tenor}" @var{music}
@end example
@noindent
edition), with the option to put several distinct articulations on the
same notes.
-@cindex @code{\context}
@cindex creating contexts
The third command for creating contexts is
any context of type @var{type}, regardless of its given name.
This variant is used with music expressions that can be interpreted at
-several levels. For example, the @code{\applyoutput} command (see
+several levels. For example, the @code{\applyOutput} command (see
@ref{Running a function on all layout objects}). Without an explicit
@code{\context}, it is usually applied to @context{Voice}
@example
-\applyoutput #@var{function} % apply to Voice
+\applyOutput #@var{function} % apply to Voice
@end example
To have it interpreted at the @context{Score} or @context{Staff} level use
these forms
@example
-\context Score \applyoutput #@var{function}
-\context Staff \applyoutput #@var{function}
+\context Score \applyOutput #@var{function}
+\context Staff \applyOutput #@var{function}
@end example
The next example shows a practical application. Bar lines and time
signatures are normally synchronized across the score. This is done
-by the @code{Timing_engraver}. This plug-in keeps an administration of
-time signature, location within the measure, etc. By moving the
-@code{Timing_engraver} engraver from @code{Score} to @code{Staff}
-context, we can have a score where each staff has its own time
-signature.
+by the @code{Timing_translator} and @code{Default_bar_line_engraver}.
+This plug-in keeps an administration of time signature, location
+within the measure, etc. By moving thes engraver from @code{Score} to
+@code{Staff} context, we can have a score where each staff has its own
+time signature.
@cindex polymetric scores
@cindex Time signatures, multiple
@lilypond[quote,relative=1,raggedright,verbatim,fragment]
\new Score \with {
- \remove "Timing_engraver"
+ \remove "Timing_translator"
+ \remove "Default_bar_line_engraver"
} <<
\new Staff \with {
- \consists "Timing_engraver"
+ \consists "Timing_translator"
+ \consists "Default_bar_line_engraver"
} {
\time 3/4
c4 c c c c c
}
\new Staff \with {
- \consists "Timing_engraver"
+ \consists "Timing_translator"
+ \consists "Default_bar_line_engraver"
} {
\time 2/4
c4 c c c c c
@seealso
Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
-@internalsref{PropertySet}, @internalsref{All-backend-properties}, and
+@internalsref{PropertySet}, @internalsref{Backend}, and
@internalsref{All layout objects}.
@lilypond[quote,raggedright]
\layout { \context {
\name ImproVoice
- \type "Engraver_group_engraver"
+ \type "Engraver_group"
\consists "Note_heads_engraver"
\consists "Text_engraver"
\consists Pitch_squash_engraver
All these plug-ins have to cooperate, and this is achieved with a
special plug-in, which must be marked with the keyword @code{\type}.
-This should always be @internalsref{Engraver_group_engraver},
+This should always be @internalsref{Engraver_group},
@example
-\type "Engraver_group_engraver"
+\type "Engraver_group"
@end example
Put together, we get
@example
\context @{
\name ImproVoice
- \type "Engraver_group_engraver"
+ \type "Engraver_group"
\consists "Note_heads_engraver"
\consists "Text_engraver"
\consists Pitch_squash_engraver
@ifhtml
the
@end ifhtml
-@ref{Notation manual}, under the sections for slurs and stems
+@c @ref{Notation manual},
+Notation manual
+@c FIXME
+under the sections for slurs and stems
respectively.
The exact tuning possibilities for each type of layout object are
The @code{padding} property for objects with
@cindex @code{padding}
@code{side-position-interface} can be set to increase the distance between
-symbols that are printed above or below notes. We only give an
-example; a more elaborate explanation is in @ref{Constructing a
+symbols that are printed above or below notes. We provide two
+examples; a more elaborate explanation is in @ref{Constructing a
tweak}:
@lilypond[quote,fragment,relative=1,verbatim]
b2\fermata
@end lilypond
+@lilypond[quote,fragment,relative=1,verbatim]
+% This will not work, see below:
+\override MetronomeMark #'padding = #3
+\tempo 4=120
+c1
+% This works:
+\override Score.MetronomeMark #'padding = #3
+\tempo 4=80
+d1
+@end lilypond
+
+Note in the second example how important it is to figure out what
+context handles a certain object. Since the @code{MetronomeMark} object
+is handled in the Score context, property changes in the @code{Voice}
+context will not be noticed.
+
@end itemize
More specific overrides are also possible. The next section
@cindex interface, layout
@cindex layout interface
+@cindex grob
The HTML page that we found in the previous section, describes the
layout object called @internalsref{Fingering}. Such an object is a
symbol within the score. It has properties that store numbers (like
thicknesses and directions), but also pointers to related objects. A
-layout object is also called @emph{grob},
-@cindex grob
-which is short for Graphical Object.
-
+layout object is also called a @emph{Grob}, which is short for Graphical
+Object. For more details about Grobs, see @internalsref{grob-interface}.
The page for @code{Fingering} lists the definitions for the
@code{Fingering} object. For example, the page says
@example
(Fingering
- . ((print-function . ,Text_interface::print)
- (padding . 0.6)
- (staff-padding . 0.6)
+ . ((padding . 0.5)
+ (avoid-slur . around)
+ (slur-padding . 0.2)
+ (staff-padding . 0.5)
(self-alignment-X . 0)
(self-alignment-Y . 0)
(script-priority . 100)
- (font-size . -5)
- (meta . ((interfaces . (finger-interface font-interface
- text-script-interface text-interface
- side-position-interface
- self-alignment-interface
- item-interface))))))
+ (callbacks . ((stencil . ,Text_interface::print)
+ (direction . ,Script_interface::calc_direction)))
+ (font-encoding . fetaNumber)
+ (font-size . -5) ; don't overlap when next to heads.
+ (meta . ((class . Item)
+ (interfaces . (finger-interface
+ font-interface
+ text-script-interface
+ text-interface
+ side-position-interface
+ self-alignment-interface
+ item-interface))))))
@end example
@noindent
@node Difficult tweaks
@subsection Difficult tweaks
-There are two classes of difficult adjustments. First, when there are
+There are a few classes of difficult adjustments.
+
+@itemize @bullet
+First, when there are
several of the same objects at one point, and you want to adjust only
-one. For example, if you want to change only one note head in a chord.
+one.
-In this case, the @code{\applyoutput} function must be used. The
+For example, if you want to change only one note head in a chord.
+
+In this case, the @code{\applyOutput} function must be used. The
next example defines a Scheme function @code{set-position-font-size}
that sets the @code{font-size} property, but only
on objects that have @internalsref{note-head-interface} and are at the
@lilypond[quote,verbatim]
#(define ((set-position-font-size pos size) grob origin current)
(let*
- ((interfaces (ly:grob-property grob 'interfaces))
+ ((meta (ly:grob-property grob 'meta))
+ (interfaces (cdr (assoc 'interfaces meta)))
(position (ly:grob-property grob 'staff-position)))
(if (and
; is this a note head?
\relative {
c
- \applyoutput #(set-position-font-size -2 4)
+ \applyOutput #(set-position-font-size -2 4)
<c e g>
}
@end lilypond
A similar technique can be used for accidentals. In that case, the
function should check for @code{accidental-interface}.
+@item
Another difficult adjustment is the appearance of spanner objects,
such as slur and tie. Initially, only one of these objects is created,
and they can be adjusted with the normal mechanism. However, in some
in. These are clones of the original object and inherit all
properties, including @code{\override}s.
+
In other words, an @code{\override} always affects all pieces of a
broken spanner. To change only one part of a spanner at a line break,
it is necessary to hook into the formatting process. The
-@code{after-line-breaking-callback} property contains the Scheme procedure
-that is called after the line breaks have been determined, and layout
+@code{after-line-breaking} callback contains the Scheme procedure that
+is called after the line breaks have been determined, and layout
objects have been split over different systems.
In the following example, we define a procedure
This procedure is installed into @internalsref{Tie}, so the last part
of the broken tie is translated up.
-
@lilypond[quote,verbatim,raggedright]
#(define (my-callback grob)
(let* (
(ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
\relative c'' {
- \override Tie #'after-line-breaking-callback =
+ \override Tie #'after-line-breaking =
#my-callback
c1 ~ \break c2 ~ c
}
@end lilypond
@noindent
-When applying this trick, the new @code{after-line-breaking-callback}
-should also call the old @code{after-line-breaking-callback}, if there
-is one. For example, if using this with @code{Slur},
-@code{Slur::after_line_breaking} should also be called.
-
-@node Fonts
-@section Fonts
-
-This section details the ways that the font can be changed.
-
-@menu
-* Selecting font sizes::
-* Font selection::
-@end menu
-
-
-
-@node Selecting font sizes
-@subsection Selecting font sizes
-
-
-The easiest method of setting the font size of any context, is by
-setting the @code{fontSize} property.
-
-@lilypond[quote,fragment,relative=1,verbatim]
-c8
-\set fontSize = #-4
-c f
-\set fontSize = #3
-g
-@end lilypond
-
-@noindent
-It does not change the size of variable symbols, such as beams or
-slurs.
-
-Internally, the @code{fontSize} context property will cause the
-@code{font-size} property to be set in all layout objects. The value
-of @code{font-size} is a number indicating the size relative to the
-standard size for the current staff height. Each step up is an
-increase of approximately 12% of the font size. Six steps is exactly a
-factor two. The Scheme function @code{magstep} converts a
-@code{font-size} number to a scaling factor.
-
-@lilypond[quote,fragment,relative=1,verbatim]
-c8
-\override NoteHead #'font-size = #-4
-c f
-\override NoteHead #'font-size = #3
-g
-@end lilypond
-
-LilyPond has fonts in different design sizes. The music fonts for
-smaller sizes are chubbier, while the text fonts are relatively wider.
-Font size changes are achieved by scaling the design size that is
-closest to the desired size. The standard font size (for
-@code{font-size} equals 0), depends on the standard staff height. For
-a 20pt staff, a 10pt font is selected.
-
-The @code{font-size} mechanism does not work for fonts selected
-through @code{font-name}. These may be scaled with
-@code{font-magnification}. The @code{font-size} property can only be
-set on layout objects that use fonts; these are the ones supporting
-the @internalsref{font-interface} layout interface.
-
-@refcommands
-
-The following commands set @code{fontSize} for the current voice:
-
-@cindex @code{\tiny}
-@code{\tiny},
-@cindex @code{\small}
-@code{\small},
-@cindex @code{\normalsize}
-@code{\normalsize}.
-
-
-
-@cindex magnification
-@cindex cue notes
-
-
-@node Font selection
-@subsection Font selection
-
-
-
-@cindex font selection
-@cindex font magnification
-@cindex @code{font-interface}
-
-By setting the object properties described below, you can select a
-font from the preconfigured font families. LilyPond has default
-support for the feta music fonts and @TeX{}'s Computer Modern text
-fonts.
-
-
-@itemize @bullet
-@item @code{font-encoding}
-is a symbol that sets layout of the glyphs. This should only be set to
-select different types of non-text fonts, eg.
-
-@code{fetaBraces} for piano staff braces, @code{fetaMusic} the
-standard music font, including ancient glyphs, @code{fetaDynamic} for
-dynamic signs and @code{fetaNumber} for the number font.
-
-@item @code{font-family}
-is a symbol indicating the general class of the typeface. Supported are
-@code{roman} (Computer Modern), @code{sans}, and @code{typewriter}.
-
-@item @code{font-shape}
-is a symbol indicating the shape of the font. There are typically
-several font shapes available for each font family. Choices are
-@code{italic}, @code{caps}, and @code{upright}.
-
-@item @code{font-series}
-is a symbol indicating the series of the font. There are typically
-several font series for each font family and shape. Choices are
-@code{medium} and @code{bold}.
-
-@end itemize
-
-Fonts selected in the way sketched above come from a predefined style
-sheet.
-
-The font used for printing a object can be selected by setting
-@code{font-name}, e.g.,
-@example
-\override Staff.TimeSignature
- #'font-name = #"cmr17"
-@end example
-
-@noindent
-Any font can be used, as long as it is available to @TeX{}. Possible
-fonts include foreign fonts or fonts that do not belong to the
-Computer Modern font family. The size of fonts selected in this way
-can be changed with the @code{font-magnification} property. For
-example, @code{2.0} blows up all letters by a factor 2 in both
-directions.
-
-@cindex font size
-@cindex font magnification
-
-
-
-@seealso
-
-Init files: @file{ly/@/declarations@/-init@/.ly} contains hints how new
-fonts may be added to LilyPond.
-
-
-
-@node Text markup
-@section Text markup
-@cindex text markup
-@cindex markup text
-
-
-@cindex typeset text
-
-The internal mechanism to typeset texts is accessed with the keyword
-@code{\markup}. Within markup mode, you can enter texts similar to
-lyrics. They are simply entered, while commands use the backslash @code{\}.
-@cindex markup
-
-@lilypond[quote,verbatim,fragment,relative=1]
-c1^\markup { hello }
-c1_\markup { hi there }
-c1^\markup { hi \bold there, is \italic anyone home? }
-@end lilypond
-
-@cindex font switching
-
-The markup in the example demonstrates font switching commands. The
-command @code{\bold} and @code{\italic} apply to the first following
-word only; enclose a set of texts with braces to apply a command
-to more words:
-@example
-\markup @{ \bold @{ hi there @} @}
-@end example
-
-@noindent
-For clarity, you can also do this for single arguments, e.g.,
-
-@example
-\markup @{ is \italic @{ anyone @} home @}
-@end example
-
-@cindex font size, texts
-
-
-In markup mode you can compose expressions, similar to mathematical
-expressions, XML documents, and music expressions. You can stack
-expressions grouped vertically with the command @code{\column}.
-Similarly, @code{\center-align} aligns texts by their center lines:
-
-@lilypond[quote,verbatim,fragment,relative=1]
-c1^\markup { \column { a bbbb \line { c d } } }
-c1^\markup { \center-align { a bbbb c } }
-c1^\markup { \line { a b c } }
-@end lilypond
-
-
-Markups can be stored in variables and these variables
-may be attached to notes, like
-@example
-allegro = \markup @{ \bold \large @{ Allegro @} @}
- @{ a^\allegro b c d @}
-@end example
-
-
-Some objects have alignment procedures of their own, which cancel out
-any effects of alignments applied to their markup arguments as a
-whole. For example, the @internalsref{RehearsalMark} is horizontally
-centered, so using @code{\mark \markup @{ \left-align .. @}} has no
-effect.
-
-Similarly, for moving whole texts over notes with
-@code{\raise}, use the following trick:
-@lilypond[quote,verbatim]
-{
- c'^\markup { \raise #0.5 not-raised }
- c'^\markup { "" \raise #0.5 raised }
-}
-@end lilypond
-
-On the second note, the text @code{raised} is moved relative to the
-empty string @code{""} which is not visible. Alternatively, complete
-objects can be moved with layout properties such as @code{padding} and
-@code{extra-offset}.
-
-
-
-
-@seealso
-
-Init files: @file{scm/@/new@/-markup@/.scm}.
-
-
-@refbugs
-
-Kerning or generation of ligatures is only done when the @TeX{}
-backend is used. In this case, LilyPond does not account for them so
-texts will be spaced slightly too wide.
-
-Syntax errors for markup mode are confusing.
-
-
-@menu
-* Text encoding::
-* Nested scores::
-* Overview of text markup commands::
-* New dynamic marks::
-@end menu
-
-@node Text encoding
-@subsection Text encoding
-
-LilyPond uses the Pango library to format multi-lingual texts, and
-does not perform any input-encoding conversions. This means that any
-text, be it title, lyric text, or musical instruction containing
-non-ASCII characters, must be utf-8. Easiest to enter such texts is
-by using a Unicode-aware editor, and save using utf-8 encoding. Most
-popular modern editors have utf-8 support, for example, vim, Emacs,
-jEdit, and GEdit do.
-
-Depending on the fonts installed, the following fragment shows Hebrew
-and Cyrillic lyrics,
-
-@cindex Cyrillic
-@cindex Hebrew
-@cindex ASCII, non
-
-@lilypondfile{utf8.ly}
-
-
-The @TeX{} backend does not handle encoding specially at all. Strings
-in the input are put in the output as-is. Extents of text items in the
-@TeX{} backend, are determined by reading a file created via the
-@file{texstr} backend,
-
-@example
-lilypond -b texstr input/les-nereides.ly
-latex les-nereides.texstr
-@end example
-
-The last command produces @file{les-nereides.textmetrics}, which is
-read when you execute
-
-@example
-lilypond -b tex input/les-nereides.ly
-@end example
-
-Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
-suitable LaTeX wrappers to load appropriate La@TeX{} packages for
-interpreting non-ASCII strings.
-
-@seealso
-
-@inputfileref[fontload]{input/regression,utf8.ly}
-
-
-@node Nested scores
-@subsection Nested scores
-
-It is possible to nest music inside markups, by adding a @code{\score}
-block to a markup expression. Such a score must contain a @code{\layout}
-block.
-
-@lilypond[quote,verbatim,raggedright]
-\relative {
- c4 d^\markup {
- \score {
- \relative { c4 d e f }
- \layout { }
- }
- }
- e f
-}
-@end lilypond
-
-
-
-@node Overview of text markup commands
-@subsection Overview of text markup commands
-
-The following commands can all be used inside @code{\markup @{ @}}.
-
-@include markup-commands.tely
-
-
-@node New dynamic marks
-@subsection New dynamic marks
-
-It is possible to print new dynamic marks or text that should be aligned
-with dynamics. Use @code{make-dynamic-script} to create these marks.
-
-@cindex make-dynamic-script
-
-@lilypond[quote,verbatim,raggedright]
-sfzp = #(make-dynamic-script "sfzp")
-\relative c' {
- c4 c c\sfzp c
-}
-@end lilypond
-
-@cindex Dynamics, editorial
-@cindex Dynamics, parenthesis
-
-It is also possible to print dynamics in round parenthesis or square
-brackets. These are often used for adding editorial dynamics.
-
-@lilypond[quote,verbatim,raggedright]
-\version "2.4.2"
-rndf = \markup{ \center-align {\line { \bold{\italic (}
- \dynamic f \bold{\italic )} }} }
-boxf = \markup{ \bracket { \dynamic f } }
-{ c'1_\rndf c'1_\boxf }
-@end lilypond
-
-
-@node Global layout
-@section Global layout
-
-The global layout is 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.
-This influences where line breaks are chosen, and thus ultimately, how
-many pages a piece of music takes.
-
-Globally spoken, this procedure happens in three steps: first,
-flexible distances (``springs'') are chosen, based on durations. All
-possible line breaking combinations 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.
-
-After spacing and linebreaking, the systems are distributed across
-pages, taking into account the size of the page, and the size of the
-titles.
-
-
-
-@menu
-* Setting global staff size::
-* Paper size::
-* Page layout::
-* Vertical spacing::
-* Vertical spacing of piano staves::
-* Horizontal spacing::
-* Line length::
-* Line breaking::
-* Page breaking::
-* Multiple movements::
-* Creating titles::
-@end menu
-
-
-@node Setting global staff size
-@subsection Setting global staff size
-
-@cindex font size, setting
-@cindex staff size, setting
-@cindex @code{layout} file
-
-To set the global staff size, use @code{set-global-staff-size}.
-
-@example
-#(set-global-staff-size 14)
-@end example
-
-@noindent
-This sets the global default size to 14pt staff height and scales all
-fonts accordingly.
-
-The Feta font provides musical symbols at eight different
-sizes. Each font is tuned for a different staff size: at a smaller size
-the font becomes heavier, to match the relatively heavier staff lines.
-The recommended font sizes are listed in the following table:
-
-@quotation
-@multitable @columnfractions .15 .2 .22 .2
-
-@item @b{font name}
-@tab @b{staff height (pt)}
-@tab @b{staff height (mm)}
-@tab @b{use}
-
-@item feta11
-@tab 11.22
-@tab 3.9
-@tab pocket scores
-
-@item feta13
-@tab 12.60
-@tab 4.4
-@tab
-
-@item feta14
-@tab 14.14
-@tab 5.0
-@tab
-
-@item feta16
-@tab 15.87
-@tab 5.6
-@tab
-
-@item feta18
-@tab 17.82
-@tab 6.3
-@tab song books
-
-@item feta20
-@tab 20
-@tab 7.0
-@tab standard parts
-
-@item feta23
-@tab 22.45
-@tab 7.9
-@tab
-
-@item feta26
-@tab 25.2
-@tab 8.9
-@tab
-@c modern rental material?
-
-@end multitable
-@end quotation
-
-These fonts are available in any sizes. The context property
-@code{fontSize} and the layout property @code{staff-space} (in
-@internalsref{StaffSymbol}) can be used to tune the size for individual
-staves. The sizes of individual staves are relative to the global size.
-
-@example
-
-@end example
-
-@seealso
-
-This manual: @ref{Selecting font sizes}.
-
-
-@node Paper size
-@subsection Paper size
+When applying this trick, the new @code{after-line-breaking} callback
+should also call the old one @code{after-line-breaking}, if there is
+one. For example, if using this with @code{Hairpin},
+@code{Hairpin::after_line_breaking} should also be called.
-@cindex paper size
-@cindex page size
-@cindex @code{papersize}
-
-To change the paper size, there are two equal commands,
-@example
-#(set-default-paper-size "a4")
-\paper @{
- #(set-paper-size "a4")
-@}
-@end example
-The first command sets the size of all pages. The second command sets the size
-of the pages that the @code{\paper} block applies to -- if the @code{\paper}
-block is at the top of the file, then it will apply to all pages. If the
-@code{\paper} block is inside a @code{\score}, then the paper size will only
-apply to that score.
-
-The following paper sizes are supported: @code{a6}, @code{a5}, @code{a4},
-@code{a3}, @code{legal}, @code{letter}, @code{tabloid}.
-
-@cindex orientation
-@cindex landscape
-
-If the symbol @code{landscape} is supplied as an argument to
-@code{set-default-paper-size}, the pages will be rotated by 90 degrees,
-and wider line widths will be set correspondingly.
-
-@example
-#(set-default-paper-size "a6" 'landscape)
-@end example
-
-
-@node Page layout
-@subsection Page layout
-
-@cindex page layout
-@cindex margins
-@cindex header, page
-@cindex footer, page
-
-LilyPond will do page layout, set margins, and add headers and
-footers to each page.
-
-The default layout responds to the following settings in the
-@code{\paper} block.
-
-@cindex \paper
-
-@quotation
-@table @code
-@item firstpagenumber
-The value of the page number of the first page. Default is@tie{}1.
-
-@item printfirstpagenumber
-If set to true, will print the page number in the first page. Default is
-false.
-
-@item hsize
-The width of the page.
-
-@item vsize
-The height of the page.
-
-@item topmargin
-Margin between header and top of the page.
-
-@item bottommargin
-Margin between footer and bottom of the page.
-
-@item leftmargin
-Margin between the left side of the page and the beginning of the music.
-
-@item linewidth
-The length of the systems.
-
-@item headsep
-Distance between the top-most music system and the page header.
-
-@item footsep
-Distance between the bottom-most music system and the page footer.
-
-@item raggedbottom
-If set to true, systems will not be spread across the page.
-
-This should be set false for pieces that have only two or three
-systems per page, for example orchestral scores.
-
-@item raggedlastbottom
-If set to false, systems will be spread to fill the last page.
-
-Pieces that amply fill two pages or more should have this set to
-true.
-
-@item betweensystemspace
-This dimensions determines the distance between systems. It is the
-ideal distance between the center of the bottom staff of one system
-and the center of the top staff of the next system.
-
-Increasing this will provide a more even appearance of the page at the
-cost of using more vertical space.
-
-@item betweensystempadding
-This dimension is the minimum amount of white space that will always
-be present between the bottom-most symbol of one system, and the
-top-most of the next system.
-
-Increasing this will put systems whose bounding boxes almost touch
-farther apart.
-
-@item aftertitlespace
-Amount of space between the title and the first system.
-
-@item beforetitlespace
-Amount of space between the last system of the previous piece and the
-title of the next.
-
-@item betweentitlespace
-Amount of space between consecutive titles (e.g., the title of the
-book and the title of a piece).
-
-@item systemSeparatorMarkup
-This contains a markup object, which will be inserted between
-systems. This is often used for orchestral scores.
-
-The markup command @code{\slashSeparator} is provided as a sensible
-default, for example
-
-@lilypond[raggedright]
-\paper {
- systemSeparatorMarkup = \slashSeparator
-}
-
-\relative { c1 \break c1 }
-@end lilypond
-
-
-@end table
-@end quotation
-
-Example:
-
-@example
-\paper@{
- hsize = 2\cm
- topmargin = 3\cm
- bottommargin = 3\cm
- raggedlastbottom = ##t
-@}
-@end example
-
-You can also define these values in Scheme. In that case @code{mm},
-@code{in}, @code{pt}, and @code{cm} are variables defined in
-@file{paper-defaults.ly} with values in millimeters. That's why the
-value has to be multiplied in the example
-
-@example
-\paper @{
- #(define bottommargin (* 2 cm))
-@}
-@end example
-
-@cindex copyright
-@cindex tagline
-
-The default footer is empty, except for the first page, where the
-@code{copyright} field from @code{\header} is inserted, and the last
-page, where @code{tagline} from @code{\header} is added. The default
-tagline is ``Engraved by LilyPond (@var{version})''.@footnote{Nicely
-printed parts are good PR for us, so please leave the tagline if you
-can.}
-
-The header and footer are created by the functions @code{make-footer}
-and @code{make-header}, defined in @code{\paper}. The default
-implementations are in @file{scm/@/page@/-layout@/.scm}.
-
-The following settings influence the header and footer layout.
-
-@quotation
-@table @code
-@item printpagenumber
- this boolean controls whether a pagenumber is printed.
-@end table
-@end quotation
-
-The page layout itself is done by two functions in the
-@code{\paper} block, @code{page-music-height} and
-@code{page-make-stencil}. The former tells the line-breaking algorithm
-how much space can be spent on a page, the latter creates the actual
-page given the system to put on it.
-
-
-@refbugs
-
-The option rightmargin is defined but doesn't set the right margin
-yet. The value for the right margin has to be defined adjusting the
-values of the leftmargin and linewidth.
-
-The default page header puts the page number and the @code{instrument}
-field from the @code{\header} block on a line.
-
-
-@node Vertical spacing
-@subsection Vertical spacing
-
-@cindex vertical spacing
-@cindex distance between staves
-@cindex staff distance
-@cindex between staves, distance
-@cindex staves per page
-@cindex space between staves
-
-The height of each system is determined automatically. To prevent
-systems from bumping into each other, some minimum distances are set.
-By changing these, you can put staves closer together, and thus put
-more systems onto one page.
-
-Normally staves are stacked vertically. To make staves maintain a
-distance, their vertical size is padded. This is done with the
-property @code{minimumVerticalExtent}. It takes a pair of numbers, so
-if you want to make it smaller than its default @code{#'(-4 . 4)},
-then you could set
-
-@example
-\set Staff.minimumVerticalExtent = #'(-3 . 3)
-@end example
-
-@noindent
-This sets the vertical size of the current staff to 3 staff spaces 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. The
-staff can be made larger at the bottom by setting it to @code{(-6 . 4)}.
-
-To change the amount of space between systems, use
-@code{betweensystemspace}. A score with only one staff is still
-considered to have systems, so setting @code{betweensystemspace}
-will be much more useful than changing @code{minimumVerticalExtent}.
-
-@example
-\layout @{
- betweensystemspace = 10\mm
-@}
-@end example
-
-
-@seealso
-
-Internals: Vertical alignment of staves is handled by the
-@internalsref{VerticalAlignment} object.
-
-@refbugs
-
-@code{minimumVerticalExtent} is syntactic sugar for setting
-@code{minimum-Y-extent} of the @internalsref{VerticalAxisGroup} of the
-current context. It can only be changed score wide.
-
-
-
-
-@node Vertical spacing of piano staves
-@subsection Vertical spacing of piano staves
-
-The distance between staves of a @internalsref{PianoStaff} cannot be
-computed during formatting. Rather, to make cross-staff beaming work
-correctly, that distance has to be fixed beforehand.
-
-The distance of staves in a @code{PianoStaff} is set with the
-@code{forced-distance} property of the
-@internalsref{VerticalAlignment} object, created in
-@internalsref{PianoStaff}.
-
-It can be adjusted as follows
-@example
-\new PianoStaff \with @{
- \override VerticalAlignment #'forced-distance = #7
-@} @{
- ...
-@}
-@end example
-
-@noindent
-This would bring the staves together at a distance of 7 staff spaces,
-measured from the center line of each staff.
-
-The difference is demonstrated in the following example,
-@lilypond[quote,verbatim]
-\relative <<
- \new PianoStaff \with {
- \override VerticalAlignment #'forced-distance = #7
- } <<
- \new Staff { c1 }
- \new Staff { c }
- >>
- \new PianoStaff <<
- \new Staff { c }
- \new Staff { c }
- >>
->>
-@end lilypond
-
-
-
-@refbugs
-
-@code{forced-distance} cannot be changed per system.
-
-
-@node Horizontal spacing
-@subsection Horizontal Spacing
-
-The spacing engine translates differences in durations into
-stretchable distances (``springs'') of differring lengths. Longer
-durations get more space, shorter durations get less. The shortest
-durations get a fixed amount of space (which is controlled by
-@code{shortest-duration-space} in the @internalsref{SpacingSpanner} object).
-The longer the duration, the more space it gets: doubling a
-duration adds a fixed amount (this amount is controlled by
-@code{spacing-increment}) of space to the note.
-
-For example, the following piece contains lots of half, quarter, and
-8th notes; the eighth note is followed by 1 note head width (NHW).
-The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
-
-@lilypond[quote,fragment,verbatim,relative=1]
-c2 c4. c8 c4. c8 c4. c8 c8
-c8 c4 c4 c4
-@end lilypond
-
-Normally, @code{spacing-increment} is set to 1.2 staff space, which is
-approximately the width of a note head, and
-@code{shortest-duration-space} is set to 2.0, meaning that the
-shortest note gets 2.4 staff space (2.0 times the
-@code{spacing-increment}) of horizontal space. This space is counted
-from the left edge of the symbol, so the shortest notes are generally
-followed by one NHW of space.
-
-If one would follow the above procedure exactly, then adding a single
-32nd 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 32nd,
-thus adding 1 NHW to every note. To prevent this, the shortest
-duration for spacing is not the shortest note in the score, but rather
-the one which occurs most frequently.
-
-
-The most common shortest duration is determined as follows: in every
-measure, the shortest duration is determined. The most common shortest
-duration is taken as the basis for the spacing, with the stipulation
-that this shortest duration should always be equal to or shorter than
-an 8th note. The shortest duration is printed when you run
-@code{lilypond} with the @code{--verbose} option.
-
-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 an 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}
-
-Notes that are even shorter than the common shortest note are
-followed by a space that is proportional 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[quote,fragment,verbatim,relative=2]
-c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
-@end lilypond
-
-
-In the introduction (see @ref{Engraving}), it was explained that stem
-directions influence spacing. This is controlled with the
-@code{stem-spacing-correction} property in the
-@internalsref{NoteSpacing}, object. These are generated for every
-@internalsref{Voice} context. The @code{StaffSpacing} object
-(generated in @internalsref{Staff} context) contains the same property
-for controlling the stem/bar line spacing. The following example shows
-these corrections, once with default settings, and once with
-exaggerated corrections:
-
-@lilypond[quote,raggedright]
-{
- c'4 e''4 e'4 b'4 |
- b'4 e''4 b'4 e''4|
- \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
- \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
- c'4 e''4 e'4 b'4 |
- b'4 e''4 b'4 e''4|
-}
-@end lilypond
-
-
-@seealso
-
-Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
-@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
-@internalsref{SeparatingGroupSpanner}.
-
-@refbugs
-
-Spacing is determined on a score wide basis. If you have a score that
-changes its character (measured in durations) halfway during the
-score, the part containing the longer durations will be spaced too
-widely.
-
-There is no convenient mechanism to manually override spacing. The
-following work-around may be used to insert extra space into a score.
-@example
- \once \override Score.SeparationItem #'padding = #1
-@end example
-
-No work-around exists for decreasing the amount of space.
-
-@node Line length
-@subsection Line length
-
-@cindex page breaks
-@cindex breaking pages
-
-@cindex @code{indent}
-@cindex @code{linewidth}
-
-@c Although linewidth can be set in \layout, it should be set in paper
-@c block, to get page layout right.
-@c Setting indent in \paper block makes not much sense, but it works.
-
-@c Bit verbose and vague, use examples?
-The most basic settings influencing the spacing are @code{indent} and
-@code{linewidth}. They are set in the @code{\layout} block. They
-control the indentation of the first line of music, and the lengths of
-the lines.
-
-If @code{raggedright} is set to true in the @code{\layout} block, then
-the lines are justified at their natural length. This is useful for
-short fragments, and for checking how tight the natural spacing is.
-
-@cindex page layout
-@cindex vertical spacing
-
-The option @code{raggedlast} is similar to @code{raggedright}, but
-only affects the last line of the piece. No restrictions are put on
-that line. The result is similar to formatting text paragraphs. In a
-paragraph, the last line simply takes its natural length.
-@c Note that for text there are several options for the last line.
-@c While Knuth TeX uses natural length, lead typesetters use the same
-@c stretch as the previous line. eTeX uses \lastlinefit to
-@c interpolate between both these solutions.
-
-@node Line breaking
-@subsection Line breaking
-
-@cindex line breaks
-@cindex breaking lines
-
-Line breaks are normally computed automatically. They are chosen so
-that lines look neither cramped nor loose, and that consecutive lines
-have similar density.
-
-Occasionally you might want to override the automatic breaks; you can
-do this by specifying @code{\break}. This will force a line break at
-this point. Line breaks can only occur at places where there are bar
-lines. If you want to have a line break where there is no bar line,
-you can force an invisible bar line by entering @code{\bar
-""}. Similarly, @code{\noBreak} forbids a line break at a
-point.
-
-
-@cindex regular line breaks
-@cindex four bar music.
-
-For line breaks at regular intervals use @code{\break} separated by
-skips and repeated with @code{\repeat}:
-@example
-<< \repeat unfold 7 @{
- s1 \noBreak s1 \noBreak
- s1 \noBreak s1 \break @}
- @emph{the real music}
->>
-@end example
-
-@noindent
-This makes the following 28 measures (assuming 4/4 time) be broken every
-4 measures, and only there.
-
-@refcommands
-
-@code{\break}, and @code{\noBreak}.
-@cindex @code{\break}
-@cindex @code{\noBreak}
-
-@seealso
-
-Internals: @internalsref{BreakEvent}.
-
-
-@node Page breaking
-@subsection Page breaking
-
-The default page breaking may be overriden by inserting
-@code{\pageBreak} or @code{\noPageBreak} commands. These commands are
-analogous to @code{\break} and @code{\noBreak}. They should be
-inserted at a bar line. These commands force and forbid a page-break
-from happening. Of course, the @code{\pageBreak} command also forces
-a line break.
-
-Page breaks are computed by the @code{page-breaking} function in the
-@code{\paper} block.
-
-@refcommands
-
-@cindex @code{\pageBreak}
-@code{\pageBreak}
-@cindex @code{\noPageBreak}
-@code{\noPageBreak}
-
-
-@node Multiple movements
-@subsection Multiple movements
-
-@cindex bibliographic information
-@cindex titles
-@cindex composer
-@cindex Engraved by LilyPond
-
-A document may contain multiple pieces of music. Examples of these
-are an etude book, or an orchestral part with multiple movements.
-Each movement is entered with a @code{\score} block,
-
-@example
-\score @{
- @var{..music..}
-@}
-@end example
-
-The movements are combined together in a @code{\book} block, like
-
-@example
-\book @{
- \score @{
- @var{..}
- @}
- \score @{
- @var{..}
- @}
-@}
-@end example
-
-
-The header for each piece of music can be put inside the @code{\score}
-block. The @code{piece} name from the header will be printed before
-each movement. The title for the entire book can be put inside the
-@code{\book}, but if it is not present, the @code{\header} which is at
-the top of the file is inserted.
-
-@cindex Engraved by LilyPond
-@cindex signature line
+@item Some objects cannot be changed with @code{\override} for
+technical reasons. Examples of those are @code{NonMusicalPaperColumn}
+and @code{PaperColumn}. They can be changed with the
+@code{\outputProperty} function, which works similar to @code{\once
+\override}, but uses a different syntax,
@example
-\book @{
- \header @{
- title = "Eight miniatures"
- composer = "Igor Stravinsky"
- @}
- \score @{
- @dots{}
- \header @{ piece = "Romanze" @}
- @}
- \score @{
- @dots{}
- \header @{ piece = "Menuetto" @}
- @}
-@}
+\outputProperty
+#"Score.NonMusicalPaperColumn" % Grob name
+#'line-break-system-details % Property name
+#'((next-padding . 20)) % Value
@end example
-
-@node Creating titles
-@subsection Creating titles
-
-Titles are created for each @code{\score} block, and over a
-@code{\book}.
-
-The contents of the titles are taken from the @code{\header} blocks.
-The header block for a book supports the following
-@table @code
-@item title
-The title of the music. Centered on top of the first page.
-
-@item subtitle
-Subtitle, centered below the title.
-
-@item subsubtitle
-Subsubtitle, centered below the subtitle.
-
-@item poet
-Name of the poet, flush-left below the subtitle.
-
-@item composer
-Name of the composer, flush-right below the subtitle.
-
-@item meter
-Meter string, flush-left below the poet.
-
-@item opus
-Name of the opus, flush-right below the composer.
-
-@item arranger
-Name of the arranger, flush-right below the opus.
-
-@item instrument
-Name of the instrument, centered below the arranger.
-
-@item dedication
-To whom the piece is dedicated.
-
-@item piece
-Name of the piece, flush-left below the instrument.
-
-@cindex page breaks, forcing
-@item breakbefore
- This forces the title to start on a new page.
-@end table
-
-Here is a demonstration of the fields available,
-
-@lilypond[quote,verbatim,linewidth=11.0\cm]
-\paper {
- linewidth = 9.0\cm
- vsize = 10.0\cm
-}
-
-\book {
- \header {
- title = "Title,"
- subtitle = "the subtitle,"
- subsubtitle = "and the sub sub title"
- poet = "Poet"
- composer = "Composer"
- texttranslator = "Text Translator"
- meter = "Meter"
- arranger = "Arranger"
- instrument = "Instrument"
- piece = "Piece"
- }
-
- \score {
- \header {
- piece = "piece1"
- opus = "opus1"
- }
- { c'1 }
- }
- \score {
- \header {
- piece = "piece2"
- opus = "opus2"
- }
- { c'1 }
- }
-}
-@end lilypond
-
-Different fonts may be selected for each element by using
-@code{\markup}, e.g.,
-
-@example
-\header @{
- title = \markup @{ \italic @{ The italic title @} @}
-@}
-@end example
-
-A more advanced option is to change the definitions of the following
-variables in the @code{\paper} block. The init file
-@file{ly/titling-init.ly} lists the default layout.
-
-@table @code
-@item bookTitleMarkup
- This is the title put over an entire @code{\book} block. Typically,
- it has the composer and the title of the piece
-
-@item scoreTitleMarkup
- This is the title put over a @code{\score} block within a
-@code{\book}. Typically, it has the name of the movement (@code{piece}
-field).
-
-@item oddHeaderMarkup
- This is the page header for odd-numbered pages.
-
- @item evenHeaderMarkup
- This is the page header for even-numbered pages. If unspecified,
- the odd header is used instead.
-
- By default, headers are defined such that the page number is on the
- outside edge, and the instrument is centered.
-
-@item oddFooterMarkup
- This is the page footer for odd-numbered pages.
-
-@item evenFooterMarkup
- This is the page footer for even-numbered pages. If unspecified,
- the odd header is used instead.
-
- By default, the footer has the copyright notice on the first, and
- the tagline on the last page.
-@end table
-
-
-@cindex \paper
-@cindex header
-@cindex footer
-@cindex page layout
-@cindex titles
-
-The following definition will put the title flush left, and the
-composer flush right on a single line.
-
-@verbatim
-\paper {
- bookTitleMarkup = \markup {
- \fill-line @{
- \fromproperty #'header:title
- \fromproperty #'header:composer
- @}
- }
-}
-@end verbatim
-
-
-
-@node File structure
-@section File structure
-
-The major part of this manual is concerned with entering various
-forms of music in LilyPond. However, many music expressions are not
-valid input on their own, for example, a @code{.ly} file containing
-only a note
-@example
-c'4
-@end example
-
-@noindent
-will result in a parsing error. Instead, music should be inside other
-expressions, which may be put in a file by themselves. Such
-expressions are called toplevel expressions. This section enumerates
-them all.
-
-A @code{.ly} file contains any number of toplevel expressions, where a
-toplevel expression is one of the following
-
-@itemize @bullet
-@item
-An output definition, such as @code{\paper}, @code{\midi}, and
-@code{\layout}. Such a definition at the toplevel changes the default
-settings for the block entered.
-
-@item
-A @code{\header} block. This sets the global header block. This
-is the block containing the definitions for book-wide settings, like
-composer, title, etc.
-
-@item
-An @code{\addquote} statement. See @ref{Quoting other voices}
-for more information.
-
-@item
-A @code{\score} block. This score will be collected with other
-toplevel scores, and combined as a single @code{\book}.
-
-This behavior can be changed by setting the variable
-@code{toplevel-score-handler} at toplevel. The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
-
-@item
-A @code{\book} block logically combines multiple movements
-(i.e., multiple @code{\score} blocks) in one document. A number of
-@code{\scores} creates a single output file, where all movement are
-concatenated.
-
-This behavior can be changed by setting the variable
-@code{toplevel-book-handler} at toplevel. The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
-
-@item A compound music expression, such as
-@example
-@{ c'4 d' e'2 @}
-@end example
-
-This will add the piece in a @code{\score} and format it in a
-single book together with all other toplevel @code{\score}s and music
-expressions.
-
-This behavior can be changed by setting the variable
-@code{toplevel-music-handler} at toplevel. The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
-
-@item An indentifier, such as
-@example
-foo = @{ c4 d e d @}
-@end example
-
-This can be used later on in the file by entering @code{\foo}.
-
@end itemize
-
-The following example shows three things that may be entered at
-toplevel
-
-@example
-\layout @{
- % movements are non-justified by default
- raggedright = ##t
-@}
-
-\header @{
- title = "Do-re-mi"
-@}
-
-@{ c'4 d' e2 @}
-@end example
-
-
-At any point in a file, any of the following lexical instructions can
-be entered:
-
-@itemize @bullet
-@item @code{\version}
-@item @code{\include}
-@item @code{\renameinput}
-@end itemize
projects / lilypond.git / blobdiff