Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.39"
+@c \version "2.14.0"
@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
Common paper sizes are available, including @code{a4},
@code{letter}, @code{legal}, and @code{11x17} (also known as
tabloid). Many more paper sizes are supported by default. For
-details, see @file{scm/@/paper@/.scm}, and search for the
+details, see @file{scm/paper.scm}, and search for the
definition of @code{paper-alist}.
@c TODO add a new appendix for paper sizes (auto-generated) -pm
Extra sizes may be added by editing the definition of
@code{paper-alist} in the initialization file
-@file{scm/@/paper@/.scm}, however they will be overridden on a
+@file{scm/paper.scm}, however they will be overridden on a
subsequent install.
@cindex orientation
@end example
@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
Installed Files:
-@file{scm/@/paper@/.scm}.
+@file{scm/paper.scm}.
@node Automatic scaling to paper size
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}.
@ref{Optimal page turning},
@ref{Minimal page breaking}.
-Installed files:
+Installed Files:
@file{ly/paper-defaults-init.ly}.
@table @code
+@cindex page numbers, auto-numbering
@item auto-first-page-number
@funindex auto-first-page-number
will result in the first page number remaining as is or being
increased by one. Default: @code{#f}.
+@cindex page numbers, specify the first
@item first-page-number
@funindex first-page-number
If set to true, a page number is printed on the first page.
+@cindex page numbers, suppress
@item print-page-number
@funindex print-page-number
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
@seealso
-Installed files:
+Installed Files:
@file{ly/titling-init.ly}.
Snippets:
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} occurring 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
@c TODO Check this
-A linebreaking configuration can be saved as a @code{.ly} file
+A linebreaking configuration can be saved as a @file{.ly} file
automatically. This allows vertical alignments to be stretched to
fit pages in a second formatting run. This is fairly new and
complicated. More details are available in
@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 }
}
>>
}
@node Within-system spacing properties
@unnumberedsubsubsec Within-system spacing properties
+@funindex staff-affinity
+@funindex staffgroup-staff-spacing
+@funindex staff-staff-spacing
+@funindex nonstaff-unrelatedstaff-spacing
+@funindex nonstaff-relatedstaff-spacing
+@funindex nonstaff-nonstaff-spacing
+@funindex default-staff-staff-spacing
+@funindex minimum-Y-extent
+@funindex extra-offset
+@funindex self-alignment-X
+@funindex X-offset
+@funindex VerticalAxisGroup
+
The within-system vertical spacing mechanisms are controlled by
two sets of grob properties. The first set is associated with the
@code{VerticalAxisGroup} grob, which is created by all staves and
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
\context { \Dynamics \alignToZero }
\context { \FiguredBass \alignToZero }
\context { \Lyrics \alignToZero }
- \context { \NoteNames \alignToZero }
- \context { \ChordNames \alignToZero \lowerCaseChords }
+ \context { \NoteNames \alignToZero \staffAffinityDown }
+ \context { \ChordNames \alignToZero
+ \staffAffinityDown
+ \lowerCaseChords }
\context { \FretBoards \alignToZero \staffAffinityDown }
\context { \Score
\override BarLine #'stencil = ##f
\new RhythmicStaff {
\set RhythmicStaff.instrumentName = #"baseline "
\textLengthOn
- \labelContext "ChordNames" s1 |
- \labelContext "NoteNames" s1 |
+ \labelContext "ChordNames " s1 |
+ \labelContext "NoteNames " s1 |
\labelContext "Lyrics" s1 |
}
\new Lyrics { \lyrics { \skip 1*2 | ghijk1 | } }
\set RhythmicStaff.instrumentName = #"vertical center "
\labelContext "Dynamics" s1*3
}
- \new Dynamics { s2\mp s\fp }
+ \new Dynamics { s1\mp s\fp }
>>
%% The reference point for FiguredBass is its highest point
@end lilypond
Each of the vertical spacing grob properties (except
-@code{staff-affinity}) is stored as an alist (association list),
-and each uses the same alist structure as the @code{\paper}
-spacing variables discussed in
+@code{staff-affinity}) uses the same alist structure as the
+@code{\paper} spacing variables discussed in
@ref{Flexible vertical spacing \paper variables}. Specific methods
for modifying alists are discussed in @ref{Modifying alists}.
Grob properties should be adjusted with an @code{\override} inside
@example
\new Staff \with @{
- \override VerticalAxisGroup #'staff-staff-spacing #'space = #10
+ \override VerticalAxisGroup #'default-staff-staff-spacing
+ #'basic-distance = #10
@} @{ @dots{} @}
\new Staff \with @{
- \override VerticalAxisGroup #'staff-staff-spacing =
- #'((padding . 1)
- (space . 10)
+ \override VerticalAxisGroup #'default-staff-staff-spacing =
+ #'((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 #'default-staff-staff-spacing
+ #'basic-distance = #10
@}
@}
@end example
@table @code
@item staff-staff-spacing
-The distance between the current staff and the staff just below it
-in the same system, even if one or more non-staff lines (such as
-@code{Lyrics}) are placed between the two staves. Does not apply
-to the bottom staff of a system. This replaces any settings
-inherited from the @code{StaffGrouper} grob of the containing
-staff-group, if there is one. If this is unset, and there are no
-@code{StaffGrouper} properties to inherit, the
-@code{default-staff-staff-spacing} property is used.
+
+Used to determine the distance between the current staff and the
+staff just below it in the same system, even if one or more
+non-staff lines (such as @code{Lyrics}) are placed between the two
+staves. Does not apply to the bottom staff of a system.
+
+Initially, the @code{staff-staff-spacing} of a
+@code{VerticalAxisGroup} is a Scheme function that applies the
+properties of the @code{StaffGrouper} if the staff is part of a
+group, or the @code{default-staff-staff-spacing} of the staff
+otherwise. This allows staves to be spaced differently when they
+are grouped. For uniform spacing regardless of grouping, this
+function may be replaced by a flexible-spacing alist, using the
+complete-redefinition form of override shown above.
@item default-staff-staff-spacing
-The settings to use for @code{staff-staff-spacing} when it is
-unset. This applies to ungrouped staves and to grouped staves
-that do not inherit settings from the @code{StaffGrouper} grob.
+A flexible-spacing alist defining the @code{staff-staff-spacing} used for
+ungrouped staves, unless @code{staff-staff-spacing} has been explicitly
+set with an @code{\override}.
@item staff-affinity
The direction of the staff to use for spacing the current
@code{DOWN}; those at the bottom should use @code{UP}. Setting
@code{staff-affinity} for a staff causes it to be treated as a
non-staff line. Setting @code{staff-affinity} to @code{#f} causes
-a non-staff line to be treated as a staff.
-
-@c TODO: verify last clause below ("even if other...")
+a non-staff line to be treated as a staff. Setting
+@code{staff-affinity} to @code{UP}, @code{CENTER}, or @code{DOWN}
+causes a staff to be spaced as a non-staff line.
@item nonstaff-relatedstaff-spacing
The distance between the current non-staff line and the nearest
@code{CENTER}, then @code{nonstaff-relatedstaff-spacing} is used
for the nearest staves on @emph{both} sides, even if other
non-staff lines appear between the current one and either of the
-staves.
+staves. This means that the placement of a non-staff line depends
+on both the surrounding staves and the surrounding non-staff lines.
+Setting the @code{stretchability} of one of these types of spacing to
+a small value will make that spacing dominate. Setting the
+@code{stretchability} to a large value will make that spacing have
+little effect.
@item nonstaff-nonstaff-spacing
The distance between the current non-staff line and the next
@item staff-staff-spacing
The distance between consecutive staves within the current
staff-group. The @code{staff-staff-spacing} property of an
-individual staff's @code{VerticalAxisGroup} grob will be used
-instead for any staves in the staff-group that have it set. Also
-see @code{default-staff-staff-spacing}.
+individual staff's @code{VerticalAxisGroup} grob can be
+overriden with different spacing settings for that staff.
@item staffgroup-staff-spacing
The distance between the last staff of the current staff-group and
non-staff lines (such as @code{Lyrics}) exist between the two
staves. Does not apply to the bottom staff of a system. The
@code{staff-staff-spacing} property of an individual staff's
-@code{VerticalAxisGroup} grob will be used instead for any staves
-in the staff-group that have it set. Also see
-@code{default-staff-staff-spacing}.
+@code{VerticalAxisGroup} grob can be overriden with different
+spacing settings for that staff.
@end table
@seealso
-Installed files:
-@file{ly/engraver-init.ly},
-@file{scm/define-grobs.scm}.
+Notation Reference:
+@ref{Flexible vertical spacing \paper variables},
+@ref{Modifying alists}.
Internals Reference:
@rinternals{Contexts},
@rinternals{VerticalAxisGroup},
@rinternals{StaffGrouper}.
+Installed Files:
+@file{ly/engraver-init.ly},
+@file{scm/define-grobs.scm}.
+
@node Spacing of ungrouped staves
@unnumberedsubsubsec Spacing of ungrouped staves
@itemize
@item @code{VerticalAxisGroup} properties:
@itemize
+@item @code{default-staff-staff-spacing}
@item @code{staff-staff-spacing}
@end itemize
@end itemize
Additional properties are involved for staves that are part of a
staff-group; see @ref{Spacing of grouped staves}.
-The following example shows how the @code{staff-staff-spacing}
-property can affect the spacing of ungrouped staves:
+The following example shows how the @code{default-staff-staff-spacing}
+property can affect the spacing of ungrouped staves.
+The same overrides applied to @code{staff-staff-spacing} would
+have the same effect, but would also apply in cases where the staves
+are combined in a group or groups.
@lilypond[verbatim,quote,staffsize=16]
\layout {
\context {
\Staff
- \override VerticalAxisGroup #'staff-staff-spacing =
- #'((padding . 1)
- (space . 8)
- (minimum-distance . 7))
+ \override VerticalAxisGroup #'default-staff-staff-spacing =
+ #'((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))
+ \override VerticalAxisGroup #'default-staff-staff-spacing =
+ #'((basic-distance . 3.5)
+ (padding . -10))
} { \clef bass g2 r | }
\new Staff { \clef bass g2 r | }
>>
@item @code{VerticalAxisGroup} properties:
@itemize
@item @code{staff-staff-spacing}
-@item @code{default-staff-staff-spacing}
@end itemize
@item @code{StaffGrouper} properties:
@itemize
\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 {
In the @emph{Essay on automated music engraving}, it was explained
-that stem directions influence spacing (see @ressay{Optical
-spacing}). This is controlled with the
+that stem directions influence spacing (see
+@ressay{Optical spacing}). This is controlled with the
@code{stem-spacing-correction} property in the
@rinternals{NoteSpacing}, object. These are generated for every
@rinternals{Voice} context. The @code{StaffSpacing} object
@rinternals{StaffSpacing},
@rinternals{NonMusicalPaperColumn}.
+Essay on automated music engraving:
+@ressay{Optical spacing}.
+
@knownissues
Next we examine the effects of the @code{Separating_line_group_engraver} and
see why proportional scores frequently remove this engraver. The following
-example shows that there is a small amount of @qq{preferatory} space
+example shows that there is a small amount of @qq{prefatory} space
just before the first note in each system.
@lilypond[quote,verbatim,ragged-right]
@end lilypond
-The amount of this preferatory space is the same whether after a time
+The amount of this prefatory space is the same whether after a time
signature, a key signature or a clef. @code{Separating_line_group_engraver}
is responsible for this space. Removing @code{Separating_line_group_engraver}
reduces this space to zero.
}
@end lilypond
-Nonmusical elements like time signatures, key signatures, clefs and
+non-musical elements like time signatures, key signatures, clefs and
accidentals are problematic in proportional notation. None of these
elements has rhythmic duration. But all of these elements consume
horizontal space. Different proportional scores approach these
are exceptional and most proportional scores include at least some
time signatures. Clefs and accidentals are even more essential.
-So what strategies exist for spacing nonmusical elements in a
+So what strategies exist for spacing non-musical elements in a
proportional context? One good option is the @code{strict-note-spacing}
property of @code{SpacingSpanner}. Compare the two scores below:
@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