Guide, node Updating translation committishes..
@end ignore
-@c \version "2.15.20"
+@c \version "2.16.0"
@ignore
GDP TODO list
@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 An appendix entry exists for paper sizes but is not auto-generated
-@c TODO add a new appendix for paper sizes (auto-generated) -pm
+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,
-@warning{The default paper size is @code{a4}.}
+@example
+#(set! paper-alist (cons '("my size" . (cons (* 15 in) (* 3 in))) paper-alist))
+
+\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
+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:
-@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
If set to false, systems will spread vertically down the last
page. Pieces that amply fill two pages or more should have this
-set to true. It also affects the last page of book parts, i.e.
+set to false. It also affects the last page of book parts, i.e.
parts of a book created with @code{\bookpart} blocks.
@end table
@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.
+Explicitly defined paper-sizes will override any user-defined top or
+bottom margin settings.
+
@node Flexible vertical spacing \paper variables
@subsection Flexible vertical spacing @code{\paper} variables
@end itemize
+For multi-page scores with a ragged bottom on the last page, the last
+page uses the same spacing as the preceding page, provided there is
+enough space for that.
+
Specific methods for modifying alists are discussed in
@ref{Modifying alists}. The following example demonstrates the
two ways these alists can be modified. The first declaration
Installed Files:
@file{ly/paper-defaults-init.ly}.
+@knownissues
+Explicitly defined paper-sizes will override any user-defined left or
+right margin settings.
+
@node \paper variables for two-sided mode
@unnumberedsubsubsec @code{\paper} variables for two-sided mode
@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
@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
@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},
@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
+Notation Reference:
+@ref{\paper variables for line breaking}.
+
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}.
previously-positioned grobs can be controlled with
@code{outside-staff-padding}.
-@lilypond[quote,ragged-right,relative=2,verbatim]
+@lilypond[quote,ragged-right,relative=2,verbatim,staffsize=18]
\once \override TextScript #'outside-staff-padding = #0
a'^"This text is placed very close to the note"
\once \override TextScript #'outside-staff-padding = #3
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