printable area (ie. the top of the bottom margin).
See @var{after-title-spacing}.
-@item foot-separation
-@funindex foot-separation
-
-Distance between the bottom-most music system and the page
-footer. Default: @code{4\mm}.
-
@item top-title-spacing
@funindex top-title-spacing
@table @code
+@item binding-offset
+@funindex binding-offset
+
+The amount @code{inner-margin} is increased
+to make sure nothing will be hidden by the binding.
+Works only with @code{two-sided} set to true. Default:
+@code{0}.
+
@item horizontal-shift
@funindex horizontal-shift
The level of indentation for the first system in a score.
Default: @code{15\mm}.
+@item inner-margin
+@funindex inner-margin
+
+The margin all pages have at the inner side if they are part
+of a book. Works only with @code{two-sided} set to true.
+Default: @code{10\mm}.
+
@item left-margin
@funindex left-margin
The margin between the left edge of the page and the beginning of
each system. Default: @code{10\mm}.
-@item right-margin
-@funindex right-margin
-
-The margin between the right edge of the page and the beginning of
-each system. Default: @code{10\mm}.
-
@item line-width
@funindex line-width
The width of music systems. Default: @code{paper-width} minus
@code{left-margin} and @code{right-margin}.
+@item outer-margin
+@funindex outer-margin
+
+The margin all pages have at the outer side if they are part
+of a book. Works only with @code{two-sided} set to true.
+Default: @code{20\mm}.
+
@item paper-width
@funindex paper-width
The width of the page. Default: the width of the current paper
size. For details, see @ref{Paper size}.
+@item right-margin
+@funindex right-margin
+
+The margin between the right edge of the page and the end of
+each system. Default: @code{10\mm}.
+
@item short-indent
@funindex short-indent
This is currently supported only by the @code{ly:optimal-breaking} algorithm.
Default: unset.
+@item two-sided
+@funindex two-sided
+
+If set to true, use @code{inner-margin}, @code{outer-margin} and
+@code{binding-offset} to determine margins depending on whether
+the page number is odd or even. This overrides @code{left-margin}
+and @code{right-margin}. Default: @code{##f}.
+
@end table
@cindex space between staves
@cindex space inside systems
-The height of each system is determined automatically. To prevent
-staves from bumping into each other, some minimum distances are set.
-By changing these, you can put staves closer together. This
-reduces the amount of space each system requires, and may result
-in having more systems per page.
-
-Normally staves are stacked vertically. To make staves maintain a
-distance, their vertical size is padded. This is done with the
-property @code{minimum-Y-extent}. When applied to a
-@rinternals{VerticalAxisGroup}, it controls the size of a horizontal
-line, such as a staff or a line of lyrics. @code{minimum-Y-extent}
-takes a pair of numbers, so
-if you want to make it smaller than its default @code{#'(-4 . 4)}
-then you could set
+The height of each system is determined in two steps. First, all of the
+staves are spaced according to the amount of space available. Then, the
+non-staff lines (eg. lyrics or chords) are distributed between the
+staves.
-@example
-\override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
-@end example
+@unnumberedsubsubsec Spacing between staves
+Spacing between staves is controlled by the @var{next-staff-spacing}
+property of the @var{VerticalAxisGroup} grob. This property is an alist
+with four elements: @var{space}, @var{minimum-distance}, @var{padding}
+and @var{stretchability}:
+@itemize
+@item
+@var{space} is the size of the stretchable space between the center line
+of one staff to the center line of the next staff.
-@noindent
-This sets the vertical size of the current staff to 3 staff spaces on
-either side of the center staff line. The value @code{(-3 . 3)} is
-interpreted as an interval, where the center line is the 0, so the
-first number is generally negative. The numbers need not match;
-for example, the staff can be made larger at the bottom by setting
-it to @code{(-6 . 4)}.
+@item
+@var{minimum-distance} provides a lower bound on the final distance
+between the center line of one staff to the center line of the next
+staff. That is, if a page has many systems and needs to be compressed,
+the distance from this staff to the next will never be compressed to
+less than @var{minimum-distance}.
-@ignore
-FIXME: update this section
-
-After page breaks are determined, the vertical spacing within each
-system is reevaluated in order to fill the page more evenly; if a page
-has space left over, systems are stretched in order to fill that space.
-The amount of stretching can be configured though the @code{max-stretch}
-property of the @rinternals{VerticalAlignment} grob. By default,
-@code{max-stretch} is set to zero, disabling stretching. To enable
-stretching, a sane value for @code{max-stretch}
-is @code{ly:align-interface::calc-max-stretch}.
-
-In some situations, you may want to stretch most of a system while
-leaving some parts fixed. For example, if a piano part occurs in the
-middle of an orchestral score, you may want to leave the piano staves
-close to each other while stretching the rest of the score. The
-@code{keep-fixed-while-stretching} property of
-@rinternals{VerticalAxisGroup} can be used to achieve this. When set
-to @code{##t}, this property keeps its staff (or line of lyrics) from
-moving relative to the one directly above it. In the example above,
-you would override @code{keep-fixed-while-stretching} to @code{##t} in
-the second piano staff:
+@item
+@var{padding} is the amount of whitespace that must be present between
+the bottom of one staff and the top of the next. It differs from
+@var{minimum-distance} in that the effect of @var{padding} depends on
+the height of objects in the staff. For example, @var{padding} is more
+likely to come into effect for staves with notes that are far below the
+staff.
+
+@item
+@var{stretchability} controls the stretchable space's propensity to
+stretch when the system is stretched. Large values will cause a
+system to stretch more, while a value of zero will prevent the
+space from stretching at all. If unset, @var{stretchability}
+defaults to @code{space - minimum-distance}.
+@end itemize
@lilypond[verbatim]
-#(set-default-paper-size "a6")
-#(set-global-staff-size 14.0)
+#(set-global-staff-size 16)
+\new StaffGroup <<
+ % Since space is small and there is no minimum-distance, the distance
+ % between this staff and the next will be determined by padding.
+ \new Staff \with {
+ \override VerticalAxisGroup #'next-staff-spacing =
+ #'((space . 1) (padding . 1))
+ }
+ { \clef bass c, }
+ % Since space is small and nothing sticks out very far, the distance
+ % between this staff and the next will be determined by minimum-distance.
+ \new Staff \with {
+ \override VerticalAxisGroup #'next-staff-spacing =
+ #'((space . 1) (minimum-distance . 12))
+ }
+ { \clef bass c, }
+ % By setting padding to a negative value, staves can be made to collide.
+ \new Staff \with {
+ \override VerticalAxisGroup #'next-staff-spacing =
+ #'((space . 4) (padding . -10))
+ }
+ { \clef bass c, }
+ \new Staff { \clef bass c, }
+>>
+@end lilypond
-\book {
-\paper {
- ragged-last-bottom = ##f
-}
-\new Score \with
-{
- \override VerticalAlignment #'max-stretch = #ly:align-interface::calc-max-stretch
-}
-{
-\new GrandStaff
-<<
- \new StaffGroup
- <<
- \new Staff {c' d' e' f'}
- \new Staff {c' d' e' f'}
- \new Staff {c' d' e' f'}
- >>
+In orchestral and other large scores, it is common to place staves in
+groups. The space between groups is typically larger than the space
+between staves of the same group. This spacing can be tweaked with the
+@var{StaffGrouper} grob: the default value of @var{next-staff-spacing}
+for @var{VerticalAxisGroup} is a callback function which operates by
+searching for a @var{StaffGrouper} grob containing the staff. If it
+finds a @var{StaffGrouper} grob and the staff in question is in the
+middle of a group, it reads the @var{between-staff-spacing} property of
+@var{StaffGrouper} and returns it. If the staff in question is the last
+staff of a group, the callback reads the @var{after-last-staff-spacing}
+property of @var{StaffGrouper} and returns it. If the callback did not
+find a @var{StaffGrouper} grob, it reads
+@var{default-next-staff-spacing} from its @var{VerticalAxisGroup} and
+returns that.
- \new PianoStaff
+@lilypond[verbatim]
+#(set-global-staff-size 16)
+<<
+ \new PianoStaff \with {
+ \override StaffGrouper #'between-staff-spacing #'space = #1
+ \override StaffGrouper #'between-staff-spacing #'padding = #0
+ \override StaffGrouper #'after-last-staff-spacing #'space = #20
+ }
<<
- \new Staff {c' d' e' f'}
- \new Staff \with {
- \override VerticalAxisGroup #'keep-fixed-while-stretching = ##t
- }
- {c' d' e' f'}
+ \new Staff c'1
+ \new Staff c'1
>>
- \new StaffGroup
+ \new StaffGroup \with {
+ \override StaffGrouper #'between-staff-spacing #'space = #1
+ \override StaffGrouper #'between-staff-spacing #'padding = #0
+ }
<<
- \new Staff {c' d' e' f'}
- \new Staff {c' d' e' f'}
+ \new Staff c'1
+ \new Staff c'1
>>
>>
-}
-}
@end lilypond
-@end ignore
-Vertical alignment of staves is handled by the
-@code{VerticalAlignment} object. The context parameters
-specifying the vertical extent are described in connection with
-the @code{Axis_group_engraver}.
+@unnumberedsubsubsec Spacing of non-staff lines
+
+After the positions of the staves are determined, the non-staff lines
+are distributed between the staves. Each of these lines has a
+@var{staff-affinity} property which controls its vertical alignment.
+For example,
+
+@example
+\new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #DOWN @}
+@end example
+
+@noindent creates a lyrics context that will be placed close to the
+staff below it. Setting @var{staff-affinity} to something which is not
+a number (@code{#f}, for example) will cause that line to be treated
+like a staff. Conversely, setting @var{staff-affinity} for a staff will
+cause it to be treated like a non-staff.
+
+Non-staff lines admit three properties to control their spacing. Each
+of the these properties is an alist of the same format as
+@var{next-staff-spacing}, above.
+@itemize
+@item
+If the nearest line in the @var{staff-affinity} direction is a staff
+then @var{inter-staff-spacing} gives the spacing between the non-staff
+and the staff. If @var{staff-affinity} is @code{CENTER}, then
+@var{inter-staff-spacing} is used for both directions.
+
+@item
+If the nearest line in the @var{staff-affinity} direction is a non-staff
+then @var{inter-loose-line-spacing} gives the spacing between the two
+non-staff lines.
+
+@item
+If the nearest line in the opposite direction to @var{staff-affinity} is
+a staff then @var{non-affinity-spacing} gives the spacing between the
+non-staff and the staff. This can be used, for example, to require
+a minimum amount of padding between a Lyrics line and the staff
+to which it does not belong.
+@end itemize
+
+@lilypond[verbatim]
+#(set-global-staff-size 16)
+\layout {
+ \context {
+ \Lyrics
+ % By default, Lyrics are placed close together. Here, we allow them to
+ % be stretched more widely.
+ \override VerticalAxisGroup
+ #'inter-loose-line-spacing #'stretchability = #1000
+ }
+}
+
+\new StaffGroup
+<<
+ \new Staff \with {
+ \override VerticalAxisGroup #'next-staff-spacing = #'((space . 30)) }
+ { c'1 }
+ \new Lyrics \with {
+ \override VerticalAxisGroup #'staff-affinity = #UP }
+ \lyricmode { up }
+ \new Lyrics \with {
+ \override VerticalAxisGroup #'staff-affinity = #CENTER }
+ \lyricmode { center }
+ \new Lyrics \with {
+ \override VerticalAxisGroup #'staff-affinity = #DOWN }
+ \lyricmode { down }
+ \new Staff
+ { c'1 }
+>>
+@end lilypond
@seealso
Snippets:
@c @lsr{spacing,alignment-vertical-spacing.ly}.
Internals Reference:
+@rinternals{VerticalAxisGroup},
@rinternals{VerticalAlignment},
@rinternals{Axis_group_engraver}.
-
-@node Vertical spacing between systems
-@subsection Vertical spacing between systems
-
-Space between systems are controlled by four @code{\paper} variables,
-
+@knownissues
+Adjacent non-staff lines should have non-increasing
+@var{staff-affinity} from top-to-bottom. For example, the behavior of
@example
-\paper @{
- between-system-space = 1.5\cm
- between-system-padding = #1
- ragged-bottom=##f
- ragged-last-bottom=##f
-@}
+<<
+ \new Staff c
+ \new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #DOWN @}
+ \new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #UP @}
+ \new Staff c
+>>
@end example
+is undefined.
-When only a couple of flat systems are placed on a page, the resulting
-vertical spacing may be non-elegant: one system at the top of the page,
-and the other at the bottom, with a huge gap between them. To avoid this
-situation, the space added between the systems can be limited. This
-feature is activated by setting to @code{#t} the
-@code{page-limit-inter-system-space} variable in the @code{\paper}
-block. The paper variable @code{page-limit-inter-system-space-factor}
-determines how much the space can be increased: for instance, the value
-@code{1.3} means that the space can be 30% larger than what it would be
-on a ragged-bottom page.
-
-In the following example, if the inter system space were not limited,
-the second system of page 1 would be placed at the page bottom. By
-activating the space limitation, the second system is placed closer to
-the first one. By setting @code{page-limit-inter-system-space-factor} to
-@code{1}, the spacing would the same as on a ragged-bottom page, like
-the last one.
+A non-staff line at the bottom of a system should have
+@var{staff-affinity} set to @code{UP}. Similarly, a non-staff
+line at the top of a system should have @var{staff-affinity} set
+to @code{DOWN}.
-@lilypond[verbatim]
-#(set-default-paper-size "a6")
-\book {
- \paper {
- page-limit-inter-system-space = ##t
- page-limit-inter-system-space-factor = 1.3
-
- oddFooterMarkup = \markup "page bottom"
- evenFooterMarkup = \markup "page bottom"
- oddHeaderMarkup = \markup \fill-line {
- "page top" \fromproperty #'page:page-number-string }
- evenHeaderMarkup = \markup \fill-line {
- "page top" \fromproperty #'page:page-number-string }
- }
- \new Staff << \repeat unfold 4 { g'4 g' g' g' \break }
- { s1*2 \pageBreak } >>
-}
-@end lilypond
+@node Vertical spacing between systems
+@subsection Vertical spacing between systems
+The mechanisms that control spacing between systems are similar to those
+that control spacing between staves within a system (see
+@ref{Vertical spacing inside a system}). The main difference is that
+the variables to control spacing between systems are set in the
+@code{\paper} block, rather than as grob properties. These paper block
+variables are @var{between-system-spacing},
+@var{between-scores-system-spacing}, @var{after-title-spacing},
+@var{before-title-spacing}, @var{between-title-spacing},
+@var{top-system-spacing}, @var{top-system-spacing},
+@var{top-title-spacing} and @var{bottom-system-spacing}. Note that
+these variables ignore non-staff lines. For example,
+@var{between-system-spacing} controls the spacing from the middle staff
+line of the bottom staff from one system to the middle staff line of the
+top staff of the next system, whether or not there are lyrics below the
+upper system. See @ref{Vertical dimensions} for a description of each
+of these variables.
+
+There are two more @code{\paper} block variables that affect vertical
+spacing: if @var{ragged-bottom} is set to @code{##t} then no pages will
+be stretched (which means that neither the space between systems nor the
+space within systems will be stretched). If @var{ragged-last-bottom}
+is set to @code{##t} then the last page will not be stretched.
@seealso
Snippets:
vertical positions on the page.
@code{NonMusicalPaperColumn #'line-break-system-details} accepts an associative
-list of five different settings:
+list of three different settings:
@itemize
@item @code{X-offset}
@item @code{Y-offset}
-@item @code{alignment-offsets}
-@item @code{alignment-extra-space}
-@item @code{fixed-alignment-extra-space}
+@item @code{alignment-distances}
@end itemize
Grob overrides, including the overrides for @code{NonMusicalPaperColumn}
#'line-break-system-details #'((X-offset . 20) (Y-offset . 40))
\overrideProperty NonMusicalPaperColumn
- #'line-break-system-details #'((alignment-offsets . (0 -15)))
+ #'line-break-system-details #'((alignment-distances . (15)))
\overrideProperty NonMusicalPaperColumn
#'line-break-system-details #'((X-offset . 20) (Y-offset . 40)
- (alignment-offsets . (0 -15)))
+ (alignment-distances . (15)))
@end example
To understand how each of these different settings work, we begin
position on the page at which each new system will render.
Now that we have set the vertical startpoint of each system
-explicitly, we can also set the vertical startpoint of each staff
-within each system manually. We do this using the @code{alignment-offsets}
+explicitly, we can also set the vertical distances between staves
+within each system manually. We do this using the @code{alignment-distances}
subproperty of @code{line-break-system-details}.
@lilypond[quote]
\new Voice {
\overrideProperty #"Score.NonMusicalPaperColumn"
#'line-break-system-details #'((Y-offset . 20)
- (alignment-offsets . (0 -15)))
+ (alignment-distances . (15)))
s1*5 \break
\overrideProperty #"Score.NonMusicalPaperColumn"
#'line-break-system-details #'((Y-offset . 60)
- (alignment-offsets . (0 -15)))
+ (alignment-distances . (15)))
s1*5 \break
\overrideProperty #"Score.NonMusicalPaperColumn"
#'line-break-system-details #'((Y-offset . 100)
- (alignment-offsets . (0 -15)))
+ (alignment-distances . (15)))
s1*5 \break
}
\new Voice { \repeat unfold 15 { c'4 c' c' c' } }
@code{line-break-system-details} attribute alist accepts many
additional spacing parameters (including, for example, a corresponding
@code{X-offset} pair), we need only set the @code{Y-offset} and
-@code{alignment-offsets} pairs to control the vertical startpoint of
-every system and every staff. Finally, note that @code{alignment-offsets}
+@code{alignment-distances} pairs to control the vertical startpoint of
+every system and every staff. Finally, note that @code{alignment-distances}
specifies the vertical positioning of staves but not of staff groups.
@lilypond[quote]
\new Voice {
\overrideProperty #"Score.NonMusicalPaperColumn"
#'line-break-system-details #'((Y-offset . 0)
- (alignment-offsets . (0 -30 -40)))
+ (alignment-distances . (30 10)))
s1*5 \break
\overrideProperty #"Score.NonMusicalPaperColumn"
#'line-break-system-details #'((Y-offset . 60)
- (alignment-offsets . (0 -10 -20)))
+ (alignment-distances . (10 10)))
s1*5 \break
\overrideProperty #"Score.NonMusicalPaperColumn"
#'line-break-system-details #'((Y-offset . 100)
- (alignment-offsets . (0 -10 -40)))
+ (alignment-distances . (10 30)))
s1*5 \break
}
\new Voice { \repeat unfold 15 { c'4 c' c' c' } }
Some points to consider:
@itemize
-@item When using @code{alignment-offsets}, lyrics count as a staff.
+@item When using @code{alignment-distances}, lyrics and other non-staff lines
+do not count as a staff.
@item The units of the numbers passed to @code{X-offset},
-@code{Y-offset} and @code{alignment-offsets} are interpreted as multiples
+@code{Y-offset} and @code{alignment-distances} are interpreted as multiples
of the distance between adjacent staff lines. Positive values move staves
and lyrics up, negative values move staves and lyrics down.
@end lilypond
-In the introduction
-FIXME FIXME FIXME
-@c (see @rlearning{Engraving}),
-it was explained that stem
-directions influence spacing. This is controlled with the
+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
@code{stem-spacing-correction} property in the
@rinternals{NoteSpacing}, object. These are generated for every
@rinternals{Voice} context. The @code{StaffSpacing} object
-(generated in @rinternals{Staff} context) contains the same property
-for controlling the stem/bar line spacing. The following example shows
-these corrections, once with default settings, and once with
-exaggerated corrections:
+(generated in @rinternals{Staff} context) contains the same
+property for controlling the stem/bar line spacing. The following
+example shows these corrections, once with default settings, and
+once with exaggerated corrections:
@lilypond[quote,ragged-right]
{
@example
\paper @{
- between-system-padding = #0.1
- between-system-space = #0.1
+ between-system-spacing = #'((padding . 0) (space . 0.1))
ragged-last-bottom = ##f
ragged-bottom = ##f
@}
projects / lilypond.git / blobdiff