]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/user/spacing.itely
bar space line.
[lilypond.git] / Documentation / user / spacing.itely
index bac2c6d96f43d7f0a92da3472339dce79ad0eafa..3f91ccb39db1b95947c4cd6958c91af4cbec417a 100644 (file)
@@ -23,8 +23,8 @@ many pages a piece of music takes.
 Globally speaking, this procedure happens in four steps: first,
 flexible distances (@q{springs}) are chosen, based on durations.  All
 possible line breaking combinations are tried, and a @q{badness} score
-is calculated for each. Then the height of each possible system is
-estimated. Finally, a page breaking and line breaking combination is chosen
+is calculated for each.  Then the height of each possible system is
+estimated.  Finally, a page breaking and line breaking combination is chosen
 so that neither the horizontal nor the vertical spacing is too cramped
 or stretched.
 
@@ -124,58 +124,58 @@ false.
 
 @funindex print-page-number
 @item print-page-number
-If set to false, page numbers will not be printed. Default is true.
+If set to false, page numbers will not be printed.  Default is true.
 
 @funindex paper-width
 @item paper-width
-The width of the page. The default is taken from the current paper size,
+The width of the page.  The default is taken from the current paper size,
 see @ref{Paper size}. 
 
 @funindex paper-height
 @item paper-height
-The height of the page. The default is taken from the current paper size,
+The height of the page.  The default is taken from the current paper size,
 see @ref{Paper size}. 
 
 @funindex top-margin
 @item top-margin
-Margin between header and top of the page. Default is@tie{}5mm.
+Margin between header and top of the page.  Default is@tie{}5mm.
 
 @funindex bottom-margin
 @item bottom-margin
-Margin between footer and bottom of the page. Default is@tie{}6mm.
+Margin between footer and bottom of the page.  Default is@tie{}6mm.
 
 @funindex left-margin
 @item left-margin
 Margin between the left side of the page and the beginning of the
-music. Unset by default, which means that the margins is determined
+music.  Unset by default, which means that the margins is determined
 based on the @code{paper-width} and @code{line-width} to center the
 score on the paper. 
 
 @funindex line-width
 @item line-width
-The length of the systems. Default is @code{paper-width} minus @tie{}20mm.
+The length of the systems.  Default is @code{paper-width} minus @tie{}20mm.
 
 @funindex head-separation
 @item head-separation
-Distance between the top-most music system and the page header. Default
+Distance between the top-most music system and the page header.  Default
 is@tie{}4mm. 
 
 @funindex foot-separation
 @item foot-separation
 Distance between the bottom-most music system and the page
-footer. Default is@tie{}4mm.
+footer.  Default is@tie{}4mm.
 
 @funindex page-top-space
 @item page-top-space
 Distance from the top of the printable area to the center of the first
-staff. This only works for staves which are vertically small. Big staves
+staff.  This only works for staves which are vertically small.  Big staves
 are set with the top of their bounding box aligned to the top of the
-printable area. Default is@tie{}12mm.
+printable area.  Default is@tie{}12mm.
 
 @funindex ragged-bottom
 @item ragged-bottom
 If set to true, systems will not be spread vertically across the page.  This
-does not affect the last page. Default is false.
+does not affect the last page.  Default is false.
 
 This should be set to true for pieces that have only two or three
 systems per page, for example orchestral scores.
@@ -183,7 +183,7 @@ systems per page, for example orchestral scores.
 @funindex ragged-last-bottom
 @item ragged-last-bottom
 If set to false, systems will be spread vertically to fill the last
-page. Default is true.
+page.  Default is true.
 
 Pieces that amply fill two pages or more should have this set to
 true.
@@ -191,13 +191,13 @@ true.
 @funindex system-count
 @item system-count
 This variable, if set, specifies into how many lines a score should be
-broken. Unset by default.
+broken.  Unset by default.
 
 @funindex between-system-space
 @item between-system-space
 This dimensions determines the distance between systems.  It is the
 ideal distance between the center of the bottom staff of one system
-and the center of the top staff of the next system. Default is@tie{}20mm.
+and the center of the top staff of the next system.  Default is@tie{}20mm.
 
 Increasing this will provide a more even appearance of the page at the
 cost of using more vertical space.
@@ -206,39 +206,39 @@ cost of using more vertical space.
 @item between-system-padding
 This dimension is the minimum amount of white space that will always
 be present between the bottom-most symbol of one system, and the
-top-most of the next system. Default is@tie{}4mm.
+top-most of the next system.  Default is@tie{}4mm.
 
 Increasing this will put systems whose bounding boxes almost touch
 farther apart.
 
 @funindex page-breaking-between-system-padding
