Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.39"
+@c \version "2.13.42"
@ignore
GDP TODO list
@end example
The available unit suffixes are @code{\mm}, @code{\cm},
-@code{\in}, and @code{\pt}. For the sake of clarity, when using
-millimeters, the @code{\mm} is typically included in the code,
-even though it is not technically necessary.
+@code{\in}, and @code{\pt}. These units are simple values for
+converting from millimeters; they are defined in
+@file{ly/paper-defaults-init.ly}. For the sake of clarity, when
+using millimeters, the @code{\mm} is typically included in the
+code, even though it is not technically necessary.
It is also possible to define @code{\paper} values using Scheme.
The Scheme equivalent of the above example is:
@seealso
Notation Reference:
-@ref{Custom headers footers and titles}.
+@ref{Paper size and automatic scaling},
+@ref{Custom headers footers and titles},
+@ref{The \layout block}.
+
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
@node Paper size and automatic scaling
@end example
@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
Installed Files:
@file{scm/paper.scm}.
values of several @code{\paper} variables are automatically scaled
to the new size. To bypass the automatic scaling for a particular
variable, set the variable after setting the paper size. Note
-that the automatic scaling is not triggered by setting
-@code{paper-height} or @code{paper-width}, even though
+that the automatic scaling is not triggered by setting the
+@code{paper-height} or @code{paper-width} variables, even though
@code{paper-width} can influence other values (this is separate
from scaling and is discussed below). The
@code{set-default-paper-size} and @code{set-paper-size} functions
are described in @ref{Setting paper size}.
The vertical dimensions affected by automatic scaling are
-@code{top-margin} and @code{bottom-margin}. The horizontal
+@code{top-margin} and @code{bottom-margin} (see
+@ref{Fixed vertical spacing \paper variables}. The horizontal
dimensions affected by automatic scaling are @code{left-margin},
@code{right-margin}, @code{inner-margin}, @code{outer-margin},
-@code{binding-offset}, @code{indent}, and @code{short-indent}.
+@code{binding-offset}, @code{indent}, and @code{short-indent} (see
+@ref{Horizontal spacing \paper variables}.
The default values for these dimensions are set in
@file{ly/paper-defaults-init.ly}, using internal variables named
@code{210\mm}.
@seealso
+Notation Reference:
+@ref{Fixed vertical spacing \paper variables},
+@ref{Horizontal spacing \paper variables}.
+
Installed Files:
@file{ly/paper-defaults-init.ly},
@file{scm/paper.scm}.
@end table
@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
Installed Files:
@file{ly/paper-defaults-init.ly}.
@itemize
@item
-@code{padding} -- the minimum required amount of unobstructed
-vertical whitespace between two items, measured in staff-spaces.
-This can be thought of as the minimum height of an unobstructed
-(invisible) rectangle that extends from the leftmost to the
-rightmost point of the combined items.
-
-@item
-@code{space} -- the vertical distance, measured in staff-spaces,
-between the @emph{reference points} of the two items, when no
-collisions would result, and no stretching or compressing is in
-effect. The reference point of a (title or top-level) markup is
-its highest point, and the reference point of a system is the
-vertical center of the nearest @code{StaffSymbol} -- even if a
-non-staff line (such as a @code{Lyrics} context) is in the way.
-Values for @code{space} that are less than either @code{padding}
-or @code{minimum-distance} are not meaningful, since the resulting
-distance will never be less than either @code{padding} or
-@code{minimum-distance}.
+@code{basic-distance} -- the vertical distance, measured in
+staff-spaces, between the @emph{reference points} of the two
+items, when no collisions would result, and no stretching or
+compressing is in effect. The reference point of a (title or
+top-level) markup is its highest point, and the reference point of
+a system is the vertical center of the nearest @code{StaffSymbol}
+-- even if a non-staff line (such as a @code{Lyrics} context) is
+in the way. Values for @code{basic-distance} that are less than
+either @code{padding} or @code{minimum-distance} are not
+meaningful, since the resulting distance will never be less than
+either @code{padding} or @code{minimum-distance}.
@item
@code{minimum-distance} -- the smallest allowable vertical
meaningful, since the resulting distance will never be less than
@code{padding.}
+@c TODO: explain skylines somewhere and xref to it from here.
+
+@item
+@code{padding} -- the minimum required amount of unobstructed
+vertical whitespace between the bounding boxes (or skylines) of
+the two items, measured in staff-spaces.
+
@item
@code{stretchability} -- a unitless measure of the dimension's
relative propensity to stretch. If zero, the distance will not
as easily. Values should be non-negative and finite. The value
@code{+inf.0} triggers a @code{programming_error} and is ignored,
but @code{1.0e7} can be used for an almost infinitely stretchable
-spring. If unset, the default value is set to @code{space}. Note
-that the dimension's propensity to @emph{compress} cannot be
-directly set by the user and is equal to
-(@code{space}@tie{}@minus{}@tie{}@code{minimum-distance}).
+spring. If unset, the default value is set to
+@code{basic-distance}. Note that the dimension's propensity to
+@emph{compress} cannot be directly set by the user and is equal to
+(@code{basic-distance}@tie{}@minus{}@tie{}@code{minimum-distance}).
@end itemize
@itemize
@item
-@code{space},
+@code{basic-distance},
@item
@code{minimum-distance}, and
@example
\paper @{
- system-system-spacing #'space = #8
+ system-system-spacing #'basic-distance = #8
score-system-spacing =
- #'((padding . 1)
- (space . 12)
+ #'((basic-distance . 12)
(minimum-distance . 6)
+ (padding . 1)
(stretchability . 12))
@}
@end example
when unset. If @code{line-width} is set, and both
@code{left-margin} and @code{right-margin} are unset, then the
margins will be updated to center the systems on the page
-automatically. Also see @code{check-consistency}.
+automatically. Also see @code{check-consistency}. This variable
+can also be set in a @code{\layout} block.
@item left-margin
@funindex left-margin
@end table
@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
Installed Files:
@file{ly/paper-defaults-init.ly}.
@end table
@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
Installed Files:
@file{ly/paper-defaults-init.ly}.
@end table
@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
Installed Files:
@file{ly/paper-defaults-init.ly}.
Installed Files:
@file{ly/paper-defaults-init.ly}.
+@knownissues
+Odd page numbers are always on the right. If you want the
+music to start on page 1 there must be a blank page on the back
+of the cover page so that page 1 is on the right hand side.
+
@node Miscellaneous \paper variables
@unnumberedsubsubsec Miscellaneous @code{\paper} variables
variables that can appear in a @code{\layout} block are:
@itemize
-@item @code{ragged-right}
-@item @code{ragged-last}
-@item @code{indent}
-@item @code{short-indent}
-@item @code{system-count}
+
+@item
+@code{line-width}, @code{ragged-right} and @code{ragged-last}
+(see @ref{\paper variables for widths and margins})
+
+@item
+@code{indent} and @code{short-indent}
+(see @ref{\paper variables for shifts and indents})
+
+@item
+@code{system-count}
+(see @ref{\paper variables for line breaking})
+
@end itemize
Here is an example @code{\layout} block:
@example
\layout @{
- indent = 2.0\cm
+ indent = 2\cm
\context @{
\StaffGroup
- \override StaffGrouper #'staff-staff-spacing #space = #8
+ \override StaffGrouper #'staff-staff-spacing #'basic-distance = #8
@}
\context @{
\Voice
- \override TextScript #'padding = #1.0
+ \override TextScript #'padding = #1
\override Glissando #'thickness = #3
@}
@}
To set the staff size individually for each score, use
@example
\score@{
- ...
- \layout@{
- #(layout-set-staff-size 15)
+ @dots{}
+ \layout @{
+ #(layout-set-staff-size 15)
@}
@}
@end example
Line breaks are normally determined automatically. They are chosen
so that lines look neither cramped nor loose, and 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. However,
-line breaks can only occur at the end of @q{complete} bars, i.e.,
-where there are no notes or tuplets left @q{hanging} over the bar
-line. 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 ""},
-although again there must be no notes left hanging over in any of
-the staves at this point, or it will be ignored.
-
-The opposite command, @code{\noBreak}, forbids a line break at the
-bar line where it is inserted.
+lines have similar density.
+
+To manually force a line break at a bar line, use the
+@code{\break} command:
+
+@lilypond[quote,ragged-right,relative=2,verbatim]
+c4 c c c | \break
+c4 c c c |
+@end lilypond
+
+By default, a @code{\break} in the middle of a measure is ignored,
+and a warning is printed. To force a line break in the middle of
+a measure, add an invisible bar line with @w{@samp{\bar ""}}:
+
+@lilypond[quote,ragged-right,relative=2,verbatim]
+c4 c c
+\bar "" \break
+c |
+c4 c c c |
+@end lilypond
+
+A @code{\break} occuring at a bar line is also ignored if the
+previous measure ends in the middle of a note, such as when a
+tuplet begins and ends in different measures. To allow
+@code{\break} commands to work in these situations, remove the
+@code{Forbid_line_break_engraver} from the @code{Voice} context.
+Note that manually forced line breaks have to be added in parallel
+with the music:
+
+@lilypond[quote,ragged-right,verbatim]
+\new Voice \with {
+ \remove Forbid_line_break_engraver
+} \relative c'' {
+ <<
+ { c2. \times 2/3 { c4 c c } c2. | }
+ { s1 | \break s1 | }
+ >>
+}
+@end lilypond
+
+Similarly, line breaks are normally forbidden when beams cross bar
+lines. This behavior can be changed by setting
+@code{\override Beam #'breakable = ##t}:
+
+@lilypond[quote,ragged-right,relative=2,verbatim]
+\override Beam #'breakable = ##t
+c2. c8[ c | \break
+c8 c] c2. |
+@end lilypond
+
+The @code{\noBreak} command forbids a line break at the bar line
+where it is inserted.
The most basic settings influencing line spacing are @code{indent}
and @code{line-width}. They are set in the @code{\layout} block.
@example
\layout @{
-indent = #0
-line-width = #150
-ragged-last = ##t
+ indent = 0\mm
+ line-width = 150\mm
+ ragged-last = ##t
@}
@end example
every 4 measures, and only there:
@example
-<< \repeat unfold 7 @{
- s1 \noBreak s1 \noBreak
- s1 \noBreak s1 \break @}
- @emph{the real music}
+<<
+ \repeat unfold 7 @{
+ s1 \noBreak s1 \noBreak
+ s1 \noBreak s1 \break
+ @}
+ @{ @var{the actual music@dots{}} @}
>>
@end example
@seealso
+Notation Reference:
+@ref{\paper variables for line breaking}.
+
Snippets:
@rlsr{Spacing}.
@rinternals{LineBreakEvent}.
-@knownissues
-
-Line breaks can only occur if there is a @q{proper} bar line. A note
-which is hanging over a bar line is not proper, such as
-
-@lilypond[quote,ragged-right,relative=2,verbatim]
-c4 c2 << c2 {s4 \break } >> % this does nothing
-c2 c4 | % a break here would work
-c4 c2 c4 ~ \break % as does this break
-c4 c2 c4
-@end lilypond
-
-This can be avoided by removing the @code{Forbid_line_break_engraver}.
-Note that manually forced line breaks have to be added in parallel
-with the music.
-
-@lilypond[quote,ragged-right,verbatim]
-\new Voice \with {
- \remove Forbid_line_break_engraver
-} {
- c4 c2 << c2 {s4 \break } >> % now the break is allowed
- c2 c4
-}
-@end lilypond
-
-Similarly, line breaks are normally forbidden when beams cross bar
-lines. This behavior can be changed by setting
-@code{\override Beam #'breakable = ##t}.
-
-
@node Page breaking
@subsection Page breaking
@code{ragged-last} which have the same effect on vertical spacing:
@code{ragged-bottom} and @code{ragged-last-bottom}. If set to
@code{##t} the systems on all pages or just the last page
-respectively will not be justified vertically.
-
-For more details see @ref{Vertical spacing}.
+respectively will not be justified vertically. See
+@ref{Fixed vertical spacing \paper variables}.
Page breaks are computed by the @code{page-breaking} function. LilyPond
provides three algorithms for computing page breaks,
but the value can be changed in the @code{\paper} block:
@example
-\paper@{
- #(define page-breaking ly:page-turn-breaking)
+\paper @{
+ page-breaking = #ly:page-turn-breaking
@}
@end example
\paper @{
%% In a part consisting mostly of text,
%% ly:minimal-breaking may be preferred
- #(define page-breaking ly:minimal-breaking)
+ page-breaking = #ly:minimal-breaking
@}
\markup @{ @dots{} @}
@dots{}
@seealso
+Notation Reference:
+@ref{\paper variables for page breaking}.
+
Snippets:
@rlsr{Spacing}.
@example
\paper @{
- #(define page-breaking ly:minimal-breaking)
+ page-breaking = #ly:minimal-breaking
@}
@end example
ragged-bottom = ##t
}
+music = \relative c'' { c8 c c c }
+
\score {
\new Staff {
- \repeat unfold 2 { c'8 c'8 c'8 c'8 } \break
- \repeat unfold 4 { c'8 c'8 c'8 c'8 } \break
- \repeat unfold 6 { c'8 c'8 c'8 c'8 } \break
- \repeat unfold 8 { c'8 c'8 c'8 c'8 } \pageBreak
- \repeat unfold 8 { c'8 c'8 c'8 c'8 } \break
- \repeat unfold 6 { c'8 c'8 c'8 c'8 } \break
- \repeat unfold 4 { c'8 c'8 c'8 c'8 } \break
- \repeat unfold 2 { c'8 c'8 c'8 c'8 }
- }
+ \repeat unfold 2 { \music } \break
+ \repeat unfold 4 { \music } \break
+ \repeat unfold 6 { \music } \break
+ \repeat unfold 8 { \music } \pageBreak
+ \repeat unfold 8 { \music } \break
+ \repeat unfold 6 { \music } \break
+ \repeat unfold 4 { \music } \break
+ \repeat unfold 2 { \music }
+ }
\layout {
\context {
\Score
Line- and page-breaking information usually appears within note entry directly.
@example
+music = \relative c'' @{ c4 c c c @}
+
\score @{
\new Staff @{
- \repeat unfold 2 @{ c'4 c'4 c'4 c'4 @}
- \break
- \repeat unfold 3 @{ c'4 c'4 c'4 c'4 @}
+ \repeat unfold 2 @{ \music @} \break
+ \repeat unfold 3 @{ \music @}
@}
@}
@end example
breaking layout information.
@lilypond[quote,verbatim]
+music = \relative c'' { c4 c c c }
+
\score {
\new Staff <<
\new Voice {
s1 * 5 \break
}
\new Voice {
- \repeat unfold 2 { c'4 c'4 c'4 c'4 }
- \repeat unfold 3 { c'4 c'4 c'4 c'4 }
- \repeat unfold 6 { c'4 c'4 c'4 c'4 }
- \repeat unfold 5 { c'4 c'4 c'4 c'4 }
+ \repeat unfold 2 { \music }
+ \repeat unfold 3 { \music }
+ \repeat unfold 6 { \music }
+ \repeat unfold 5 { \music }
}
>>
}
@code{NonMusicalPaperColumnGrob}, as explained in @ref{Vertical spacing}.
@lilypond[quote,verbatim]
+music = \relative c'' { c4 c c c }
+
\score {
\new Staff <<
\new Voice {
s1 * 5 \break
}
\new Voice {
- \repeat unfold 2 { c'4 c'4 c'4 c'4 }
- \repeat unfold 3 { c'4 c'4 c'4 c'4 }
- \repeat unfold 6 { c'4 c'4 c'4 c'4 }
- \repeat unfold 5 { c'4 c'4 c'4 c'4 }
+ \repeat unfold 2 { \music }
+ \repeat unfold 3 { \music }
+ \repeat unfold 6 { \music }
+ \repeat unfold 5 { \music }
}
>>
}
of these reference points:
@lilypond[quote,noragged-right,line-width=110\mm]
-#(define zero-space '((padding . -inf.0) (space . 0)))
+#(define zero-space '((padding . -inf.0) (basic-distance . 0)))
alignToZero = \with {
\override VerticalAxisGroup #'nonstaff-relatedstaff-spacing = #zero-space
@example
\new Staff \with @{
- \override VerticalAxisGroup #'staff-staff-spacing #'space = #10
+ \override VerticalAxisGroup #'staff-staff-spacing #'basic-distance = #10
@} @{ @dots{} @}
\new Staff \with @{
\override VerticalAxisGroup #'staff-staff-spacing =
- #'((padding . 1)
- (space . 10)
+ #'((basic-distance . 10)
(minimum-distance . 9)
+ (padding . 1)
(stretchability . 10))
@} @{ @dots{} @}
@end example
\layout @{
\context @{
\Staff
- \override VerticalAxisGroup #'staff-staff-spacing #'space = #10
+ \override VerticalAxisGroup #'staff-staff-spacing #'basic-distance = #10
@}
@}
@end example
\context {
\Staff
\override VerticalAxisGroup #'staff-staff-spacing =
- #'((padding . 1)
- (space . 8)
- (minimum-distance . 7))
+ #'((basic-distance . 8)
+ (minimum-distance . 7)
+ (padding . 1))
}
}
\new StaffGroup <<
- % The very low note here needs more room than 'space can
- % provide, so the distance between this staff and the next is
- % determined by 'padding.
+ % The very low note here needs more room than 'basic-distance
+ % can provide, so the distance between this staff and the next
+ % is determined by 'padding.
\new Staff { b,2 r | }
- % Here, 'space provides enough room, and there is no need to
- % compress the space (towards 'minimum-distance) to make room
- % for anything else on the page, so the distance between this
- % staff and the next is determined by 'space.
+ % Here, 'basic-distance provides enough room, and there is no
+ % need to compress the space (towards 'minimum-distance) to make
+ % room for anything else on the page, so the distance between
+ % this staff and the next is determined by 'basic-distance.
\new Staff { \clef bass g2 r | }
% By setting 'padding to a negative value, staves can be made to
- % collide. The lowest acceptable value for 'space is 0.
+ % collide. The lowest acceptable value for 'basic-distance is 0.
\new Staff \with {
\override VerticalAxisGroup #'staff-staff-spacing =
- #'((padding . -10)
- (space . 3.5))
+ #'((basic-distance . 3.5)
+ (padding . -10))
} { \clef bass g2 r | }
\new Staff { \clef bass g2 r | }
>>
\context {
\Score
\override StaffGrouper #'staff-staff-spacing #'padding = #0
- \override StaffGrouper #'staff-staff-spacing #'space = #1
+ \override StaffGrouper #'staff-staff-spacing #'basic-distance = #1
}
}
<<
\new PianoStaff \with {
- \override StaffGrouper #'staffgroup-staff-spacing #'space = #20
+ \override StaffGrouper #'staffgroup-staff-spacing #'basic-distance = #20
} <<
\new Staff { c'1 }
\new Staff { c'1 }
\new StaffGroup
<<
\new Staff \with {
- \override VerticalAxisGroup #'staff-staff-spacing = #'((space . 30))
+ \override VerticalAxisGroup #'staff-staff-spacing = #'((basic-distance . 30))
} { c'1 }
\new Lyrics \with {
\override VerticalAxisGroup #'staff-affinity = #UP
@node Explicit staff and system positioning
@subsection Explicit staff and system positioning
-One way to understand the @code{VerticalAxisGroup} and @code{\paper}
-settings explained in the previous two sections is as a collection of
-different settings that primarily concern the amount of vertical padding
-different staves and systems running down the page.
+One way to understand the flexible vertical spacing mechanisms
+explained above is as a collection of settings that control the
+amount of vertical padding between staves and systems.
-It is possible to approach vertical spacing in a different way using
-@code{NonMusicalPaperColumn #'line-break-system-details}. Where
-@code{VerticalAxisGroup} and @code{\paper} settings specify vertical padding,
-@code{NonMusicalPaperColumn #'line-break-system-details} specifies exact
-vertical positions on the page.
+It is possible to approach vertical spacing in a different way
+using @code{NonMusicalPaperColumn #'line-break-system-details}.
+While the flexible vertical spacing mechanisms specify vertical
+padding, @code{NonMusicalPaperColumn #'line-break-system-details}
+can specify exact vertical positions on the page.
-@code{NonMusicalPaperColumn #'line-break-system-details} accepts an associative
-list of three different settings:
+@code{NonMusicalPaperColumn #'line-break-system-details} accepts
+an associative list of three different settings:
@itemize
@item @code{X-offset}
#'line-break-system-details #'((Y-offset . 40))
\overrideProperty NonMusicalPaperColumn
- #'line-break-system-details #'((X-offset . 20) (Y-offset . 40))
+ #'line-break-system-details #'((X-offset . 20)
+ (Y-offset . 40))
\overrideProperty NonMusicalPaperColumn
#'line-break-system-details #'((alignment-distances . (15)))
\overrideProperty NonMusicalPaperColumn
- #'line-break-system-details #'((X-offset . 20) (Y-offset . 40)
+ #'line-break-system-details #'((X-offset . 20)
+ (Y-offset . 40)
(alignment-distances . (15)))
@end example
@c \book { } is required in these examples to ensure the spacing
@c overrides can be seen between systems. -np
-@lilypond[quote]
+@lilypond[verbatim,quote,staffsize=16]
\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
the @code{Y-offset} pair in the @code{line-break-system-details}
attribute of the @code{NonMusicalPaperColumn} grob:
-@lilypond[quote]
+@lilypond[verbatim,quote,staffsize=16]
\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
within each system manually. We do this using the @code{alignment-distances}
subproperty of @code{line-break-system-details}.
-@lilypond[quote]
+@lilypond[verbatim,quote,staffsize=16]
\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
every system and every staff. Finally, note that @code{alignment-distances}
specifies the vertical positioning of staves but not of staff groups.
-@lilypond[quote]
+@lilypond[verbatim,quote,staffsize=16]
\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
@example
\paper @{
- system-system-spacing = #'((padding . 0) (space . 0.1))
+ system-system-spacing = #'((basic-distance . 0.1) (padding . 0))
ragged-last-bottom = ##f
ragged-bottom = ##f
@}
projects / lilypond.git / blobdiff