Doc-fr: consistency in seealsos

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

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index 53ef68ad37a6a3caf0d68d7a1476ef5bdc7935b4..89810f6dad17b130f1566f91d5aa28a88b2169f1 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.13.39"
+@c \version "2.13.42"

 
 @ignore
 GDP TODO list
 
 @ignore
 GDP TODO list


@@ -174,7 +174,9 @@ The Scheme equivalent of the above example is:
 
 @seealso
 Notation Reference:
 
 @seealso
 Notation Reference:

-@ref{Custom headers footers and titles}.
+@ref{Paper size and automatic scaling},
+@ref{Custom headers footers and titles},
+@ref{The \layout block}.

 
 Installed Files:
 @file{ly/paper-defaults-init.ly}.
 
 Installed Files:
 @file{ly/paper-defaults-init.ly}.


@@ -255,6 +257,9 @@ degrees, and wider line widths will be set accordingly.
 @end example
 
 @seealso
 @end example
 
 @seealso

+Notation Reference:
+@ref{Automatic scaling to paper size}.
+

 Installed Files:
 @file{scm/paper.scm}.
 
 Installed Files:
 @file{scm/paper.scm}.
 


@@ -350,6 +355,9 @@ parts of a book created with @code{\bookpart} blocks.
 @end table
 
 @seealso
 @end table
 
 @seealso

+Notation Reference:
+@ref{Automatic scaling to paper size}.
+

 Installed Files:
 @file{ly/paper-defaults-init.ly}.
 
 Installed Files:
 @file{ly/paper-defaults-init.ly}.
 


@@ -395,24 +403,17 @@ an alist (association list) containing four @emph{keys}:
 @itemize
 
 @item
 @itemize
 
 @item

-@code{padding} -- the minimum required amount of unobstructed
-vertical whitespace between two items, measured in staff-spaces.
-This can be thought of as the minimum height of an unobstructed
-(invisible) rectangle that extends from the leftmost to the
-rightmost point of the combined items.
-
-@item
-@code{space} -- the vertical distance, measured in staff-spaces,
-between the @emph{reference points} of the two items, when no
-collisions would result, and no stretching or compressing is in
-effect.  The reference point of a (title or top-level) markup is
-its highest point, and the reference point of a system is the
-vertical center of the nearest @code{StaffSymbol} -- even if a
-non-staff line (such as a @code{Lyrics} context) is in the way.
-Values for @code{space} that are less than either @code{padding}
-or @code{minimum-distance} are not meaningful, since the resulting
-distance will never be less than either @code{padding} or
-@code{minimum-distance}.
+@code{basic-distance} -- the vertical distance, measured in
+staff-spaces, between the @emph{reference points} of the two
+items, when no collisions would result, and no stretching or
+compressing is in effect.  The reference point of a (title or
+top-level) markup is its highest point, and the reference point of
+a system is the vertical center of the nearest @code{StaffSymbol}
+-- even if a non-staff line (such as a @code{Lyrics} context) is
+in the way.  Values for @code{basic-distance} that are less than
+either @code{padding} or @code{minimum-distance} are not
+meaningful, since the resulting distance will never be less than
+either @code{padding} or @code{minimum-distance}.

 
 @item
 @code{minimum-distance} -- the smallest allowable vertical
 
 @item
 @code{minimum-distance} -- the smallest allowable vertical


@@ -422,6 +423,13 @@ of the two items, when compressing is in effect.  Values for
 meaningful, since the resulting distance will never be less than
 @code{padding.}
 
 meaningful, since the resulting distance will never be less than
 @code{padding.}
 

+@c TODO: explain skylines somewhere and xref to it from here.
+
+@item
+@code{padding} -- the minimum required amount of unobstructed
+vertical whitespace between the bounding boxes (or skylines) of
+the two items, measured in staff-spaces.
+

 @item
 @code{stretchability} -- a unitless measure of the dimension's
 relative propensity to stretch.  If zero, the distance will not
 @item
 @code{stretchability} -- a unitless measure of the dimension's
 relative propensity to stretch.  If zero, the distance will not


@@ -433,10 +441,10 @@ twice the @code{stretchability} of another, it will stretch twice
 as easily.  Values should be non-negative and finite.  The value
 @code{+inf.0} triggers a @code{programming_error} and is ignored,
 but @code{1.0e7} can be used for an almost infinitely stretchable
 as easily.  Values should be non-negative and finite.  The value
 @code{+inf.0} triggers a @code{programming_error} and is ignored,
 but @code{1.0e7} can be used for an almost infinitely stretchable

