The purpose of LilyPond's design is to provide the finest output
quality as a default. Nevertheless, it may happen that you need to
-change that default layout. The layout is controlled through a large
+change this default layout. The layout is controlled through a large
number of proverbial ``knobs and switches.'' This chapter does not
list each and every knob. Rather, it outlines what groups of controls
-are available, and it explains how to lookup which knob to use for a
+are available and explains how to lookup which knob to use for a
certain effect.
-The controls are available for tuning are described in a separate
-document, the @internalsref{Program reference} manual. This manual
+The controls available for tuning are described in a separate
+document, the @internalsref{Program reference} manual. That manual
lists all different variables, functions and options available in
-LilyPond. It is available as a HTML document, which is available
+LilyPond. It is written as a HTML document, which is available
@uref{http://lilypond.org/doc/Documentation/user/out-www/lilypond-internals/,on-line},
but is also included with the LilyPond documentation package.
@menu
* Scheme tutorial::
+* File structure::
* Interpretation contexts::
* Tuning output::
* Fonts::
* Text markup::
* Global layout::
-* Output details::
@end menu
@node Scheme tutorial
In a music file, snippets of Scheme code are introduced with the hash
-mark @code{#}. So, the previous examples translated in LilyPondese are
+mark @code{#}. So, the previous examples translated in LilyPond are
@example
##t ##f
@end lisp
The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
-is @code{3}. Calculations may be nested: the result of a function may
+is @code{3}. Calculations may be nested; the result of a function may
be used for another calculation.
@lisp
@result{} #13
@end lisp
-These calculations are examples of evaluations: an expression (like
+These calculations are examples of evaluations; an expression like
@code{(* 3 4)} is replaced by its value @code{12}. A similar thing
happens with variables. After defining a variable
(intervals with a left and right point) are entered as @code{pairs}. A
pair@footnote{In Scheme terminology, the pair is called @code{cons},
and its two elements are called car and cdr respectively.} is entered
-as @code{(first . second)}, and like symbols, they must be quoted,
+as @code{(first . second)} and, like symbols, they must be quoted,
@example
\override TextScript #'extra-offset = #'(1 . 2)
We have been using lists all along. A calculation, like @code{(+ 1
2)} is also a list (containing the symbol @code{+} and the numbers 1
-and 2). For entering lists, use a quote @code{'} and for
-calculations, do not use a quote.
+and 2). Normally lists are interpreted as calculations, and the Scheme
+interpreter substitutes the outcome of the calculation. To enter a
+list, we stop evaluation. This is done by quoting the list with a
+quote @code{'} symbol. For calculations, do not use a quote.
Inside a quoted list or pair, there is no need to quote anymore. The
following is a pair of symbols, a list of symbols and a list of lists
#'((1) (2))
@end example
+@node File structure
+@section File structure
+The following items may be present in a @file{.ly} file at toplevel
+
+@itemize @bullet
+@item An output definition, such as @code{\bookpaper}, @code{\midi}
+and @code{\paper}. Such a definition at toplevel changes the default
+settings for the block entered.
+
+@item An @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 formats the block
+
+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 formats it into 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}.
+
+@end itemize
+
+The following example shows three things which may be entered at
+toplevel
+@verbatim
+ \paper {
+ % movements are non-justified by default
+ raggedright = ##t
+ }
+
+ \header {
+ title = "Do-re-mi"
+ }
+
+ { c'4 d' e2 }
+@end verbatim
+
+
+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{\encoding}
+@item @code{\renameinput}
+@end itemize
+
+
+
@node Interpretation contexts
@section Interpretation contexts
-When music is printed, a lot of things notation elements must be added
-to the input, which is often bare bones. For example, compare the
-input and output of the following example
+When music is printed, a lot of notation elements must be added to the
+input, which is often bare bones. For example, compare the input and
+output of the following example:
-@lilypond[verbatim,relative=2]
+@lilypond[verbatim,relative=2,fragment]
cis4 cis2. g4
@end lilypond
The input is rather sparse, but in the output, bar lines, accidentals,
-clef and time signature are added. LilyPond @emph{interprets} the
+clef, and time signature are added. LilyPond @emph{interprets} the
input. During this step, the musical information is inspected in time
order, similar to reading a score from left to right. While reading,
the program remembers where measure boundaries are, and what pitches
-need explicit accidentals.
+need explicit accidentals. This information can be presented on
+several levels. For example, the effect of an accidental is limited
+to a single stave, while a bar line must be synchronized across the
+entire score.
+
+Within LilyPond, these rules and bits of information are grouped in
+so-called Contexts. Examples of context are @context{Voice},
+@context{Staff}, and @context{Score}. They are hierarchical, for
+example, a @context{Staff} can contain many @context{Voice}s, and a
+@context{Score} can contain many @context{Staff} contexts.
+
+Each context has the responsibility for enforcing some notation rules,
+creating some notation objects and maintaining the associated
+properties. So, the synchronization of bar lines is handled at
+@context{Score} context. The @context{Voice} may introduce an
+accidentals and then the @context{Staff} context maintains the rule to
+show or suppress the accidental for the remainder of the measure.
+
+For simple scores, contexts are created implicitly, and you need not
+be aware of them. For larger pieces, such as piano music, they must be
+created explicitly to make sure that you get as many staves as you
+need, and that they are in the correct order. For typesetting pieces
+with specialized notation, it can be useful to modify existing or
+define new contexts.
-This is contextual information. and it can be present on several
-levels. For example, the effect of an accidental is limited to a
-single stave, while a bar line must be synchronized across the entire
-score. To match this hierarchy, LilyPond's interpretation step is
-hierarchical. There are interpretation contexts, like
-@context{Voice}, Staff and Score, and each level can maintain its own
-properties.
Full description of all available contexts is in the program
reference, see
@ifhtml
-@internalsref{Contexts}
+@internalsref{Contexts}.
@end ifhtml
@ifnothtml
Translation @arrow{} Context.
@end ifnothtml
-[TODO: describe propagation]
+@c [TODO: describe propagation]
@menu
* Creating contexts::
-* Changing context properties on the fly ::
+* Changing context properties on the fly::
* Modifying context plug-ins::
* Layout tunings within contexts::
* Changing context default settings::
For scores with only one voice and one staff, correct contexts are
created automatically. For more complex scores, it is necessary to
-instantiate them by hand. There are three commands to do this.
+create them by hand. There are three commands which do this.
The easiest command is @code{\new}, and it also the quickest to type.
-It is prepended to a music expression, for example
+It is prepended to a music expression, for example
+
+@cindex @code{\new}
+@cindex new contexts
+@cindex Context, creating
@example
\new @var{type} @var{music expression}
interpreting @var{music expression} with that.
A practical application of @code{\new} is a score with many
-staves. Each part that should be on its own staff, gets a @code{\new
-Staff}.
+staves. Each part that should be on its own staff, is preceded with
+@code{\new Staff}.
-@lilypond[verbatim,relative=2,raggedright]
+@lilypond[verbatim,relative=2,raggedright,fragment]
<< \new Staff { c4 c }
\new Staff { d4 d }
>>
@end lilypond
+@cindex @code{\context}
+
Like @code{\new}, the @code{\context} command also directs a music
expression to a context object, but gives the context an extra name. The
syntax is
This form will search for an existing context of type @var{type}
called @var{id}. If that context does not exist yet, it is created.
-This is useful if the context referred to later on. For example, when
+This is useful if the context is referred to later on. For example, when
setting lyrics the melody is in a named context
@example
@verbatim
music = \notes { c4 c4 }
-arts = \notes { s4-. s4-> }
+arts = \notes { s4-. s4-> }
@end verbatim
They are combined by sending both to the same @context{Voice} context,
>>
@end verbatim
@lilypond[raggedright]
-music = \notes { c4 c4 }
+music = \notes { c4 c4 }
arts = \notes { s4-. s4-> }
\score {
- \notes \relative c'' << \new Staff \context Voice = "A" \music
+ \notes \relative c'' << \new Staff \context Voice = "A" \music
\context Voice = "A" \arts
>>
}
@end lilypond
-
+@cindex @code{\context}
+@cindex creating contexts
The third command for creating contexts is
@example
\applyoutput #@var{function} % apply to Voice
@end example
-To have it interpreted at @context{Score} or @context{Staff} level use
+To have it interpreted at the @context{Score} or @context{Staff} level use
these forms
@example
@end example
-@node Changing context properties on the fly
-@subsection Changing context properties on the fly
+@node Changing context properties on the fly
+@subsection Changing context properties on the fly
+
+@cindex properties
+@cindex @code{\set}
+@cindex changing properties
Each context can have different @emph{properties}, variables contained
in that context. They can be changed during the interpretation step.
@end quotation
For example,
-@lilypond[verbatim,relative=2]
+@lilypond[verbatim,relative=2,fragment]
R1*2
\set Score.skipBars = ##t
R1*2
this case, it is @code{#t}, the boolean True value.
If the @var{context} argument is left out, then the current bottom-most
-context (typically @context{ChordNames}, @context{Voice} or
+context (typically @context{ChordNames}, @context{Voice}, or
@context{Lyrics}) is used. In this example,
-@lilypond[verbatim,relative=2]
+@lilypond[verbatim,relative=2,fragment]
c8 c c c
\set autoBeaming = ##f
c8 c c c
`on-the-fly', during the music, so that the setting only affects the
second group of eighth notes.
+@cindex @code{\unset}
+
There is also an @code{\unset} command,
@quotation
@code{\set }@var{context}@code{.}@var{prop}
@end quotation
@noindent
-which removes the definition of @var{prop}. This command only removes
-the definition if it is set in @var{context}. In
+which removes the definition of @var{prop}. This command removes
+the definition only if it is set in @var{context}. In
@example
\set Staff.autoBeaming = ##f
Settings that should only apply to a single time-step can be entered
easily with @code{\once}, for example in
-@lilypond[verbatim,relative=2]
+@lilypond[verbatim,relative=2,fragment]
c4
\once \set fontSize = #4.7
c4
For a full a description of each plug-in, see
@ifhtml
-@internalsref{Engravers}
+@internalsref{Engravers}.
@end ifhtml
@ifnothtml
Program reference @arrow Translation @arrow{} Engravers.
example which removes @code{Time_signature_engraver} and
@code{Clef_engraver} from a @code{Staff} context,
-@lilypond[relative=1, verbatim]
+@lilypond[relative=1, verbatim,fragment]
<< \new Staff {
f2 g
}
@end lilypond
In the second stave there are no time signature or clef symbols. This
-is a rather crude method of making objects disappear, it will affect the
-entire staff. The spacing will be adversely influenced too. More
-sophisticated methods of blanking objects are shown in (TODO).
+is a rather crude method of making objects disappear since it will affect
+the entire staff. The spacing will be adversely influenced too. A more
+sophisticated methods of blanking objects is shown in @ref{Common
+tweaks}.
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 Score to Staff context, we can
-have score where each staff has its own time signature.
+have a score where each staff has its own time signature.
@cindex polymetric scores
-@lilypond[relative=1,raggedright,verbatim]
+@lilypond[relative=1,raggedright,verbatim,fragment]
\new Score \with {
\remove "Timing_engraver"
} <<
@end example
Here @var{name} is the name of a graphical object, like @code{Stem} or
-@code{NoteHead}. @var{property} is an internal variable of the
-formatting system (`grob property' or `layout property'). It is a
-symbol, so it must be quoted. The subsection refTODO explains what to
-fill in for @var{name}, @var{property} and @var{value}. Here we only
-discuss functionality of this command.
+@code{NoteHead}, and @var{property} is an internal variable of the
+formatting system (`grob property' or `layout property'). The latter is a
+symbol, so it must be quoted. The subsection @ref{Constructing a
+tweak} explains what to fill in for @var{name}, @var{property}, and
+@var{value}. Here we only discuss functionality of this command.
The command
applies to the current staff. Other staves will keep their normal
appearance. Here we see the command in action:
-@lilypond[verbatim,relative=2]
+@lilypond[verbatim,relative=2,fragment]
c4
\override Staff.Stem #'thickness = #4.0
c4
@context{Staff}. After the command all stems are thickened.
Analogous to @code{\set}, the @var{context} argument may be left out,
-causing it to default to @context{Voice} and adding @code{\once} applies
-the change during only one timestep
+causing it to default to @context{Voice}, and adding @code{\once} applies
+the change during one timestep only
-@lilypond[verbatim,relative=2]
+@lilypond[fragment,verbatim,relative=2]
c4
\once \override Stem #'thickness = #4.0
c4
The @code{\override} must be done before the object is
started. Therefore, when altering @emph{Spanner} objects, like slurs or
-beams, the @code{\override} command must be executed at the moment that
+beams, the @code{\override} command must be executed at the moment when
the object is created. In this example,
-@lilypond[verbatim,relative=2]
+@lilypond[fragment,verbatim,relative=2]
\override Slur #'thickness = #3.0
c8[( c
\override Beam #'thickness = #0.6
The back-end is not very strict in type-checking object properties.
Cyclic references in Scheme values for properties can cause hangs
-and/or crashes.
+or crashes, or both.
@node Changing context default settings
\paper @{
@dots{}
\context @{
- \StaffContext
+ \Staff
\set fontSize = #-2
\override Stem #'thickness
@}
@end example
-This
+Here
@example
- \StaffContext
+ \Staff
@end example
@noindent
takes the existing definition @context{Staff} from the identifier
-@code{StaffContext}. This works analogously other contexts, so the
-existing definition of @code{Voice} is in
-@code{\VoiceContext}.
+@code{Staff}. This works analogously to other contexts.
The statements
@example
@refbugs
It is not possible to collect changes in a variable, and apply them to
-one @code{\context} definition by referencing that variable.
+one @code{\context} definition by referring to that variable.
@node Defining new contexts
@subsection Defining new contexts
-Specific contexts, like @context{Staff} and @code{Voice} are made of
+Specific contexts, like @context{Staff} and @code{Voice}, are made of
simple building blocks, and it is possible to compose engraver
plug-ins in different combinations, thereby creating new types of
contexts.
\override Stem #'transparent = ##t
\alias Voice
}
- \context { \StaffContext
+ \context { \Staff
\accepts "ImproVoice"
}}
\score { \notes \relative c'' {
@end example
In the following discussion, the example input shown should go on the
-@dots{} of the previous fragment.
+@dots{} in the previous fragment.
First, name the context gets a name. Instead of @context{Voice} it
will be called @context{ImproVoice},
\type "Engraver_group_engraver"
@end example
-Put together, we get
+Putting together, we get
@verbatim
\context {
@verbatim
\context {
- \StaffContext
+ \Staff
\accepts ImproVoice
}
@end verbatim
@dots{}
@}
\context @{
- \StaffContext
+ \Staff
\accepts "ImproVoice"
@}
@}
There are many different properties. Not all of them are listed in
this manual. However, the program reference lists them all in the
-section @internalsref{Context-properties}, and most properties are
-demonstrated in one of the
+section @internalsref{Tunable-context-properties}, and most properties
+are demonstrated in one of the
@ifhtml
-@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
+@uref{../../../../input/test/out-www/collated-files.html,tips-and-tricks}
@end ifhtml
@ifnothtml
tips-and-tricks
for many situations. The next section will discuss general use of
@code{\override}.
-
-
--nmost adjustments simply
-
-
-
-The commands changes
-
-
+@ignore
There are situations where default layout decisions are not
sufficient. In this section we discuss ways to override these
defaults.
Formatting is internally done by manipulating so called objects
(graphic objects). Each object carries with it a set of properties
-(object or layout properties) specific to that object. For example, a
-stem object has properties that specify its direction, length and
+(object or layout properties) specific to the 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
+The most direct way of tuning the output is to alter the values of
+these properties. There are two ways of doing that: First, you can
temporarily change the definition of one type of object, thus
affecting a whole set of objects. Second, you can select one specific
object, and set a layout property in that object.
#'layout-property-name
@end example
+@end ignore
@menu
* Common tweaks::
@subsection Common tweaks
Some overrides are so common that predefined commands are provided as
-a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
+a short-cut, for example, @code{\slurUp} and @code{\stemDown}. These
commands are described in
@ifhtml
the
The exact tuning possibilities for each type of layout object are
documented in the program reference of the respective
object. However, many layout objects share properties, which can be
-used to apply generic tweaks. We mention a couple of these:
+used to apply generic tweaks. We mention a few of these:
@itemize @bullet
@item The @code{extra-offset} property, which
@cindex setting object properties
-@lilypond[relative=1,verbatim]
+@lilypond[fragment,relative=1,verbatim]
\stemUp
f-5
\once \override Fingering
@cindex invisible objects
The following example demonstrates how to connect different voices
using ties. Normally, ties only connect two notes in the same
-voice. By introducing a tie in a different voice, and blanking a stem
-in that voice, the tie appears to cross voices:
+voice. By introducing a tie in a different voice,
+
+@lilypond[fragment,relative=2]
+ << {
+ b8~ b8\noBeam
+ } \\ {
+ b[ g8]
+ } >>
+@end lilypond
+
+@noindent
+and blanking a stem in that voice, the tie appears to cross voices:
@lilypond[fragment,relative=2,verbatim]
<< {
example; a more elaborate explanation is in @ref{Constructing a
tweak}:
-@lilypond[relative=1,verbatim]
+@lilypond[fragment,relative=1,verbatim]
c2\fermata
\override Script #'padding = #3
b2\fermata
@end itemize
-More specific overrides are also possible. The following section
+More specific overrides are also possible. The next section
discusses in depth how to figure out these statements for yourself.
means that we have to determine these bits of information:
@itemize
-@item The context, here: @context{Voice}.
-@item The layout object, here @code{Stem}.
-@item The layout property, here @code{thickness}
-@item A sensible value, here @code{3.0}
+@item the context: here @context{Voice}.
+@item the layout object: here @code{Stem}.
+@item the layout property: here @code{thickness}
+@item a sensible value: here @code{3.0}
@end itemize
and the program reference.
The program reference is a set of HTML pages, which is part of the
-documentation package. On Unix systems, it is is typically in
-@file{/usr/share/doc/lilypond}, if you have them, it is best to
+documentation package. On Unix systems, it is typically in
+@file{/usr/share/doc/lilypond}. If you have them, it is best to
bookmark them in your webbrowser, because you will need them. They
are also available on the web: go to the
@uref{http://lilypond.org,LilyPond website}, click ``Documentation'',
and they are exactly matched to LilyPond version installed.
-
-@c [TODO: revise for new site.]
-
@node Navigating the program reference
@subsection Navigating the program reference
Suppose we want to move the fingering indication in the fragment
below:
-@lilypond[relative=2,verbatim]
+@lilypond[fragment,relative=2,verbatim]
c-2
\stemUp
f
@end quotation
This fragments points to two parts of the program reference: a page
-on @code{FingerEvent} and @code{Fingering}.
+on @code{FingerEvent} and on @code{Fingering}.
The page on @code{FingerEvent} describes the properties of the music
expression for the input @code{-2}. The page contains many links
starts from the output, and ends at the input event.
The program reference can also be browsed like a normal document. It
-contains a chapter on @internalsref{Music definitions}, on
-@internalsref{Translation}, and the @internalsref{Backend}. Every
- chapter lists all the definitions used, and all properties that may
- be tuned.
+contains a chapter on
+@ifhtml
+@internalsref{Music-definitions},
+@end ifhtml
+@ifnothtml
+Music definitions
+@end ifnothtml
+on @internalsref{Translation}, and the @internalsref{Backend}. Every
+chapter lists all the definitions used, and all properties that may be
+tuned.
@node Layout interfaces
@item It is a piece of text. Granted, it's usually a very short text.
-@item That piece of text is set in a font, unlike slurs or beams.
+@item That piece of text is typeset with a font, unlike slurs or beams.
@item Horizontally, the center of the symbol should be aligned to the
center of the notehead
@item Vertically, the symbol is placed next to the note and the staff.
@internalsref{self-alignment-interface},
@internalsref{side-position-interface}, @internalsref{text-interface},
@internalsref{text-script-interface}, @internalsref{font-interface},
-@internalsref{finger-interface} and @internalsref{grob-interface}
+@internalsref{finger-interface}, and @internalsref{grob-interface}.
@end quotation
Clicking any of the links will take you to the page of the respective
are.
We have been talking of `the' @code{Fingering} object, but actually it
-does not amount to much. The initialization file
+does not amount to much. The initialization file
@file{scm/define-grobs.scm} shows the soul of the `object',
@verbatim
Recall that we wanted to change the position of the @b{2} in
-@lilypond[relative=2,verbatim]
+@lilypond[fragment,relative=2,verbatim]
c-2
\stemUp
f
Since the @b{2} is vertically positioned next to its note, we have to
meddle with the interface associated with this positioning. This is
-done by @code{side-position-interface}. The page for this interface says
+done using @code{side-position-interface}. The page for this interface
+says
@quotation
@code{side-position-interface}
notes. An elaborate example of those is in
@inputfileref{input/test,cue-notes.ly}.
+@cindex cue notes
@cindex @code{font-style}
@refcommands
-The following commands set @code{fontSize} for the current voice.
+The following commands set @code{fontSize} for the current voice:
@cindex @code{\tiny}
@code{\tiny},
@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}
+@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}.
+@code{italic}, @code{caps}, and @code{upright}.
@item @code{font-series}
is a symbol indicating the series of the font. There are typically several
@cindex font switching
The markup in the example demonstrates font switching commands. The
-command @code{\bold} and @code{\italic} only apply to the first
-following word; enclose a set of texts with braces to apply a command
+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 @} @}
In markup mode you can compose expressions, similar to mathematical
-expressions, XML documents and music expressions. The braces group
+expressions, XML documents, and music expressions. The braces group
notes into horizontal lines. Other types of lists also exist: you can
-stack expressions grouped with @code{<}, and @code{>} vertically with
+stack expressions grouped with @code{<} and @code{>} vertically with
the command @code{\column}. Similarly, @code{\center-align} aligns
texts by their center lines:
@section Global layout
The global layout determined by three factors: the page layout, the
-line breaks and the spacing. These all influence each other. The
+line breaks, and the spacing. These all influence each other. The
choice of spacing determines how densely each system of music is set,
-which influences where line breaks breaks are chosen, and thus
+which influences where line breaks are chosen, and thus
ultimately how many pages a piece of music takes. This section
explains how to tune the algorithm for spacing.
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{}, each page is filled with systems, and page breaks
-are chosen whenever the page gets full.
+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.
* Vertical spacing::
* Horizontal spacing::
* Line breaking::
+* Line length and line breaking::
+* Titling::
+* Page breaking::
+* Paper size::
* Page layout::
@end menu
@cindex @code{paper} file
The Feta font provides musical symbols at eight different
-sizes. Each font is tuned for a different staff size: at smaller sizes
-the font gets heavier, to match the relatively heavier staff lines.
+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:
@multitable @columnfractions .25 .25 .25 .25
@tab 7.9
@tab
-@item feta20
+@item feta26
@tab 25.2
@tab 8.9
@tab
@example
\paper @{
\context @{
- \PianoStaffContext
+ \PianoStaff
\override VerticalAlignment #'forced-distance = #9
@}
@dots{}
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
+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[fragment,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8
@cindex @code{stem-spacing-correction}
@cindex @code{spacing}
-In the introduction it was explained that stem directions influence
+In the Introduction it was explained that stem directions influence
spacing. This is controlled with @code{stem-spacing-correction}
property in @internalsref{NoteSpacing}, which are generated for every
@internalsref{Voice} context. The @code{StaffSpacing} object
\score { \notes {
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
+ \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|
}
created before any property commands are interpreted.
@example
\paper @{ \context @{
- \ScoreContext
- SpacingSpanner \override #'spacing-increment = #3.0
+ \Score
+ \override SpacingSpanner #'spacing-increment = #3.0
@} @}
@end example
score, the part containing the longer durations will be spaced too
widely.
-There is no convenient mechanism to manually override spacing.
+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.
@menu
@refcommands
-@code{\break}, @code{\noBreak}
+@code{\break}, and @code{\noBreak}.
@cindex @code{\break}
@cindex @code{\noBreak}
Internals: @internalsref{BreakEvent}.
-
-@node Page layout
-@subsection Page layout
+@node Line length and line breaking
+@subsection Line length and line breaking
@cindex page breaks
@cindex breaking pages
@cindex page layout
@cindex vertical spacing
-The page layout process happens outside the LilyPond formatting
-engine: variables controlling page layout are passed to the output,
-and are further interpreted by @code{lilypond} wrapper program. It
-responds to the following variables in the @code{\paper} block. 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,
-@c fixme: this should only be done if lastpagefill= #t
-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. The @command{lilypond-book} command ignores
-@code{lastpagefill}. See @ref{lilypond-book manual} 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. This
-is done by setting the @code{between-systems-strings} on the
-@internalsref{NonMusicalPaperColumn} where the system is broken.
-An example is shown in @inputfileref{input/regression,between-systems.ly}.
-The predefined command @code{\newpage} also does this.
+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 paragraphs. In a
+paragraph, the last line simply takes its natural length.
+
+
+@node Titling
+@subsection Titling
+
+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 poet
+ Name of the poet, left flushed below the subtitle.
+@item composer
+ Name of the composer, right flushed below the subtitle.
+@item meter
+ Meter string, left flushed below the poet.
+@item opus
+ Name of the opus, right flushed below the composer.
+@item arranger
+ Name of the arranger, right flushed 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, left flushed below the instrument.
+@end table
+
+This is a demonstration of the fields available,
+
+@lilypond[verbatim]
+\book {
+ \header {
+ title = "Title"
+ subtitle = "(and (the) subtitle)"
+ subsubtitle = "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 a
+@code{\markup}, e.g.
+
+@verbatim
+ \header {
+ title = \markup { \italic { The italic title } }
+ }
+@end verbatim
+
+A more advanced option is to change the Scheme functions
+@code{make-book-title} and @code{make-score-title} functions, defined
+in the @code{\bookpaper} of the @code{\book} block. These functions
+create a block of titling, given the information in the
+@code{\header}. The init file @file{ly/titling.scm} shows how the
+default format is created, and it may be used as a template for
+different styles.
+
+
+
+@cindex header
+@cindex footer
+@cindex page layout
+@cindex titles
+
+
+
+
+@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 with a bar line. These commands force and forbid a page-break
+from happening.
+
+Page breaks are computed by the @code{page-breaking} function in the
+@code{\bookpaper} block.
+
+@refcommands
+
+@cindex @code{\pageBreak}
+@code{\pageBreak}
+@cindex @code{\noPageBreak}
+@code{\noPageBreak}
+
+@node Paper size
+@subsection Paper size
@cindex paper size
@cindex page size
#(set-paper-size "a4")
@}
@end example
-The second one sets the size of the @code{\paper} block that it's in.
-
-@refcommands
+The second one sets the size of the @code{\paper} block that it is in.
-@cindex @code{\newpage}
-@code{\newpage}.
+@node Page layout
+@subsection Page layout
-@seealso
-
-In this manual: @ref{Invoking lilypond}.
-
-Examples: @inputfileref{input/regression,between-systems.ly}.
+@cindex page layout
+@cindex margins
+@cindex header, page
+@cindex footer, page
-Internals: @internalsref{NonMusicalPaperColumn}.
+LilyPond will do page layout, setting margins and adding headers and
+footers to each page.
-@refbugs
+The default layout responds to the following settings in the
+@code{\bookpaper} block
-LilyPond has no concept of page layout, which makes it difficult to
-reliably choose page breaks in longer pieces.
+@table @code
+@item hsize
+ The width of the page
+@item vsize
+ The height of the page
+@item top-margin
+ Margin between header and top of the page
+@item bottom-margin
+ Margin between footer and bottom of the page
+@item head-sep
+ Distance between top-most music system and the page header
+@item foot-sep
+ Distance between bottom-most music system and the page footer
+@item raggedbottom
+ If set to true, systems will not be spread across the page.
+@item raggedlastbottom
+ If set to true, systems will not be spread to fill the last page.
+@end table
+The default page header puts the page number and the @code{instrument}
+field from the @code{\header} block on a line.
-@node Output details
-@section Output details
-The default output format is La@TeX{}, which should be run
-through La@TeX{}. Using the option @option{-f}
-(or @option{--format}) other output formats can be selected also, but
- none of them work reliably.
+@cindex copyright
+@cindex tagline
-Now the music is output system by system (a `system' consists of all
-staves belonging together). From @TeX{}'s point of view, a system is an
-@code{\hbox} which contains a lowered @code{\vbox} so that it is centered
-vertically on the baseline of the text. Between systems,
-@code{\interscoreline} is inserted vertically to have stretchable space.
-The horizontal dimension of the @code{\hbox} is given by the
-@code{linewidth} parameter from LilyPond's @code{\paper} block.
+The default footer is empty, except for the first page, where it 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})''.
-After the last system LilyPond emits a stronger variant of
-@code{\interscoreline} only if the macro
-@code{\lilypondpaperlastpagefill} is not defined (flushing the systems
-to the top of the page). You can avoid that by setting the variable
-@code{lastpagefill} in LilyPond's @code{\paper} block.
+The header and footer are created by the functions @code{make-footer}
+and @code{make-header}, defined in @code{\bookpaper}. The default
+implementations are in @file{scm/page-layout.scm}.
-It is possible to fine-tune the vertical offset further by defining the
-macro @code{\lilypondscoreshift}:
+The following settings influence the header and footer layout.
-@example
-\def\lilypondscoreshift@{0.25\baselineskip@}
-@end example
+@table @code
+@item printpagenumber
+ this boolean controls whether a pagenumber is printed.
+@end table
-@noindent
-where @code{\baselineskip} is the distance from one text line to the next.
-Here an example how to embed a small LilyPond file @code{foo.ly} into
-running La@TeX{} text without using the @code{lilypond-book} script
-(@pxref{lilypond-book manual}):
-@example
-\documentclass@{article@}
+The page layout itself is done by two functions:
+@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.
-\def\lilypondpaperlastpagefill@{@}
-\lineskip 5pt
-\def\lilypondscoreshift@{0.25\baselineskip@}
-\begin@{document@}
-This is running text which includes an example music file
-\input@{foo.tex@}
-right here.
-\end@{document@}
-@end example
+@seealso
-The file @file{foo.tex} has been simply produced with
+Examples: @inputfileref{input/test/,page-breaks.ly}
-@example
- lilypond-bin foo.ly
-@end example
-The call to @code{\lineskip} assures that there is enough vertical space
-between the LilyPond box and the surrounding text lines.
projects / lilypond.git / blobdiff