-@c -*-texinfo-*-
+@c -*- coding: latin-1; mode: texinfo; -*-
@node Changing defaults
@chapter Changing defaults
* Modifying context plug-ins::
* Layout tunings within contexts::
* Changing context default settings::
-* Defining new contexts::
+* Defining new contexts::
@end menu
@node Creating contexts
are equivalent.
+@cindex \once
Settings that should only apply to a single time-step can be entered
with @code{\once}, for example in
The adjustments of the previous subsections (@ref{Changing context
properties on the fly}, @ref{Modifying context plug-ins} and
@ref{Layout tunings within contexts}) can also be entered separate
-from the music, in the @code{\paper} block,
+from the music, in the @code{\layout} block,
@example
-\paper @{
+\layout @{
@dots{}
\context @{
\Staff
\set fontSize = #-2
- \override Stem #'thickness
+ \override Stem #'thickness = #4.0
\remove "Time_signature_engraver"
@}
@}
The statements
@example
\set fontSize = #-2
- \override Stem #'thickness
+ \override Stem #'thickness = #4.0
\remove "Time_signature_engraver"
@end example
Other contexts can be modified analogously.
-The @code{\set} keyword is optional within the @code{\paper} block, so
+The @code{\set} keyword is optional within the @code{\layout} block, so
@example
\context @{
them to one @code{\context} definition by referring to that variable.
-@node Defining new contexts
-@subsection Defining new contexts
+@node Defining new contexts
+@subsection Defining new contexts
Specific contexts, like @context{Staff} and @code{Voice}, are made of
simple building blocks, and it is possible to compose engraver
to indicate improvisation in Jazz pieces,
@lilypond[raggedright]
- \paper { \context {
+ \layout { \context {
\name ImproVoice
\type "Engraver_group_engraver"
\consists "Note_heads_engraver"
These settings are again done within a @code{\context} block inside a
-@code{\paper} block,
+@code{\layout} block,
@example
- \paper @{
+ \layout @{
\context @{
@dots{}
@}
\name ImproVoice
\type "Engraver_group_engraver"
\consists "Note_heads_engraver"
- \consists "Text_script_engraver"
+ \consists "Text_engraver"
\consists Pitch_squash_engraver
squashedPosition = #0
\override NoteHead #'style = #'slash
}
@end verbatim
-Putting both into a @code{\paper} block, like
+Putting both into a @code{\layout} block, like
@example
- \paper @{
+ \layout @{
\context @{
\name ImproVoice
@dots{}
@itemize @bullet
@item Its size is independent of the horizontal spacing, unlike slurs or beams.
-@item It is a piece of text. Granted, it's usually a very short text.
+@item It is a piece of text. Granted, it is usually a very short text.
@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
@verbatim
(Fingering
. (
- (print-function . ,Text_item::print)
+ (print-function . ,Text_interface::print)
(padding . 0.6)
(staff-padding . 0.6)
(self-alignment-X . 0)
and is passed similarly to lyric syllables.
If no @code{\encoding} has been specified, then the encoding is taken
-from the @code{\paper} block (or @code{\bookpaper}, if @code{\paper}
+from the @code{\layout} block (or @code{\paper}, if @code{\layout}
does not specify encoding). The variable @code{inputencoding} may be
set to a string or symbol specifying the encoding, e.g.
@verbatim
- \paper {
+ \layout {
inputencoding = "latin1"
}
@end verbatim
@verbatim
\header {
title = "Grazing cow"
- instrument = "Baßtuba"
+ instrument = "Baßtuba"
}
@end verbatim
Rather, you should say
@verbatim
- instrument = \markup { Baßtuba }
+ instrument = \markup { Baßtuba }
@end verbatim
@noindent
-or set @code{inputencoding} in the @code{\bookpaper} block.
+or set @code{inputencoding} in the @code{\paper} block.
There is a special encoding, called @code{TeX}. This encoding does not
reencode text for the font used. Rather, it tries to guess the width
@subsection Nested scores
It is possible to nest music inside markups, by adding a @code{\score}
-block to markup expression. Such a score must contain a @code{\paper}
+block to markup expression. Such a score must contain a @code{\layout}
block.
@lilypond[verbatim,raggedright]
c4 d^\markup {
\score {
\relative { c4 d e f }
- \paper { }
+ \layout { }
}
}
e f
@menu
* Setting global staff size::
+* Vertical spacing of piano staves::
* Vertical spacing::
* Horizontal spacing::
+* Line length::
* Line breaking::
-* Line length and line breaking::
* Multiple movements::
-* Titling::
+* Creating titles::
* Page breaking::
-* Paper size::
+* paper size::
* Page layout::
@end menu
@cindex font size, setting
@cindex staff size, setting
-@cindex @code{paper} file
+@cindex @code{layout} file
The Feta font provides musical symbols at eight different
sizes. Each font is tuned for a different staff size: at a smaller size
@tab 12.60
@tab 4.4
@tab
-
+
@item feta14
@tab 14.14
@tab 5.0
-@menu
-* Vertical spacing::
-* Horizontal spacing::
-* Line breaking::
-* Page layout::
-@end menu
-
@node Vertical spacing of piano staves
@subsection Vertical spacing of piano staves
It can be adjusted as follows
@verbatim
\new PianoStaff \with {
- \override VerticalAlignment #'forced-distance = #9
+ \override VerticalAlignment #'forced-distance = #7
} {
...
}
-@end example
-This would bring the staves together at a distance of 9 staff spaces,
+@end verbatim
+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[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 Vertical spacing
@subsection Vertical spacing
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
+@lilypond[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, 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 NHW of space. For normal
-notes, this space is always counted from the left edge of the symbol, so
-the shortest notes are generally followed by one NHW of space.
+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
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 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 the most commonly found shortest note. Notes that are even
-shorter this 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:
+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.
-@lilypond[fragment,verbatim,relative=2]
- c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
-@end lilypond
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}.
+1/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 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}
-property in @internalsref{NoteSpacing}, which are generated for every
+Notes that are even shorter than the commoon 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[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 at @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
+for controlling the stem/bar line spacing. The following example shows
+these corrections, once with default settings, and once with
exaggerated corrections:
@lilypond[raggedright]
}
@end lilypond
-@cindex SpacingSpanner, overriding properties
-
-Properties of the @internalsref{SpacingSpanner} must be overridden
-from the @code{\paper} block, since the @internalsref{SpacingSpanner} is
-created before any property commands are interpreted.
-@example
-\paper @{ \context @{
- \Score
- \override SpacingSpanner #'spacing-increment = #3.0
-@} @}
-@end example
-
@seealso
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 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
Internals: @internalsref{BreakEvent}.
-@node Line length and line breaking
-@subsection Line length and line breaking
-
-@cindex page breaks
-@cindex breaking pages
-
-@cindex @code{indent}
-@cindex @code{linewidth}
-
-The most basic settings influencing the spacing are @code{indent} and
-@code{linewidth}. They are set in the @code{\paper} block. They
-control the indentation of the first line of music, and the lengths of
-the lines.
-
-If @code{raggedright} is set to true in the @code{\paper}
-block, then the lines are justified at their natural length. This
-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 paragraphs. In a
-paragraph, the last line simply takes its natural length.
@node Multiple movements
@}
@end example
-@node Titling
-@subsection Titling
+@node Creating titles
+@subsection Creating titles
Titles are created for each @code{\score} block, and over a
@code{\book}.
\book {
\header {
title = "Title"
- subtitle = "(and (the) subtitle)"
+ subtitle = "and the subtitle"
subsubtitle = "Sub sub title"
poet = "Poet"
composer = "Composer"
}
{ c'1 }
}
+ \paper {
+ linewidth = 8.0 \cm
+ }
}
@end lilypond
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
+in the @code{\paper} 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 \bookpaper
+@cindex \paper
@cindex header
@cindex footer
@cindex page layout
@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.
+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{\bookpaper} block.
+@code{\paper} block.
@refcommands
@cindex @code{\noPageBreak}
@code{\noPageBreak}
-@node Paper size
-@subsection Paper size
+@node paper size
+@subsection paper size
@cindex paper size
@cindex page size
To change the paper size, there are two commands,
@example
#(set-default-paper-size "a4")
- \paper@{
+ \layout@{
#(set-paper-size "a4")
@}
@end example
-The second one sets the size of the @code{\paper} block that it is in.
+The second one sets the size of the @code{\layout} block that it is in.
+The following paper sizes are supported.
+
+@table @code
+@item a6
+@item a5
+@item a4
+@item a3
+@item legal
+@item letter
+@item tabloid
+@end table
+
+@cindex orientation
+@cindex landscape
+
+If the symbol @code{landscape} is supplied as argument to
+@code{set-default-paper-size}, the pages will be rotated 90 degrees,
+and line widths will be set longer correspondingly.
+
+@example
+#(set-default-paper-size "a6" 'landscape)
+@end example
@node Page layout
@subsection Page layout
footers to each page.
The default layout responds to the following settings in the
-@code{\bookpaper} block
-@cindex \bookpaper
+@code{\paper} block
+
+@cindex \paper
@table @code
@item firstpagenumber
The value of the page number of the first page. Default is 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
@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.
+ Margin between the left side of the page and the beginning of the music
@item linewidth
- The length of the paper line.
+ The length of the systems
@item headsep
Distance between top-most music system and the page header
@item footsep
Distance between bottom-most music system and the page footer
@item raggedbottom
- If set to true, systems will not be spread across the page.
+ 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 true, systems will not be spread to fill the last page.
+ 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
+topmost of the next system.
+
+Increasing this will put systems whose bounding boxes almost touch
+farther apart.
+
+@item aftertitlespace
+Amount of space between title and the first system
+@item beforetitlespace
+Amount of space between last system of the previous piece and the
+title of the next
+@item betweentitlespace
+Amount of space between consecutive titles (eg. the title of the
+book and the title of piece).
+
@end table
@example
- \bookpaper@{
+ \paper@{
hsize = 2\cm
topmargin = 3\cm
bottommargin = 3\cm
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{book-paper-defaults.ly} with values in millimeters. That's why the
+@file{paper-defaults.ly} with values in millimeters. That's why the
value has to be multiplied in the example above.
@example
- \bookpaper@{
+ \paper@{
#(define bottommargin (* 2 cm))
@}
@end example
can.}
The header and footer are created by the functions @code{make-footer}
-and @code{make-header}, defined in @code{\bookpaper}. The default
+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.
this boolean controls whether a pagenumber is printed.
@end table
-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.
+The page layout itself is done by two functions in the
+@code{\paper}, @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.
@seealso
-Examples: @inputfileref{input/test/,page-breaks.ly}
+Examples: @inputfileref{input/test,page-breaks.ly}
@refbugs
toplevel expressions is one of the following
@itemize @bullet
-@item An output definition, such as @code{\bookpaper}, @code{\midi}
-and @code{\paper}. Such a definition at toplevel changes the default
+@item An output definition, such as @code{\paper}, @code{\midi}
+and @code{\layout}. 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
The following example shows three things which may be entered at
toplevel
@verbatim
- \paper {
+ \layout {
% movements are non-justified by default
raggedright = ##t
}