]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/notation/spacing.itely
Doc: extend explanation of relative-includes (2558)
[lilypond.git] / Documentation / notation / spacing.itely
index dba9dbbae26b9c6a0f6895f97dbe0b58726a7011..ecc3217cf9bab0370d9f0b23780bebb61888a715 100644 (file)
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.15.20"
+@c \version "2.16.0"
 
 @ignore
 GDP TODO list
@@ -130,7 +130,7 @@ section, @ref{Paper size and automatic scaling}.  The
 @code{\paper} variables that deal with page layout are discussed
 in later sections.  The markup definitions that deal with headers,
 footers, and titles are discussed in
-@ref{Custom headers footers and titles}.
+@ref{Custom titles headers and footers}.
 
 Most @code{\paper} variables will only work in a @code{\paper}
 block.  The few that will also work in a @code{\layout} block are
@@ -175,7 +175,7 @@ The Scheme equivalent of the above example is:
 @seealso
 Notation Reference:
 @ref{Paper size and automatic scaling},
-@ref{Custom headers footers and titles},
+@ref{Custom titles headers and footers},
 @ref{The \layout block}.
 
 Installed Files:
@@ -265,7 +265,18 @@ accordingly.
 #(set-default-paper-size "a6" 'landscape)
 @end example
 
-The music output will @emph{not} be rotated, just the paper size.
+Swapping the paper dimensions @emph{without} having the print rotated
+(like when printing to postcard size, or creating graphics for inclusion
+rather than a standalone document) can be achieved by appending
+@samp{landscape} to the name of the paper size itself:
+
+@example
+#(set-default-paper-size "a6landscape")
+@end example
+
+When the paper size ends with an explicit @samp{landscape} or
+@samp{portrait}, the presence of a @code{'landscape} symbol @emph{only}
+affects print orientation, not the paper dimensions used for layout.
 
 @seealso
 Notation Reference:
@@ -807,8 +818,6 @@ Snippets:
 @node \paper variables for line breaking
 @unnumberedsubsubsec @code{\paper} variables for line breaking
 
-@c TODO: Mention that ly:optimal-breaking is on by default? -mp
-
 @table @code
 
 @item max-systems-per-page
@@ -854,32 +863,13 @@ Default values not listed here are defined in
 
 @table @code
 
-@item blank-after-score-page-force
-@funindex blank-after-score-page-force
-
-The penalty for having a blank page after the end of one score and
-before the next.  By default, this is smaller than
-@code{blank-page-force}, so that we prefer blank pages after
-scores to blank pages within a score.
-
-@item blank-last-page-force
-@funindex blank-last-page-force
-
-The penalty for ending the score on an odd-numbered page.
-
-@item blank-page-force
-@funindex blank-page-force
-
-The penalty for having a blank page in the middle of a
-score.  This is not used by @code{ly:optimal-breaking} since it will
-never consider blank pages in the middle of a score.
-
 @item page-breaking
 @funindex page-breaking
 
 The page-breaking algorithm to use.  Choices are
-@code{ly:minimal-breaking}, @code{ly:page-turn-breaking}, and
-@code{ly:optimal-breaking}.
+@code{ly:minimal-breaking}, @code{ly:page-turn-breaking},
+@code{ly:one-line-breaking} and @code{ly:optimal-breaking}
+(the default).
 
 @item page-breaking-system-system-spacing
 @funindex page-breaking-system-system-spacing
@@ -898,6 +888,56 @@ The number of pages to be used for a score, unset by default.
 
 @end table
 
+The following variables are effective only when @code{page-breaking}
+is set to @code{ly:page-turn-breaking}.  Page breaks are then chosen
+to minimize the number of page turns.  Since page turns are required
+on moving from an odd-numbered page to an even-numbered one, a
+layout in which the last page is odd-numbered will usually be
+favoured.  Places where page turns are preferred can be indicated
+manually by inserting @code{\allowPageTurn} or automatically by
+including the @code{Page_turn_engraver} (see @ref{Optimal page turning}).
+
+If there are insufficient choices available for making suitable page
+turns, LilyPond may insert a blank page either within a score, between
+scores (if there are two or more scores), or by ending a score on an
+even-numbered page.  The values of the following three variables may
+be increased to make these actions less likely.
+
+The values are penalties, i.e. the higher the value the less likely
+will be the associated action relative to other choices.
+
+@table @code
+
+@item blank-page-penalty
+@funindex blank-page-penalty
+
+The penalty for having a blank page in the middle of a score.  If
+@code{blank-page-penalty} is large and @code{ly:page-turn-breaking} is
+selected, then LilyPond will be less likely to insert a page in the
+middle of a score.  Instead, it will space out the music further to
+fill the blank page and the following one.  Default: 5.
+
+@item blank-last-page-penalty
+@funindex blank-last-page-penalty
+
+The penalty for ending the score on an even-numbered page.  If
+@code{blank-last-page-penalty} is large and
+@code{ly:page-turn-breaking} is selected, then LilyPond will be less
+likely to produce a score in which the last page is even-numbered.
+Instead, it will adjust the spacing in order to use one page more or
+one page less.  Default: 0.
+
+@item blank-after-score-page-penalty
+@funindex blank-after-score-page-penalty
+
+The penalty for having a blank page after the end of one score and
+before the next.  By default, this is smaller than
+@code{blank-page-penalty}, so that blank pages after scores are
+inserted in preference to blank pages within a score.  Default: 2.
+
+@end table
+
+
 @seealso
 Notation Reference:
 @ref{Page breaking},
@@ -1350,7 +1390,7 @@ with the music:
 
 @lilypond[quote,ragged-right,verbatim]
 \new Voice \with {
-  \remove Forbid_line_break_engraver
+  \remove "Forbid_line_break_engraver"
 } \relative c'' {
   <<
     { c2. \times 2/3 { c4 c c } c2. | }
@@ -1416,13 +1456,6 @@ every 4 measures, and only there:
 >>
 @end example
 
-@c TODO Check this
-A linebreaking configuration can be saved as a @file{.ly} file
-automatically.  This allows vertical alignments to be stretched to
-fit pages in a second formatting run.  This is fairly new and
-complicated.  More details are available in
-@rlsr{Spacing}.
-
 
 @predefined
 @funindex \break
@@ -1613,6 +1646,9 @@ top-level markups.
 @endpredefined
 
 @seealso
+Notation Reference:
+@ref{\paper variables for line breaking}.
+
 Snippets:
 @rlsr{Spacing}.
 
@@ -3012,7 +3048,7 @@ which may be used together or alone:
 @item @code{proportionalNotationDuration}
 @item @code{uniform-stretching}
 @item @code{strict-note-spacing}
-@item @code{\remove Separating_line_group_engraver}
+@item @code{\remove "Separating_line_group_engraver"}
 @item @code{\override PaperColumn #'used = ##t}
 @end itemize
 
@@ -3302,7 +3338,7 @@ reduces this space to zero.
 }
 
 \new Staff \with {
-  \remove Separating_line_group_engraver
+  \remove "Separating_line_group_engraver"
 } {
   c'1
   \break
@@ -3367,7 +3403,7 @@ that frequently appear in proportional scores.  These include:
 @item @code{\override Beam #'breakable = ##t}
 @item @code{\override Glissando #'breakable = ##t}
 @item @code{\override TextSpanner #'breakable = ##t}
-@item @code{\remove Forbid_line_break_engraver in the Voice context}
+@item @code{\remove "Forbid_line_break_engraver" in the Voice context}
 @end itemize
 
 These settings space grace notes strictly, extend tuplet brackets to