]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/notation/spacing.itely
Doc: ensure two spaces after end of sentence.
[lilypond.git] / Documentation / notation / spacing.itely
index 002151cb64e7788484f67b79d33494f1d6e3b149..da64448d74b78b10036a5651d65b70cf716b0426 100644 (file)
@@ -4,7 +4,8 @@
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the
-    version that you are working on.  See TRANSLATION for details.
+    version that you are working on.  For details, see the Contributors'
+    Guide, node Updating translation committishes..
 @end ignore
 
 @c \version "2.12.0"
@@ -36,11 +37,11 @@ distance between
 staff lines accordingly."
 
 Actually I found, that the @internalsref{StaffSymbol} at line 481
-sends to an uncomplete
-documentation. The property staff-space is not explained here. I
+sends to an incomplete
+documentation.  The property staff-space is not explained here.  I
 thought Y-extent might be of
 help, but it is in turn explained by x-space which again is
-missing from the list. Who has the
+missing from the list.  Who has the
 knowledge to fix this?
 
 
@@ -215,13 +216,20 @@ present between a title and the staff that follows it;
 space increases when a page is stretched.
 If this is zero, the distance to the next staff will not stretch at all;
 @item @var{minimum-distance} -- the minimum distance to place between
-the baseline of a title and the center of the staff that follows it. This differs
+the baseline of a title and the center of the staff that follows it.  This differs
 from @var{padding} in that the height of a staff has no effect on
 the application of @var{minimum-distance} (whereas the height of a
 staff is crucial for @var{padding}).
 @end itemize
 
-If a page has a ragged bottom, @var{space} is not stretched. In particular, the
+For example, the default is:
+
+@example
+after-title-spacing = #'((space . 2) (padding . 0.5))
+@end example
+
+
+If a page has a ragged bottom, @var{space} is not stretched.  In particular, the
 resulting distance on such a page is the largest of
 @itemize @bullet
 @item @var{space},
@@ -241,7 +249,7 @@ the baseline of the title that follows it.  See @var{after-title-spacing}.
 @funindex between-scores-system-spacing
 
 Specifies the spacing between two systems if they are in different scores, but
-there is no title between them. See @var{after-title-spacing}.
+there is no title between them.  See @var{after-title-spacing}.
 
 @item between-system-spacing
 @funindex between-system-spacing
@@ -270,12 +278,6 @@ baseline of the last top-level markup) to the bottom of the
 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
 
@@ -464,7 +466,7 @@ first system.  Default: @code{0}.
 
 @end table
 
-If some values are not set, defaults will be taken. Their exact
+If some values are not set, defaults will be taken.  Their exact
 value is adjusted, depending on the paper size specified.  Currently,
 the following values are affected by this scaling:
 
@@ -559,7 +561,7 @@ increased by one.  Default: @code{##f}.
 
 @ignore
 
-FIXME: this variable is used, but I don't know what it does. -pm
+TODO: this variable is used, but I don't know what it does. -pm
 @item blank-after-score-page-force
 @funindex blank-after-score-page-force
 
@@ -585,7 +587,7 @@ never consider blank pages in the middle of a score.  Default:
 @funindex check-consistency
 
 If set to true, check whether @code{left-margin}, @code{right-margin} and
-@code{line-width} fit each other. Also make sure that their combination
+@code{line-width} fit each other.  Also make sure that their combination
 does not exceed the available @code{paper-width}.  Default: @code{##t}.
 
 @item first-page-number
@@ -595,23 +597,24 @@ The value of the page number on the first page.  Default:
 @code{#1}.
 
 @item max-systems-per-page
-The maximum number of systems that will be placed on a page. This
+The maximum number of systems that will be placed on a page.  This
 is currently supported only by the @code{ly:optimal-breaking} algorithm.
 Default: unset.
 
 @item min-systems-per-page
-The minimum number of systems that will be placed on a page. This
-may cause pages to be overfilled if it is made too large. This is
+The minimum number of systems that will be placed on a page.  This
+may cause pages to be overfilled if it is made too large.  This is
 currently supported only by the @code{ly:optimal-breaking} algorithm.
 Default: unset.
 
-@item page-breaking-between-system-padding
-@funindex page-breaking-between-system-padding
+@item page-breaking-between-system-spacing
+@funindex page-breaking-between-system-spacing
 
 Tricks the page breaker into thinking that
-@code{between-system-padding} is set to something different than
-it really is.  For example, if this variable is set to something
-substantially larger than @code{between-system-padding}, then the
+@code{between-system-spacing} is set to something different than
+it really is.  For example, if
+@code{page-breaking-between-system-spacing #'padding} is set to something
+substantially larger than @code{between-system-spacing #'padding}, then the
 page-breaker will put fewer systems on each page.  Default: unset.
 
 @item page-count
@@ -709,7 +712,7 @@ default,  for example
 #(set-default-paper-size "a6" 'landscape)
 \book {
   \score {
-    \relative { c1 \break c1 }
+    \relative c' { c1 \break c1 }
   }
   \paper {
     system-separator-markup = \slashSeparator
@@ -733,6 +736,9 @@ Default: unset.
 @item two-sided
 @funindex two-sided
 
+@cindex gutter
+@cindex binding gutter
+
 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}
@@ -924,11 +930,11 @@ Snippets:
 @cindex line breaks
 @cindex breaking lines
 
-Line breaks are normally determined automatically. They are chosen
+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,
+@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,
@@ -940,13 +946,13 @@ The opposite command, @code{\noBreak}, 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.
+and @code{line-width}.  They are set in the @code{\layout} block.
 They control the indentation of the first line of music, and the
 lengths of the lines.
 
 If @code{ragged-right} is set to true in the @code{\layout} block,
 then systems end at their natural horizontal length, instead of
-being spread horizontally to fill the whole line. This is useful
+being spread horizontally to fill the whole line.  This is useful
 for short fragments, and for checking how tight the natural
 spacing is.
 
@@ -1084,7 +1090,7 @@ book parts.
   @}
   \paper @{
      %% In a part consisting mostly of text,
-     %% ly:minimal-breaking may be prefered
+     %% ly:minimal-breaking may be preferred
      #(define page-breaking ly:minimal-breaking)
   @}
   \markup @{ @dots{} @}
@@ -1402,104 +1408,182 @@ staves inside a system.
 @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:
@@ -1509,61 +1593,53 @@ 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-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:
@@ -1585,14 +1661,12 @@ It is possible to approach vertical spacing in a different way using
 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}
@@ -1623,11 +1697,11 @@ example @code{NonMusicalPaperColumn} overrides with the special
   #'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
@@ -1703,8 +1777,8 @@ 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}
+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]
@@ -1717,15 +1791,15 @@ subproperty of @code{line-break-system-details}.
         \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' } }
@@ -1744,8 +1818,8 @@ Note that here we assign two different values to 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}
+@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]
@@ -1758,15 +1832,15 @@ specifies the vertical positioning of staves but not of staff groups.
         \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' } }
