Issue 3926: Add \magnifyMusic; clarify fontSize in docs.

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

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index 91eeefa4e82687acb6fb7b6f40a57b5c6c6e61e6..3ee12b679876fdc986ccaabbbb78690b2d7cd06a 100644 (file)
--- a/Documentation/notation/spacing.itely
+++ b/Documentation/notation/spacing.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     Guide, node Updating translation committishes..
 @end ignore
 

-@c \version "2.17.11"
+@c \version "2.17.30"

 
 @ignore
 GDP TODO list
 
 @ignore
 GDP TODO list


@@ -21,30 +21,6 @@ Negative numbers are allowed:
 > and prints page number -1 on the second page, for example.
 
 
 > 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
 
 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
 block.
 
 @menu

-* The \paper block::
+* The paper block::

 * Paper size and automatic scaling::
 * 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
 
 
 @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:
 
 @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
 
 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,
 
 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},
 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}.
 
 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,
 @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
 
 
 @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 @{
 
 @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 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
 
 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
 @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
 
 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
 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
 
 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:
 
 @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}.
 
 
 
 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.
 
 @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
 
 @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
 
 
 @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
 
 
 @end table
 


@@ -423,8 +402,8 @@ Explicitly defined paper-sizes will override any user-defined top or
 bottom margin settings.
 
 
 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
 
 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::
 
 @menu
 * Structure of flexible vertical spacing alists::

-* List of flexible vertical spacing \paper variables::
+* List of flexible vertical spacing paper variables::

 @end menu
 
 
 @end menu
 
 


@@ -539,8 +518,8 @@ redefines the variable:
 @end example
 
 
 @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}}
 
 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}.
 
 
 @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
 
 @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
 
 
 @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}.
 
 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.
 
 
 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}.
 
 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}.
 
 
 @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}.
 
 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}.
 
 
 @rlsr{Spacing}.
 
 

-@node Other \paper variables
-@subsection Other @code{\paper} variables
+@node Other paper variables
+@subsection Other @code{@bs{}paper} variables

 
 @menu
 
 @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
 
 
 @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
 
 
 @table @code
 


@@ -882,8 +861,8 @@ Notation Reference:
 @ref{Line breaking}.
 
 
 @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}
 
 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}.
 
 
 @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}
 
 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.
 
 
 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
 
 
 @table @code
 


@@ -1088,13 +1067,13 @@ This section discusses score layout options for the @code{\layout}
 block.
 
 @menu
 block.
 
 @menu

-* The \layout block::
+* The layout block::

 * Setting the staff size::
 @end menu
 
 
 * 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
 
 
 @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}
 
 @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}
 
 @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}
 
 @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
 
 
 @end itemize
 


@@ -1264,92 +1243,109 @@ Snippets:
 @cindex font size, setting
 @cindex staff size, setting
 @funindex layout file
 @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
 
 @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
 @example

-\score@{
+\score @{

   @dots{}
   \layout @{
   @dots{}
   \layout @{

-    #(layout-set-staff-size 15)
+    #(layout-set-staff-size 14)

   @}
 @}
 @end example
 
   @}
 @}
 @end example
 

+@item
+To set the staff size for a single staff within a system, set the
+staff's font-size and staff-space using units relative to the
+score's default staff size.  Using relative units prevents the
+proportion of staff sizes from being altered if the default staff
+size is modified with @code{set-global-staff-size} or
+@code{layout-set-staff-size}.
+
+For example, traditionally engraved chamber music scores with
+piano often used 7mm piano staves while the other staves were up
+to 5/7 as large (if space allowed), or down to 3/5 as large (if
+space was cramped).  To achieve the 5/7 proportion, use:
+
+@example
+\score @{
+  <<
+    \new Staff \with @{
+      fontSize = #(magnification->font-size 5/7)
+      \override StaffSymbol.staff-space = #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 @{
+      fontSize = -3
+      \override StaffSymbol.staff-space = #(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:
 
 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
 @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 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:
 
 @seealso
 Notation Reference:


@@ -1493,7 +1489,7 @@ every 4 measures, and only there:
 
 @seealso
 Notation Reference:
 
 @seealso
 Notation Reference:

-@ref{\paper variables for line breaking}.
+@ref{paper variables for line breaking,,@code{@bs{}paper} variables for line breaking}.

 
 Snippets:
 @rlsr{Spacing}.
 
 Snippets:
 @rlsr{Spacing}.


@@ -1516,11 +1512,13 @@ 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
 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}.
+@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,
 
 Page breaks are computed by the @code{page-breaking} function.  LilyPond
 provides three algorithms for computing page breaks,


@@ -1577,7 +1575,7 @@ book parts.
 
 @seealso
 Notation Reference:
 
 @seealso
 Notation Reference:

-@ref{\paper variables for page breaking}.
+@ref{paper variables for page breaking,,@code{@bs{}paper} variables for page breaking}.

 
 Snippets:
 @rlsr{Spacing}.
 
 Snippets:
 @rlsr{Spacing}.


@@ -1674,7 +1672,7 @@ top-level markups.
 
 @seealso
 Notation Reference:
 
 @seealso
 Notation Reference:

-@ref{\paper variables for line breaking}.
+@ref{paper variables for line breaking,,@code{@bs{}paper} variables for line breaking}.

 
 Snippets:
 @rlsr{Spacing}.
 
 Snippets:
 @rlsr{Spacing}.


@@ -1928,7 +1926,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
 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::
 
 @menu
 * Within-system spacing properties::


@@ -1982,7 +1980,7 @@ given in the following table:
 @item @code{ChordNames}  @tab baseline
 @item @code{NoteNames}   @tab baseline
 @item @code{Lyrics}      @tab baseline
 @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
 @item @code{FiguredBass} @tab highest point
 @item @code{FretBoards}  @tab top line
 @end multitable


@@ -1996,87 +1994,70 @@ of these reference points:
 alignToZero = \with {
   \override VerticalAxisGroup.nonstaff-relatedstaff-spacing = #zero-space
   \override VerticalAxisGroup.nonstaff-nonstaff-spacing = #zero-space
 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
 }
 }
 lowerCaseChords = \with {
   chordNameLowercaseMinor = ##t
 }