-spring.  If unset, the default value is set to @code{space}.  Note
-that the dimension's propensity to @emph{compress} cannot be
-directly set by the user and is equal to
-(@code{space}@tie{}@minus{}@tie{}@code{minimum-distance}).
+spring.  If unset, the default value is set to
+@code{basic-distance}.  Note that the dimension's propensity to
+@emph{compress} cannot be directly set by the user and is equal to
+(@code{basic-distance}@tie{}@minus{}@tie{}@code{minimum-distance}).

 
 @end itemize
 
 
 @end itemize
 


@@ -446,7 +454,7 @@ largest of:
 @itemize
 
 @item
 @itemize
 
 @item

-@code{space},
+@code{basic-distance},

 
 @item
 @code{minimum-distance}, and
 
 @item
 @code{minimum-distance}, and


@@ -465,11 +473,11 @@ redefines the variable:
 
 @example
 \paper @{
 
 @example
 \paper @{

-  system-system-spacing #'space = #8
+  system-system-spacing #'basic-distance = #8

   score-system-spacing =
   score-system-spacing =

-    #'((padding . 1)
-       (space . 12)
+    #'((basic-distance . 12)

        (minimum-distance . 6)
        (minimum-distance . 6)

+       (padding . 1)

        (stretchability . 12))
 @}
 @end example
        (stretchability . 12))
 @}
 @end example


@@ -658,6 +666,9 @@ set in a @code{\layout} block.
 @end table
 
 @seealso
 @end table
 
 @seealso

+Notation Reference:
+@ref{Automatic scaling to paper size}.
+

 Installed Files:
 @file{ly/paper-defaults-init.ly}.
 
 Installed Files:
 @file{ly/paper-defaults-init.ly}.
 


@@ -708,6 +719,9 @@ with @code{two-sided} set to true.
 @end table
 
 @seealso
 @end table
 
 @seealso

+Notation Reference:
+@ref{Automatic scaling to paper size}.
+

 Installed Files:
 @file{ly/paper-defaults-init.ly}.
 
 Installed Files:
 @file{ly/paper-defaults-init.ly}.
 


@@ -747,6 +761,9 @@ set in a @code{\layout} block.
 @end table
 
 @seealso
 @end table
 
 @seealso

+Notation Reference:
+@ref{Automatic scaling to paper size}.
+

 Installed Files:
 @file{ly/paper-defaults-init.ly}.
 
 Installed Files:
 @file{ly/paper-defaults-init.ly}.
 