@@ -1783,10 +1857,11 @@ specifies the vertical positioning of staves but not of staff groups.
 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.
 
@@ -1967,18 +2042,16 @@ c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
 @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]
 {
@@ -2407,14 +2480,14 @@ timeline or graphic if we want.
 
 Note that the LilyPond's proportional notation package expects
 that all proportional scores set the SpacingSpanner's
-'uniform-stretching attribute to ##t. Setting
+'uniform-stretching attribute to ##t.  Setting
 proportionalNotationDuration without also setting the
 SpacingSpanner's 'uniform-stretching attribute to ##t will, for
 example, cause Skips to consume an incorrect amount of horizontal
 space.
 
 The SpacingSpanner is an abstract grob that lives in the Score
-context. As with our settings of proportionalNotationDuration,
+context.  As with our settings of proportionalNotationDuration,
 overrides to the SpacingSpanner can occur in any of three
 different places in our input file – in the Score \with block, in
 a Score \context block, or in note entry directly.
@@ -2505,14 +2578,14 @@ property of @code{SpacingSpanner}.  Compare the two scores below:
 @end lilypond
 
 Both scores are proportional, but the spacing in the first score
-is too loose because of the clef change. The spacing of the second
+is too loose because of the clef change.  The spacing of the second
 score remains strict, however, because strict-note-spacing is
 turned on.  Turning on strict-note-spacing causes the width of
 time signatures, key signatures, clefs and accidentals to play no
 part in the spacing algorithm.
 
 In addition to the settings given here, there are other settings
-that frequently appear in proportional scores. These include:
+that frequently appear in proportional scores.  These include:
 
 @itemize
 @item @code{\override SpacingSpanner #'strict-grace-spacing = ##t}
@@ -2581,7 +2654,7 @@ All layout dimensions are displayed in staff-spaces, regardless
 of the units specified in the @code{\paper} or @code{\layout} block.
 In the above example, @code{paper-height} has a value of 59.75
 @code{staff-spaces}, and the @code{staff-size} is 20 points (the
-default value). Note that:
+default value).  Note that:
 
 @multitable {1 staff-space} {staff-size)/4 * (25.4/72.27) mm}
 
@@ -2597,7 +2670,7 @@ default value). Note that:
 
 @noindent
 In this case, one @code{staff-space} is approximately equal to
-1.757mm. Thus the @code{paper-height} measurement of 59.75
+1.757mm.  Thus the @code{paper-height} measurement of 59.75
 @code{staff-spaces} is equivalent to 105 millimeters, the height
 of @code{a6} paper in landscape orientation.  The pairs
 (@var{a},@var{b}) are intervals, where @var{a} is the lower
@@ -2629,8 +2702,7 @@ there is no blank space at the bottom of the page.
 
 @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
 @}
@@ -2642,7 +2714,7 @@ setting a value, even the same value as the number of systems
 being typeset by default, will sometimes cause more systems to
 be fitted onto each page, as an estimation step is then bypassed,
 giving a more accurate fit to each page.  Also, forcing an actual
-reduction in the number of systems may save a further page. For
+reduction in the number of systems may save a further page.  For
 example, if the default layout has 11 systems, the following
 assignment will force a layout with 10 systems.