X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fspacing.itely;h=fbeb4c9dfd380360bdc87b5938ff4bb028089ede;hb=e3fbf0543b38e5c20155cef9dc48d70e91da45c2;hp=658fc62dbae02bc59adb3161910a79a60aee0d2d;hpb=f3487cef38f45d65137225ece9f5c289569138bd;p=lilypond.git

diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely
index 658fc62dba..fbeb4c9dfd 100644
--- a/Documentation/user/spacing.itely
+++ b/Documentation/user/spacing.itely
@@ -1,5 +1,11 @@
 @c -*- coding: utf-8; mode: texinfo; -*-
 @c This file is part of lilypond.tely
+@ignore
+    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.
+@end ignore
 
 @c A menu is needed before every deeper *section nesting of @node's; run
 @c     M-x texinfo-all-menus-update
@@ -15,8 +21,8 @@ This influences where line breaks are chosen, and thus ultimately, how
 many pages a piece of music takes.
 
 Globally speaking, this procedure happens in four steps: first,
-flexible distances (``springs'') are chosen, based on durations.  All
-possible line breaking combinations are tried, and a ``badness'' score
+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
 so that neither the horizontal nor the vertical spacing is too cramped
@@ -25,10 +31,10 @@ or stretched.
 @menu
 * Paper and pages::             
 * Music layout::                
+* Displaying spacing::          
+* Breaks::                      
 * Vertical spacing::            
 * Horizontal spacing::          
-* Breaks::                      
-* Displaying spacing::          
 @end menu
 
 
@@ -111,7 +117,7 @@ The default layout responds to the following settings in the
 @item first-page-number
 The value of the page number of the first page.  Default is@tie{}1.
 
-@funindex printfirst-page-number
+@funindex print-first-page-number
 @item print-first-page-number
 If set to true, will print the page number in the first page.  Default is
 false.
@@ -280,6 +286,30 @@ result in the first page number remaining as is or being increased by one.
 @end table
 @end quotation
 
+
+@commonprop
+
+The header and footer are created by the functions make-footer and
+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
+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,
+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
+example
+
+@example
+\paper @{
+ #(define bottom-margin (* 2 cm))
+@}
+@end example
+
+
 Example:
 
 @example
@@ -291,6 +321,23 @@ Example:
 @}
 @end example
 
