+Often it is necessary to find a page breaking configuration so that there is
+a rest at the end of every second page. This way, the musician can turn the
+page without having to miss notes. The @code{ly:page-turn-breaking} function
+attempts to find a page breaking minimizing cramping and stretching, but with
+the additional restriction that it is only allowed to introduce page turns
+in specified places.
+
+There are two steps to using this page breaking function. First, you
+must enable it in the @code{\paper} block, as explained in @ref{Page
+breaking}. Then you must tell the function where you would like to allow
+page breaks.
+
+There are two ways to achieve the second step. First, you can specify each
+potential page turn manually, by inserting @code{\allowPageTurn} into your
+input file at the appropriate places.
+
+If this is too tedious, you can add a @code{Page_turn_engraver} to a Staff or
+Voice context. The @code{Page_turn_engraver} will scan the context for
+sections without notes (note that it does not scan for rests; it scans for
+the absence of notes. This is so that single-staff polyphony with rests in one
+of the parts does not throw off the @code{Page_turn_engraver}). When it finds
+a sufficiently long section without notes, the @code{Page_turn_engraver} will
+insert an @code{\allowPageTurn} at the final barline in that section, unless
+there is a @q{special} barline (such as a double bar), in which case the
+@code{\allowPageTurn} will be inserted at the final @q{special} barline in
+the section.
+
+@funindex minimumPageTurnLength
+The @code{Page_turn_engraver} reads the context property
+@code{minimumPageTurnLength} to determine how long a note-free section must
+be before a page turn is considered. The default value for
+@code{minimumPageTurnLength} is @code{#(ly:make-moment 1 1)}. If you want
+to disable page turns, you can set it to something very large.
+
+@example
+\new Staff \with @{ \consists "Page_turn_engraver" @}
+@{
+ a4 b c d |
+ R1 | % a page turn will be allowed here
+ a4 b c d |
+ \set Staff.minimumPageTurnLength = #(ly:make-moment 5 2)
+ R1 | % a page turn will not be allowed here
+ a4 b r2 |
+ R1*2 | % a page turn will be allowed here
+ a1
+@}
+@end example
+
+@funindex minimumRepeatLengthForPageTurn
+The @code{Page_turn_engraver} detects volta repeats. It will only allow a page
+turn during the repeat if there is enough time at the beginning and end of the
+repeat to turn the page back. The @code{Page_turn_engraver} can also disable
+page turns if the repeat is very short. If you set the context property
+@code{minimumRepeatLengthForPageTurn} then the @code{Page_turn_engraver} will
+only allow turns in repeats whose duration is longer than this value.
+
+The page turning commands, @code{\pageTurn}, @code{\noPageTurn} and
+@code{\allowPageTurn}, may also be used at top-level, between scores and
+top-level markups.
+
+@refcommands
+
+@funindex \pageTurn
+@code{\pageTurn}
+@funindex \noPageTurn
+@code{\noPageTurn}
+@funindex \allowPageTurn
+@code{\allowPageTurn}
+
+@refbugs
+
+There should only be one @code{Page_turn_engraver} in a score. If there is more
+than one, they will interfere with each other.
+
+@node Minimal page breaking
+@subsection Minimal page breaking
+
+@funindex ly:minimal-breaking
+
+The @code{ly:minimal-breaking} function performs minimal computations to
+calculate the page breaking: it fills a page with as many systems as
+possible before moving to the next one. Thus, it may be prefered for
+scores with many pages, where the other page breaking functions could be
+too slow or memory demanding, or a lot of texts. It is enabled using:
+
+@example
+\paper @{
+ #(define page-breaking ly:minimal-breaking)
+@}
+@end example
+
+@node Explicit breaks
+@subsection Explicit breaks
+
+Lily sometimes rejects explicit @code{\break} and @code{\pageBreak}
+commands. There are two commands to override this behavior:
+
+@example
+\override NonMusicalPaperColumn #'line-break-permission = ##f
+\override NonMusicalPaperColumn #'page-break-permission = ##f
+@end example
+
+When @code{line-break-permission} is overriden to false, Lily will insert
+line breaks at explicit @code{\break} commands and nowhere else. When
+@code{page-break-permission} is overriden to false, Lily will insert
+page breaks at explicit @code{\pageBreak} commands and nowhere else.
+
+@lilypond[quote,verbatim]
+\paper {
+ indent = #0
+ ragged-right = ##t
+ ragged-bottom = ##t
+}
+
+\score {
+ \new Score \with {
+ \override NonMusicalPaperColumn #'line-break-permission = ##f
+ \override NonMusicalPaperColumn #'page-break-permission = ##f
+ } {
+ \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 }
+ }
+ }
+}
+@end lilypond
+
+
+@node Using an extra voice for breaks
+@subsection Using an extra voice for breaks
+
+Line- and page-breaking information usually appears within note entry directly.
+
+@example
+\new 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 @}
+ @}
+@}
+@end example
+
+This makes @code{\break} and @code{\pageBreak} commands easy to enter but mixes
+music entry with information that specifies how music should lay out
+on the page. You can keep music entry and line- and page-breaking
+information in two separate places by introducing an extra voice to
+contain the breaks. This extra voice
+contains only skips together with @code{\break}, @code{pageBreak} and other
+breaking layout information.
+
+@lilypond[quote,verbatim]
+\new Score {
+ \new Staff <<
+ \new Voice {
+ s1 * 2 \break
+ s1 * 3 \break
+ s1 * 6 \break
+ 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 }
+ }
+ >>
+}
+@end lilypond
+
+This pattern becomes especially helpful when overriding
+@code{line-break-system-details} and the other useful but long properties of
+@code{NonMusicalPaperColumnGrob}, as explained in @ref{Vertical spacing}.
+
+@lilypond[quote,verbatim]
+\new Score {
+ \new Staff <<
+ \new Voice {
+
+ \overrideProperty "Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 0))
+ s1 * 2 \break
+
+ \overrideProperty "Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 35))
+ s1 * 3 \break
+
+ \overrideProperty "Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 70))
+ s1 * 6 \break
+
+ \overrideProperty "Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 105))
+ 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 }
+ }
+ >>
+}
+@end lilypond
+
+
+@node Vertical spacing
+@section Vertical spacing
+
+@cindex vertical spacing
+@cindex spacing, vertical
+
+Vertical spacing is controlled by three things: the amount of
+space available (i.e., paper size and margins), the amount of
+space between systems, and the amount of space between
+staves inside a system.
+
+@menu
+* Vertical spacing inside a system::
+* Vertical spacing between systems::
+* Explicit staff and system positioning::
+* Two-pass vertical spacing::
+* Vertical collision avoidance::
+@end menu
+
+
+@node Vertical spacing inside a system
+@subsection Vertical spacing inside a system
+
+@cindex distance between staves
+@cindex staff distance
+@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
+@internalsref{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
+
+@example
+\override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
+@end example
+
+@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)}.
+
+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 @internalsref{VerticalAlignment} grob. To disable this
+stretching entirely, set @code{max-stretch} to zero.
+
+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
+@internalsref{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:
+
+@lilypond[verbatim]
+#(set-default-paper-size "a6")
+#(set-global-staff-size 14.0)
+
+\book {
+\paper {
+ ragged-last-bottom = ##f
+}
+
+\score {
+\new GrandStaff
+<<
+ \new StaffGroup
+ <<
+ \new Staff {c' d' e' f'}
+ \new Staff {c' d' e' f'}
+ \new Staff {c' d' e' f'}
+ >>
+
+ \new PianoStaff
+ <<
+ \new Staff {c' d' e' f'}
+ \new Staff \with {
+ \override VerticalAxisGroup #'keep-fixed-while-stretching = ##t
+ }
+ {c' d' e' f'}
+ >>
+
+ \new StaffGroup
+ <<
+ \new Staff {c' d' e' f'}
+ \new Staff {c' d' e' f'}
+ >>
+>>
+}
+}
+@end lilypond
+
+@seealso
+
+Internals: Vertical alignment of staves is handled by the
+@internalsref{VerticalAlignment} object. The context parameters
+specifying the vertical extent are described in connection with
+the @internalsref{Axis_group_engraver}.
+
+Example files: @lsr{spacing,page-spacing.ly},
+@lsr{spacing,alignment-vertical-spacing.ly}.
+
+
+@node Vertical spacing between systems
+@subsection Vertical spacing between systems
+
+Space between systems are controlled by four @code{\paper} variables,
+
+@example
+\paper @{
+ between-system-space = 1.5\cm
+ between-system-padding = #1
+ ragged-bottom=##f
+ ragged-last-bottom=##f
+@}
+@end example
+
+When only a couple of flat systems are placed on a page, the resulting
+vertical spacing may be non-eleguant: 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.
+
+@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 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.
+
+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.
+
+@code{NonMusicalPaperColumn #'line-break-system-details} accepts an associative
+list of five 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}
+@end itemize
+
+Grob overrides, including the overrides for @code{NonMusicalPaperColumn}
+below, can occur in any of three different places in an input file:
+
+@itemize
+@item in the middle of note entry directly
+@item in a @code{\context} block
+@item in the @code{\with} block
+@end itemize
+
+When we override @code{NonMusicalPaperColumn}, we use the usual
+@code{\override} command in @code{\context} blocks and in the
+@code{\with} block. On the other hand, when we override
+@code{NonMusicalPaperColumn} in the middle of note entry,
+use the special @code{\overrideProperty} command. Here are some
+example @code{NonMusicalPaperColumn} overrides with the special
+@code{\overrideProperty} command:
+
+@example
+\overrideProperty NonMusicalPaperColumn
+ #'line-break-system-details #'((X-offset . 20))
+
+\overrideProperty NonMusicalPaperColumn
+ #'line-break-system-details #'((Y-offset . 40))
+
+\overrideProperty NonMusicalPaperColumn
+ #'line-break-system-details #'((X-offset . 20) (Y-offset . 40))
+
+\override NonMusicalPaperColumn
+ #'line-break-system-details #'((alignment-offsets . (0 -15)))
+
+\override NonMusicalPaperColumn
+ #'line-break-system-details #'((X-offset . 20) (Y-offset . 40)
+ (alignment-offsets . (0 -15)))
+@end example
+
+To understand how each of these different settings work, we begin
+by looking at an example that includes no overrides at all.
+
+@lilypond[quote,ragged-right]
+\new Score <<
+ \new Staff <<
+ \new Voice {
+ s1 * 6 \break
+ s1 * 6 \break
+ s1 * 6 \break
+ }
+ \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
+ >>
+ \new Staff {
+ \repeat unfold 18 { d'4 d'4 d'4 d'4 }
+ }
+>>
+@end lilypond
+
+This score isolates line- and page-breaking information in a dedicated
+voice. This technique of creating a breaks voice will help keep layout
+separate from music entry as our example becomes more complicated.
+See @ref{Using an extra voice for breaks}.
+
+Explicit @code{\breaks} evenly divide the music into six measures per
+line. Vertical spacing results from LilyPond's defaults. To set
+the vertical startpoint of each system explicitly, we can set
+the @code{Y-offset} pair in the @code{line-break-system-details}
+attribute of the @code{NonMusicalPaperColumn} grob:
+
+@lilypond[quote,ragged-right]
+\new Score <<
+ \new Staff <<
+ \new Voice {
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 0))
+ s1 * 6 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 40))
+ s1 * 6 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 80))
+ s1 * 6 \break
+ }
+ \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
+ >>
+ \new Staff {
+ \repeat unfold 18 { d'4 d'4 d'4 d'4 }
+ }
+>>
+@end lilypond
+
+Note that @code{line-break-system-details} takes an associative list of
+potentially many values, but that we set only one value here. Note,
+too, that the @code{Y-offset} property here determines the exact vertical
+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}
+subproperty of @code{line-break-system-details}.
+
+@lilypond[quote,ragged-right]
+\new Score <<
+ \new Staff <<
+ \new Voice {
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 20)
+ (alignment-offsets . (0 -15)))
+ s1 * 6 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 60)
+ (alignment-offsets . (0 -15)))
+ s1 * 6 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 100)
+ (alignment-offsets . (0 -15)))
+ s1 * 6 \break
+ }
+ \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
+ >>
+ \new Staff {
+ \repeat unfold 18 { d'4 d'4 d'4 d'4 }
+ }
+>>
+@end lilypond
+
+Note that here we assign two different values to the
+@code{line-break-system-details} attribute of the
+@code{NonMusicalPaperColumn} grob. Though the
+@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}
+specifies the vertical positioning of staves but not of staff groups.
+
+@lilypond[quote,ragged-right]
+\new Score <<
+ \new Staff <<
+ \new Voice {
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 0)
+ (alignment-offsets . (0 -30 -40)))
+ s1 * 6 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 60)
+ (alignment-offsets . (0 -10 -20)))
+ s1 * 6 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 100)
+ (alignment-offsets . (0 -10, -40)))
+ s1 * 6 \break
+ }
+ \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
+ >>
+ \new StaffGroup <<
+ \new Staff {
+ \repeat unfold 18 { d'4 d'4 d'4 d'4 }
+ }
+ \new Staff {
+ \repeat unfold 18 { e'4 e'4 e'4 e'4 }
+ }
+ >>
+>>
+@end lilypond
+
+Some points to consider:
+
+@itemize
+@item When using @code{alignment-offsets}, lyrics 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
+of the distance between adjacent staff lines. Positive values move staves
+and lyrics up, negative values move staves and lyrics down.
+
+@item Because the @code{NonMusicalPaperColumn #'line-break-system-details}
+settings given here allow the positioning of staves and systems anywhere
+on the page, it is possible to violate paper or margin boundaries or even
+to print staves or systems on top of one another. Reasonable values
+passed to these different settings will avoid this.
+@end itemize
+
+
+@node Two-pass vertical spacing
+@subsection Two-pass vertical spacing
+
+Warning: two-pass vertical spacing is deprecated and will be removed in
+a future version of LilyPond. Systems are now stretched automatically
+in a single pass. See @ref{Vertical spacing inside a system}.
+
+In order to automatically stretch systems so that they should fill the
+space left on a page, a two-pass technique can be used:
+
+@enumerate
+@item In the first pass, the amount of vertical space used to increase
+the height of each system is computed and dumped to a file.
+@item In the second pass, spacing inside the systems are
+stretched according to the data in the page layout file.
+@end enumerate
+
+The @code{ragged-bottom} property adds space between systems, while
+the two-pass technique adds space between staves inside a system.
+
+To allow this behaviour, a @code{tweak-key} variable has to be set in
+each score @code{\layout} block, and the tweaks included in each score
+music, using the @code{\scoreTweak} music function.
+
+@quotation
+@verbatim
+%% include the generated page layout file:
+\includePageLayoutFile
+
+\score {
+ \new StaffGroup <<
+ \new Staff <<
+ %% Include this score tweaks:
+ \scoreTweak "scoreA"
+ { \clef french c''1 \break c''1 }
+ >>
+ \new Staff { \clef soprano g'1 g'1 }
+ \new Staff { \clef mezzosoprano e'1 e'1 }
+ \new Staff { \clef alto g1 g1 }
+ \new Staff { \clef bass c1 c1 }
+ >>
+ \header {
+ piece = "Score with tweaks"
+ }
+ %% Define how to name the tweaks for this score:
+ \layout { #(define tweak-key "scoreA") }
+}
+@end verbatim
+@end quotation
+
+For the first pass, the @code{dump-tweaks} option should be set to
+generate the page layout file.
+
+@example
+lilypond -dbackend=null -d dump-tweaks <file>.ly
+lilypond <file>.ly
+@end example
+
+
+@node Vertical collision avoidance
+@subsection Vertical collision avoidance
+
+@funindex outside-staff-priority
+@funindex outside-staff-padding
+@funindex outside-staff-horizontal-padding
+
+Intuitively, there are some objects in musical notation that belong
+to the staff and there are other objects that should be placed outside
+the staff. Objects belonging outside the staff include things such as
+rehearsal marks, text and dynamic markings (from now on, these will
+be called outside-staff objects). LilyPond's rule for the
+vertical placement of outside-staff objects is to place them as close
+to the staff as possible but not so close that they collide with
+another object.
+
+LilyPond uses the @code{outside-staff-priority} property to determine
+whether a grob is an outside-staff object: if @code{outside-staff-priority}
+is a number, the grob is an outside-staff object. In addition,
+@code{outside-staff-priority} tells LilyPond in which order the objects
+should be placed.
+
+First, LilyPond places all the objects that do not belong outside
+the staff. Then it sorts the outside-staff objects according to their
+@code{outside-staff-priority} (in increasing order). One by one, LilyPond
+takes the outside-staff objects and places them so that they do
+not collide with any objects that have already been placed. That
+is, if two outside-staff grobs are competing for the same space, the one
+with the lower @code{outside-staff-priority} will be placed closer to
+the staff.
+
+@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+c4_"Text"\pp
+r2.
+\once \override TextScript #'outside-staff-priority = #1
+c4_"Text"\pp % this time the text will be closer to the staff
+r2.
+% by setting outside-staff-priority to a non-number, we
+% disable the automatic collision avoidance
+\once \override TextScript #'outside-staff-priority = ##f
+\once \override DynamicLineSpanner #'outside-staff-priority = ##f
+c4_"Text"\pp % now they will collide
+@end lilypond
+
+The vertical padding between an outside-staff object and the
+previously-positioned grobs can be controlled with
+@code{outside-staff-padding}.
+
+@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+\once \override TextScript #'outside-staff-padding = #0
+a'^"This text is placed very close to the note"
+\once \override TextScript #'outside-staff-padding = #3
+c^"This text is padded away from the previous text"
+c^"This text is placed close to the previous text"
+@end lilypond
+
+By default, outside-staff objects are placed without regard to
+their horizontal distance from the previously-posititioned grobs. This
+can lead to situations in which objects are placed very close to each
+other horizontally. Setting @code{outside-staff-horizontal-padding}
+causes an object to be offset vertically so that such a situation
+doesn't occur.
+
+@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+% the markup is too close to the following note
+c2^"Text"
+c''2
+% setting outside-staff-horizontal-padding fixes this
+R1
+\once \override TextScript #'outside-staff-horizontal-padding = #1
+c,,2^"Text"
+c''2
+@end lilypond
+
+
+
+@node Horizontal spacing
+@section Horizontal Spacing
+
+@cindex horizontal spacing
+@cindex spacing, horizontal
+
+@menu
+* Horizontal spacing overview::
+* New spacing area::
+* Changing horizontal spacing::
+* Line length::
+* Proportional notation::
+@end menu
+
+
+@node Horizontal spacing overview
+@subsection Horizontal spacing overview
+
+The spacing engine translates differences in durations into stretchable
+distances (@q{springs}) of differring lengths. Longer durations get
+more space, shorter durations get less. The shortest durations get a
+fixed amount of space (which is controlled by
+@code{shortest-duration-space} in the @internalsref{SpacingSpanner}
+object). The longer the duration, the more space it gets: doubling a
+duration adds a fixed amount (this amount is controlled by
+@code{spacing-increment}) of space to the note.
projects / lilypond.git / blobdiff