X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fspacing.itely;h=f00b437bb29f076dbd53904337fcdbcf6854ba65;hb=811cdc2809ee224dfbe79576c4ac6e1fe9057db5;hp=7e9b1d66aa232acf386d92db569d1da1e7ae51d4;hpb=81f5263fa1b6adf642b06970cd34e10d4635495d;p=lilypond.git

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index 7e9b1d66aa..f00b437bb2 100644
--- a/Documentation/notation/spacing.itely
+++ b/Documentation/notation/spacing.itely
@@ -175,6 +175,11 @@ Snippets:
 Margins, headers, and footers and other layout variables are
 automatically set according to the paper size.
 
+Default margin values are accessible in
+@file{ly/@/paper@/-defaults@/-init@/.ly}.  They apply to the default
+paper size (a4, unless specified differently) and are scaled
+accordingly for other paper sizes.
+
 This section lists and describes a number of paper variables that
 may be altered.
 
@@ -328,7 +333,7 @@ example
 Example:
 
 @example
-\paper@{
+\paper @{
   paper-width = 2\cm
   top-margin = 3\cm
   bottom-margin = 3\cm
@@ -355,7 +360,7 @@ This second example centers page numbers at the bottom of every page.
 
 You can also define these values in Scheme.  In that case @code{mm},
 @code{in}, @code{pt}, and @code{cm} are variables defined in
-@file{paper@/-defaults@/.ly} with values in millimeters.  That is why the
+@file{paper@/-defaults@/-init@/.ly} with values in millimeters.  That is why the
 value must be multiplied in the example
 
 @example
@@ -366,7 +371,7 @@ value must be multiplied in the example
 
 The header and footer are created by the functions @code{make-footer}
 and @code{make-header}, defined in @code{\paper}.  The default
-implementations are in @file{ly/@/paper@/-defaults@/.ly} and
+implementations are in @file{ly/@/paper@/-defaults@/-init@/.ly} and
 @file{ly/@/titling@/-init@/.ly}.
 
 The page layout itself is done by two functions in the
@@ -387,15 +392,20 @@ Snippets:
 @node Horizontal dimensions
 @unnumberedsubsubsec Horizontal dimensions
 
-@warning{If @code{paper-width} is manually set, @code{line-width},
-@code{left-margin}, @code{indent}, and @code{short-indent} may
-have to be adjusted as well.}
 
 There are a few variables that determine the horizontal dimensions
 on a page:
 
 @table @code
 
+@item binding-offset
+@funindex binding-offset
+
+The amount @code{inner-margin} is increased
+to make sure nothing will be hidden by the binding.
+Works only with @code{two-sided} set to true.  Default:
+@code{0}.
+
 @item horizontal-shift
 @funindex horizontal-shift
 
@@ -406,22 +416,33 @@ separators) are shifted to the right.  Default: @code{0.0}.
 @funindex indent
 
 The level of indentation for the first system in a score.
-Default: @code{paper-width} divided by @code{14}, as determined by
-@code{set-default-paper-size} or @code{set-paper-size}.
+Default: @code{15\mm}.
+
+@item inner-margin
+@funindex inner-margin
+
+The margin all pages have at the inner side if they are part
+of a book.  Works only with @code{two-sided} set to true.
+Default: @code{10\mm}.
 
 @item left-margin
 @funindex left-margin
 
 The margin between the left edge of the page and the beginning of
-each system.  Default: @code{10\mm}, as determined by
-@code{set-default-paper-size} or @code{set-paper-size}.
+each system.  Default: @code{10\mm}.
 
 @item line-width
 @funindex line-width
 
 The width of music systems.  Default: @code{paper-width} minus
-@code{20\mm}, as determined by @code{set-default-paper-size} or
-@code{set-paper-size}.
+@code{left-margin} and @code{right-margin}.
+
+@item outer-margin
+@funindex outer-margin
+
+The margin all pages have at the outer side if they are part
+of a book.  Works only with @code{two-sided} set to true.
+Default: @code{20\mm}.
 
 @item paper-width
 @funindex paper-width
@@ -429,28 +450,96 @@ The width of music systems.  Default: @code{paper-width} minus
 The width of the page.  Default: the width of the current paper
 size.  For details, see @ref{Paper size}.
 
+@item right-margin
+@funindex right-margin
+
+The margin between the right edge of the page and the end of
+each system.  Default: @code{10\mm}.
+
 @item short-indent
 @funindex short-indent
 
 The level of indentation for all systems in a score besides the
-first system.  Default: @code{0}, as determined by
-@code{set-default-paper-size} or @code{set-paper-size}.
+first system.  Default: @code{0}.
 
 @end table
 
+If some values are not set, defaults will be taken. Their exact
+value is adjusted, depending on the paper size specified.  Currently,
+the following values are affected by this scaling:
+
+@itemize
+@item @var{left-margin}
+@item @var{right-margin}
+@item @var{top-margin}
+@item @var{bottom-margin}
+@item @var{head-separation}
+@item @var{foot-separation}
+@item @var{indent}
+@item @var{short-indent}
+@end itemize
+
+The settings for @code{line-width}, @code{left-margin},
+@code{right-margin} and @code{paper-width} depend on
+each other, but they do not have to be specified
+completely.
+
+@example
+\paper @{
+  left-margin = 30\mm
+@}
+@end example
+
+In this example, only @code{left-margin} is set.  The value for
+@code{right-margin} will remain default, @code{line-width} is
+calculated automatically.
+
+@example
+\paper @{
+  line-width = 150\mm
+@}
+@end example
+
+Here @code{left-margin} and @code{right-margin} will be set
+to the same value.  Therefore, @code{line-width} is subtracted
+from @code{paper-width} and divided by two.  That means systems
+are centered on the page, if only @code{line-width} is
+specified.
+
+Some checks occur to ensure the values are set correctly.
+If the values do not match or systems would run off the page,
+a warning is printed and default values are set.
+
+@example
+\paper @{
+  paper-width = 210\mm
+  left-margin = 20\mm
+  right-margin = 30\mm
+  line-width = 100\mm
+@}
+@end example
+
+These checks can be avoided by setting @code{check-consistency}
+to false.
+
+@example
+\paper @{
+  paper-width = 210\mm
+  left-margin = 20\mm
+  line-width = 200\mm
+  check-consistency = ##f
+@}
+@end example
+
+@warning{If @code{paper-width} is manually set, @code{line-width},
+@code{left-margin}, @code{indent}, and @code{short-indent} may
+have to be adjusted as well.}
 
 @seealso
 Snippets:
 @rlsr{Spacing}.
 
 
-@knownissues
-
-The option @code{right-margin} is defined but doesn't set the
-right margin yet.  The value for the right margin has to be
-defined by adjusting the values of @code{left-margin} and
-@code{line-width}.
-
 
 @node Other layout variables
 @unnumberedsubsubsec Other layout variables
@@ -492,6 +581,13 @@ score.  This is not used by @code{ly:optimal-breaking} since it will
 never consider blank pages in the middle of a score.  Default:
 @code{5}.
 
+@item check-consistency
+@funindex check-consistency
+
+If set to true, check whether @code{left-margin}, @code{right-margin} and
+@code{line-width} fit each other. Also make sure that their combination
+does not exceed the available @code{paper-width}.  Default: @code{##t}.
+
 @item first-page-number
 @funindex first-page-number
 
@@ -634,6 +730,14 @@ The number of systems that should be placed on each page.
 This is currently supported only by the @code{ly:optimal-breaking} algorithm.
 Default: unset.
 
+@item two-sided
+@funindex two-sided
+
+If set to true, use @code{inner-margin}, @code{outer-margin} and
+@code{binding-offset} to determine margins depending on whether
+the page number is odd or even.  This overrides @code{left-margin}
+and @code{right-margin}.  Default: @code{##f}.
+
 @end table
 
 
@@ -1298,104 +1402,189 @@ staves inside a system.
 @cindex space between staves
 @cindex space inside systems
 
-The height of each system is determined automatically.  To prevent
-staves from bumping into each other, some minimum distances are set.
-By changing these, you can put staves closer together.  This
-reduces the amount of space each system requires, and may result
-in having more systems per page.
-
-Normally staves are stacked vertically.  To make staves maintain a
-distance, their vertical size is padded.  This is done with the
-property @code{minimum-Y-extent}.  When applied to a
-@rinternals{VerticalAxisGroup}, it controls the size of a horizontal
-line, such as a staff or a line of lyrics.  @code{minimum-Y-extent}
-takes a pair of numbers, so
-if you want to make it smaller than its default @code{#'(-4 . 4)}
-then you could set
+The height of each system is determined in two steps.  First, all of the
+staves are spaced according to the amount of space available.  Then, the
+non-staff lines (eg. lyrics or chords) are distributed between the
+staves.
 
-@example
-\override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
-@end example
+@unnumberedsubsubsec Spacing between staves
+Spacing between staves is controlled by the @var{next-staff-spacing}
+property of the @var{VerticalAxisGroup} grob.  This property is an alist
+with four elements: @var{space}, @var{minimum-distance}, @var{padding}
+and @var{stretchability}:
+@itemize
+@item
+@var{space} is the size of the stretchable space between the center line
+of one staff to the center line of the next staff.
 
-@noindent
-This sets the vertical size of the current staff to 3 staff spaces on
-either side of the center staff line.  The value @code{(-3 . 3)} is
-interpreted as an interval, where the center line is the 0, so the
-first number is generally negative.  The numbers need not match;
-for example, the staff can be made larger at the bottom by setting
-it to @code{(-6 . 4)}.
+@item
+@var{minimum-distance} provides a lower bound on the final distance
+between the center line of one staff to the center line of the next
+staff.  That is, if a page has many systems and needs to be compressed,
+the distance from this staff to the next will never be compressed to
+less than @var{minimum-distance}.
 
-@ignore
-FIXME: update this section
-
-After page breaks are determined, the vertical spacing within each
-system is reevaluated in order to fill the page more evenly; if a page
-has space left over, systems are stretched in order to fill that space.
-The amount of stretching can be configured though the @code{max-stretch}
-property of the @rinternals{VerticalAlignment} grob. By default,
-@code{max-stretch} is set to zero, disabling stretching. To enable
-stretching, a sane value for @code{max-stretch}
-is @code{ly:align-interface::calc-max-stretch}.
-
-In some situations, you may want to stretch most of a system while
-leaving some parts fixed.  For example, if a piano part occurs in the
-middle of an orchestral score, you may want to leave the piano staves
-close to each other while stretching the rest of the score.  The
-@code{keep-fixed-while-stretching} property of
-@rinternals{VerticalAxisGroup} can be used to achieve this.  When set
-to @code{##t}, this property keeps its staff (or line of lyrics) from
-moving relative to the one directly above it.  In the example above,
-you would override @code{keep-fixed-while-stretching} to @code{##t} in
-the second piano staff:
+@item
+@var{padding} is the amount of whitespace that must be present between
+the bottom of one staff and the top of the next.  It differs from
+@var{minimum-distance} in that the effect of @var{padding} depends on
+the height of objects in the staff.  For example, @var{padding} is more
+likely to come into effect for staves with notes that are far below the
+staff.
+
+@item
+@var{stretchability} controls the stretchable space's propensity to
+stretch when the system is stretched.  Large values will cause a
+system to stretch more, while a value of zero will prevent the
+space from stretching at all.  If unset, @var{stretchability}
+defaults to @code{space - minimum-distance}.
+@end itemize
 
 @lilypond[verbatim]
-#(set-default-paper-size "a6")
-#(set-global-staff-size 14.0)
+#(set-global-staff-size 16)
+\new StaffGroup <<
+  % Since space is small and there is no minimum-distance, the distance
+  % between this staff and the next will be determined by padding.
+  \new Staff \with {
+    \override VerticalAxisGroup #'next-staff-spacing = #'((space . 1) (padding . 1))
+  }
+  { \clef bass c, }
+  % Since space is small and nothing sticks out very far, the distance
+  % between this staff and the next will be determined by minimum-distance.
+  \new Staff \with {
+    \override VerticalAxisGroup #'next-staff-spacing = #'((space . 1) (minimum-distance . 12))
+  }
+  { \clef bass c, }
+  % By setting padding to a negative value, staves can be made to collide.
+  \new Staff \with {
+    \override VerticalAxisGroup #'next-staff-spacing = #'((space . 4) (padding . -10))
+  }
+  { \clef bass c, }
+  \new Staff { \clef bass c, }
+>>
+@end lilypond
 
-\book {
-\paper {
-  ragged-last-bottom = ##f
-}
 
-\new Score \with
-{
-  \override VerticalAlignment #'max-stretch = #ly:align-interface::calc-max-stretch
-}
-{
-\new GrandStaff
+In orchestral and other large scores, it is common to place staves in
+groups.  The space between groups is typically larger than the space
+between staves of the same group.  This spacing can be tweaked with the
+@var{StaffGrouper} grob: the default value of @var{next-staff-spacing}
+for @var{VerticalAxisGroup} is a callback function which operates by
+searching for a @var{StaffGrouper} grob containing the staff.  If it
+finds a @var{StaffGrouper} grob and the staff in question is in the
+middle of a group, it reads the @var{between-staff-spacing} property of
+@var{StaffGrouper} and returns it.  If the staff in question is the last
+staff of a group, the callback reads the @var{after-last-staff-spacing}
+property of @var{StaffGrouper} and returns it.  If the callback did not
+find a @var{StaffGrouper} grob, it reads
+@var{default-next-staff-spacing} from its @var{VerticalAxisGroup} and
+returns that.
+
+@lilypond[verbatim]
+#(set-global-staff-size 16)
 <<
-  \new StaffGroup
+  \new PianoStaff \with {
+    \override StaffGrouper #'between-staff-spacing #'space = #1
+    \override StaffGrouper #'between-staff-spacing #'padding = #0
+    \override StaffGrouper #'after-last-staff-spacing #'space = #20
+  }
   <<
-    \new Staff {c' d' e' f'}
-    \new Staff {c' d' e' f'}
-    \new Staff {c' d' e' f'}
+    \new Staff c'1
+    \new Staff c'1
   >>
 
-  \new PianoStaff
-  <<
-    \new Staff {c' d' e' f'}
-    \new Staff \with {
-      \override VerticalAxisGroup #'keep-fixed-while-stretching = ##t
-    }
-    {c' d' e' f'}
-  >>
-
-  \new StaffGroup
+  \new StaffGroup \with {
+    \override StaffGrouper #'between-staff-spacing #'space = #1
+    \override StaffGrouper #'between-staff-spacing #'padding = #0
+  }
   <<
-    \new Staff {c' d' e' f'}
-    \new Staff {c' d' e' f'}
+    \new Staff c'1
+    \new Staff c'1
   >>
 >>
-}
-}
 @end lilypond
-@end ignore
 
-Vertical alignment of staves is handled by the
-@code{VerticalAlignment} object.  The context parameters
-specifying the vertical extent are described in connection with
-the @code{Axis_group_engraver}.
 
+@unnumberedsubsubsec Spacing of non-staff lines
+
+After the positions of the staves are determined, the non-staff lines
+are distributed between the staves.  Each of these lines has a
+@var{staff-affinity} property which controls its vertical alignment.
+For example,
+
+@example
+\new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #DOWN @}
+@end example
+
+@noindent creates a lyrics context that will be placed close to the
+staff below it.  Setting @var{staff-affinity} to something which is not
+a number (@code{#f}, for example) will cause that line to be treated
+like a staff.  Conversely, setting @var{staff-affinity} for a staff will
+cause it to be treated like a non-staff.
+
+@c FIXME: is it possible to have @example inside @warning?
+@c @warning{ Adjacent non-staff lines should have non-increasing
+@c @var{staff-affinity} from top-to-bottom.  For example, the behavior of
+@c @example
+@c <<
+@c   \new Staff c
+@c   \new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #DOWN @}
+@c   \new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #UP @}
+@c   \new Staff c
+@c >>
+@c @end example
+@c is undefined.
+@c }
+
+@warning{A non-staff line at the bottom of a system should have
+@var{staff-affinity} set to @code{UP}.  Similarly, a non-staff
+line at the top of a system should have @var{staff-affinity} set
+to @code{DOWN}.
+}
+
+Non-staff lines admit three properties to control their spacing.  Each
+of the these properties is an alist of the same format as
+@var{next-staff-spacing}, above.
+@itemize
+@item
+If the nearest line in the @var{staff-affinity} direction is a staff
+then @var{inter-staff-spacing} gives the spacing between the non-staff
+and the staff.  If @var{staff-affinity} is @code{CENTER}, then
+@var{inter-staff-spacing} is used for both directions.
+
+@item
+If the nearest line in the @var{staff-affinity} direction is a non-staff
+then @var{inter-loose-line-spacing} gives the spacing between the two
+non-staff lines.
+
+@item
+If the nearest line in the opposite direction to @var{staff-affinity} is
+a staff then @var{non-affinity-spacing} gives the spacing between the
+non-staff and the staff.  This can be used, for example, to require
+a minimum amount of padding between a Lyrics line and the staff
+to which it does not belong.
+@end itemize
+
+@lilypond[verbatim]
+#(set-global-staff-size 16)
+\layout {
+  \context {
+    \Lyrics
+    % By default, Lyrics are placed close together. Here, we allow them to be stretched
+    % more widely.
+    \override VerticalAxisGroup #'inter-loose-line-spacing #'stretchability = #1000
+  }
+}
+
+\new StaffGroup
+<<
+  \new Staff \with { \override VerticalAxisGroup #'next-staff-spacing = #'((space . 30)) } c'1
+  \new Lyrics \with { \override VerticalAxisGroup #'staff-affinity = #UP } \lyricmode { up }
+  \new Lyrics \with { \override VerticalAxisGroup #'staff-affinity = #CENTER } \lyricmode { center }
+  \new Lyrics \with { \override VerticalAxisGroup #'staff-affinity = #DOWN } \lyricmode { down }
+  \new Staff c'1
+>>
+@end lilypond
 
 @seealso
 Snippets:
@@ -1405,6 +1594,7 @@ Snippets:
 @c @lsr{spacing,alignment-vertical-spacing.ly}.
 
 Internals Reference:
+@rinternals{VerticalAxisGroup},
 @rinternals{VerticalAlignment},
 @rinternals{Axis_group_engraver}.
 
@@ -1865,7 +2055,7 @@ c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
 
 In the introduction
 FIXME FIXME FIXME
-@c (see @rlearning{Engraving}), 
+@c (see @rlearning{Engraving}),
 it was explained that stem
 directions influence spacing.  This is controlled with the
 @code{stem-spacing-correction} property in the