+This second example centers page numbers at the bottom of every page. 
+
+@example
+\paper @{
+  print-page-number = ##t
+  print-first-page-number = ##t
+  oddHeaderMarkup = \markup \fill-line @{ " " @}
+  evenHeaderMarkup = \markup \fill-line @{ " " @}
+  oddFooterMarkup = \markup @{ \fill-line @{
+     \bold \fontsize #3 \on-the-fly #print-page-number-check-first
+     \fromproperty #'page:page-number-string @} @}
+  evenFooterMarkup = \markup @{ \fill-line @{
+     \bold \fontsize #3 \on-the-fly #print-page-number-check-first
+     \fromproperty #'page:page-number-string @} @}
+@} 
+@end example
+
 You can also define these values in Scheme.  In that case @code{mm},
 @code{in}, @code{pt}, and @code{cm} are variables defined in
 @file{paper-defaults.ly} with values in millimeters.  That is why the
@@ -332,7 +379,7 @@ add space between the titles and the first system of the score.
 @section Music layout
 
 @menu
-* Setting the staff size::   
+* Setting the staff size::      
 * Score layout::                
 @end menu
 
@@ -461,210 +508,686 @@ layout.
 
 @seealso
 
-This manual: @ref{Changing context default settings}
+This manual: @ref{Changing context default settings}.
 
 
-@node Vertical spacing
-@section Vertical spacing
+@node Displaying spacing
+@section Displaying spacing
 
-@cindex vertical spacing
-@cindex spacing, vertical
+@funindex annotate-spacing
+@cindex Spacing, display of properties
 
-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.
+To graphically display the dimensions of vertical properties that may
+be altered for page formatting, set @code{annotate-spacing} in the
+@code{\paper} block, like this
+
+
+@lilypond[verbatim]
+#(set-default-paper-size "a6" 'landscape)
+
+\book {
+  \score { { c4 } }
+  \paper { annotate-spacing = ##t }
+}
+@end lilypond
+
+@c need to have \book{} otherwise we get  the separate systems. -hwn
+
+@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
+(@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
+@var{b} the upper edge of the interval.
+
+
+@node Breaks
+@section Breaks
 
 @menu
-* Vertical spacing inside a system::  
-* Vertical spacing of piano staves::  
-* Vertical spacing between systems::  
-* Controlling spacing of individual systems::  
-* Two-pass vertical spacing::
+* Line breaking::               
+* Page breaking::               
+* Optimal page breaking::       
+* Optimal page turning::        
+* Explicit breaks::             
+* Using an extra voice for breaks::  
 @end menu
 
+@node Line breaking
+@subsection Line breaking
 
-@node Vertical spacing inside a system
-@subsection Vertical spacing inside a system
+@cindex line breaks
+@cindex breaking lines
 
-@cindex distance between staves
-@cindex staff distance
-@cindex space between staves
-@cindex space inside systems
+Line breaks are normally computed automatically.  They are chosen so
+that lines look neither cramped nor loose, and that consecutive lines
+have similar density.
 
-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.
+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.  Line breaks can only occur at places where there are bar
+lines.  If you want to have a line break where there is no bar line,
+you can force an invisible bar line by entering @code{\bar
+""}.  Similarly, @code{\noBreak} forbids a line break at a
+point.
 
-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
 
+@cindex regular line breaks
+@cindex four bar music.
+
+For line breaks at regular intervals use @code{\break} separated by
+skips and repeated with @code{\repeat}:
 @example
-\override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
+<< \repeat unfold 7 @{
+         s1 \noBreak s1 \noBreak
+         s1 \noBreak s1 \break @}
+   @emph{the real music}
+>>
 @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)}.
+This makes the following 28 measures (assuming 4/4 time) be broken every
+4 measures, and only there.
+
+@refcommands
 
+@code{\break}, and @code{\noBreak}.
+@funindex \break
+@funindex \noBreak
 
 @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}.
+Internals: @internalsref{LineBreakEvent}.
 
-Example files: @inputfileref{input/regression/,page-spacing.ly},
-@inputfileref{input/regression/,alignment-vertical-spacing.ly}.
+A linebreaking configuration can now 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}
 
 
-@node Vertical spacing of piano staves
-@subsection Vertical spacing of piano staves
+@refbugs
 
-The distance between staves of a @internalsref{PianoStaff} cannot be
-computed during formatting.  Rather, to make cross-staff beaming work
-correctly, that distance has to be fixed beforehand.
+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
 
-The distance of staves in a @code{PianoStaff} is set with the
-@code{forced-distance} property of the
-@internalsref{VerticalAlignment} object, created in
-@internalsref{PianoStaff}.
+@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+c4 c2 c2 \break   % this does nothing
+c2 c4 |           % a break here would work
+c4 c2 c4 ~ \break % as does this break
+c4 c2 c4
+@end lilypond
 
-It can be adjusted as follows
-@example
-\new PianoStaff \with @{
-  \override VerticalAlignment #'forced-distance = #7
-@} @{
-  ...
-@}
-@end example
+To allow line breaks on such bar lines, the
+@code{Forbid_line_break_engraver} can be removed from @code{Voice}
+context, like so
 
-@noindent
-This would bring the staves together at a distance of 7 staff spaces,
-measured from the center line of each staff.
 
-The difference is demonstrated in the following example,
-@lilypond[quote,verbatim]
-\relative c'' <<
-  \new PianoStaff \with {
-    \override VerticalAlignment #'forced-distance = #7
-  } <<
-    \new Staff { c1 }
-    \new Staff { c }
-  >>
-  \new PianoStaff <<
-    \new Staff { c }
-    \new Staff { c }
-  >>
->>
+@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+\new Voice \with {
+  \remove "Forbid_line_break_engraver"
+} {
+  c4 c2 c2 \break   % now the break is allowed
+  c2 c4
+}
 @end lilypond
 
 
-@seealso
-
-Example files: @inputfileref{input/regression/,alignment-vertical-spacing.ly}.
 
+@node Page breaking
+@subsection Page breaking
 
-@node Vertical spacing between systems
-@subsection Vertical spacing between systems
+The default page breaking may be overriden by inserting
+@code{\pageBreak} or @code{\noPageBreak} commands.  These commands are
+analogous to @code{\break} and @code{\noBreak}.  They should be
+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.
 
-Space between systems are controlled by four @code{\paper} variables,
+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:
 
 @example
-\paper @{
-  between-system-space = 1.5\cm
-  between-system-padding = #1
-  ragged-bottom=##f
-  ragged-last-bottom=##f
+\paper@{
+  #(define page-breaking ly:page-turn-breaking)
 @}
 @end example
 
+The old page breaking algorithm is called
+@code{optimal-page-breaks}. If you are having trouble with the new page
+breakers, you can enable the old one as a workaround.
 
-@node Controlling spacing of individual systems
-@subsection Controlling spacing of individual systems
+@refcommands
 
-It is also possible to change the distance between for each system
-individually.  This is done by including the command
+@funindex \pageBreak
+@code{\pageBreak}
+@funindex \noPageBreak
+@code{\noPageBreak}
 
-@example
-\overrideProperty
-#"Score.NonMusicalPaperColumn"
-#'line-break-system-details
-#'((fixed-alignment-extra-space . 15))
-@end example
 
-@noindent
-at the line break before the system to be changed. The distance
-@code{15} is distributed over all staves that have a fixed distance
-alignment.  For example,
+@node Optimal page breaking
+@subsection Optimal page breaking
 
-@lilypond[ragged-right, fragment, relative=2, staffsize=13]
-\new PianoStaff <<
-  \new Staff {
-    c1\break
-  
-    \overrideProperty
-    #"Score.NonMusicalPaperColumn"
-    #'line-break-system-details
-    #'((fixed-alignment-extra-space . 15))
-
-    c\break
-  }
-  \new Staff { c c }
->>
-@end lilypond
+@funindex ly:optimal-breaking
 
-The distance for @code{fixed-alignment-extra-space} may also be
-negative.
+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
+@code{ly:page-turn-breaking}, it has no concept of page turns.
 
 
-@node Two-pass vertical spacing
-@subsection Two-pass vertical spacing
+@node Optimal page turning
+@subsection Optimal page turning
 
-In order to automatically stretch systems so that they should fill the
-space left on a page, a two-pass technique can be used:
+@funindex ly:page-turn-breaking
 
-@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
+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.
 
-The @code{ragged-bottom} property adds space between systems, while
-the two-pass technique adds space between staffs inside a system.
+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.
 
-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.
+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.
 
-@quotation
-@verbatim
-%% include the generated page layout file:
-\includePageLayoutFile
+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.
 
-\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 }
+@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.
+
+@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 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)}.
+
+
+@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
+
+
+@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
+
+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 }
   >>