-@item between-system-padding
-This variable, if set, tricks the page breaker into thinking that
+@item page-breaking-between-system-padding
+This variable 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
+really is.  For example, if this variable is set to something substantially
 larger than @code{between-system-padding}, then the page-breaker will put
 fewer systems on each page.
 
 @funindex horizontal-shift
 @item horizontal-shift
 All systems (including titles and system separators) are shifted by
-this amount to the right. Page markup, such as headers and footers are
-not affected by this. The purpose of this variable is to make space
-for instrument names at the left. Default is@tie{}0.
+this amount to the right.  Page markup, such as headers and footers are
+not affected by this.  The purpose of this variable is to make space
+for instrument names at the left.  Default is@tie{}0.
 
 @funindex after-title-space
 @item after-title-space
-Amount of space between the title and the first system. Default is@tie{}5mm.
+Amount of space between the title and the first system.  Default is@tie{}5mm.
 
 @funindex before-title-space
 @item before-title-space
 Amount of space between the last system of the previous piece and the
-title of the next. Default is@tie{}10mm.
+title of the next.  Default is@tie{}10mm.
 
 @funindex between-title-space
 @item between-title-space
 Amount of space between consecutive titles (e.g., the title of the
-book and the title of a piece). Default is@tie{}2mm.
+book and the title of a piece).  Default is@tie{}2mm.
 
 @funindex printallheaders
 @item printallheaders
@@ -248,7 +248,7 @@ output.  Normally only the piece and opus \headers are printed.
 @funindex systemSeparatorMarkup
 @item systemSeparatorMarkup
 This contains a markup object, which will be inserted between
-systems.  This is often used for orchestral scores. Unset by default.
+systems.  This is often used for orchestral scores.  Unset by default.
 
 The markup command @code{\slashSeparator} is provided as a sensible
 default,  for example
@@ -268,8 +268,8 @@ default,  for example
 @funindex blank-page-force
 @item blank-page-force
 The penalty for having a blank page in the middle of a
-score. This is not used by @code{ly:optimal-breaking} since it will
-never consider blank pages in the middle of a score. Default value
+score.  This is not used by @code{ly:optimal-breaking} since it will
+never consider blank pages in the middle of a score.  Default value
 is 10.
 
 @funindex blank-last-page-force
@@ -280,7 +280,7 @@ Default value is 0.
 @funindex page-spacing-weight
 @item page-spacing-weight
 The relative importance of page (vertical) spacing and line (horizontal)
-spacing. High values will make page spacing more important. Default
+spacing.  High values will make page spacing more important.  Default
 value is 10.
 
 @funindex auto-first-page-number
@@ -297,17 +297,17 @@ result in the first page number remaining as is or being increased by one.
 @commonprop
 
 The header and footer are created by the functions make-footer and
-make-header, defined in \paper. The default implementations are in
+make-header, defined in \paper.  The default implementations are in
 ly/paper-defaults.ly and ly/titling-init.ly.
 
 The page layout itself is done by two functions in the \paper block,
-page-music-height and page-make-stencil. The former tells the
+page-music-height and page-make-stencil.  The former tells the
 line-breaking algorithm how much space can be spent on a page, the
 latter creates the actual page given the system to put on it.
 
-You can define paper block values in Scheme. In that case mm, in, pt,
+You can define paper block values in Scheme.  In that case mm, in, pt,
 and cm are variables defined in paper-defaults.ly with values in
-millimeters. That is why the value 2 cm must be multiplied in the
+millimeters.  That is why the value 2 cm must be multiplied in the
 example
 
 @example
@@ -490,6 +490,12 @@ staves.  The sizes of individual staves are relative to the global size.
 This manual: @ref{Selecting notation font size}.
 
 
+@refbugs
+
+@code{layout-set-staff-size} does not change the distance between the
+staff lines.
+
+
 @node Score layout
 @subsection Score layout
 
@@ -529,6 +535,7 @@ be altered for page formatting, set @code{annotate-spacing} in the
 @code{\paper} block, like this
 
 
+@c need to have \book{} otherwise we get  the separate systems. -hwn
 @lilypond[verbatim]
 #(set-default-paper-size "a6" 'landscape)
 
@@ -538,10 +545,9 @@ be altered for page formatting, set @code{annotate-spacing} in the
 }
 @end lilypond
 
-@c need to have \book{} otherwise we get  the separate systems. -hwn
 
+@c  TODO: really bad vagueness due to bug in annotate-spacing.  -gp
 @noindent
-@c  FIXME: really bad vagueness due to bug in annotate-spacing.  -gp
 Some unit dimensions are measured in staff spaces, while others
 are measured in millimeters.
 The pairs
