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.
The distances are measured from the center of the last staff in the system to
the baseline of the title that follows it. See @var{after-title-spacing}.
+@item between-scores-system-spacing
+@funindex between-scores-system-spacing
+
+Specifies the spacing between two systems if they are in different scores, but
+there is no title between them. See @var{after-title-spacing}.
+
@item between-system-spacing
@funindex between-system-spacing
Example:
@example
-\paper@{
+\paper @{
paper-width = 2\cm
top-margin = 3\cm
bottom-margin = 3\cm
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
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
@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
@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
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
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
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
* Vertical spacing inside a system::
* Vertical spacing between systems::
* Explicit staff and system positioning::
-* Two-pass vertical spacing::
* Vertical collision avoidance::
@end menu
@rlsr{Spacing}.
-@node Two-pass vertical spacing
-@subsection Two-pass vertical spacing
-
-@warning{Two-pass vertical spacing is deprecated and will be removed in
-a future version of LilyPond. Systems are now stretched automatically
-in a single pass. See @ref{Vertical spacing inside a system}.}
-
-In order to automatically stretch systems so that they should fill the
-space left on a page, a two-pass technique can be used:
-
-@enumerate
-@item In the first pass, the amount of vertical space used to increase
-the height of each system is computed and dumped to a file.
-@item In the second pass, spacing inside the systems are
-stretched according to the data in the page layout file.
-@end enumerate
-
-The @code{ragged-bottom} property adds space between systems, while
-the two-pass technique adds space between staves inside a system.
-
-To allow this behavior, a @code{tweak-key} variable has to be set in
-each score @code{\layout} block, and the tweaks included in each score
-music, using the @code{\scoreTweak} music function.
-
-@quotation
-@verbatim
-%% include the generated page layout file:
-\includePageLayoutFile
-
-\score {
- \new StaffGroup <<
- \new Staff <<
- %% Include this score tweaks:
- \scoreTweak "scoreA"
- { \clef french c''1 \break c''1 }
- >>
- \new Staff { \clef soprano g'1 g'1 }
- \new Staff { \clef mezzosoprano e'1 e'1 }
- \new Staff { \clef alto g1 g1 }
- \new Staff { \clef bass c1 c1 }
- >>
- \header {
- piece = "Score with tweaks"
- }
- %% Define how to name the tweaks for this score:
- \layout { #(define tweak-key "scoreA") }
-}
-@end verbatim
-@end quotation
-
-For the first pass, the @code{dump-tweaks} option should be set to
-generate the page layout file.
-
-@example
-lilypond -dbackend=null -d dump-tweaks <file>.ly
-lilypond <file>.ly
-@end example
-
-
-@seealso
-Snippets:
-@rlsr{Spacing}.
-
-
@node Vertical collision avoidance
@subsection Vertical collision avoidance
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
projects / lilypond.git / blobdiff