Guide, node Updating translation committishes..
@end ignore
-@c \version "2.17.11"
+@c \version "2.17.30"
@ignore
GDP TODO list
> and prints page number -1 on the second page, for example.
-In 5.2.1 the @refbugs (line 495 in spacing.itely on master) it
-states:
-
-"@code{layout-set-staff-size} does not change the distance between
-the
-staff lines."
-
-Could we add a sentence:
-"Use instead the pair fontSize = #@var{N}
- \override StaffSymbol.staff-space = #(magstep
-@var{N})
-inside the Staff context to change the size of the font and the
-distance between
-staff lines accordingly."
-
-Actually I found, that the @internalsref{StaffSymbol} at line 481
-sends to an incomplete
-documentation. The property staff-space is not explained here. I
-thought Y-extent might be of
-help, but it is in turn explained by x-space which again is
-missing from the list. Who has the
-knowledge to fix this?
-
-
Clarify
http://code.google.com/p/lilypond/issues/detail?id=68
block.
@menu
-* The \paper block::
+* The paper block::
* Paper size and automatic scaling::
-* Fixed vertical spacing \paper variables::
-* Flexible vertical spacing \paper variables::
-* Horizontal spacing \paper variables::
-* Other \paper variables::
+* Fixed vertical spacing paper variables::
+* Flexible vertical spacing paper variables::
+* Horizontal spacing paper variables::
+* Other paper variables::
@end menu
-@node The \paper block
-@subsection The @code{\paper} block
+@node The paper block
+@subsection The @code{@bs{}paper} block
@code{\paper} blocks may be placed in three different places to form
a descending hierarchy of @code{\paper} blocks:
Most @code{\paper} variables will only work in a @code{\paper}
block. The few that will also work in a @code{\layout} block are
-listed in @ref{The \layout block}.
+listed in @ref{The layout block,,The @code{@bs{}layout} block}.
Except when specified otherwise, all @code{\paper} variables that
correspond to distances on the page are measured in millimeters,
Notation Reference:
@ref{Paper size and automatic scaling},
@ref{Custom titles headers and footers},
-@ref{The \layout block}.
+@ref{The layout block,,The @code{@bs{}layout} block}.
Installed Files:
@file{ly/paper-defaults-init.ly}.
@unnumberedsubsubsec Setting the paper size
@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},
+there are two functions that can be used to change it:
+
+@table @code
+@item set-default-paper-size
@example
#(set-default-paper-size "quarto")
@end example
-which must always be placed at the toplevel scope. and
-@code{set-paper-size},
+which must always be placed at the toplevel scope, and
+
+@item set-paper-size
@example
\paper @{
@end example
which must always be placed in a @code{\paper} block.
+@end table
If the @code{set-default-paper-size} function is used in the toplevel
-scope, it must come before the any @code{\paper} block.
+scope, it must come before 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
The vertical dimensions affected by automatic scaling are
@code{top-margin} and @code{bottom-margin} (see
-@ref{Fixed vertical spacing \paper variables}). The horizontal
+@ref{Fixed vertical spacing paper variables,,Fixed vertical spacing @code{@bs{}paper} variables}).
+The horizontal
dimensions affected by automatic scaling are @code{left-margin},
@code{right-margin}, @code{inner-margin}, @code{outer-margin},
@code{binding-offset}, @code{indent}, and @code{short-indent} (see
-@ref{Horizontal spacing \paper variables}).
+@ref{Horizontal spacing paper variables,,Horizontal spacing @code{@bs{}paper} variables}).
The default values for these dimensions are set in
@file{ly/paper-defaults-init.ly}, using internal variables named
@seealso
Notation Reference:
-@ref{Fixed vertical spacing \paper variables},
-@ref{Horizontal spacing \paper variables}.
+@ref{Fixed vertical spacing paper variables,,Fixed vertical spacing @code{@bs{}paper} variables},
+@ref{Horizontal spacing paper variables,,Horizontal spacing @code{@bs{}paper} variables}.
Installed Files:
@file{ly/paper-defaults-init.ly},
@file{scm/paper.scm}.
-@node Fixed vertical spacing \paper variables
-@subsection Fixed vertical spacing @code{\paper} variables
+@node Fixed vertical spacing paper variables
+@subsection Fixed vertical spacing @code{@bs{}paper} variables
@warning{Some @code{@bs{}paper} dimensions are automatically
scaled to the paper size, which may lead to unexpected behavior.
@item ragged-bottom
@funindex ragged-bottom
-If set to true, systems will not spread vertically down the page.
-This does not affect the last page. This should be set to true
-for pieces that have only two or three systems per page, for
-example orchestral scores.
+If this is set to true,
+systems will be set at their natural spacing, neither compressed
+nor stretched vertically to fit the page.
@item ragged-last-bottom
@funindex ragged-last-bottom
-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 false. It also affects the last page of book parts, i.e.
-parts of a book created with @code{\bookpart} blocks.
+If this is set to false, then the last page,
+and the last page in each section created with a @code{\bookpart} block,
+will be vertically justified in the same way as the earlier pages.
@end table
bottom margin settings.
-@node Flexible vertical spacing \paper variables
-@subsection Flexible vertical spacing @code{\paper} variables
+@node Flexible vertical spacing paper variables
+@subsection Flexible vertical spacing @code{@bs{}paper} variables
In most cases, it is preferable for the vertical distances between
certain items (such as margins, titles, systems, and separate
@menu
* Structure of flexible vertical spacing alists::
-* List of flexible vertical spacing \paper variables::
+* List of flexible vertical spacing paper variables::
@end menu
@end example
-@node List of flexible vertical spacing \paper variables
-@unnumberedsubsubsec List of flexible vertical spacing @code{\paper} variables
+@node List of flexible vertical spacing paper variables
+@unnumberedsubsubsec List of flexible vertical spacing @code{@bs{}paper} variables
The names of these variables follow the format
@code{@var{upper}-@var{lower}-spacing}, where @code{@var{upper}}
@rlsr{Spacing}.
-@node Horizontal spacing \paper variables
-@subsection Horizontal spacing @code{\paper} variables
+@node Horizontal spacing paper variables
+@subsection Horizontal spacing @code{@bs{}paper} variables
@warning{Some @code{@bs{}paper} dimensions are automatically
scaled to the paper size, which may lead to unexpected behavior.
See @ref{Automatic scaling to paper size}.}
@menu
-* \paper variables for widths and margins::
-* \paper variables for two-sided mode::
-* \paper variables for shifts and indents::
+* paper variables for widths and margins::
+* paper variables for two-sided mode::
+* paper variables for shifts and indents::
@end menu
-@node \paper variables for widths and margins
-@unnumberedsubsubsec @code{\paper} variables for widths and margins
+@node paper variables for widths and margins
+@unnumberedsubsubsec @code{@bs{}paper} variables for widths and margins
Default values (before scaling) that are not listed here are
defined in @file{ly/paper-defaults-init.ly}.
right margin settings.
-@node \paper variables for two-sided mode
-@unnumberedsubsubsec @code{\paper} variables for two-sided mode
+@node paper variables for two-sided mode
+@unnumberedsubsubsec @code{@bs{}paper} variables for two-sided mode
Default values (before scaling) are defined in
@file{ly/paper-defaults-init.ly}.
@file{ly/paper-defaults-init.ly}.
-@node \paper variables for shifts and indents
-@unnumberedsubsubsec @code{\paper} variables for shifts and indents
+@node paper variables for shifts and indents
+@unnumberedsubsubsec @code{@bs{}paper} variables for shifts and indents
Default values (before scaling) that are not listed here are
defined in @file{ly/paper-defaults-init.ly}.
@rlsr{Spacing}.
-@node Other \paper variables
-@subsection Other @code{\paper} variables
+@node Other paper variables
+@subsection Other @code{@bs{}paper} variables
@menu
-* \paper variables for line breaking::
-* \paper variables for page breaking::
-* \paper variables for page numbering::
-* Miscellaneous \paper variables::
+* paper variables for line breaking::
+* paper variables for page breaking::
+* paper variables for page numbering::
+* Miscellaneous paper variables::
@end menu
-@node \paper variables for line breaking
-@unnumberedsubsubsec @code{\paper} variables for line breaking
+@node paper variables for line breaking
+@unnumberedsubsubsec @code{@bs{}paper} variables for line breaking
@table @code
@ref{Line breaking}.
-@node \paper variables for page breaking
-@unnumberedsubsubsec @code{\paper} variables for page breaking
+@node paper variables for page breaking
+@unnumberedsubsubsec @code{@bs{}paper} variables for page breaking
Default values not listed here are defined in
@file{ly/paper-defaults-init.ly}
@file{ly/paper-defaults-init.ly}.
-@node \paper variables for page numbering
-@unnumberedsubsubsec @code{\paper} variables for page numbering
+@node paper variables for page numbering
+@unnumberedsubsubsec @code{@bs{}paper} variables for page numbering
Default values not listed here are defined in
@file{ly/paper-defaults-init.ly}
of the cover page so that page 1 is on the right hand side.
-@node Miscellaneous \paper variables
-@unnumberedsubsubsec Miscellaneous @code{\paper} variables
+@node Miscellaneous paper variables
+@unnumberedsubsubsec Miscellaneous @code{@bs{}paper} variables
@table @code
block.
@menu
-* The \layout block::
+* The layout block::
* Setting the staff size::
@end menu
-@node The \layout block
-@subsection The @code{\layout} block
+@node The layout block
+@subsection The @code{@bs{}layout} block
@funindex \layout
@item
@code{line-width}, @code{ragged-right} and @code{ragged-last}
-(see @ref{\paper variables for widths and margins})
+(see @ref{paper variables for widths and margins,,@code{@bs{}paper} variables for widths and margins})
@item
@code{indent} and @code{short-indent}
-(see @ref{\paper variables for shifts and indents})
+(see @ref{paper variables for shifts and indents,,@code{@bs{}paper} variables for shifts and indents})
@item
@code{system-count}
-(see @ref{\paper variables for line breaking})
+(see @ref{paper variables for line breaking,,@code{@bs{}paper} variables for line breaking})
@end itemize
@cindex font size, setting
@cindex staff size, setting
@funindex layout file
+@funindex magnification->font-size
+@funindex magstep
+@funindex set-global-staff-size
+@funindex layout-set-staff-size
-The default @strong{staff size} is set to 20 points.
-This may be changed in two ways:
+The default @strong{staff size} is 20 points, which corresponds to
+a staff height of 7.03mm (one point is equal to 100/7227 of an
+inch, or 2540/7227 mm). The staff size may be changed in three
+ways:
-To set the staff size globally for all scores in a file (or
-in a @code{book} block, to be precise), use @code{set-global-staff-size}.
+@enumerate
+
+@item
+To set the staff size globally for all scores in a file (or in a
+@code{\book} block, to be precise), use
+@code{set-global-staff-size}:
@example
#(set-global-staff-size 14)
@end example
@noindent
-This sets the global default size to 14pt staff height and scales all
-fonts accordingly.
+The above example sets the global default staff size to 14pt
+(4.92mm) and scales all fonts accordingly.
+
+@item
+To set the staff size for a single score within a book, use
+@code{layout-set-staff-size} inside that score's @code{\layout}
+block:
-To set the staff size individually for each score, use
@example
-\score@{
+\score @{
@dots{}
\layout @{
- #(layout-set-staff-size 15)
+ #(layout-set-staff-size 14)
@}
@}
@end example
+@item
+To set the staff size for a single staff within a system, use the
+@code{\magnifyStaff} command. For example, traditionally engraved
+chamber music scores with piano often used 7mm piano staves while
+the other staves were typically between 3/5 and 5/7 as large
+(between 60% and 71%). To achieve the 5/7 proportion, use:
+
+@example
+\score @{
+ <<
+ \new Staff \with @{
+ \magnifyStaff #5/7
+ @} @{ @dots{} @}
+ \new PianoStaff @{ @dots{} @}
+ >>
+@}
+@end example
+
+If you happen to know which @code{fontSize} you wish to use, you
+could use the following form:
+
+@example
+\score @{
+ <<
+ \new Staff \with @{
+ \magnifyStaff #(magstep -3)
+ @} @{ @dots{} @}
+ \new PianoStaff @{ @dots{} @}
+ >>
+@}
+@end example
+
+To emulate the look of traditional engraving, it is best to avoid
+reducing the thickness of the staff lines.
+
+@end enumerate
+
+
+@subheading Automatic font weight at different sizes
+
The Feta font provides musical symbols at eight different
sizes. Each font is tuned for a different staff size: at a smaller size
the font becomes heavier, to match the relatively heavier staff lines.
The recommended font sizes are listed in the following table:
-@quotation
@multitable @columnfractions .15 .2 .22 .2
-
-@item @b{font name}
-@tab @b{staff height (pt)}
-@tab @b{staff height (mm)}
-@tab @b{use}
-
-@item feta11
-@tab 11.22
-@tab 3.9
-@tab pocket scores
-
-@item feta13
-@tab 12.60
-@tab 4.4
-@tab
-
-@item feta14
-@tab 14.14
-@tab 5.0
-@tab
-
-@item feta16
-@tab 15.87
-@tab 5.6
-@tab
-
-@item feta18
-@tab 17.82
-@tab 6.3
-@tab song books
-
-@item feta20
-@tab 20
-@tab 7.0
-@tab standard parts
-
-@item feta23
-@tab 22.45
-@tab 7.9
-@tab
-
-@item feta26
-@tab 25.2
-@tab 8.9
-@tab
-@c modern rental material?
-
+@item @b{font name} @tab @b{staff height (pt)} @tab @b{staff height (mm)} @tab @b{use}
+@item feta11 @tab 11.22 @tab 3.9 @tab pocket scores
+@item feta13 @tab 12.60 @tab 4.4 @tab
+@item feta14 @tab 14.14 @tab 5.0 @tab
+@item feta16 @tab 15.87 @tab 5.6 @tab
+@item feta18 @tab 17.82 @tab 6.3 @tab song books
+@item feta20 @tab 20 @tab 7.0 @tab standard parts
+@item feta23 @tab 22.45 @tab 7.9 @tab
+@item feta26 @tab 25.2 @tab 8.9 @tab @c modern rental material?
@end multitable
-@end quotation
-
-These fonts are available in any sizes. The context property
-@code{fontSize} and the layout property @code{staff-space} (in
-@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:
@menu
* Line breaking::
* Page breaking::
-* Optimal page breaking::
-* Optimal page turning::
-* Minimal page breaking::
-* One-line page breaking::
* Explicit breaks::
-* Using an extra voice for breaks::
@end menu
@cindex line breaks
@cindex breaking lines
-Line breaks are normally determined automatically. They are chosen
-so that lines look neither cramped nor loose, and consecutive
-lines have similar density.
+Line breaks are normally determined automatically. They are
+chosen so that lines look neither cramped nor loose, and
+consecutive lines have similar density.
To manually force a line break at a bar line, use the
@code{\break} command:
@}
@end example
-
-
@cindex regular line breaks
@cindex four bar music.
-For line breaks at regular intervals use @code{\break} separated by
-skips and repeated with @code{\repeat}. For example, this would
-cause the following 28 measures (assuming 4/4 time) to be broken
-every 4 measures, and only there:
+For line breaks at regular intervals use @code{\break} separated
+by skips and repeated with @code{\repeat}. For example, this
+would cause the following 28 measures (assuming 4/4 time) to be
+broken every 4 measures, and only there:
@example
<<
@seealso
Notation Reference:
-@ref{\paper variables for line breaking}.
+@ref{paper variables for line breaking}
+@ref{The layout block}.
Snippets:
@rlsr{Spacing}.
@node Page breaking
@subsection Page breaking
+This section describes the different page breaking methods, and
+how to modify them.
+
+@menu
+* Manual page breaking::
+* Optimal page breaking::
+* Minimal page breaking::
+* One-line page breaking::
+* Optimal page turning::
+@end menu
+
+
+@node Manual page breaking
+@unnumberedsubsubsec Manual page breaking
+
The default page breaking may be overridden by inserting
-@code{\pageBreak} or @code{\noPageBreak} commands. These commands are
-analogous to @code{\break} and @code{\noBreak}. They should be
-inserted at a bar line. These commands force and forbid a page-break
-from happening. Of course, the @code{\pageBreak} command also forces
-a line break.
+@code{\pageBreak} or @code{\noPageBreak} commands. These commands
+are analogous to @code{\break} and @code{\noBreak}. They should
+be inserted at a bar line. These commands force and forbid a
+page-break from happening. Of course, the @code{\pageBreak}
+command also forces a line break.
The @code{\pageBreak} and @code{\noPageBreak} commands may also be
inserted at top-level, between scores and top-level markups.
There are also analogous settings to @code{ragged-right} and
-@code{ragged-last} which have the same effect on vertical spacing:
-@code{ragged-bottom} and @code{ragged-last-bottom}. If set to
-@code{#t} the systems on all pages or just the last page
-respectively will not be justified vertically. See
-@ref{Fixed vertical spacing \paper variables}.
-
-Page breaks are computed by the @code{page-breaking} function. LilyPond
-provides three algorithms for computing page breaks,
+@code{ragged-last} which have the same effect on vertical spacing.
+If @code{ragged-bottom} is set to @code{#t} the systems will not
+be justified vertically. When @code{ragged-last-bottom} is set
+to @code{#t}, as it is by default, empty space is allowed at the
+bottom of the final page (or the final page in each
+@code{\bookpart}). See
+@ref{Fixed vertical spacing paper variables,,Fixed vertical spacing @code{@bs{}paper} variables}.
+
+Page breaks are computed by the @code{page-breaking} function.
+LilyPond provides three algorithms for computing page breaks,
@code{ly:optimal-breaking}, @code{ly:page-turn-breaking} and
-@code{ly:minimal-breaking}. The default is @code{ly:optimal-breaking},
-but the value can be changed in the @code{\paper} block:
+@code{ly:minimal-breaking}. The default is
+@code{ly:optimal-breaking}, but the value can be changed in the
+@code{\paper} block:
@example
\paper @{
@funindex \bookpart
-When a book has many scores and pages, the page breaking problem may be
-difficult to solve, requiring large processing time and memory. To ease
-the page breaking process, @code{\bookpart} blocks are used to divide
-the book into several parts: the page breaking occurs separately on each
-part. Different page breaking functions may also be used in different
-book parts.
+When a book has many scores and pages, the page breaking problem
+may be difficult to solve, requiring large processing time and
+memory. To ease the page breaking process, @code{\bookpart}
+blocks are used to divide the book into several parts: the page
+breaking occurs separately on each part. Different page breaking
+functions may also be used in different book parts.
@example
\bookpart @{
@seealso
Notation Reference:
-@ref{\paper variables for page breaking}.
+@ref{paper variables for page breaking}.
Snippets:
@rlsr{Spacing}.
@node Optimal page breaking
-@subsection Optimal page breaking
+@unnumberedsubsubsec Optimal page breaking
@funindex ly:optimal-breaking
-The @code{ly:optimal-breaking} function is LilyPond's default method of
-determining page breaks. It attempts to find a page breaking that minimizes
-cramping and stretching, both horizontally and vertically. Unlike
-@code{ly:page-turn-breaking}, it has no concept of page turns.
+The @code{ly:optimal-breaking} function is LilyPond's default
+method of determining page breaks. It attempts to find a page
+breaking that minimizes cramping and stretching, both horizontally
+and vertically. Unlike @code{ly:page-turn-breaking}, it has no
+concept of page turns.
@seealso
Snippets:
@rlsr{Spacing}.
+@node Minimal page breaking
+@unnumberedsubsubsec Minimal page breaking
+
+@funindex ly:minimal-breaking
+
+The @code{ly:minimal-breaking} function performs minimal
+computations to calculate the page breaking: it fills a page with
+as many systems as possible before moving to the next one. Thus,
+it may be preferred for scores with many pages, where the other
+page breaking functions could be too slow or memory demanding, or
+a lot of texts. It is enabled using:
+
+@example
+\paper @{
+ page-breaking = #ly:minimal-breaking
+@}
+@end example
+
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+
+@node One-line page breaking
+@unnumberedsubsubsec 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 Optimal page turning
-@subsection Optimal page turning
+@unnumberedsubsubsec Optimal page turning
@funindex ly:page-turn-breaking
-Often it is necessary to find a page breaking configuration so that there is
-a rest at the end of every second page. This way, the musician can turn the
-page without having to miss notes. The @code{ly:page-turn-breaking} function
-attempts to find a page breaking minimizing cramping and stretching, but with
-the additional restriction that it is only allowed to introduce page turns
-in specified places.
-
-There are two steps to using this page breaking function. First, you
-must enable it in the @code{\paper} block, as explained in @ref{Page
-breaking}. Then you must tell the function where you would like to allow
-page breaks.
-
-There are two ways to achieve the second step. First, you can specify each
-potential page turn manually, by inserting @code{\allowPageTurn} into your
-input file at the appropriate places.
-
-If this is too tedious, you can add a @code{Page_turn_engraver} to a Staff or
-Voice context. The @code{Page_turn_engraver} will scan the context for
-sections without notes (note that it does not scan for rests; it scans for
-the absence of notes. This is so that single-staff polyphony with rests in one
-of the parts does not throw off the @code{Page_turn_engraver}). When it finds
-a sufficiently long section without notes, the @code{Page_turn_engraver} will
-insert an @code{\allowPageTurn} at the final bar line in that section, unless
-there is a @q{special} bar line (such as a double bar), in which case the
-@code{\allowPageTurn} will be inserted at the final @q{special} bar line in
-the section.
+Often it is necessary to find a page breaking configuration so
+that there is a rest at the end of every second page. This way,
+the musician can turn the page without having to miss notes. The
+@code{ly:page-turn-breaking} function attempts to find a page
+breaking minimizing cramping and stretching, but with the
+additional restriction that it is only allowed to introduce page
+turns in specified places.
+
+There are two steps to using this page breaking function. First,
+you must enable it in the @code{\paper} block, as explained in
+@ref{Page breaking}. Then you must tell the function where you
+would like to allow page breaks.
+
+There are two ways to achieve the second step. First, you can
+specify each potential page turn manually, by inserting
+@code{\allowPageTurn} into your input file at the appropriate
+places.
+
+If this is too tedious, you can add a @code{Page_turn_engraver} to
+a Staff or Voice context. The @code{Page_turn_engraver} will scan
+the context for sections without notes (note that it does not scan
+for rests; it scans for the absence of notes. This is so that
+single-staff polyphony with rests in one of the parts does not
+throw off the @code{Page_turn_engraver}). When it finds a
+sufficiently long section without notes, the
+@code{Page_turn_engraver} will insert an @code{\allowPageTurn} at
+the final bar line in that section, unless there is a @q{special}
+bar line (such as a double bar), in which case the
+@code{\allowPageTurn} will be inserted at the final @q{special}
+bar line in the section.
@funindex minimumPageTurnLength
The @code{Page_turn_engraver} reads the context property
-@code{minimumPageTurnLength} to determine how long a note-free section must
-be before a page turn is considered. The default value for
-@code{minimumPageTurnLength} is @code{(ly:make-moment 1/1)}. If you want
-to disable page turns, you can set it to something very large.
+@code{minimumPageTurnLength} to determine how long a note-free
+section must be before a page turn is considered. The default
+value for @code{minimumPageTurnLength} is
+@code{(ly:make-moment 1/1)}. If you want to disable page turns,
+set it to something @q{very large}.
@example
\new Staff \with @{ \consists "Page_turn_engraver" @}
@end example
@funindex minimumRepeatLengthForPageTurn
-The @code{Page_turn_engraver} detects volta repeats. It will only allow a page
-turn during the repeat if there is enough time at the beginning and end of the
-repeat to turn the page back. The @code{Page_turn_engraver} can also disable
-page turns if the repeat is very short. If you set the context property
-@code{minimumRepeatLengthForPageTurn} then the @code{Page_turn_engraver} will
-only allow turns in repeats whose duration is longer than this value.
-
-The page turning commands, @code{\pageTurn}, @code{\noPageTurn} and
-@code{\allowPageTurn}, may also be used at top-level, between scores and
-top-level markups.
+With volta repeats, the @code{Page_turn_engraver} will only
+allow a page turn during the repeat if there is enough time at the
+beginning and end of the repeat to turn the page back. If the
+repeat is very short, the @code{Page_turn_engraver} can also be
+used to disable page turns by setting a value for the context
+property @code{minimumRepeatLengthForPageTurn} where as
+@code{Page_turn_engraver} only allows turns in repeats whose
+duration is longer than this value.
+
+The page turning commands, @code{\pageTurn}, @code{\noPageTurn}
+and @code{\allowPageTurn}, may also be used at top-level, in
+top-level markups and between scores.
@predefined
@funindex \pageTurn
@seealso
Notation Reference:
-@ref{\paper variables for line breaking}.
+@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.
-
-
-@node Minimal page breaking
-@subsection Minimal page breaking
-
-@funindex ly:minimal-breaking
-
-The @code{ly:minimal-breaking} function performs minimal computations to
-calculate the page breaking: it fills a page with as many systems as
-possible before moving to the next one. Thus, it may be preferred for
-scores with many pages, where the other page breaking functions could be
-too slow or memory demanding, or a lot of texts. It is enabled using:
-
-@example
-\paper @{
- page-breaking = #ly:minimal-breaking
-@}
-@end example
-
-@seealso
-Snippets:
-@rlsr{Spacing}.
-
-@node One-line page breaking
-@subsection One-line page breaking
-
-@funindex ly:one-line-breaking
+Use only one @code{Page_turn_engraver} per score. If there are
+more, they will interfere with each other.
-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
-Lily sometimes rejects explicit @code{\break} and @code{\pageBreak}
-commands. There are two commands to override this behavior:
+There are cases when manual @code{\break} or @code{\pageBreak}
+commands are ignored by LilyPond. There are two commands to
+override this behavior:
@example
\override NonMusicalPaperColumn.line-break-permission = ##f
\override NonMusicalPaperColumn.page-break-permission = ##f
@end example
-When @code{line-break-permission} is overridden to false, Lily will insert
-line breaks at explicit @code{\break} commands and nowhere else. When
-@code{page-break-permission} is overridden to false, Lily will insert
-page breaks at explicit @code{\pageBreak} commands and nowhere else.
+If @code{line-break-permission} is set to @code{##f}, all line
+breaks must be explicitly inserted with a @code{\break} command.
+Likewise, if @code{page-break-permission} is set to @code{##f},
+all page breaks must be explicitly inserted with a
+@code{\pageBreak} command.
@lilypond[quote,verbatim]
\paper {
}
@end lilypond
-@seealso
-Snippets:
-@rlsr{Spacing}.
-
-
-@node Using an extra voice for breaks
-@subsection Using an extra voice for breaks
-
-Line- and page-breaking information usually appears within note entry directly.
-
-@example
-music = \relative c'' @{ c4 c c c @}
-
-\score @{
- \new Staff @{
- \repeat unfold 2 @{ \music @} \break
- \repeat unfold 3 @{ \music @}
- @}
-@}
-@end example
-
-This makes @code{\break} and @code{\pageBreak} commands easy to enter but mixes
-music entry with information that specifies how music should lay out
-on the page. You can keep music entry and line- and page-breaking
-information in two separate places by introducing an extra voice to
-contain the breaks. This extra voice
-contains only skips together with @code{\break}, @code{pageBreak} and other
-breaking layout information.
-
-@lilypond[quote,verbatim]
-music = \relative c'' { c4 c c c }
-
-\header { tagline = ##f }
-\paper { left-margin = 0\mm }
-\book {
- \score {
- \new Staff <<
- \new Voice {
- s1 * 2 \break
- s1 * 3 \break
- s1 * 6 \break
- s1 * 5 \break
- }
- \new Voice {
- \repeat unfold 2 { \music }
- \repeat unfold 3 { \music }
- \repeat unfold 6 { \music }
- \repeat unfold 5 { \music }
- }
- >>
- }
-}
-@end lilypond
-
-This pattern becomes especially helpful when overriding
-@code{line-break-system-details} and the other useful but long properties of
-@code{NonMusicalPaperColumnGrob}, as explained in @ref{Vertical spacing}.
+@snippets
-@lilypond[quote,verbatim]
-music = \relative c'' { c4 c c c }
-
-\header { tagline = ##f }
-\paper { left-margin = 0\mm }
-\book {
- \score {
- \new Staff <<
- \new Voice {
- \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
- #'((Y-offset . 0))
- s1 * 2 \break
-
- \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
- #'((Y-offset . 5))
- s1 * 3 \break
-
- \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
- #'((Y-offset . 15))
- s1 * 6 \break
-
- \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
- #'((Y-offset . 30))
- s1 * 5 \break
- }
- \new Voice {
- \repeat unfold 2 { \music }
- \repeat unfold 3 { \music }
- \repeat unfold 6 { \music }
- \repeat unfold 5 { \music }
- }
- >>
- }
-}
-@end lilypond
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{using-an-extra-voice-for-breaks.ly}
@seealso
Notation Reference:
Vertical spacing is controlled by three things: the amount of
space available (i.e., paper size and margins), the amount of
-space between systems, and the amount of space between
-staves inside a system.
+space between systems, and the amount of space between staves
+inside a system.
@menu
* Flexible vertical spacing within systems::
individual systems. The vertical spacing between separate
systems, scores, markups, and margins is controlled by
@code{\paper} variables, which are discussed in
-@ref{Flexible vertical spacing \paper variables}.
+@ref{Flexible vertical spacing paper variables,,Flexible vertical spacing @code{@bs{}paper} variables}.
@menu
* Within-system spacing properties::
@item @code{ChordNames} @tab baseline
@item @code{NoteNames} @tab baseline
@item @code{Lyrics} @tab baseline
-@item @code{Dynamics} @tab vertical center
+@item @code{Dynamics} @tab mid-height of @q{m}
@item @code{FiguredBass} @tab highest point
@item @code{FretBoards} @tab top line
@end multitable
alignToZero = \with {
\override VerticalAxisGroup.nonstaff-relatedstaff-spacing = #zero-space
\override VerticalAxisGroup.nonstaff-nonstaff-spacing = #zero-space
+ \override VerticalAxisGroup.staff-affinity = #DOWN
+ \remove Text_engraver % avoid having two
+ \consists Text_engraver
}
lowerCaseChords = \with {
chordNameLowercaseMinor = ##t
}
-staffAffinityDown = \with {
- \override VerticalAxisGroup.staff-affinity = #DOWN
-}
labelContext =
#(define-music-function
(parser location context)
(string?)
- #{ s1*0^\markup { \typewriter #context } #})
+ #{ s1*0^\markup { \upright {\typewriter #context } } #})
\layout {
\context { \Dynamics \alignToZero }
\context { \FiguredBass \alignToZero }
\context { \Lyrics \alignToZero }
- \context { \NoteNames \alignToZero \staffAffinityDown }
- \context { \ChordNames \alignToZero
- \staffAffinityDown
- \lowerCaseChords }
- \context { \FretBoards \alignToZero \staffAffinityDown }
+ \context { \NoteNames \alignToZero }
+ \context { \ChordNames \alignToZero \lowerCaseChords }
+ \context { \FretBoards \alignToZero }
\context { \Score
- \override BarLine.stencil = ##f
+ \omit BarLine
\override DynamicText.self-alignment-X = #-1
\override FretBoard.X-offset = #1.75
- \override InstrumentName.minimum-Y-extent = #'(-2 . 2)
- \override InstrumentName.extra-offset = #'(0 . -0.5)
- \override TextScript.minimum-Y-extent = #'(-2 . 3)
- \override TimeSignature.stencil = ##f
+ \override InstrumentName.minimum-Y-extent = #'(-1 . 2)
+ \textLengthOn
+ \omit TimeSignature
}
}
%% These contexts have reference points at the baseline:
%% ChordNames, NoteNames, and Lyrics
<<
- \new ChordNames { \chords { g1:m } }
- \new NoteNames { s1 | g1 | }
- \new RhythmicStaff {
- \set RhythmicStaff.instrumentName = #"baseline "
- \textLengthOn
- \labelContext "ChordNames " s1 |
- \labelContext "NoteNames " s1 |
- \labelContext "Lyrics" s1 |
- }
- \new Lyrics { \lyrics { \skip 1*2 | ghijk1 | } }
+ \new ChordNames { \chords { \labelContext "ChordNames" g1:m } }
+ \new NoteNames { s1 |\labelContext "NoteNames" g1 | }
+ \new Lyrics { \lyrics { \skip 1*2 | \labelContext "Lyrics" ghijk1 | } }
+ \new RhythmicStaff \with { instrumentName = #"baseline " } s1*3
>>
-%% The reference point for Dynamics is its vertical center
+%% The reference point for Dynamics is the midline of 'm' in the font
<<
- \new RhythmicStaff {
- \set RhythmicStaff.instrumentName = #"vertical center "
- \labelContext "Dynamics" s1*3
- }
- \new Dynamics { s1\mp s\fp }
+ \new Dynamics { \labelContext "Dynamics" s1\mp s\fp }
+ \new RhythmicStaff \with { instrumentName = #"mid-height " } s1*3
>>
%% The reference point for FiguredBass is its highest point
<<
- \new RhythmicStaff {
- \set RhythmicStaff.instrumentName = #"highest point "
- \labelContext "FiguredBass" s1
- }
- \new FiguredBass { \figuremode { <6 5>1 } }
+ \new FiguredBass { \labelContext "FiguredBass" \figuremode { <6 5>1 } }
+ \new RhythmicStaff \with { instrumentName = #"highest point " } s1
>>
%% The reference point for FretBoards is the top line
\include "predefined-guitar-fretboards.ly"
<<
- \new FretBoards { \chordmode { e1 } }
- \new RhythmicStaff {
- \set RhythmicStaff.instrumentName = #"top line "
- \labelContext "FretBoards " s1
- }
+ \new FretBoards { \labelContext "FretBoards" \chordmode { e1 } }
+ \new RhythmicStaff \with { instrumentName = #"top line " } s1
>>
@end lilypond
Each of the vertical spacing grob properties (except
@code{staff-affinity}) uses the same alist structure as the
@code{\paper} spacing variables discussed in
-@ref{Flexible vertical spacing \paper variables}. Specific methods
+@ref{Flexible vertical spacing paper variables,,Flexible vertical spacing @code{@bs{}paper} variables}.
+Specific methods
for modifying alists are discussed in @ref{Modifying alists}.
Grob properties should be adjusted with an @code{\override} inside
a @code{\score} or @code{\layout} block, and not inside a
@seealso
Notation Reference:
-@ref{Flexible vertical spacing \paper variables},
+@ref{Flexible vertical spacing paper variables,,Flexible vertical spacing @code{@bs{}paper} variables},
@ref{Modifying alists}.
Installed Files:
@emph{Non-staff lines} (such as @code{Lyrics}, @code{ChordNames},
etc.) are contexts whose layout objects are engraved like staves
(i.e. in horizontal lines within systems). Specifically,
-non-staff lines are non-staff contexts that create the
-@code{VerticalAxisGroup} layout object.
+non-staff lines are non-staff contexts that contain the
+@rinternals{Axis_group_engraver}.
The following properties affect the spacing of non-staff lines:
This score isolates line- and page-breaking information in a dedicated
voice. This technique of creating a breaks voice will help keep layout
separate from music entry as our example becomes more complicated.
-See @ref{Using an extra voice for breaks}.
+See @ref{Explicit breaks}.
Explicit @code{\breaks} evenly divide the music into six measures per
line. Vertical spacing results from LilyPond's defaults. To set
* Horizontal spacing overview::
* New spacing area::
* Changing horizontal spacing::
-* Line length::
+* Line width::
* Proportional notation::
@end menu
fixed amount of space (which is controlled by
@code{shortest-duration-space} in the @rinternals{SpacingSpanner}
object). The longer the duration, the more space it gets: doubling a
-duration adds a fixed amount (this amount is controlled by
-@code{spacing-increment}) of space to the note.
+duration adds @code{spacing-increment} of space to the note.
For example, the following piece contains lots of half, quarter, and
8th notes; the eighth note is followed by 1 note head width (NHW).
@lilypond[quote,ragged-right,relative=2,verbatim]
\override Score.SpacingSpanner.strict-note-spacing = ##t
-\new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c] c32[ c] }
+\new Staff { c8[ c \clef alto c \grace { c16 c } c8 c c] c32[ c] }
@end lilypond
@seealso
@rlsr{Spacing}.
-@node Line length
-@subsection Line length
+@node Line width
+@subsection Line width
@cindex page breaks
@cindex breaking pages
We start with the following one-measure example, which uses classical
spacing with ragged-right turned on.
+@c The initial pitch is not necessary as long as RhythmicStaff is
+@c not preceded by other material in the score, but we don't want
+@c to explain that.
@lilypond[quote,verbatim,ragged-right]
\score {
<<
\new RhythmicStaff {
- c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
>>
}
\score {
<<
\new RhythmicStaff {
- c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
>>
\layout {
\score {
<<
\new RhythmicStaff {
- c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
>>
\layout {
\score {
<<
\new RhythmicStaff {
- c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
>>
\layout {
\score {
<<
\new RhythmicStaff {
- c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
>>
\layout {
\score {
<<
\new RhythmicStaff {
- c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
\new RhythmicStaff {
- \tuplet 9/8 { c'8 c' c' c' c' c' c' c' c' }
+ \tuplet 9/8 { c8 8 8 8 8 8 8 8 8 }
}
>>
}
\score {
<<
\new RhythmicStaff {
- c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
\new RhythmicStaff {
- \tuplet 9/8 { c'8 c' c' c' c' c' c' c' c' }
+ \tuplet 9/8 { c8 8 8 8 8 8 8 8 8 }
}
>>
\layout {
\score {
<<
\new RhythmicStaff {
- c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
\new RhythmicStaff {
- \tuplet 9/8 { c'8 c' c' c' c' c' c' c' c' }
+ \tuplet 9/8 { c8 8 8 8 8 8 8 8 8 }
}
>>
\layout {
@lilypond[quote,verbatim,ragged-right]
\new Staff {
\set Score.proportionalNotationDuration = #(ly:make-moment 1/16)
- c''8 c'' c'' \clef alto d' d'2
+ c''8 8 8 \clef alto d'2 2
}
\new Staff {
\set Score.proportionalNotationDuration = #(ly:make-moment 1/16)
\override Score.SpacingSpanner.strict-note-spacing = ##t
- c''8 c'' c'' \clef alto d' d'2
+ c''8 8 8 \clef alto d'2 2
}
@end lilypond
projects / lilypond.git / blobdiff