]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/notation/spacing.itely
Issue 3926: Add \magnifyMusic; clarify fontSize in docs.
[lilypond.git] / Documentation / notation / spacing.itely
index 91eeefa4e82687acb6fb7b6f40a57b5c6c6e61e6..3ee12b679876fdc986ccaabbbb78690b2d7cd06a 100644 (file)
@@ -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,109 @@ 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, 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:
 
-@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:
@@ -1493,7 +1489,7 @@ every 4 measures, and only there:
 
 @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}.
@@ -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
-@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,
@@ -1577,7 +1575,7 @@ book parts.
 
 @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}.
@@ -1674,7 +1672,7 @@ top-level markups.
 
 @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}.
@@ -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
-@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 +1980,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 +1994,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 +2199,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:
@@ -2722,16 +2703,17 @@ r2.
 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
-a'^"This text is placed very close to the note"
+a4-"outside-staff-padding = #0"
 \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
 
 
@@ -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
-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).
@@ -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
-\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
@@ -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.
 
+@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 }
     }
   >>
 }
@@ -3129,7 +3113,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 {
@@ -3173,7 +3157,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 {
@@ -3187,7 +3171,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 {
@@ -3201,7 +3185,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 {
@@ -3229,10 +3213,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 }
     }
   >>
 }
@@ -3247,10 +3231,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 {
@@ -3272,10 +3256,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 {
@@ -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)
-  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