X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fspacing.itely;h=b4b3d7a80b95d8705c505be54fdddf6c6eb884c7;hb=2bcfd84f0d276e0db06d6248ed54a05685e8cca6;hp=c85be8386969835c5bf0b318926fb03b07ca12db;hpb=f0eca19f1dc9ffddf98eadf39800405fe4d3e7a5;p=lilypond.git

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index c85be83869..b4b3d7a80b 100644
--- a/Documentation/notation/spacing.itely
+++ b/Documentation/notation/spacing.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.17.11"
+@c \version "2.17.30"
 
 @ignore
 GDP TODO list
@@ -21,30 +21,6 @@ Negative numbers are allowed:
 > and prints page number -1 on the second page, for example.
 
 
-In 5.2.1 the @refbugs (line 495 in spacing.itely on master) it
-states:
-
-"@code{layout-set-staff-size} does not change the distance between
-the
-staff lines."
-
-Could we add a sentence:
-"Use instead the pair               fontSize = #@var{N}
-            \override StaffSymbol.staff-space = #(magstep
-@var{N})
-inside the Staff context to change the size of the font and the
-distance between
-staff lines accordingly."
-
-Actually I found, that the @internalsref{StaffSymbol} at line 481
-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
-knowledge to fix this?
-
-
 Clarify
 http://code.google.com/p/lilypond/issues/detail?id=68
 
@@ -94,17 +70,17 @@ This section discusses page layout options for the @code{\paper}
 block.
 
 @menu
-* The \paper block::
+* The paper block::
 * Paper size and automatic scaling::
-* Fixed vertical spacing \paper variables::
-* Flexible vertical spacing \paper variables::
-* Horizontal spacing \paper variables::
-* Other \paper variables::
+* Fixed vertical spacing paper variables::
+* Flexible vertical spacing paper variables::
+* Horizontal spacing paper variables::
+* Other paper variables::
 @end menu
 
 
-@node The \paper block
-@subsection The @code{\paper} block
+@node The paper block
+@subsection The @code{@bs{}paper} block
 
 @code{\paper} blocks may be placed in three different places to form
 a descending hierarchy of @code{\paper} blocks:
@@ -161,7 +137,7 @@ footers, and titles are discussed in
 
 Most @code{\paper} variables will only work in a @code{\paper}
 block.  The few that will also work in a @code{\layout} block are
-listed in @ref{The \layout block}.
+listed in @ref{The layout block,,The @code{@bs{}layout} block}.
 
 Except when specified otherwise, all @code{\paper} variables that
 correspond to distances on the page are measured in millimeters,
@@ -203,7 +179,7 @@ The Scheme equivalent of the above example is:
 Notation Reference:
 @ref{Paper size and automatic scaling},
 @ref{Custom titles headers and footers},
-@ref{The \layout block}.
+@ref{The layout block,,The @code{@bs{}layout} block}.
 
 Installed Files:
 @file{ly/paper-defaults-init.ly}.
@@ -227,15 +203,18 @@ Installed Files:
 @unnumberedsubsubsec Setting the paper size
 
 @q{A4} is the default value when no explicit paper size is set. However,
-there are two functions that can be used to change it
-@code{set-default-paper-size},
+there are two functions that can be used to change it:
+
+@table @code
+@item set-default-paper-size
 
 @example
 #(set-default-paper-size "quarto")
 @end example
 
-which must always be placed at the toplevel scope. and
-@code{set-paper-size},
+which must always be placed at the toplevel scope, and
+
+@item set-paper-size
 
 @example
 \paper @{
@@ -244,9 +223,10 @@ which must always be placed at the toplevel scope. and
 @end example
 
 which must always be placed in a @code{\paper} block.
+@end table
 
 If the @code{set-default-paper-size} function is used in the toplevel
-scope, it must come before the any @code{\paper} block.
+scope, it must come before any @code{\paper} block.
 @code{set-default-paper-size} sets the paper size for all pages,
 whereas @code{set-paper-size} only sets the paper size for the pages
 that the @code{\paper} block applies to.  For example, if the
@@ -331,11 +311,12 @@ are described in @ref{Setting the paper size}.
 
 The vertical dimensions affected by automatic scaling are
 @code{top-margin} and @code{bottom-margin} (see
-@ref{Fixed vertical spacing \paper variables}).  The horizontal
+@ref{Fixed vertical spacing paper variables,,Fixed vertical spacing @code{@bs{}paper} variables}).
+The horizontal
 dimensions affected by automatic scaling are @code{left-margin},
 @code{right-margin}, @code{inner-margin}, @code{outer-margin},
 @code{binding-offset}, @code{indent}, and @code{short-indent} (see
-@ref{Horizontal spacing \paper variables}).
+@ref{Horizontal spacing paper variables,,Horizontal spacing @code{@bs{}paper} variables}).
 
 The default values for these dimensions are set in
 @file{ly/paper-defaults-init.ly}, using internal variables named
@@ -347,16 +328,16 @@ These are the values that result at the default paper size
 
 @seealso
 Notation Reference:
