Doc: NR 4: Add cross-references.

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

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index af03cc74a357e97966776ca9c20dea22e89bb16e..53ef68ad37a6a3caf0d68d7a1476ef5bdc7935b4 100644 (file)
--- a/Documentation/notation/spacing.itely
+++ b/Documentation/notation/spacing.itely
@@ -275,10 +275,12 @@ from scaling and is discussed below).  The
 are described in @ref{Setting paper size}.
 
 The vertical dimensions affected by automatic scaling are
-@code{top-margin} and @code{bottom-margin}.  The horizontal
+@code{top-margin} and @code{bottom-margin} (see
+@ref{Fixed vertical spacing \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}.
+@code{binding-offset}, @code{indent}, and @code{short-indent} (see
+@ref{Horizontal spacing \paper variables}.
 
 The default values for these dimensions are set in
 @file{ly/paper-defaults-init.ly}, using internal variables named
@@ -289,6 +291,10 @@ These are the values that result at the default paper size
 @code{210\mm}.
 
 @seealso
+Notation Reference:
+@ref{Fixed vertical spacing \paper variables},
+@ref{Horizontal spacing \paper variables}.
+
 Installed Files:
 @file{ly/paper-defaults-init.ly},
 @file{scm/paper.scm}.
@@ -1003,26 +1009,33 @@ discussed in a separate chapter; see
 variables that can appear in a @code{\layout} block are:
 
 @itemize
-@item @code{line-width}
-@item @code{ragged-right}
-@item @code{ragged-last}
-@item @code{indent}
-@item @code{short-indent}
-@item @code{system-count}
+
+@item
+@code{line-width}, @code{ragged-right} and @code{ragged-last}
+(see @ref{\paper variables for widths and margins})
+
+@item
+@code{indent} and @code{short-indent}
+(see @ref{\paper variables for shifts and indents})
+
+@item
+@code{system-count}
+(see @ref{\paper variables for line breaking})
+
 @end itemize
 
 Here is an example @code{\layout} block:
 
 @example
 \layout @{
-  indent = 2.0\cm
+  indent = 2\cm
   \context @{
     \StaffGroup
     \override StaffGrouper #'staff-staff-spacing #space = #8
   @}
   \context @{
     \Voice
-    \override TextScript #'padding = #1.0
+    \override TextScript #'padding = #1
     \override Glissando #'thickness = #3
   @}
 @}
@@ -1061,9 +1074,9 @@ fonts accordingly.
 To set the staff size individually for each score, use
 @example
 \score@{
-  ...
-  \layout@{
-  #(layout-set-staff-size 15)
+  @dots{}
+  \layout @{
+    #(layout-set-staff-size 15)
   @}
 @}
 @end example
@@ -1198,9 +1211,9 @@ but affects only the last line of the piece.
 
 @example
 \layout @{
-indent = #0
-line-width = #150
-ragged-last = ##t
+  indent = 0\mm
+  line-width = 150\mm
+  ragged-last = ##t
 @}
 @end example
 
@@ -1215,10 +1228,12 @@ cause the following 28 measures (assuming 4/4 time) to be broken
 every 4 measures, and only there:
 
 @example
-<< \repeat unfold 7 @{
-         s1 \noBreak s1 \noBreak
-         s1 \noBreak s1 \break @}
-   @emph{the real music}
+<<
+  \repeat unfold 7 @{
+    s1 \noBreak s1 \noBreak
+    s1 \noBreak s1 \break
+  @}
+  @{ @var{the actual music@dots{}} @}
 >>
 @end example
 
@@ -1293,9 +1308,8 @@ 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.
-
-For more details see @ref{Vertical spacing}.
+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,
@@ -1304,8 +1318,8 @@ provides three algorithms for computing page breaks,
 but the value can be changed in the @code{\paper} block:
 
 @example
-\paper@{
-  #(define page-breaking ly:page-turn-breaking)
+\paper @{
+  page-breaking = #ly:page-turn-breaking
 @}
 @end example
 
@@ -1326,7 +1340,7 @@ book parts.
   \paper @{
      %% In a part consisting mostly of text,
      %% ly:minimal-breaking may be preferred
-     #(define page-breaking ly:minimal-breaking)
+     page-breaking = #ly:minimal-breaking
   @}
   \markup @{ @dots{} @}
   @dots{}
@@ -1472,7 +1486,7 @@ too slow or memory demanding, or a lot of texts.  It is enabled using:
 
 @example
 \paper @{
-  #(define page-breaking ly:minimal-breaking)
+  page-breaking = #ly:minimal-breaking
 @}
 @end example
 
@@ -1505,17 +1519,19 @@ page breaks at explicit @code{\pageBreak} commands and nowhere else.
   ragged-bottom = ##t
 }
 
+music = \relative c'' { c8 c c c }
+
 \score {
   \new Staff {
-    \repeat unfold 2 { c'8 c'8 c'8 c'8 } \break
-    \repeat unfold 4 { c'8 c'8 c'8 c'8 } \break
-    \repeat unfold 6 { c'8 c'8 c'8 c'8 } \break
-    \repeat unfold 8 { c'8 c'8 c'8 c'8 } \pageBreak
-    \repeat unfold 8 { c'8 c'8 c'8 c'8 } \break
-    \repeat unfold 6 { c'8 c'8 c'8 c'8 } \break
-    \repeat unfold 4 { c'8 c'8 c'8 c'8 } \break
-    \repeat unfold 2 { c'8 c'8 c'8 c'8 }
-    }
+    \repeat unfold 2 { \music } \break
+    \repeat unfold 4 { \music } \break
+    \repeat unfold 6 { \music } \break
+    \repeat unfold 8 { \music } \pageBreak
+    \repeat unfold 8 { \music } \break
+    \repeat unfold 6 { \music } \break
+    \repeat unfold 4 { \music } \break
+    \repeat unfold 2 { \music }
+  }
   \layout {
     \context {
       \Score
@@ -1538,11 +1554,12 @@ Snippets:
 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 @{ c'4 c'4 c'4 c'4 @}
-    \break
-    \repeat unfold 3 @{ c'4 c'4 c'4 c'4 @}
+    \repeat unfold 2 @{ \music @} \break
+    \repeat unfold 3 @{ \music @}
   @}
 @}
 @end example
@@ -1556,6 +1573,8 @@ contains only skips together with @code{\break}, @code{pageBreak} and other
 breaking layout information.
 
 @lilypond[quote,verbatim]
+music = \relative c'' { c4 c c c }
+
 \score {
   \new Staff <<
     \new Voice {
@@ -1565,10 +1584,10 @@ breaking layout information.
       s1 * 5 \break
     }
     \new Voice {
-      \repeat unfold 2 { c'4 c'4 c'4 c'4 }
-      \repeat unfold 3 { c'4 c'4 c'4 c'4 }
-      \repeat unfold 6 { c'4 c'4 c'4 c'4 }
-      \repeat unfold 5 { c'4 c'4 c'4 c'4 }
+      \repeat unfold 2 { \music }
+      \repeat unfold 3 { \music }
+      \repeat unfold 6 { \music }
+      \repeat unfold 5 { \music }
     }
   >>
 }
@@ -1579,6 +1598,8 @@ This pattern becomes especially helpful when overriding
 @code{NonMusicalPaperColumnGrob}, as explained in @ref{Vertical spacing}.
 
 @lilypond[quote,verbatim]
+music = \relative c'' { c4 c c c }
+
 \score {
   \new Staff <<
     \new Voice {
@@ -1599,10 +1620,10 @@ This pattern becomes especially helpful when overriding
       s1 * 5 \break
     }
     \new Voice {
-      \repeat unfold 2 { c'4 c'4 c'4 c'4 }
-      \repeat unfold 3 { c'4 c'4 c'4 c'4 }
-      \repeat unfold 6 { c'4 c'4 c'4 c'4 }
-      \repeat unfold 5 { c'4 c'4 c'4 c'4 }
+      \repeat unfold 2 { \music }
+      \repeat unfold 3 { \music }
+      \repeat unfold 6 { \music }
+      \repeat unfold 5 { \music }
     }
   >>
 }
@@ -2211,13 +2232,15 @@ example @code{NonMusicalPaperColumn} overrides with the special
   #'line-break-system-details #'((Y-offset . 40))
 
 \overrideProperty NonMusicalPaperColumn
-  #'line-break-system-details #'((X-offset . 20) (Y-offset . 40))
+  #'line-break-system-details #'((X-offset . 20)
+                                 (Y-offset . 40))
 
 \overrideProperty NonMusicalPaperColumn
   #'line-break-system-details #'((alignment-distances . (15)))
 
 \overrideProperty NonMusicalPaperColumn
-  #'line-break-system-details #'((X-offset . 20) (Y-offset . 40)
+  #'line-break-system-details #'((X-offset . 20)
+                                 (Y-offset . 40)
                                  (alignment-distances . (15)))
 @end example
 
@@ -2227,7 +2250,7 @@ by looking at an example that includes no overrides at all.
 @c \book { } is required in these examples to ensure the spacing
 @c overrides can be seen between systems. -np
 
-@lilypond[quote]
+@lilypond[verbatim,quote,staffsize=16]
 \header { tagline = ##f }
 \paper { left-margin = 0\mm }
 \book {
@@ -2260,7 +2283,7 @@ the vertical startpoint of each system explicitly, we can set
 the @code{Y-offset} pair in the @code{line-break-system-details}
 attribute of the @code{NonMusicalPaperColumn} grob:
 
-@lilypond[quote]
+@lilypond[verbatim,quote,staffsize=16]
 \header { tagline = ##f }
 \paper { left-margin = 0\mm }
 \book {
@@ -2298,7 +2321,7 @@ explicitly, we can also set the vertical distances between staves
 within each system manually.  We do this using the @code{alignment-distances}
 subproperty of @code{line-break-system-details}.
 
-@lilypond[quote]
+@lilypond[verbatim,quote,staffsize=16]
 \header { tagline = ##f }
 \paper { left-margin = 0\mm }
 \book {
@@ -2339,7 +2362,7 @@ additional spacing parameters (including, for example, a corresponding
 every system and every staff.  Finally, note that @code{alignment-distances}
 specifies the vertical positioning of staves but not of staff groups.
 
-@lilypond[quote]
+@lilypond[verbatim,quote,staffsize=16]
 \header { tagline = ##f }
 \paper { left-margin = 0\mm }
 \book {