More 3-value macro LSR stuff.

[lilypond.git] / Documentation / user / spacing.itely

diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely
index e33182425b6addc43314cc399233a42d88346e37..03bcc9b7178f0fb42dd4ae149f532e1591b51b19 100644 (file)
--- a/Documentation/user/spacing.itely
+++ b/Documentation/user/spacing.itely
@@ -618,7 +618,7 @@ A linebreaking configuration can be saved as a @code{.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
-@lsrdir{spacing}
+@c @lsrdir{spacing}
 
 @refbugs
 
@@ -725,9 +725,9 @@ 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
+insert an @code{\allowPageTurn} at the final bar line in that section, unless
+there is a @q{special} bar line (such as a double bar), in which case the
+@code{\allowPageTurn} will be inserted at the final @q{special} bar line in
 the section.
 
 @funindex minimumPageTurnLength
@@ -974,8 +974,10 @@ 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.
+property of the @internalsref{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
@@ -997,7 +999,11 @@ the second piano staff:
   ragged-last-bottom = ##f
 }
 
-\score {
+\new Score \with
+{
+  \override VerticalAlignment #'max-stretch = #ly:align-interface::calc-max-stretch
+}
+{
 \new GrandStaff
 <<
   \new StaffGroup
@@ -1033,8 +1039,8 @@ Internals: Vertical alignment of staves is handled by the
 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}.
+Example files: @c @lsr{spacing,page-spacing.ly},
+@c @lsr{spacing,alignment-vertical-spacing.ly}.
 
 
 @node Vertical spacing between systems
@@ -1408,6 +1414,8 @@ c^"This text is padded away from the previous text"
 c^"This text is placed close to the previous text"
 @end lilypond
 
+TODO: this example doesn't work any more ?
+
 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
@@ -1775,7 +1783,7 @@ space.  We could place a measured timeline or graphic above or below
 this example.
 
 The @code{proportionalNotationDuration} setting is a context setting that
-lives in @context{Score}.  Recall that context settings appear in one of
+lives in @code{Score}.  Recall that context settings appear in one of
 three locations in our input file -- in a @code{\with} block, in a
 @code{\context} block, or directly in music entry
 preceeded by the @code{\set} command.  As with all
@@ -1836,7 +1844,7 @@ reference durations space music tightly.
 @end lilypond
 
 Note that too large a reference duration -- such as the eighth note,
-above -- spaces music too tightly and can cause notehead collisions.
+above -- spaces music too tightly and can cause note head collisions.
 Note also that proportional notation in general takes up more
 horizontal space that does classical spacing.  Proportional spacing
 provides rhythmic clarity at the expense of horizontal space.