Re: [PATCH] [doc] New paper margin handling

[Michael Käppler]

Hi Neil,
> @itemize
>
> There are a few places where a full stop could do with an extra space,
> but the rest of the patch looks fine.
>
> You've mentioned check-consistency in the main discussion, but you
> might like to add it to `Other layout variables' too.
>   
Fixed.

Regards,
Michael

>From 0b9a3c726c5b236fa63e0a58cddc7608faee5594 Mon Sep 17 00:00:00 2001
From: =?utf-8?q?Michael=20K=C3=A4ppler?= <address@hidden>
Date: Fri, 30 Oct 2009 08:17:59 +0100
Subject: [PATCH] Docs: Add documentation for new paper margin handling and 
scaling.

---
 Documentation/changes.tely           |   11 ++++
 Documentation/notation/spacing.itely |  106 ++++++++++++++++++++++++++++------
 2 files changed, 98 insertions(+), 19 deletions(-)

diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index 07e9374..1e1e6d4 100644
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -63,6 +63,17 @@ which scares away people.
 
 @end ignore
 
+
address@hidden
+Paper margin defaults, as specified in 
@file{ly/@/paper@/-defaults@/-init@/.ly}, apply
+to the default paper size (a4) and are automatically scaled according to the
+paper size chosen.
+
address@hidden
+All combinations of @code{left-margin}, @code{right-margin} and
address@hidden work now.  There is no more need to set @code{line-width}
+manually unless you explicitly want to.
+
 @item
 Support for using an alternative music font, such as Gonville, is now
 added.
diff --git a/Documentation/notation/spacing.itely 
b/Documentation/notation/spacing.itely
index 7e9b1d6..eebcce5 100644
--- a/Documentation/notation/spacing.itely
+++ b/Documentation/notation/spacing.itely
@@ -175,6 +175,20 @@ Snippets:
 Margins, headers, and footers and other layout variables are
 automatically set according to the paper size.
 
+Default margin values are accessible in
address@hidden/@/paper@/-defaults@/-init@/.ly}.  They apply to the default
+paper size (a4, unless specified differently) and are scaled
+accordingly for other paper sizes.  This currently affects:
address@hidden
address@hidden @var{left-margin}
address@hidden @var{right-margin}
address@hidden @var{top-margin}
address@hidden @var{bottom-margin}
address@hidden @var{head-separation}
address@hidden @var{foot-separation}
address@hidden @var{indent}
address@hidden @var{short-indent}
+
 This section lists and describes a number of paper variables that
 may be altered.
 
@@ -328,7 +342,7 @@ example
 Example:
 
 @example
address@hidden
+\paper @{
   paper-width = 2\cm
   top-margin = 3\cm
   bottom-margin = 3\cm
@@ -355,7 +369,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
address@hidden@/-defaults@/.ly} with values in millimeters.  That is why the
address@hidden@/-defaults@/-init@/.ly} with values in millimeters.  That is why 
the
 value must be multiplied in the example
 
 @example
@@ -366,7 +380,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,6 +401,58 @@ Snippets:
 @node Horizontal dimensions
 @unnumberedsubsubsec Horizontal dimensions
 
+The settings for @code{line-width}, @code{left-margin},
address@hidden and @code{paper-width} depend on
+each other, but they do not have to be specified
+completely.
+
address@hidden
+\paper @{
+  left-margin = 30\mm
address@hidden
address@hidden example
+
+In this example, only @code{left-margin} is set.  The value for
address@hidden will remain default, @code{line-width} is
+calculated automatically.
+
address@hidden
+\paper @{
+  line-width = 150\mm
address@hidden
address@hidden 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.
+
address@hidden
+\paper @{
+  paper-width = 210\mm
+  left-margin = 20\mm
+  right-margin = 30\mm
+  line-width = 100\mm
address@hidden
address@hidden example
+
+These checks can be avoided by setting @code{check-consistency}
+to false.
+
address@hidden
+\paper @{
+  paper-width = 210\mm
+  left-margin = 20\mm
+  line-width = 200\mm
+  check-consistency = ##f
address@hidden
address@hidden 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.}
@@ -406,22 +472,25 @@ 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
address@hidden or @code{set-paper-size}.
+Default: @code{15\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
address@hidden or @code{set-paper-size}.
+each system.  Default: @code{10\mm}.
+
address@hidden right-margin
address@hidden right-margin
+
+The margin between the right edge of the page and the beginning of
+each system.  Default: @code{10\mm}.
 
 @item line-width
 @funindex line-width
 
 The width of music systems.  Default: @code{paper-width} minus
address@hidden, as determined by @code{set-default-paper-size} or
address@hidden
address@hidden and @code{right-margin}.
 
 @item paper-width
 @funindex paper-width
@@ -433,8 +502,7 @@ size.  For details, see @ref{Paper size}.
 @funindex short-indent
 
 The level of indentation for all systems in a score besides the
-first system.  Default: @code{0}, as determined by
address@hidden or @code{set-paper-size}.
+first system.  Default: @code{0}.
 
 @end table
 
@@ -444,13 +512,6 @@ Snippets:
 @rlsr{Spacing}.
 
 
address@hidden
-
-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
address@hidden
-
 
 @node Other layout variables
 @unnumberedsubsubsec Other layout variables
@@ -492,6 +553,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}.
 
address@hidden check-consistency
address@hidden check-consistency
+
+If set to true, check whether @code{left-margin}, @code{right-margin} and
address@hidden 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
 
@@ -1865,7 +1933,7 @@ c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
 
 In the introduction
 FIXME FIXME FIXME
address@hidden (see @rlearning{Engraving}), 
address@hidden (see @rlearning{Engraving}),
 it was explained that stem
 directions influence spacing.  This is controlled with the
 @code{stem-spacing-correction} property in the
-- 
1.6.0.2