@@ -681,10 +1204,87 @@ For the first pass, the @code{dump-tweaks} option should be set to
 generate the page layout file.
 
 @example
-lilypond -b null -d dump-tweaks <file>.ly
+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
 
@@ -692,10 +1292,11 @@ lilypond <file>.ly
 @cindex spacing, horizontal
 
 @menu
-* Horizontal spacing overview::
-* New spacing area::
-* Changing horizontal spacing::
-* Line length::
+* Horizontal spacing overview::  
+* New spacing area::            
+* Changing horizontal spacing::  
+* Line length::                 
+* Proportional notation::       
 @end menu
 
 
@@ -703,7 +1304,7 @@ lilypond <file>.ly
 @subsection Horizontal spacing overview
 
 The spacing engine translates differences in durations into stretchable
-distances (``springs'') of differring lengths.  Longer durations get
+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}
@@ -838,7 +1439,9 @@ Horizontal spacing may be altered with the
 we compare the same music; once without altering
 the property, and then altered.  Larger values
 of @code{ly:make-moment} will produce smaller
-music.
+music.  Note that @code{ly:make-moment} constructs
+a duration, so @code{1 4} is a longer duration
+than @code{1 16}.
 
 @lilypond[relative,verbatim,line-width=12\cm]
 \score {
@@ -863,7 +1466,7 @@ music.
     \context {
       \Score
       \override SpacingSpanner
-                #'base-shortest-duration = #(ly:make-moment 1 4)
+                #'base-shortest-duration = #(ly:make-moment 1 16)
     }
   }
 }
@@ -954,235 +1557,389 @@ paragraph, the last line simply takes its natural horizontal length.
 @end example
 
 
