@funindex \paper
@menu
-* Setting paper size::
+* Setting the paper size::
* Automatic scaling to paper size::
@end menu
-@node Setting paper size
-@unnumberedsubsubsec Setting paper size
+@node Setting the paper size
+@unnumberedsubsubsec Setting the paper size
-Two functions are available for changing the paper size:
-@code{set-default-paper-size} and @code{set-paper-size}.
-@code{set-default-paper-size} must be placed in the toplevel
-scope, and @code{set-paper-size} must be placed in a @code{\paper}
-block:
+@q{A4} is the default value when no explicit paper size is set. However,
+there are two functions that can be used to change it
+@code{set-default-paper-size},
@example
-#(set-default-paper-size "a4")
+#(set-default-paper-size "quarto")
@end example
+which must always be placed at the toplevel scope. and
+@code{set-paper-size},
+
@example
\paper @{
- #(set-paper-size "a4")
+ #(set-paper-size "tabloid")
@}
@end example
-@noindent
-In the toplevel scope, the @code{set-default-paper-size} function
-can safely be called anywhere before the first @code{\paper}
-block. Within a @code{\paper} block, the safest place to call
-@code{set-paper-size} is at the top, above the list of variable
-declarations. The reasons for this are discussed in
-@ref{Automatic scaling to paper size}.
+which must always be placed in a @code{\paper} block.
-@code{set-default-paper-size} sets the size of all pages, whereas
-@code{set-paper-size} only sets the size of the pages that the
-@code{\paper} block applies to. For example, if the @code{\paper}
-block is at the top of the file, then it will apply the paper size
-to all pages. If the @code{\paper} block is inside a
+If the @code{set-default-paper-size} function is used in the toplevel
+scope, it must come before the any @code{\paper} block.
+@code{set-default-paper-size} sets the paper size for all pages,
+whereas @code{set-paper-size} only sets the paper size for the pages
+that the @code{\paper} block applies to. For example, if the
+@code{\paper} block is at the top of the file, then it will apply the
+paper size to all pages. If the @code{\paper} block is inside a
@code{\book}, then the paper size will only apply to that book.
-Common paper sizes are available, including @code{a4},
-@code{letter}, @code{legal}, and @code{11x17} (also known as
-tabloid). Many more paper sizes are supported by default. For
-details, see @file{scm/paper.scm}, and search for the
-definition of @code{paper-alist}.
+When the @code{set-paper-size} function is used, it must be
+placed @emph{before} any other functions used within the same
+@code{\paper} block. See @ref{Automatic scaling to paper size}.
+
+Paper sizes are defined in @file{scm/paper.scm}, and while it is
+possible to add custom sizes, they will be overwritten on subsequent
+software updates. The available paper sizes are listed in
+@ref{Predefined paper sizes}.
-@c TODO add a new appendix for paper sizes (auto-generated) -pm
+@c An appendix entry exists for paper sizes but is not auto-generated
+
+The following command can be used in the file to add a custom paper size
+which can then be used with @code{set-default-paper-size} or
+@code{set-paper-size} as appropriate,
+
+@example
+#(set! paper-alist (cons '("my size" . (cons (* 15 in) (* 3 in))) paper-alist))
-@warning{The default paper size is @code{a4}.}
+\paper @{
+ #(set-paper-size "my size")
+@}
+@end example
-Extra sizes may be added by editing the definition of
-@code{paper-alist} in the initialization file
-@file{scm/paper.scm}, however they will be overridden on a
-subsequent install.
+The units @code{in} (inches), @code{cm} (centimeters) and @code{mm}
+(millimeters) can all be used.
-@cindex orientation
-@cindex landscape
+@cindex paper size, orientation
+@cindex page, orientation
+@cindex paper size, landscape
-If the symbol @code{'landscape} is supplied as an argument to
-@code{set-default-paper-size}, pages will be rotated by 90
-degrees, and wider line widths will be set accordingly.
+If the symbol @code{'landscape} is added to the paper size function,
+pages will be rotated by 90 degrees, and wider line widths will be set
+accordingly.
@example
#(set-default-paper-size "a6" 'landscape)
@end example
+The music output will @emph{not} be rotated, just the paper size.
+
@seealso
Notation Reference:
-@ref{Automatic scaling to paper size}.
+@ref{Automatic scaling to paper size},
+@ref{Predefined paper sizes}.
Installed Files:
@file{scm/paper.scm}.
@code{paper-width} can influence other values (this is separate
from scaling and is discussed below). The
@code{set-default-paper-size} and @code{set-paper-size} functions
-are described in @ref{Setting paper size}.
+are described in @ref{Setting the paper size}.
The vertical dimensions affected by automatic scaling are
@code{top-margin} and @code{bottom-margin} (see
@rlsr{Spacing}.
@knownissues
-
The titles (from the @code{\header} block) are treated as a
system, so @code{ragged-bottom} and @code{ragged-last-bottom} will
add space between the titles and the first system of the score.
@file{ly/paper-defaults-init.ly}.
@knownissues
-
Explicitly defined paper-sizes will override any user-defined left or
right margin settings.
@ref{Page breaking},
@ref{Optimal page breaking},
@ref{Optimal page turning},
-@ref{Minimal page breaking}.
+@ref{Minimal page breaking},
+@ref{One-line page breaking}.
Installed Files:
@file{ly/paper-defaults-init.ly}.
@end table
-
@seealso
Installed Files:
@file{ly/titling-init.ly}.
Snippets:
@rlsr{Spacing}.
-
@knownissues
-
The default page header puts the page number and the @code{instrument}
field from the @code{\header} block on a line.
@}
@end example
+Multiple @code{\layout} blocks can be entered as toplevel expressions.
+This can, for example, be useful if different settings are stored in
+separate files and included optionally. Internally, when
+a @code{\layout} block is evaluated, a copy of the current
+@code{\layout} configuration is made, then any changes defined within
+the block are applied and the result is saved as the new current
+configuration. From the user's perspective the @code{\layout} blocks
+are combined, but in conflicting situations (when the same property
+is changed in different blocks) the later definitions take precedence.
+
+For example, if this block:
+
+@example
+\layout @{
+ \context @{
+ \Voice
+ \override TextScript #'color = #magenta
+ \override Glissando #'thickness = #1.5
+ @}
+@}
+@end example
+
+is placed after the one from the preceding example the @code{'padding}
+and @code{'color} overrides for @code{TextScript} are combined, but
+the later @code{'thickness} override for @code{Glissando} replaces
+(or hides) the earlier one.
+
+@code{\layout} blocks may be assigned to variables for reuse later,
+but the way this works is slightly but significantly different from
+writing them literally.
+
+If a variable is defined like this:
+
+@example
+layoutVariable = \layout @{
+ \context @{
+ \Voice
+ \override NoteHead #'font-size = #4
+ @}
+@}
+@end example
+
+it will hold the current @code{\layout} configuration with the
+@code{NoteHead #'font-size} override added, but this combination
+is @emph{not} saved as the new current configuration. Be aware
+that the @q{current configuration} is read when the variable is
+defined and not when it is used, so the content of the variable
+is dependent on its position in the source.
+
+The variable can then be used inside another @code{\layout} block,
+for example:
+
+@example
+\layout @{
+ \layoutVariable
+ \context @{
+ \Voice
+ \override NoteHead #'color = #red
+ @}
+@}
+@end example
+
+A @code{\layout} block containing a variable, as in the example above,
+does @emph{not} copy the current configuration but instead uses the
+content of @code{\layoutVariable} as the base configuration for the
+further additions. This means that any changes defined between the
+definition and the use of the variable are lost.
+
+If @code{layoutVariable} is defined (or @code{\include}d) immediately
+before being used, its content is just the current configuration plus
+the overrides defined within it. So in the example above showing the
+use of @code{\layoutVariable} the final @code{\layout} block would
+consist of:
+
+@example
+ TextScript #'padding = #1
+ TextScript #'color = #magenta
+ Glissando #'thickness = #1.5
+ NoteHead #' font-size = #4
+ NoteHead #' color = #red
+@end example
+
+plus the @code{indent} and the @code{StaffGrouper} overrides.
+
+But if the variable had already been defined before the first
+@code{\layout} block the current configuration would now contain
+only
+
+@example
+ NoteHead #' font-size= #4 % (written in the variable definition)
+ NoteHead #' color = #red % (added after the use of the variable)
+@end example
+
+If carefully planned, @code{\layout} variables can be a valuable tool
+to structure the layout design of sources, and also to reset the
+@code{\layout} configuration to a known state.
@seealso
Notation Reference:
@rinternals{StaffSymbol}) can be used to tune the size for individual
staves. The sizes of individual staves are relative to the global size.
-
@seealso
Notation Reference:
@ref{Selecting notation font size}.
Snippets:
@rlsr{Spacing}.
-
@knownissues
-
@code{layout-set-staff-size} does not change the distance between the
staff lines.
* Optimal page breaking::
* Optimal page turning::
* Minimal page breaking::
+* One-line page breaking::
* Explicit breaks::
* Using an extra voice for breaks::
@end menu
@code{\noBreak}.
@endpredefined
-
@seealso
Notation Reference:
@ref{\paper variables for line breaking}.
@code{\noPageBreak}.
@endpredefined
-
@seealso
Notation Reference:
@ref{\paper variables for page breaking}.
cramping and stretching, both horizontally and vertically. Unlike
@code{ly:page-turn-breaking}, it has no concept of page turns.
-
@seealso
Snippets:
@rlsr{Spacing}.
@code{\allowPageTurn}, may also be used at top-level, between scores and
top-level markups.
-
@predefined
@funindex \pageTurn
@code{\pageTurn},
@code{\allowPageTurn}.
@endpredefined
-
@seealso
Snippets:
@rlsr{Spacing}.
-
@knownissues
-
There should only be one @code{Page_turn_engraver} in a score. If there is more
than one, they will interfere with each other.
@}
@end example
-
@seealso
Snippets:
@rlsr{Spacing}.
+@node One-line page breaking
+@subsection One-line page breaking
+
+@funindex ly:one-line-breaking
+
+The @code{ly:one-line-breaking} function is a special-purpose
+page breaking algorithm that puts each score on its own page,
+and on a single line. This page breaking function does not
+typeset titles or margins; only the score will be displayed.
+
+The page width will be adjusted so that
+the longest score fits on one line. In particular,
+@code{paper-width}, @code{line-width} and @code{indent}
+variables in the @code{\paper} block will be ignored, although
+@code{left-margin} and @code{right-margin} will
+still be honored. The height of the page will
+be left unmodified.
@node Explicit breaks
@subsection Explicit breaks
}
@end lilypond
-
@seealso
Snippets:
@rlsr{Spacing}.
}
@end lilypond
-
@seealso
Notation Reference:
@ref{Vertical spacing}.
@ref{Flexible vertical spacing \paper variables},
@ref{Modifying alists}.
+Installed Files:
+@file{ly/engraver-init.ly},
+@file{scm/define-grobs.scm}.
+
Internals Reference:
@rinternals{Contexts},
@rinternals{VerticalAxisGroup},
@rinternals{StaffGrouper}.
-Installed Files:
-@file{ly/engraver-init.ly},
-@file{scm/define-grobs.scm}.
-
@node Spacing of ungrouped staves
@unnumberedsubsubsec Spacing of ungrouped staves
>>
@end lilypond
-
@seealso
Installed Files:
@file{ly/engraver-init.ly},
passed to these different settings will avoid this.
@end itemize
-
@seealso
Snippets:
@rlsr{Spacing}.
c''2
@end lilypond
-
@seealso
Snippets:
@rlsr{Spacing}.
Proportional notation is supported; see @ref{Proportional notation}.
-
@seealso
+Essay on automated music engraving:
+@ressay{Optical spacing}.
+
Snippets:
@rlsr{Spacing}.
@rinternals{StaffSpacing},
@rinternals{NonMusicalPaperColumn}.
-Essay on automated music engraving:
-@ressay{Optical spacing}.
-
-
@knownissues
-
There is no convenient mechanism to manually override spacing. The
following work-around may be used to insert extra space into a score,
adjusting the padding value as necessary.
+
@example
\override Score.NonMusicalPaperColumn #'padding = #10
@end example
@code{SpacingSpanner} object, and hence new @code{\override}s
may be used in that location.
-
@seealso
Snippets:
@rlsr{Spacing}.
\new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c] c32[ c32] }
@end lilypond
-
@seealso
Snippets:
@rlsr{Spacing}.
@}
@end example
-
@seealso
Snippets:
@rlsr{Spacing}.
to break across systems and pages. See the respective parts of the manual
for these related settings.
-
@seealso
Notation Reference:
@ref{New spacing area}.
(@var{a},@var{b}) are intervals, where @var{a} is the lower
edge and @var{b} the upper edge of the interval.
-
@seealso
Notation Reference:
@ref{Setting the staff size}.
@}
@end example
+@item
+Force the number of pages. For example, the following
+assignment will force a layout with 2 pages.
+
+@example
+\paper @{
+ page-count = #2
+@}
+@end example
+
@item
Avoid (or reduce) objects that increase the vertical size of a
system. For example, volta repeats (or alternate repeats) require
@end itemize
-
@seealso
Notation Reference:
@ref{Page layout},
projects / lilypond.git / blobdiff