@@ -557,6 +563,7 @@ The pairs
 * Page breaking::               
 * Optimal page breaking::       
 * Optimal page turning::        
+* Minimal page breaking::        
 * Explicit breaks::             
 * Using an extra voice for breaks::  
 @end menu
@@ -607,6 +614,11 @@ This makes the following 28 measures (assuming 4/4 time) be broken every
 
 Internals: @internalsref{LineBreakEvent}.
 
+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}
 
 @refbugs
 
@@ -614,26 +626,28 @@ 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,fragment,verbatim]
-c4 c2 c2 \break   % this does nothing
+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
 
-To allow line breaks on such bar lines, the
-@code{Forbid_line_break_engraver} can be removed from @code{Voice}
-context, like so
-
+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,relative=2,fragment,verbatim]
+@lilypond[quote,ragged-right,verbatim]
 \new Voice \with {
-  \remove "Forbid_line_break_engraver"
+  \remove Forbid_line_break_engraver
 } {
-  c4 c2 c2 \break   % now the break is allowed
-  c2 c4
+  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
@@ -646,11 +660,14 @@ inserted at a bar line.  These commands force and forbid a page-break
 from happening.  Of course, the @code{\pageBreak} command also forces
 a line break.
 
-Page breaks are computed by the @code{page-breaking} function.
-LilyPond provides two algorithms for computing page
-breaks, @code{ly:optimal-breaking} and @code{ly:page-turn-breaking}. The
-default is @code{ly:optimal-breaking}, but the value can be changed in
-the @code{\paper} block:
+The @code{\pageBreak} and @code{\noPageBreak} commands may also be
+inserted at top-level, between scores and top-level markups.
+
+Page breaks are computed by the @code{page-breaking} function.  LilyPond
+provides three algorithms for computing page breaks,
+@code{ly:optimal-breaking}, @code{ly:page-turn-breaking} and
+@code{ly:minimal-breaking}.  The default is @code{ly:optimal-breaking},
+but the value can be changed in the @code{\paper} block:
 
 @example
 \paper@{
@@ -659,7 +676,7 @@ the @code{\paper} block:
 @end example
 
 The old page breaking algorithm is called
-@code{optimal-page-breaks}. If you are having trouble with the new page
+@code{optimal-page-breaks}.  If you are having trouble with the new page
 breakers, you can enable the old one as a workaround.
 
 @refcommands
@@ -676,8 +693,8 @@ breakers, you can enable the old one as a workaround.
 @funindex ly:optimal-breaking
 
 The @code{ly:optimal-breaking} function is LilyPond's default method of
-determining page breaks. It attempts to find a page breaking that minimizes
-cramping and stretching, both horizontally and vertically. Unlike
+determining page breaks.  It attempts to find a page breaking that minimizes
+cramping and stretching, both horizontally and vertically.  Unlike
 @code{ly:page-turn-breaking}, it has no concept of page turns.
 
 
@@ -687,36 +704,37 @@ cramping and stretching, both horizontally and vertically. Unlike
 @funindex ly:page-turn-breaking
 
 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
+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. Then, you must tell the function
-where you would like to allow page breaks.
+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
+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
+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
+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
 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
+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
@@ -734,18 +752,47 @@ to disable page turns, you can set it to something very large.
 @end example
 
 @funindex minimumRepeatLengthForPageTurn
-The @code{Page_turn_engraver} detects volta repeats. It will only allow a page
+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
+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
+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
@@ -927,25 +974,36 @@ 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
+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
+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
+@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,
+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:
 
-@example
+@lilypond[verbatim]
+#(set-default-paper-size "a6")
+#(set-global-staff-size 14.0)
+
+\book {
 \paper {
   ragged-last-bottom = ##f
 }
 
+\new Score \with
+{
+  \override VerticalAlignment #'max-stretch = #ly:align-interface::calc-max-stretch
+}
+{
 \new GrandStaff
 <<
   \new StaffGroup
@@ -970,12 +1028,14 @@ the second piano staff:
     \new Staff {c' d' e' f'}
   >>
 >>
-@end example
+}
+}
+@end lilypond
 
 @seealso
 
 Internals: Vertical alignment of staves is handled by the
-@internalsref{VerticalAlignment} object. The context parameters
+@internalsref{VerticalAlignment} object.  The context parameters
 specifying the vertical extent are described in connection with
 the @internalsref{Axis_group_engraver}.
 
@@ -997,6 +1057,42 @@ Space between systems are controlled by four @code{\paper} variables,
 @}
 @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
@@ -1078,7 +1174,7 @@ by looking at an example that includes no overrides at all.
 @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
+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}.
 