-@node Breaks
-@section Breaks
-
-@menu
-* Line breaking::               
-* Page breaking::               
-* Optimal page breaking::       
-* Optimal page turning::        
-@end menu
-
-@node Line breaking
-@subsection Line breaking
+@node Proportional notation
+@subsection Proportional notation
 
-@cindex line breaks
-@cindex breaking lines
+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
+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.
 
-Line breaks are normally computed automatically.  They are chosen so
-that lines look neither cramped nor loose, and that consecutive lines
-have similar density.
+LilyPond supports five different settings for proportional notation,
+which may be used together or alone:
 
-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.  Line breaks can only occur at places where there are bar
-lines.  If you want to have a line break where there is no bar line,
-you can force an invisible bar line by entering @code{\bar
-""}.  Similarly, @code{\noBreak} forbids a line break at a
-point.
+@itemize
+@item @code{proportionalNotationDuration}
+@item @code{uniform-stretching}
+@item @code{strict-note-spacing}
+@item @code{\remove Separating_line_group_engraver}
+@item @code{\override PaperColumn #'used = ##t}
+@end itemize
 
+In the examples that follow, we explore these five different
+proportional notation settings and examine how these settings interact.
 
-@cindex regular line breaks
-@cindex four bar music.
+We start with the following one-measure example, which uses classical
+spacing with ragged-right turned on.
 
-For line breaks at regular intervals use @code{\break} separated by
-skips and repeated with @code{\repeat}:
-@example
-<< \repeat unfold 7 @{
-         s1 \noBreak s1 \noBreak
-         s1 \noBreak s1 \break @}
-   @emph{the real music}
+@lilypond[quote,verbatim,ragged-right]
+\new Score <<
+  \new RhythmicStaff {
+    c'2
+    c'16 c'16 c'16 c'16
+    \times 4/5 {
+      c'16 c'16 c'16 c'16 c'16
+    }
+  }
 >>
-@end example
-
-@noindent
-This makes the following 28 measures (assuming 4/4 time) be broken every
-4 measures, and only there.
-
-@refcommands
-
-@code{\break}, and @code{\noBreak}.
-@funindex \break
-@funindex \noBreak
-
-@seealso
-
-Internals: @internalsref{LineBreakEvent}.
+@end lilypond
 
-A linebreaking configuration can now 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; see @inputfileref{input/regression/,page-layout-twopass.ly}
-for details.
+Notice that the half note which begins the measure takes up far less
+than half of the horizontal space of the measure.  Likewise, the
+sixteenth notes and sixteenth-note quintuplets (or twentieth notes)
+which end the measure together take up far more than half the
+horizontal space of the measure.
 
-@refbugs
+In classical engraving, this spacing may be exactly what we want
+because we can borrow horizontal space from the half note and conserve
+horizontal space across the measure as a whole.
 
-Line breaks can only occur if there is a ``proper'' bar line.  A note
-which is hanging over a bar line is not proper, such as
+On the other hand, if we want to insert a measured timeline or other
+graphic above or below our score, we need proportional notation.  We
+turn proportional notation on with the proportionalNotationDuration
+setting.
 
-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
-c4 c2 c2 \break   % this does nothing
-c2 c4 |           % a break here would work
-c4 c2 c4 ~ \break % as does this break
-c4 c2 c4
+@lilypond[quote,verbatim,ragged-right]
+\new Score \with {
+  proportionalNotationDuration = #(ly:make-moment 1 20)
+} <<
+  \new RhythmicStaff {
+    c'2
+    c'16 c'16 c'16 c'16
+    \times 4/5 {
+      c'16 c'16 c'16 c'16 c'16
+    }
+  }
+>>
 @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
+The half note at the beginning of the measure and the faster notes in
+the second half of the measure now occupy equal amounts of horizontal
+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
+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
+context settings, users can pick which of the three different
+locations they would like to set @code{proportionalNotationDuration}.
+
+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
+@code{#(ly:make-moment 1 16)}, @code{#(ly:make-moment 1 8)}, and
+@code{#(ly:make-moment 3 97)} are all possible as well.
+
+How do we select the right reference duration to pass to
+@code{proportionalNotationDuration}?  Usually by a process of trial and error,
+beginning with a duration close to the fastest (or smallest) duration
+in the piece.  Smaller reference durations space music loosely; larger
+reference durations space music tightly.
+
+@lilypond[quote,verbatim,ragged-right]
+\new Score \with {
+  proportionalNotationDuration = #(ly:make-moment 1 8)
+} <<
+  \new RhythmicStaff {
+    c'2
+    c'16 c'16 c'16 c'16
+    \times 4/5 {
+      c'16 c'16 c'16 c'16 c'16
+    }
+  }
+>>
 
+\new Score \with {
+  proportionalNotationDuration = #(ly:make-moment 1 16)
+} <<
+  \new RhythmicStaff {
+    c'2
+    c'16 c'16 c'16 c'16
+    \times 4/5 {
+      c'16 c'16 c'16 c'16 c'16
+    }
+  }
+>>
 
-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
-\new Voice \with {
-  \remove "Forbid_line_break_engraver"
-} {
-  c4 c2 c2 \break   % now the break is allowed
-  c2 c4
-}
+\new Score \with {
+  proportionalNotationDuration = #(ly:make-moment 1 32)
+} <<
+  \new RhythmicStaff {
+    c'2
+    c'16 c'16 c'16 c'16
+    \times 4/5 {
+      c'16 c'16 c'16 c'16 c'16
+    }
+  }
+>>
 @end lilypond
 
+Note that too large a reference duration -- such as the eighth note,
+above -- spaces music too tightly and can cause notehead 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.
 
+Next we examine how to optimally space overlapping tuplets.
 
-@node Page breaking
-@subsection Page breaking
+We start by examining what happens to our original example, with
+classical spacing, when we add a second staff with a different type of
+tuplet.
 
-The default page breaking may be overriden by inserting
-@code{\pageBreak} or @code{\noPageBreak} commands.  These commands are
-analogous to @code{\break} and @code{\noBreak}.  They should be
-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:
-
-@example
-\paper@{
-  #(define page-breaking ly:page-turn-breaking)
-@}
-@end example
-
-The old page breaking algorithm is called
-@code{optimal-page-breaks}. If you are having trouble with the new page
-breakers, you can enable the old one as a workaround.
-
-@refcommands
-
-@funindex \pageBreak
-@code{\pageBreak}
-@funindex \noPageBreak
-@code{\noPageBreak}
-
-
-@node Optimal page breaking
-@subsection Optimal page breaking
-
-@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
-@code{ly:page-turn-breaking}, it has no concept of page turns.
-
-
-@node Optimal page turning
-@subsection Optimal page turning
-
-@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
-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.
+@lilypond[quote,verbatim,ragged-right]
+\new Score <<
+  \new RhythmicStaff {
+    c'2
+    c'16 c'16 c'16 c'16
+    \times 4/5 {
+      c'16 c'16 c'16 c'16 c'16
+    }
+  }
+  \new RhythmicStaff {
+    \times 8/9 {
+      c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
+    }
+  }
+>>
+@end lilypond
 
-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.
+The spacing is bad because the evenly notes of the bottom staff do not
+stretch uniformly.  Classical engraving includes very few complex
+triplets and so classical engraving rules can generate this type of
+result.  Setting @code{proportionalNotationDuration} remedies this
+situation considerably.
 
-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 ``special'' barline (such as a double bar), in which case the
-@code{\allowPageTurn} will be inserted at the final ``special'' barline in
-the section.
+@lilypond[quote,verbatim,ragged-right]
+\new Score \with {
+  proportionalNotationDuration = #(ly:make-moment 1 20)
+} <<
+  \new RhythmicStaff {
+    c'2
+    c'16 c'16 c'16 c'16
+    \times 4/5 {
+      c'16 c'16 c'16 c'16 c'16
+    }
+  }
+  \new RhythmicStaff {
+    \times 8/9 {
+      c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
+    }
+  }
+>>
+@end lilypond
 
-@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.
+But if we look very carefully we can see that notes of the second half
+of the 9-tuplet space ever so slightly more widely than do the notes
+of the first half of the 9-tuplet.  To ensure uniform stretching, we
+turn on @code{uniform-stretching}, which is a property of
+@code{SpacingSpanner}.
 
-@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
+@lilypond[quote,verbatim,ragged-right]
+\new Score \with {
+  proportionalNotationDuration = #(ly:make-moment 1 20)
+  \override SpacingSpanner #'uniform-stretching = ##t
+} <<
+  \new RhythmicStaff {
+    c'2
+    c'16 c'16 c'16 c'16
+    \times 4/5 {
+      c'16 c'16 c'16 c'16 c'16
+    }
+  }
+  \new RhythmicStaff {
+    \times 8/9 {
+      c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
+    }
+  }
+>>
+@end lilypond
 
-@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.
+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.
+
+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
+entire score or turned off for the entire score.  We can, however,
+override this behavior and turn on different spacing features at
+different places in the score.  We do this with the command
+@code{\newSpacingSection}.  See @ref{New spacing area}, for more info.
+
+Next we examine the effects of the @code{Separating_line_group_engraver} and
+see why proportional scores frequently remove this engraver.  The following
+example shows that there is a small amount of @qq{preferatory} space
+just before the first note in each system.
+
+@lilypond[quote,verbatim,ragged-right]
+\paper {
+  indent = #0
+}
 
-@refbugs
+\new Staff {
+  c'1
+  \break
+  c'1
+}
+@end lilypond
 
-There should only be one @code{Page_turn_engraver} in a score. If there is more
-than one, they will interfere with each other.
 
+The amount of this preferatory space is the same whether after a time
+signature, a key signature or a clef.  @code{Separating_line_group_engraver}
+is responsible for this space.  Removing @code{Separating_line_group_engraver}
+reduces this space to zero.
 
-@node Displaying spacing
-@section Displaying spacing
+@lilypond[quote,verbatim,ragged-right]
+\paper {
+  indent = #0
+}
 
-@funindex annotate-spacing
-@cindex Spacing, display of properties
+\new Staff \with {
+  \remove Separating_line_group_engraver
+} {
+  c'1
+  \break
+  c'1
+}
+@end lilypond
 
-To graphically display the dimensions of vertical properties that may
-be altered for page formatting, set @code{annotate-spacing} in the
-@code{\paper} block, like this
+Nonmusical elements like time signatures, key signatures, clefs and
+accidentals are problemmatic in proportional notation.  None of these
+elements has rhythmic duration.  But all of these elements consume
+horizontal space.  Different proportional scores approach these
+problems differently.
+
+It may be possible to avoid spacing problems with key signatures
+simply by not having any.  This is a valid option since most
+proportional scores are contemporary music.  The same may be true
+of time signatures, especially for those scores
+that include a measured timeline or other graphic.  But these scores
+are exceptional and most proportional scores include at least some
+time signatures.  Clefs and accidentals are even more essential.
+
+So what strategies exist for spacing nonmusical elements in a
+proportional context?  One good option is the @code{strict-note-spacing}
+property of @code{SpacingSpanner}.  Compare the two scores below:
+
+@lilypond[quote,verbatim,ragged-right]
+\new Staff {
+  \set Score.proportionalNotationDuration = #(ly:make-moment 1 16)
+  c''8
+  c''8
+  c''8
+  \clef alto
+  d'8
+  d'2
+}
 
+\new Staff {
+  \set Score.proportionalNotationDuration = #(ly:make-moment 1 16)
+  \override Score.SpacingSpanner #'strict-note-spacing = ##t
+  c''8
+  c''8
+  c''8
+  \clef alto
+  d'8
+  d'2
+}
+@end lilypond
 
-@lilypond[verbatim]
-#(set-default-paper-size "a6" 'landscape)
+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
+}
 
-\book {
-  \score { { c4 } }
-  \paper { annotate-spacing = ##t }
+\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
 
-@c need to have \book{} otherwise we get  the separate systems. -hwn
+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
 
-@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
-(@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
-@var{b} the upper edge of the interval.
+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}
+@item @code{tupletFullLength = ##t}
+@item @code{\override Beam #'breakable = ##t}
+@item @code{\override Glissando #'breakable = ##t}
+@item @code{\override TextSpanner #'breakable = ##t}
+@item @code{\remove Forbid_line_break_engraver in the Voice context}
+@end itemize
+
+These settings space grace notes strictly, extend tuplet brackets to
+mark both rhythmic start- and stop-points, and allow spanning elements
+to break across systems and pages.  See the respective parts of the manual
+for these related settings.