-@ref{Fixed vertical spacing \paper variables},
-@ref{Horizontal spacing \paper variables}.
+@ref{Fixed vertical spacing paper variables,,Fixed vertical spacing @code{@bs{}paper} variables},
+@ref{Horizontal spacing paper variables,,Horizontal spacing @code{@bs{}paper} variables}.
 
 Installed Files:
 @file{ly/paper-defaults-init.ly},
 @file{scm/paper.scm}.
 
 
-@node Fixed vertical spacing \paper variables
-@subsection Fixed vertical spacing @code{\paper} variables
+@node Fixed vertical spacing paper variables
+@subsection Fixed vertical spacing @code{@bs{}paper} variables
 
 @warning{Some @code{@bs{}paper} dimensions are automatically
 scaled to the paper size, which may lead to unexpected behavior.
@@ -389,18 +370,16 @@ default value is scaled accordingly.
 @item ragged-bottom
 @funindex ragged-bottom
 
-If set to true, systems will not spread vertically down the page.
-This does not affect the last page.  This should be set to true
-for pieces that have only two or three systems per page, for
-example orchestral scores.
+If this is set to true,
+systems will be set at their natural spacing, neither compressed
+nor stretched vertically to fit the page.
 
 @item ragged-last-bottom
 @funindex ragged-last-bottom
 
-If set to false, systems will spread vertically down the last
-page.  Pieces that amply fill two pages or more should have this
-set to false.  It also affects the last page of book parts, i.e.
-parts of a book created with @code{\bookpart} blocks.
+If this is set to false, then the last page,
+and the last page in each section created with a @code{\bookpart} block,
+will be vertically justified in the same way as the earlier pages.
 
 @end table
 
@@ -423,8 +402,8 @@ Explicitly defined paper-sizes will override any user-defined top or
 bottom margin settings.
 
 
-@node Flexible vertical spacing \paper variables
-@subsection Flexible vertical spacing @code{\paper} variables
+@node Flexible vertical spacing paper variables
+@subsection Flexible vertical spacing @code{@bs{}paper} variables
 
 In most cases, it is preferable for the vertical distances between
 certain items (such as margins, titles, systems, and separate
@@ -442,7 +421,7 @@ settings typically entered inside a @code{\score} or
 
 @menu
 * Structure of flexible vertical spacing alists::
-* List of flexible vertical spacing \paper variables::
+* List of flexible vertical spacing paper variables::
 @end menu
 
 
@@ -539,8 +518,8 @@ redefines the variable:
 @end example
 
 
-@node List of flexible vertical spacing \paper variables
-@unnumberedsubsubsec List of flexible vertical spacing @code{\paper} variables
+@node List of flexible vertical spacing paper variables
+@unnumberedsubsubsec List of flexible vertical spacing @code{@bs{}paper} variables
 
 The names of these variables follow the format
 @code{@var{upper}-@var{lower}-spacing}, where @code{@var{upper}}
@@ -620,22 +599,22 @@ Snippets:
 @rlsr{Spacing}.
 
 
-@node Horizontal spacing \paper variables
-@subsection Horizontal spacing @code{\paper} variables
+@node Horizontal spacing paper variables
+@subsection Horizontal spacing @code{@bs{}paper} variables
 
 @warning{Some @code{@bs{}paper} dimensions are automatically
 scaled to the paper size, which may lead to unexpected behavior.
 See @ref{Automatic scaling to paper size}.}
 
 @menu
-* \paper variables for widths and margins::
-* \paper variables for two-sided mode::
-* \paper variables for shifts and indents::
+* paper variables for widths and margins::
+* paper variables for two-sided mode::
+* paper variables for shifts and indents::
 @end menu
 
 
-@node \paper variables for widths and margins
-@unnumberedsubsubsec @code{\paper} variables for widths and margins
+@node paper variables for widths and margins
+@unnumberedsubsubsec @code{@bs{}paper} variables for widths and margins
 
 Default values (before scaling) that are not listed here are
 defined in @file{ly/paper-defaults-init.ly}.
@@ -733,8 +712,8 @@ Explicitly defined paper-sizes will override any user-defined left or
 right margin settings.
 
 
-@node \paper variables for two-sided mode
-@unnumberedsubsubsec @code{\paper} variables for two-sided mode
+@node paper variables for two-sided mode
+@unnumberedsubsubsec @code{@bs{}paper} variables for two-sided mode
 
 Default values (before scaling) are defined in
 @file{ly/paper-defaults-init.ly}.
@@ -786,8 +765,8 @@ Installed Files:
 @file{ly/paper-defaults-init.ly}.
 
 
-@node \paper variables for shifts and indents
-@unnumberedsubsubsec @code{\paper} variables for shifts and indents
+@node paper variables for shifts and indents
+@unnumberedsubsubsec @code{@bs{}paper} variables for shifts and indents
 
 Default values (before scaling) that are not listed here are
 defined in @file{ly/paper-defaults-init.ly}.
@@ -831,19 +810,19 @@ Snippets:
 @rlsr{Spacing}.
 
 
-@node Other \paper variables
-@subsection Other @code{\paper} variables
+@node Other paper variables
+@subsection Other @code{@bs{}paper} variables
 
 @menu
-* \paper variables for line breaking::
-* \paper variables for page breaking::
-* \paper variables for page numbering::
-* Miscellaneous \paper variables::
+* paper variables for line breaking::
+* paper variables for page breaking::
+* paper variables for page numbering::
+* Miscellaneous paper variables::
 @end menu
 
 
-@node \paper variables for line breaking
-@unnumberedsubsubsec @code{\paper} variables for line breaking
+@node paper variables for line breaking
+@unnumberedsubsubsec @code{@bs{}paper} variables for line breaking
 
 @table @code
 
@@ -882,8 +861,8 @@ Notation Reference:
 @ref{Line breaking}.
 
 
-@node \paper variables for page breaking
-@unnumberedsubsubsec @code{\paper} variables for page breaking
+@node paper variables for page breaking
+@unnumberedsubsubsec @code{@bs{}paper} variables for page breaking
 
 Default values not listed here are defined in
 @file{ly/paper-defaults-init.ly}
@@ -977,8 +956,8 @@ Installed Files:
 @file{ly/paper-defaults-init.ly}.
 
 
-@node \paper variables for page numbering
-@unnumberedsubsubsec @code{\paper} variables for page numbering
+@node paper variables for page numbering
+@unnumberedsubsubsec @code{@bs{}paper} variables for page numbering
 
 Default values not listed here are defined in
 @file{ly/paper-defaults-init.ly}
@@ -1024,8 +1003,8 @@ music to start on page 1 there must be a blank page on the back
 of the cover page so that page 1 is on the right hand side.
 
 
-@node Miscellaneous \paper variables
-@unnumberedsubsubsec Miscellaneous @code{\paper} variables
+@node Miscellaneous paper variables
+@unnumberedsubsubsec Miscellaneous @code{@bs{}paper} variables
 
 @table @code
 
@@ -1088,13 +1067,13 @@ This section discusses score layout options for the @code{\layout}
 block.
 
 @menu
-* The \layout block::
+* The layout block::
 * Setting the staff size::
 @end menu
 
 
-@node The \layout block
-@subsection The @code{\layout} block
+@node The layout block
+@subsection The @code{@bs{}layout} block
 
 @funindex \layout
 
@@ -1124,15 +1103,15 @@ variables that can appear in a @code{\layout} block are:
 
 @item
 @code{line-width}, @code{ragged-right} and @code{ragged-last}
-(see @ref{\paper variables for widths and margins})
+(see @ref{paper variables for widths and margins,,@code{@bs{}paper} variables for widths and margins})
 
 @item
 @code{indent} and @code{short-indent}
-(see @ref{\paper variables for shifts and indents})
+(see @ref{paper variables for shifts and indents,,@code{@bs{}paper} variables for shifts and indents})
 
 @item
 @code{system-count}
-(see @ref{\paper variables for line breaking})
+(see @ref{paper variables for line breaking,,@code{@bs{}paper} variables for line breaking})
 
 @end itemize
 
@@ -1264,92 +1243,101 @@ Snippets:
 @cindex font size, setting
 @cindex staff size, setting
 @funindex layout file
+@funindex magnification->font-size
+@funindex magstep
+@funindex set-global-staff-size
+@funindex layout-set-staff-size
 
-The default @strong{staff size} is set to 20 points.
-This may be changed in two ways:
+The default @strong{staff size} is 20 points, which corresponds to
+a staff height of 7.03mm (one point is equal to 100/7227 of an
+inch, or 2540/7227 mm).  The staff size may be changed in three
+ways:
 
-To set the staff size globally for all scores in a file (or
-in a @code{book} block, to be precise), use @code{set-global-staff-size}.
+@enumerate
+
+@item
+To set the staff size globally for all scores in a file (or in a
+@code{\book} block, to be precise), use
+@code{set-global-staff-size}:
 
 @example
 #(set-global-staff-size 14)
 @end example
 
 @noindent
-This sets the global default size to 14pt staff height and scales all
-fonts accordingly.
+The above example sets the global default staff size to 14pt
+(4.92mm) and scales all fonts accordingly.
+
+@item
+To set the staff size for a single score within a book, use
+@code{layout-set-staff-size} inside that score's @code{\layout}
+block:
 
-To set the staff size individually for each score, use
 @example
-\score@{
+\score @{
   @dots{}
   \layout @{
-    #(layout-set-staff-size 15)
+    #(layout-set-staff-size 14)
   @}
 @}
 @end example
 
+@item
+To set the staff size for a single staff within a system, use the
+@code{\magnifyStaff} command.  For example, traditionally engraved
+chamber music scores with piano often used 7mm piano staves while
+the other staves were typically between 3/5 and 5/7 as large
+(between 60% and 71%).  To achieve the 5/7 proportion, use:
+
+@example
+\score @{
+  <<
+    \new Staff \with @{
+      \magnifyStaff #5/7
+    @} @{ @dots{} @}
+    \new PianoStaff @{ @dots{} @}
+  >>
+@}
+@end example
+
+If you happen to know which @code{fontSize} you wish to use, you
+could use the following form:
+
+@example
+\score @{
+  <<
+    \new Staff \with @{
+      \magnifyStaff #(magstep -3)
+    @} @{ @dots{} @}
+    \new PianoStaff @{ @dots{} @}
+  >>
+@}
+@end example
+
+To emulate the look of traditional engraving, it is best to avoid
+reducing the thickness of the staff lines.
+
+@end enumerate
+
+
+@subheading Automatic font weight at different sizes
+
 The Feta font provides musical symbols at eight different
 sizes.  Each font is tuned for a different staff size: at a smaller size
 the font becomes heavier, to match the relatively heavier staff lines.
 The recommended font sizes are listed in the following table:
 
-@quotation
 @multitable @columnfractions .15 .2 .22 .2
-
-@item @b{font name}
-@tab @b{staff height (pt)}
-@tab @b{staff height (mm)}
-@tab @b{use}
-
-@item feta11
-@tab 11.22
-@tab 3.9
-@tab pocket scores
-
-@item feta13
-@tab 12.60
-@tab 4.4
-@tab
-
-@item feta14
-@tab 14.14
-@tab 5.0
-@tab
-
-@item feta16
-@tab 15.87
-@tab 5.6
-@tab
-
-@item feta18
-@tab 17.82
-@tab 6.3
-@tab song books
-
-@item feta20
-@tab 20
-@tab 7.0
-@tab standard parts
-
-@item feta23
-@tab 22.45
-@tab 7.9
-@tab
-
-@item feta26
-@tab 25.2
-@tab 8.9
-@tab
-@c modern rental material?
-
+@item @b{font name} @tab @b{staff height (pt)} @tab @b{staff height (mm)} @tab @b{use}
+@item feta11 @tab 11.22 @tab 3.9 @tab pocket scores
+@item feta13 @tab 12.60 @tab 4.4 @tab
+@item feta14 @tab 14.14 @tab 5.0 @tab
+@item feta16 @tab 15.87 @tab 5.6 @tab
+@item feta18 @tab 17.82 @tab 6.3 @tab song books
+@item feta20 @tab 20 @tab 7.0 @tab standard parts
+@item feta23 @tab 22.45 @tab 7.9 @tab
+@item feta26 @tab 25.2 @tab 8.9 @tab @c modern rental material?
 @end multitable
-@end quotation
-
-These fonts are available in any sizes.  The context property
-@code{fontSize} and the layout property @code{staff-space} (in
-@rinternals{StaffSymbol}) can be used to tune the size for individual
-staves.  The sizes of individual staves are relative to the global size.
 
 @seealso
 Notation Reference:
@@ -1369,12 +1357,7 @@ staff lines.
 @menu
 * Line breaking::
 * Page breaking::
-* Optimal page breaking::
-* Optimal page turning::
-* Minimal page breaking::
-* One-line page breaking::
 * Explicit breaks::
-* Using an extra voice for breaks::
 @end menu
 
 
@@ -1384,9 +1367,9 @@ staff lines.
 @cindex line breaks
 @cindex breaking lines
 
-Line breaks are normally determined automatically.  They are chosen
-so that lines look neither cramped nor loose, and consecutive
-lines have similar density.
+Line breaks are normally determined automatically.  They are
+chosen so that lines look neither cramped nor loose, and
+consecutive lines have similar density.
 
 To manually force a line break at a bar line, use the
 @code{\break} command:
@@ -1463,15 +1446,13 @@ but affects only the last line of the piece.
 @}
 @end example
 
-
-
 @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}.  For example, this would
-cause the following 28 measures (assuming 4/4 time) to be broken
-every 4 measures, and only there:
+For line breaks at regular intervals use @code{\break} separated
+by skips and repeated with @code{\repeat}.  For example, this
+would cause the following 28 measures (assuming 4/4 time) to be
+broken every 4 measures, and only there:
 
 @example
 <<
@@ -1493,7 +1474,8 @@ every 4 measures, and only there:
 
 @seealso
 Notation Reference:
-@ref{\paper variables for line breaking}.
+@ref{paper variables for line breaking}
+@ref{The layout block}.
 
 Snippets:
 @rlsr{Spacing}.
@@ -1505,28 +1487,46 @@ Internals Reference:
 @node Page breaking
 @subsection Page breaking
 
+This section describes the different page breaking methods, and
+how to modify them.
+
+@menu
+* Manual page breaking::
+* Optimal page breaking::
+* Minimal page breaking::
+* One-line page breaking::
+* Optimal page turning::
+@end menu
+
+
+@node Manual page breaking
+@unnumberedsubsubsec Manual page breaking
+
 The default page breaking may be overridden 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.
+@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.
 
 The @code{\pageBreak} and @code{\noPageBreak} commands may also be
 inserted at top-level, between scores and top-level markups.
 
 There are also analogous settings to @code{ragged-right} and
-@code{ragged-last} which have the same effect on vertical spacing:
-@code{ragged-bottom} and @code{ragged-last-bottom}.  If set to
-@code{#t} the systems on all pages or just the last page
-respectively will not be justified vertically.  See
-@ref{Fixed vertical spacing \paper variables}.
-
-Page breaks are computed by the @code{page-breaking} function.  LilyPond
-provides three algorithms for computing page breaks,
+@code{ragged-last} which have the same effect on vertical spacing.
+If @code{ragged-bottom} is set to @code{#t} the systems will not
+be justified vertically.  When @code{ragged-last-bottom} is set
+to @code{#t}, as it is by default, empty space is allowed at the
+bottom of the final page (or the final page in each
+@code{\bookpart}).  See
+@ref{Fixed vertical spacing paper variables,,Fixed vertical spacing @code{@bs{}paper} variables}.
+
+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:
+@code{ly:minimal-breaking}.  The default is
+@code{ly:optimal-breaking}, but the value can be changed in the
+@code{\paper} block:
 
 @example
 \paper @{
@@ -1536,12 +1536,12 @@ but the value can be changed in the @code{\paper} block:
 
 @funindex \bookpart
 
-When a book has many scores and pages, the page breaking problem may be
-difficult to solve, requiring large processing time and memory.  To ease
-the page breaking process, @code{\bookpart} blocks are used to divide
-the book into several parts: the page breaking occurs separately on each
-part.  Different page breaking functions may also be used in different
-book parts.
+When a book has many scores and pages, the page breaking problem
+may be difficult to solve, requiring large processing time and
+memory.  To ease the page breaking process, @code{\bookpart}
+blocks are used to divide the book into several parts: the page
+breaking occurs separately on each part.  Different page breaking
+functions may also be used in different book parts.
 
 @example
 \bookpart @{
@@ -1577,65 +1577,111 @@ book parts.
 
 @seealso
 Notation Reference:
-@ref{\paper variables for page breaking}.
+@ref{paper variables for page breaking}.
 
 Snippets:
 @rlsr{Spacing}.
 
 
 @node Optimal page breaking
-@subsection Optimal page breaking
+@unnumberedsubsubsec 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.
+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.
 
 @seealso
 Snippets:
 @rlsr{Spacing}.
 
 
+@node Minimal page breaking
+@unnumberedsubsubsec 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 preferred 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 @{
+  page-breaking = #ly:minimal-breaking
+@}
+@end example
+
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+
+@node One-line page breaking
+@unnumberedsubsubsec One-line page breaking
+
+@funindex ly:one-line-breaking
+
+The @code{ly:one-line-breaking} function is a special-purpose
+page breaking algorithm that puts each score on its own page, and
+on a single line.  This page breaking function does not typeset
+titles or margins; only the score will be displayed.
+
+The page width will be adjusted so that the longest score fits on
+one line.  In particular, @code{paper-width}, @code{line-width}
+and @code{indent} variables in the @code{\paper} block will be
+ignored, although @code{left-margin} and @code{right-margin} will
+still be honored.  The height of the page will be left unmodified.
+
+
 @node Optimal page turning
-@subsection Optimal page turning
+@unnumberedsubsubsec 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.
-
-There are two steps to using this page breaking function.  First, you
-must enable it in the @code{\paper} block, as explained in @ref{Page
-breaking}.  Then you must tell the function where you would like to allow
-page breaks.
-
-There are two ways to achieve the second step.  First, you can specify each
-potential page turn manually, by inserting @code{\allowPageTurn} into your
-input file at the appropriate places.
-
-If this is too tedious, you can add a @code{Page_turn_engraver} to a Staff or
-Voice context.  The @code{Page_turn_engraver} will scan the context for
-sections without notes (note that it does not scan for rests; it scans for
-the absence of notes.  This is so that single-staff polyphony with rests in one
-of the parts does not throw off the @code{Page_turn_engraver}).  When it finds
-a sufficiently long section without notes, the @code{Page_turn_engraver} will
-insert an @code{\allowPageTurn} at the final 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.
+Often it is necessary to find a page breaking configuration so
+that there is a rest at the end of every second page.  This way,
+the musician can turn the page without having to miss notes.  The
+@code{ly:page-turn-breaking} function attempts to find a page
+breaking minimizing cramping and stretching, but with the
+additional restriction that it is only allowed to introduce page
+turns in specified places.
+
+There are two steps to using this page breaking function.  First,
+you must enable it in the @code{\paper} block, as explained in
+@ref{Page breaking}.  Then you must tell the function where you
+would like to allow page breaks.
+
+There are two ways to achieve the second step.  First, you can
+specify each potential page turn manually, by inserting
+@code{\allowPageTurn} into your input file at the appropriate
+places.
+
+If this is too tedious, you can add a @code{Page_turn_engraver} to
+a Staff or Voice context.  The @code{Page_turn_engraver} will scan
+the context for sections without notes (note that it does not scan
+for rests; it scans for the absence of notes.  This is so that
+single-staff polyphony with rests in one of the parts does not
+throw off the @code{Page_turn_engraver}).  When it finds a
+sufficiently long section without notes, the
+@code{Page_turn_engraver} will insert an @code{\allowPageTurn} at
+the final 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
-to disable page turns, you can set it to something very large.
+@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,
+set it to something @q{very large}.
 
 @example
 \new Staff \with @{ \consists "Page_turn_engraver" @}
@@ -1652,16 +1698,18 @@ 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
-turn during the repeat if there is enough time at the beginning and end of the
-repeat to turn the page back.  The @code{Page_turn_engraver} can also disable
-page turns if the repeat is very short.  If you set the context property
-@code{minimumRepeatLengthForPageTurn} then the @code{Page_turn_engraver} will
-only allow turns in repeats whose duration is longer than this value.
-
-The page turning commands, @code{\pageTurn}, @code{\noPageTurn} and
-@code{\allowPageTurn}, may also be used at top-level, between scores and
-top-level markups.
+With volta repeats, the @code{Page_turn_engraver} 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.  If the
+repeat is very short, the @code{Page_turn_engraver} can also be
+used to disable page turns by setting a value for the context
+property @code{minimumRepeatLengthForPageTurn} where as
+@code{Page_turn_engraver} only allows 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, in
+top-level markups and between scores.
 
 @predefined
 @funindex \pageTurn
@@ -1674,70 +1722,33 @@ top-level markups.
 
 @seealso
 Notation Reference:
-@ref{\paper variables for line breaking}.
+@ref{paper variables for line breaking}.
 
 Snippets:
 @rlsr{Spacing}.
 
 @knownissues
-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 preferred 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 @{
-  page-breaking = #ly:minimal-breaking
-@}
-@end example
-
-@seealso
-Snippets:
-@rlsr{Spacing}.
-
-@node One-line page breaking
-@subsection One-line page breaking
-
-@funindex ly:one-line-breaking
+Use only one @code{Page_turn_engraver} per score.  If there are
+more, they will interfere with each other.
 
-The @code{ly:one-line-breaking} function is a special-purpose
-page breaking algorithm that puts each score on its own page,
-and on a single line.  This page breaking function does not
-typeset titles or margins; only the score will be displayed.
-
-The page width will be adjusted so that
-the longest score fits on one line.  In particular,
-@code{paper-width}, @code{line-width} and @code{indent}
-variables in the @code{\paper} block will be ignored, although
-@code{left-margin} and @code{right-margin} will
-still be honored.  The height of the page will
-be left unmodified.
 
 @node Explicit breaks
 @subsection Explicit breaks
 
-Lily sometimes rejects explicit @code{\break} and @code{\pageBreak}
-commands.  There are two commands to override this behavior:
+There are cases when manual @code{\break} or @code{\pageBreak}
+commands are ignored by LilyPond.  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 overridden to false, Lily will insert
-line breaks at explicit @code{\break} commands and nowhere else.  When
-@code{page-break-permission} is overridden to false, Lily will insert
-page breaks at explicit @code{\pageBreak} commands and nowhere else.
+If @code{line-break-permission} is set to @code{##f}, all line
+breaks must be explicitly inserted with a @code{\break} command.
+Likewise, if @code{page-break-permission} is set to @code{##f},
+all page breaks must be explicitly inserted with a
+@code{\pageBreak} command.
 
 @lilypond[quote,verbatim]
 \paper {
@@ -1769,99 +1780,10 @@ music = \relative c'' { c8 c c c }
 }
 @end lilypond
 
-@seealso
-Snippets:
-@rlsr{Spacing}.
-
-
-@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
-music = \relative c'' @{ c4 c c c @}
-
-\score @{
-  \new Staff @{
-    \repeat unfold 2 @{ \music @} \break
-    \repeat unfold 3 @{ \music @}
-  @}
-@}
-@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]
-music = \relative c'' { c4 c c c }
-
-\header { tagline = ##f }
-\paper { left-margin = 0\mm }
-\book {
-  \score {
-    \new Staff <<
-      \new Voice {
-        s1 * 2 \break
-        s1 * 3 \break
-        s1 * 6 \break
-        s1 * 5 \break
-      }
-      \new Voice {
-        \repeat unfold 2 { \music }
-        \repeat unfold 3 { \music }
-        \repeat unfold 6 { \music }
-        \repeat unfold 5 { \music }
-      }
-    >>
-  }
-}
-@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}.
+@snippets
 
-@lilypond[quote,verbatim]
-music = \relative c'' { c4 c c c }
-
-\header { tagline = ##f }
-\paper { left-margin = 0\mm }
-\book {
-  \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 . 5))
-        s1 * 3 \break
-
-        \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
-          #'((Y-offset . 15))
-        s1 * 6 \break
-
-        \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
-          #'((Y-offset . 30))
-        s1 * 5 \break
-      }
-      \new Voice {
-        \repeat unfold 2 { \music }
-        \repeat unfold 3 { \music }
-        \repeat unfold 6 { \music }
-        \repeat unfold 5 { \music }
-      }
-    >>
-  }
-}
-@end lilypond
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{using-an-extra-voice-for-breaks.ly}
 
 @seealso
 Notation Reference:
@@ -1879,8 +1801,8 @@ Snippets:
 
 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.
+space between systems, and the amount of space between staves
+inside a system.
 
 @menu
 * Flexible vertical spacing within systems::
@@ -1928,7 +1850,7 @@ control the vertical spacing of staves and non-staff lines within
 individual systems.  The vertical spacing between separate
 systems, scores, markups, and margins is controlled by
 @code{\paper} variables, which are discussed in
-@ref{Flexible vertical spacing \paper variables}.
+@ref{Flexible vertical spacing paper variables,,Flexible vertical spacing @code{@bs{}paper} variables}.
 
 @menu
 * Within-system spacing properties::
@@ -1982,7 +1904,7 @@ given in the following table:
 @item @code{ChordNames}  @tab baseline
 @item @code{NoteNames}   @tab baseline
 @item @code{Lyrics}      @tab baseline
-@item @code{Dynamics}    @tab vertical center
+@item @code{Dynamics}    @tab mid-height of @q{m}
 @item @code{FiguredBass} @tab highest point
 @item @code{FretBoards}  @tab top line
 @end multitable
@@ -1996,87 +1918,70 @@ of these reference points:
 alignToZero = \with {
   \override VerticalAxisGroup.nonstaff-relatedstaff-spacing = #zero-space
   \override VerticalAxisGroup.nonstaff-nonstaff-spacing = #zero-space
+  \override VerticalAxisGroup.staff-affinity = #DOWN
+  \remove Text_engraver % avoid having two
+  \consists Text_engraver
 }
 lowerCaseChords = \with {
   chordNameLowercaseMinor = ##t
 }
-staffAffinityDown = \with {
-  \override VerticalAxisGroup.staff-affinity = #DOWN
-}
 labelContext =
 #(define-music-function
      (parser location context)
      (string?)
-   #{ s1*0^\markup { \typewriter #context } #})
+     #{ s1*0^\markup { \upright {\typewriter #context } } #})
 
 \layout {
   \context { \Dynamics    \alignToZero }
   \context { \FiguredBass \alignToZero }
   \context { \Lyrics      \alignToZero }
-  \context { \NoteNames   \alignToZero \staffAffinityDown }
-  \context { \ChordNames  \alignToZero
-                          \staffAffinityDown
-			  \lowerCaseChords }
-  \context { \FretBoards  \alignToZero \staffAffinityDown }
+  \context { \NoteNames   \alignToZero }
+  \context { \ChordNames  \alignToZero \lowerCaseChords }
+  \context { \FretBoards  \alignToZero }
   \context { \Score
-    \override BarLine.stencil = ##f
+    \omit BarLine
     \override DynamicText.self-alignment-X = #-1
     \override FretBoard.X-offset = #1.75
-    \override InstrumentName.minimum-Y-extent = #'(-2 . 2)
-    \override InstrumentName.extra-offset = #'(0 . -0.5)
-    \override TextScript.minimum-Y-extent = #'(-2 . 3)
-    \override TimeSignature.stencil = ##f
+    \override InstrumentName.minimum-Y-extent = #'(-1 . 2)
+    \textLengthOn
+    \omit TimeSignature
   }
 }
 
 %% These contexts have reference points at the baseline:
 %%   ChordNames, NoteNames, and Lyrics
 <<
-  \new ChordNames { \chords { g1:m } }
-  \new NoteNames { s1 | g1 | }
-  \new RhythmicStaff {
-    \set RhythmicStaff.instrumentName = #"baseline "
-    \textLengthOn
-    \labelContext "ChordNames " s1 |
-    \labelContext "NoteNames "  s1 |
-    \labelContext "Lyrics"     s1 |
-  }
-  \new Lyrics { \lyrics { \skip 1*2 | ghijk1 | } }
+  \new ChordNames { \chords { \labelContext "ChordNames"  g1:m } }
+  \new NoteNames { s1 |\labelContext "NoteNames"  g1 | }
+  \new Lyrics { \lyrics { \skip 1*2 | \labelContext "Lyrics" ghijk1 | } }
+  \new RhythmicStaff \with { instrumentName = #"baseline " } s1*3
 >>
 
-%% The reference point for Dynamics is its vertical center
+%% The reference point for Dynamics is the midline of 'm' in the font
 <<
-  \new RhythmicStaff {
-    \set RhythmicStaff.instrumentName = #"vertical center "
-    \labelContext "Dynamics" s1*3
-  }
-  \new Dynamics { s1\mp s\fp }
+  \new Dynamics { \labelContext "Dynamics" s1\mp s\fp }
+  \new RhythmicStaff \with { instrumentName = #"mid-height " } s1*3
 >>
 
 %% The reference point for FiguredBass is its highest point
 <<
-  \new RhythmicStaff {
-    \set RhythmicStaff.instrumentName = #"highest point "
-    \labelContext "FiguredBass" s1
-  }
-  \new FiguredBass { \figuremode { <6 5>1 } }
+  \new FiguredBass { \labelContext "FiguredBass" \figuremode { <6 5>1 } }
+  \new RhythmicStaff \with { instrumentName = #"highest point " } s1
 >>
 
 %% The reference point for FretBoards is the top line
 \include "predefined-guitar-fretboards.ly"
 <<
-  \new FretBoards { \chordmode { e1 } }
-  \new RhythmicStaff {
-    \set RhythmicStaff.instrumentName = #"top line "
-    \labelContext "FretBoards " s1
-  }
+  \new FretBoards { \labelContext "FretBoards" \chordmode { e1 } }
+  \new RhythmicStaff \with { instrumentName = #"top line " } s1
 >>
 @end lilypond
 
 Each of the vertical spacing grob properties (except
 @code{staff-affinity}) uses the same alist structure as the
 @code{\paper} spacing variables discussed in
-@ref{Flexible vertical spacing \paper variables}.  Specific methods
+@ref{Flexible vertical spacing paper variables,,Flexible vertical spacing @code{@bs{}paper} variables}.
+Specific methods
 for modifying alists are discussed in @ref{Modifying alists}.
 Grob properties should be adjusted with an @code{\override} inside
 a @code{\score} or @code{\layout} block, and not inside a
@@ -2218,7 +2123,7 @@ spacing settings for that staff.
 
 @seealso
 Notation Reference:
-@ref{Flexible vertical spacing \paper variables},
+@ref{Flexible vertical spacing paper variables,,Flexible vertical spacing @code{@bs{}paper} variables},
 @ref{Modifying alists}.
 
 Installed Files:
@@ -2380,8 +2285,8 @@ Internals Reference:
 @emph{Non-staff lines} (such as @code{Lyrics}, @code{ChordNames},
 etc.) are contexts whose layout objects are engraved like staves
 (i.e. in horizontal lines within systems).  Specifically,
-non-staff lines are non-staff contexts that create the
-@code{VerticalAxisGroup} layout object.
+non-staff lines are non-staff contexts that contain the
+@rinternals{Axis_group_engraver}.
 
 The following properties affect the spacing of non-staff lines:
 
@@ -2536,7 +2441,7 @@ by looking at an example that includes no overrides at all.
 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}.
+See @ref{Explicit breaks}.
 
 Explicit @code{\breaks} evenly divide the music into six measures per
 line.  Vertical spacing results from LilyPond's defaults.  To set
@@ -2766,7 +2671,7 @@ Snippets:
 * Horizontal spacing overview::
 * New spacing area::
 * Changing horizontal spacing::
-* Line length::
+* Line width::
 * Proportional notation::
 @end menu
 
@@ -2780,8 +2685,7 @@ 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 @rinternals{SpacingSpanner}
 object).  The longer the duration, the more space it gets: doubling a
-duration adds a fixed amount (this amount is controlled by
-@code{spacing-increment}) of space to the note.
+duration adds @code{spacing-increment} of space to the note.
 
 For example, the following piece contains lots of half, quarter, and
 8th notes; the eighth note is followed by 1 note head width (NHW).
@@ -3012,7 +2916,7 @@ regard for clefs, bar lines, and grace notes,
 
 @lilypond[quote,ragged-right,relative=2,verbatim]
 \override Score.SpacingSpanner.strict-note-spacing = ##t
-\new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c]  c32[ c] }
+\new Staff { c8[ c \clef alto c \grace { c16 c } c8 c c]  c32[ c] }
 @end lilypond
 
 @seealso
@@ -3020,8 +2924,8 @@ Snippets:
 @rlsr{Spacing}.
 
 
-@node Line length
-@subsection Line length
+@node Line width
+@subsection Line width
 
 @cindex page breaks
 @cindex breaking pages
@@ -3101,11 +3005,14 @@ proportional notation settings and examine how these settings interact.
 We start with the following one-measure example, which uses classical
 spacing with ragged-right turned on.
 
+@c The initial pitch is not necessary as long as RhythmicStaff is
+@c not preceded by other material in the score, but we don't want
+@c to explain that.
 @lilypond[quote,verbatim,ragged-right]
 \score {
   <<
     \new RhythmicStaff {
-      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
     }
   >>
 }
@@ -3130,7 +3037,7 @@ setting.
 \score {
   <<
     \new RhythmicStaff {
-      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
     }
   >>
  \layout {
@@ -3174,7 +3081,7 @@ larger reference durations space music tightly.
 \score {
   <<
     \new RhythmicStaff {
-      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
     }
   >>
   \layout {
@@ -3188,7 +3095,7 @@ larger reference durations space music tightly.
 \score {
   <<
     \new RhythmicStaff {
-      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
     }
   >>
   \layout {
@@ -3202,7 +3109,7 @@ larger reference durations space music tightly.
 \score {
   <<
     \new RhythmicStaff {
-      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
     }
   >>
   \layout {
@@ -3230,10 +3137,10 @@ tuplet.
 \score {
   <<
     \new RhythmicStaff {
-      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
     }
     \new RhythmicStaff {
-      \tuplet 9/8 { c'8 c' c' c' c' c' c' c' c' }
+      \tuplet 9/8 { c8 8 8 8 8 8 8 8 8 }
     }
   >>
 }
@@ -3248,10 +3155,10 @@ result.  Setting @code{proportionalNotationDuration} fixes this.
 \score {
   <<
     \new RhythmicStaff {
-      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
     }
     \new RhythmicStaff {
-      \tuplet 9/8 { c'8 c' c' c' c' c' c' c' c' }
+      \tuplet 9/8 { c8 8 8 8 8 8 8 8 8 }
     }
   >>
   \layout {
@@ -3273,10 +3180,10 @@ turn on @code{uniform-stretching}, which is a property of
 \score {
   <<
     \new RhythmicStaff {
-      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+      c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
     }
     \new RhythmicStaff {
-      \tuplet 9/8 { c'8 c' c' c' c' c' c' c' c' }
+      \tuplet 9/8 { c8 8 8 8 8 8 8 8 8 }
     }
   >>
   \layout {
@@ -3372,13 +3279,13 @@ 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'' c'' \clef alto d' d'2
+  c''8 8 8 \clef alto d'2 2
 }
 
 \new Staff {
   \set Score.proportionalNotationDuration = #(ly:make-moment 1/16)
   \override Score.SpacingSpanner.strict-note-spacing = ##t
-  c''8 c'' c'' \clef alto d' d'2
+  c''8 8 8 \clef alto d'2 2
 }
 @end lilypond