-staffAffinityDown = \with {
-  \override VerticalAxisGroup.staff-affinity = #DOWN
-}

 labelContext =
 #(define-music-function
      (parser location context)
      (string?)
 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 }
 
 \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
   \context { \Score

-    \override BarLine.stencil = ##f
+    \omit BarLine

     \override DynamicText.self-alignment-X = #-1
     \override FretBoard.X-offset = #1.75
     \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
 <<
   }
 }
 
 %% 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
 <<
 >>
 
 %% 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"
 <<
 >>
 
 %% 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
 >>
 @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
 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 +2199,7 @@ spacing settings for that staff.
 
 @seealso
 Notation Reference:
 
 @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:
 @ref{Modifying alists}.
 
 Installed Files:


@@ -2722,16 +2703,17 @@ r2.
 c4_"Text"\pp % now they will collide
 @end lilypond
 
 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}.
+The vertical padding around outside-staff objects
+can be controlled with @code{outside-staff-padding}.

 
 @lilypond[quote,ragged-right,relative=2,verbatim,staffsize=18]
 \once \override TextScript.outside-staff-padding = #0
 
 @lilypond[quote,ragged-right,relative=2,verbatim,staffsize=18]
 \once \override TextScript.outside-staff-padding = #0

-a'^"This text is placed very close to the note"
+a4-"outside-staff-padding = #0"

 \once \override TextScript.outside-staff-padding = #3
 \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"
+d-"outside-staff-padding = #3"
+c-"default outside-staff-padding"
+b-"default outside-staff-padding"
+R1

 @end lilypond
 
 
 @end lilypond
 
 


@@ -2779,8 +2761,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
 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).
 
 For example, the following piece contains lots of half, quarter, and
 8th notes; the eighth note is followed by 1 note head width (NHW).


@@ -3011,7 +2992,7 @@ regard for clefs, bar lines, and grace notes,
 
 @lilypond[quote,ragged-right,relative=2,verbatim]
 \override Score.SpacingSpanner.strict-note-spacing = ##t
 
 @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
 @end lilypond
 
 @seealso


@@ -3100,11 +3081,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.
 
 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 {
 @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 }

     }
   >>
 }
     }
   >>
 }


@@ -3129,7 +3113,7 @@ setting.
 \score {
   <<
     \new RhythmicStaff {
 \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 {
     }
   >>
  \layout {


@@ -3173,7 +3157,7 @@ larger reference durations space music tightly.
 \score {
   <<
     \new RhythmicStaff {
 \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 {
     }
   >>
   \layout {


@@ -3187,7 +3171,7 @@ larger reference durations space music tightly.
 \score {
   <<
     \new RhythmicStaff {
 \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 {
     }
   >>
   \layout {


@@ -3201,7 +3185,7 @@ larger reference durations space music tightly.
 \score {
   <<
     \new RhythmicStaff {
 \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 {
     }
   >>
   \layout {


@@ -3229,10 +3213,10 @@ tuplet.
 \score {
   <<
     \new RhythmicStaff {
 \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 {
     }
     \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 }

     }
   >>
 }
     }
   >>
 }


@@ -3247,10 +3231,10 @@ result.  Setting @code{proportionalNotationDuration} fixes this.
 \score {
   <<
     \new RhythmicStaff {
 \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 {
     }
     \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 {
     }
   >>
   \layout {


@@ -3272,10 +3256,10 @@ turn on @code{uniform-stretching}, which is a property of
 \score {
   <<
     \new RhythmicStaff {
 \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 {
     }
     \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 {
     }
   >>
   \layout {


@@ -3371,13 +3355,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)
 @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
 }
 
 \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
 
 }
 @end lilypond