@@ -1031,7 +1048,7 @@ Here is an example @code{\layout} block:
   indent = 2\cm
   \context @{
     \StaffGroup
   indent = 2\cm
   \context @{
     \StaffGroup

-    \override StaffGrouper #'staff-staff-spacing #space = #8
+    \override StaffGrouper #'staff-staff-spacing #'basic-distance = #8

   @}
   \context @{
     \Voice
   @}
   \context @{
     \Voice


@@ -1180,18 +1197,58 @@ staff lines.
 
 Line breaks are normally determined automatically.  They are chosen
 so that lines look neither cramped nor loose, and consecutive
 
 Line breaks are normally determined automatically.  They are chosen
 so that lines look neither cramped nor loose, and consecutive

-lines have similar density.  Occasionally you might want to
-override the automatic breaks; you can do this by specifying
-@code{\break}.  This will force a line break at this point.  However,
-line breaks can only occur at the end of @q{complete} bars, i.e.,
-where there are no notes or tuplets left @q{hanging} over the bar
-line.  If you want to have a line break where there is no bar line,
-you can force an invisible bar line by entering @code{\bar ""},
-although again there must be no notes left hanging over in any of
-the staves at this point, or it will be ignored.
-
-The opposite command, @code{\noBreak}, forbids a line break at the
-bar line where it is inserted.
+lines have similar density.
+
+To manually force a line break at a bar line, use the
+@code{\break} command:
+
+@lilypond[quote,ragged-right,relative=2,verbatim]
+c4 c c c | \break
+c4 c c c |
+@end lilypond
+
+By default, a @code{\break} in the middle of a measure is ignored,
+and a warning is printed.  To force a line break in the middle of
+a measure, add an invisible bar line with @w{@samp{\bar ""}}:
+
+@lilypond[quote,ragged-right,relative=2,verbatim]
+c4 c c
+\bar "" \break
+c |
+c4 c c c |
+@end lilypond
+
+A @code{\break} occuring at a bar line is also ignored if the
+previous measure ends in the middle of a note, such as when a
+tuplet begins and ends in different measures.  To allow
+@code{\break} commands to work in these situations, remove the
+@code{Forbid_line_break_engraver} from the @code{Voice} context.
+Note that manually forced line breaks have to be added in parallel
+with the music:
+
+@lilypond[quote,ragged-right,verbatim]
+\new Voice \with {
+  \remove Forbid_line_break_engraver
+} \relative c'' {
+  <<
+    { c2. \times 2/3 { c4 c c } c2. | }
+    { s1 | \break s1 | }
+  >>
+}
+@end lilypond
+
+Similarly, line breaks are normally forbidden when beams cross bar
+lines.  This behavior can be changed by setting
+@code{\override Beam #'breakable = ##t}:
+
+@lilypond[quote,ragged-right,relative=2,verbatim]
+\override Beam #'breakable = ##t
+c2. c8[ c | \break
+c8 c] c2. |
+@end lilypond
+
+The @code{\noBreak} command forbids a line break at the bar line
+where it is inserted.

 
 The most basic settings influencing line spacing are @code{indent}
 and @code{line-width}.  They are set in the @code{\layout} block.
 
 The most basic settings influencing line spacing are @code{indent}
 and @code{line-width}.  They are set in the @code{\layout} block.


@@ -1254,6 +1311,9 @@ complicated.  More details are available in
 
 
 @seealso
 
 
 @seealso

+Notation Reference:
+@ref{\paper variables for line breaking}.
+

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


@@ -1261,36 +1321,6 @@ Internals Reference:
 @rinternals{LineBreakEvent}.
 
 
 @rinternals{LineBreakEvent}.
 
 

-@knownissues
-
-Line breaks can only occur if there is a @q{proper} bar line.  A note
-which is hanging over a bar line is not proper, such as
-
-@lilypond[quote,ragged-right,relative=2,verbatim]
-c4 c2 << c2 {s4 \break } >>  % this does nothing
-c2 c4 |           % a break here would work
-c4 c2 c4 ~ \break % as does this break
-c4 c2 c4
-@end lilypond
-
-This can be avoided by removing the @code{Forbid_line_break_engraver}.
-Note that manually forced line breaks have to be added in parallel
-with the music.
-
-@lilypond[quote,ragged-right,verbatim]
-\new Voice \with {
-  \remove Forbid_line_break_engraver
-} {
-  c4 c2 << c2 {s4 \break } >>  % now the break is allowed
-  c2 c4
-}
-@end lilypond
-
-Similarly, line breaks are normally forbidden when beams cross bar
-lines.  This behavior can be changed by setting
-@code{\override Beam #'breakable = ##t}.
-
-

 @node Page breaking
 @subsection Page breaking
 
 @node Page breaking
 @subsection Page breaking
 


@@ -1366,6 +1396,9 @@ book parts.
 
 
 @seealso
 
 
 @seealso

+Notation Reference:
+@ref{\paper variables for page breaking}.
+

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


@@ -1745,7 +1778,7 @@ In the following image, horizontal lines indicate the positions
 of these reference points:
 
 @lilypond[quote,noragged-right,line-width=110\mm]
 of these reference points:
 
 @lilypond[quote,noragged-right,line-width=110\mm]

-#(define zero-space '((padding . -inf.0) (space . 0)))
+#(define zero-space '((padding . -inf.0) (basic-distance . 0)))

 
 alignToZero = \with {
   \override VerticalAxisGroup #'nonstaff-relatedstaff-spacing = #zero-space
 
 alignToZero = \with {
   \override VerticalAxisGroup #'nonstaff-relatedstaff-spacing = #zero-space


@@ -1841,14 +1874,14 @@ individually, and the second completely re-defines the property:
 
 @example
 \new Staff \with @{
 
 @example
 \new Staff \with @{

-  \override VerticalAxisGroup #'staff-staff-spacing #'space = #10
+  \override VerticalAxisGroup #'staff-staff-spacing #'basic-distance = #10

 @} @{ @dots{} @}
 
 \new Staff \with @{
   \override VerticalAxisGroup #'staff-staff-spacing =
 @} @{ @dots{} @}
 
 \new Staff \with @{
   \override VerticalAxisGroup #'staff-staff-spacing =

-    #'((padding . 1)
-       (space . 10)
+    #'((basic-distance . 10)

        (minimum-distance . 9)
        (minimum-distance . 9)

+       (padding . 1)

        (stretchability . 10))
 @} @{ @dots{} @}
 @end example
        (stretchability . 10))
 @} @{ @dots{} @}
 @end example


@@ -1860,7 +1893,7 @@ To change any spacing settings globally, put them in the
 \layout @{
   \context @{
     \Staff
 \layout @{
   \context @{
     \Staff

-    \override VerticalAxisGroup #'staff-staff-spacing #'space = #10
+    \override VerticalAxisGroup #'staff-staff-spacing #'basic-distance = #10

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


@@ -2002,30 +2035,30 @@ property can affect the spacing of ungrouped staves:
   \context {
     \Staff
     \override VerticalAxisGroup #'staff-staff-spacing =
   \context {
     \Staff
     \override VerticalAxisGroup #'staff-staff-spacing =

-      #'((padding . 1)
-         (space . 8)
-         (minimum-distance . 7))
+      #'((basic-distance . 8)
+         (minimum-distance . 7)
+         (padding . 1))

   }
 }
 
 \new StaffGroup <<
   }
 }
 
 \new StaffGroup <<

-  % The very low note here needs more room than 'space can
-  % provide, so the distance between this staff and the next is
-  % determined by 'padding.
+  % The very low note here needs more room than 'basic-distance
+  % can provide, so the distance between this staff and the next
+  % is determined by 'padding.

   \new Staff { b,2 r | }
 
   \new Staff { b,2 r | }
 

-  % Here, 'space provides enough room, and there is no need to
-  % compress the space (towards 'minimum-distance) to make room
-  % for anything else on the page, so the distance between this
-  % staff and the next is determined by 'space.
+  % Here, 'basic-distance provides enough room, and there is no
+  % need to compress the space (towards 'minimum-distance) to make
+  % room for anything else on the page, so the distance between
+  % this staff and the next is determined by 'basic-distance.

   \new Staff { \clef bass g2 r | }
 
   % By setting 'padding to a negative value, staves can be made to
   \new Staff { \clef bass g2 r | }
 
   % By setting 'padding to a negative value, staves can be made to

-  % collide.  The lowest acceptable value for 'space is 0.
+  % collide.  The lowest acceptable value for 'basic-distance is 0.

   \new Staff \with {
     \override VerticalAxisGroup #'staff-staff-spacing =
   \new Staff \with {
     \override VerticalAxisGroup #'staff-staff-spacing =

-      #'((padding . -10)
-         (space . 3.5))
+      #'((basic-distance . 3.5)
+         (padding . -10))

   } { \clef bass g2 r | }
   \new Staff { \clef bass g2 r | }
 >>
   } { \clef bass g2 r | }
   \new Staff { \clef bass g2 r | }
 >>


@@ -2080,13 +2113,13 @@ The following example shows how properties of the
   \context {
     \Score
     \override StaffGrouper #'staff-staff-spacing #'padding = #0
   \context {
     \Score
     \override StaffGrouper #'staff-staff-spacing #'padding = #0

-    \override StaffGrouper #'staff-staff-spacing #'space = #1
+    \override StaffGrouper #'staff-staff-spacing #'basic-distance = #1

   }
 }
 
 <<
   \new PianoStaff \with {
   }
 }
 
 <<
   \new PianoStaff \with {

-    \override StaffGrouper #'staffgroup-staff-spacing #'space = #20
+    \override StaffGrouper #'staffgroup-staff-spacing #'basic-distance = #20

   } <<
     \new Staff { c'1 }
     \new Staff { c'1 }
   } <<
     \new Staff { c'1 }
     \new Staff { c'1 }


@@ -2153,7 +2186,7 @@ able to stretch much more than usual:
 \new StaffGroup
 <<
   \new Staff \with {
 \new StaffGroup
 <<
   \new Staff \with {

-    \override VerticalAxisGroup #'staff-staff-spacing = #'((space . 30))
+    \override VerticalAxisGroup #'staff-staff-spacing = #'((basic-distance . 30))

   } { c'1 }
   \new Lyrics \with {
     \override VerticalAxisGroup #'staff-affinity = #UP
   } { c'1 }
   \new Lyrics \with {
     \override VerticalAxisGroup #'staff-affinity = #UP


@@ -3287,7 +3320,7 @@ there is no blank space at the bottom of the page.
 
 @example
 \paper @{
 
 @example
 \paper @{

-  system-system-spacing = #'((padding . 0) (space . 0.1))
+  system-system-spacing = #'((basic-distance . 0.1) (padding . 0))

   ragged-last-bottom = ##f
   ragged-bottom = ##f
 @}
   ragged-last-bottom = ##f
   ragged-bottom = ##f
 @}