@@ -1202,6 +1298,66 @@ 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
 
@@ -1357,7 +1513,7 @@ c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
 @end lilypond
 
 
-In the introduction (see @ref{Engraving}), it was explained that stem
+In the introduction (see @rlearning{Engraving}), it was explained that stem
 directions influence spacing.  This is controlled with the
 @code{stem-spacing-correction} property in the
 @internalsref{NoteSpacing}, object.  These are generated for every
@@ -1555,8 +1711,8 @@ paragraph, the last line simply takes its natural horizontal length.
 
 LilyPond supports proportional notation, a type of horizontal spacing
 in which each note consumes an amount of horizontal space exactly
-equivalent to its rhythmic duration. This type of proportional spacing
-is comparable to horizontal spacing on top of graph paper. Some late
+equivalent to its rhythmic duration.  This type of proportional spacing
+is comparable to horizontal spacing on top of graph paper.  Some late
 20th- and early 21st-century scores use proportional notation to
 clarify complex rhythmic relationships or to faciliate the placement
 of timelines or other graphics directly in the score.
@@ -1636,8 +1792,8 @@ The @code{proportionalNotationDuration} setting takes a single argument,
 which is the reference duration against which all music will be
 spaced.  The LilyPond Scheme function make-moment takes two arguments
 -- a numerator and denominator which together express some fraction of
-a whole note. The call @code{#(ly:make-moment 1 20)} therefore produces a
-reference duration of a twentieth note. The values
+a whole note.  The call @code{#(ly:make-moment 1 20)} therefore produces a
+reference duration of a twentieth note.  The values
 @code{#(ly:make-moment 1 16)}, @code{#(ly:make-moment 1 8)}, and
 @code{#(ly:make-moment 3 97)} are all possible as well.
 
@@ -1765,16 +1921,23 @@ turn on @code{uniform-stretching}, which is a property of
 >>
 @end lilypond
 
-Our two-staff example now spaces exactly, our rhythmic relationships
-are visually clear, and we can include a measured timeline or graphic
-if we want.
+Our two-staff example now spaces exactly, our rhythmic
+relationships are visually clear, and we can include a measured
+timeline or graphic if we want.
 
-The @code{SpacingSpanner} is an abstract grob that lives in the
-@context{Score} context.  As with our settings of
-@code{proportionalNotationDuration},
-overrides to the @code{SpacingSpanner} can occur in any of three different
-places in our input file -- in the Score @code{\with} block, in a
-Score @code{\context} block, or in note entry directly.
+Note that the LilyPond's proportional notation package expects
+that all proportional scores set the SpacingSpanner's
+'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,
+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.
 
 There is by default only one @code{SpacingSpanner} per @code{Score}.  This
 means that, by default, @code{uniform-stretching} is either turned on for the
@@ -1861,65 +2024,15 @@ 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 score
-remains strict, however, because @code{strict-note-spacing} is turned
-on.  Turning on @code{strict-note-spacing} causes the width of time
-signatures, key signatures and clefs to play no part in the spacing
-algorithm.  Accidentals are a different matter, however.  By default, all
-accidentals consume a little extra space, as the following pair of
-scores shows.
-
-@lilypond[quote,verbatim,ragged-right]
-\new Staff {
-  \set Score.proportionalNotationDuration = #(ly:make-moment 1 32)
-  c'16
-  c'16
-  c'16
-  c'16
-  c'16
-  c'16
-  c'16
-  c'16
-}
-
-\new Staff {
-  \set Score.proportionalNotationDuration = #(ly:make-moment 1 32)
-  c'16
-  cis'16
-  c'16
-  c'16
-  c'16
-  c'16
-  c'16
-  c'16
-}
-@end lilypond
-
-Both scores are proportional but the second score exhibits spacing
-irregularities due to accidentals.  Turning on @code{strict-note-spacing}
-does not work for accidentals.  Instead,
-we override the @code{X-extent} of all accidentals to zero and then move the
-accidentals to the left of the notes they modify.
-
-@lilypond[quote,verbatim,ragged-right]
-\new Staff {
-  \set Score.proportionalNotationDuration = #(ly:make-moment 1 32)
-  \override Accidental #'X-extent = #'(0 . 0)
-  \override Accidental #'extra-offset = #'(-1 . 0)
-  c'16
-  cis'16
-  c'16
-  c'16
-  c'16
-  c'16
-  c'16
-  c'16
-}
-@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
+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:
+In addition to the settings given here, there are other settings
+that frequently appear in proportional scores. These include:
 
 @itemize
 @item @code{\override SpacingSpanner #'strict-grace-spacing = ##t}