Guide, node Updating translation committishes..
@end ignore
-@c \version "2.17.30"
+@c \version "2.19.22"
@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
@example
\paper @{
- system-system-spacing #'basic-distance = #8
+ system-system-spacing.basic-distance = #8
score-system-spacing =
#'((basic-distance . 12)
(minimum-distance . 6)
@item line-width
@funindex line-width
-The horizontal extent of the staff lines in unindented, non-ragged
-systems, equal to
-@code{(paper-width@tie{}@minus{}@tie{}left-margin@tie{}@minus{}@tie{}right-margin)}
-when unset. If @code{line-width} is set, and both
-@code{left-margin} and @code{right-margin} are unset, then the
-margins will be updated to center the systems on the page
-automatically. Also see @code{check-consistency}. This variable
-can also be set in a @code{\layout} block.
+When specified in a @code{\paper} block this defines the horizontal
+extent available for the staff lines in un-indented systems. If left
+unspecified, the paper's @code{line-width} is determined from
+@code{(paper-width@tie{}@minus{}@tie{}left-margin@tie{}@minus{}@tie{}right-margin)}.
+If the paper's @code{line-width} is specified, and both
+@code{left-margin} and @code{right-margin} are not, then the margins
+will be updated to center the systems on the page automatically. Also
+see @code{check-consistency}.
+
+@code{line-width}s for individual scores can be specified in the
+scores' @code{\layout} blocks. These values control the width of the
+lines produced on a score-by-score basis. If @code{line-width} is not
+specified for a score, it defaults to the paper's @code{line-width}.
+Setting a score's @code{line-width} has no effect on the paper margins.
+Staff lines, of a length determined by the score's @code{line-width},
+are left-aligned within the paper area defined by the paper's
+@code{line-width}. If the score and paper @code{line-width}s are equal,
+the staff lines will extend exactly from the left margin to the right
+margin, but if the score's @code{line-width} is greater than the
+paper's @code{line-width} the staff lines will run over into the right
+margin.
@item left-margin
@funindex left-margin
@item check-consistency
@funindex check-consistency
-If set to true, print a warning if @code{left-margin},
-@code{line-width}, and @code{right-margin} do not exactly add up
-to @code{paper-width}, and replace each of these (except
-@code{paper-width}) with its default value (scaled to the paper
-size if necessary). If set to false, ignore any inconsistencies
-and allow systems to run off the edge of the page.
+If this is true (the default value), print a warning if
+@code{left-margin}, @code{line-width}, and @code{right-margin} do not
+exactly add up to @code{paper-width}, and replace each of these
+(except @code{paper-width}) with their default values (scaled to the
+paper size if necessary). If set to false, ignore any
+inconsistencies and allow systems to run off the edge of the page.
@item ragged-right
@funindex ragged-right
The level of indentation for the first system in a score. If the
paper size is modified, this dimension's default value is scaled
-accordingly. This variable can also be set in a @code{\layout}
-block.
+accordingly. The space within @code{line-width} available for
+the first system is reduced by this amount. @code{indent} may also
+be specified in @code{\layout} blocks to set indents on a
+score-by-score basis.
@item short-indent
@funindex short-indent
The level of indentation for all systems in a score besides the
first system. If the paper size is modified, this dimension's
-default value is scaled accordingly. This variable can also be
-set in a @code{\layout} block.
+default value is scaled accordingly. The space within
+@code{line-width} available for systems other than the first is
+reduced by this amount. @code{short-indent} may also be specified in
+@code{\layout} blocks to set short indents on a score-by-score
+basis.
@end table
The page-breaking algorithm to use. Choices are
@code{ly:minimal-breaking}, @code{ly:page-turn-breaking},
-@code{ly:one-line-breaking} and @code{ly:optimal-breaking}
-(the default).
+@code{ly:one-line-breaking}, @code{ly:one-line-auto-height-breaking},
+and @code{ly:optimal-breaking} (the default).
@item page-breaking-system-system-spacing
@funindex page-breaking-system-system-spacing
If set to false, page numbers are not printed.
+@cindex page numbers in roman numerals
+@item page-number-type
+@funindex page-number-type
+
+The type of numerals used for page numbers. Choices include
+@code{roman-lower}, @code{roman-upper} and @code{arabic}.
+Default: @code{'arabic}.
+
@end table
@seealso
tagline = ##f
}
\score {
- \relative c'' { c1 \break c1 \break c1 }
+ \relative { c''1 \break c1 \break c1 }
}
}
@end lilypond
section, @ref{Setting the staff size}. Context modifications are
discussed in a separate chapter; see
@ref{Modifying context plug-ins} and
-@ref{Changing context default settings}. The @code{\paper}
-variables that can appear in a @code{\layout} block are:
+@ref{Changing context default settings}.
+
+The @code{\paper} variables that can appear in a @code{\layout}
+block, with default values taken from the @code{\paper} block are:
@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
@node Line breaking
@subsection Line breaking
-@cindex line breaks
+@funindex \break
+@funindex \noBreak
+@funindex \autoBreaksOff
+@funindex \autoBreaksOn
+@funindex \autoLineBreaksOff
+@funindex \autoLineBreaksOn
+@cindex manual 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:
-@lilypond[quote,ragged-right,relative=2,verbatim]
-c4 c c c | \break
-c4 c c c |
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ c4 c c c | \break
+ c4 c c c |
+}
@end lilypond
-By default, a @code{\break} in the middle of a measure is ignored,
-and a warning is printed. To force a line break in the middle of
-a measure, add an invisible bar line with @w{@samp{\bar ""}}:
+By default, a @code{\break} command inserted in the @q{middle} of a
+measure will be ignored (and a warning message will be output during the
+compilation of the LilyPond file). Adding an invisible bar line
+-- @w{@samp{\bar ""}} -- before the @code{\break} command will force the
+issue:
-@lilypond[quote,ragged-right,relative=2,verbatim]
-c4 c c
-\bar "" \break
-c |
-c4 c c c |
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ c4 c c
+ \bar ""
+ \break
+ c |
+ c4 c c c |
+}
@end lilypond
-A @code{\break} occurring at a bar line is also ignored if the
-previous measure ends in the middle of a note, such as when a
-tuplet begins and ends in different measures. To allow
-@code{\break} commands to work in these situations, remove the
-@code{Forbid_line_break_engraver} from the @code{Voice} context.
-Note that manually forced line breaks have to be added in parallel
-with the music:
+A @code{\break} command that occurrs at a bar line will also ignored if
+the previous measure ends in the middle of a note (e.g. when a tuplet
+begins in one measure and ends in another). In this case remove the
+@code{Forbid_line_break_engraver} from the @code{Voice} context and,
+use a simultaneous music construction inserting the @code{\break} at the
+appropriate place in the second @q{voice}:
@lilypond[quote,ragged-right,verbatim]
\new Voice \with {
\remove "Forbid_line_break_engraver"
-} \relative c'' {
+} \relative {
<<
- { c2. \tuplet 3/2 { c4 c c } c2. | }
+ { c''2. \tuplet 3/2 { c4 c c } c2. | }
{ s1 | \break s1 | }
>>
}
@end lilypond
-Similarly, line breaks are normally forbidden when beams cross bar
-lines. This behavior can be changed by setting
-@code{\override Beam.breakable = ##t}:
+Similarly, by default, line breaks are ignored when beams cross bar
+lines. Use the @code{\override Beam.breakable = ##t} command to force
+this:
-@lilypond[quote,ragged-right,relative=2,verbatim]
-\override Beam.breakable = ##t
-c2. c8[ c | \break
-c8 c] c2. |
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ \override Beam.breakable = ##t
+ c2. c8[ c | \break
+ c8 c] c2. |
+}
@end lilypond
-The @code{\noBreak} command forbids a line break at the bar line
+The @code{\noBreak} command will prevent a line break at the bar line
where it is inserted.
+Within a score, automatic line breaking is prevented within music
+lying between @code{\autoLineBreaksOff} and @code{\autoLineBreaksOn}
+commands. If automatic page breaks should also be prevented, the
+commands @code{\autoBreaksOff} and @code{\autoBreaksOn} should be
+used. Manual breaks are unaffected by these commands. Note that
+inhibiting automatic line breaks may cause music to run over the
+right margin if it cannot all be contained within one line.
+
+Automatic line breaks (but not page breaks) may be enabled at single
+bar lines by using @code{\once \autoLineBreaksOn} at a bar line.
+This identifies a permitted rather than a forced line break.
+
The most basic settings influencing line spacing are @code{indent}
and @code{line-width}. They are set in the @code{\layout} block.
They control the indentation of the first line of music, and the
@}
@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
<<
@predefined
-@funindex \break
@code{\break},
-@funindex \noBreak
-@code{\noBreak}.
+@code{\noBreak},
+@code{\autoBreaksOff},
+@code{\autoBreaksOn},
+@code{\autoLineBreaksOff},
+@code{\autoLineBreaksOn}.
@endpredefined
+@snippets
+
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{using-an-extra-voice-for-breaks.ly}
+
@seealso
Notation Reference:
-@ref{paper variables for line breaking,,@code{@bs{}paper} variables for line breaking}.
+@ref{paper variables for line breaking}
+@ref{The layout block}.
Snippets:
@rlsr{Spacing}.
Internals Reference:
@rinternals{LineBreakEvent}.
+@knownissues
+
+Placing @code{\autoLineBreaksOff} or @code{\autoBreaksOff} before
+any music will cause error messages to appear. Always place these
+commands after some music.
+
@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::
+* One-line-auto-height page breaking::
+* Optimal page turning::
+@end menu
+
+
+@node Manual page breaking
+@unnumberedsubsubsec Manual page breaking
+
+@funindex \pageBreak
+@funindex \noPageBreak
+@funindex \autoPageBreaksOn
+@funindex \autoPageBreaksOff
+@cindex page breaking, manual
+
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 at that bar line. 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.
+Within a score, automatic page breaks are prevented within music
+lying between @code{\autoPageBreaksOff} and @code{\autoPageBreaksOn}
+commands. Manual page breaks are unaffected by these commands.
+
There are also analogous settings to @code{ragged-right} and
@code{ragged-last} which have the same effect on vertical spacing.
If @code{ragged-bottom} is set to @code{#t} the systems will not
@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:
+Page breaks are computed by the @code{page-breaking} function.
+LilyPond provides several algorithms for computing page breaks,
+including @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:
@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 @{
@predefined
-@funindex \pageBreak
@code{\pageBreak},
-@funindex \noPageBreak
-@code{\noPageBreak}.
+@code{\noPageBreak},
+@code{\autoPageBreaksOn},
+@code{\autoPageBreaksOff}.
@endpredefined
@seealso
Notation Reference:
-@ref{paper variables for page breaking,,@code{@bs{}paper} variables for page breaking}.
+@ref{paper variables for page breaking}.
Snippets:
@rlsr{Spacing}.
+@knownissues
+
+The @code{\once} prefix is ineffective with @code{\autoPageBreaksOn}
+and @code{\autoPageBreaksOff}. If auto page breaking is off and is
+then turned on to permit a page break, it must remain on for a few
+bars (the precise number of bars depends on the score) before being
+turned off, else the opportunity to break the page will not be taken.
@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. No titles or margins are typeset; only the score is
+displayed.
+
+The page width is 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 are ignored,
+although @code{left-margin} and @code{right-margin} are still honored.
+The height of the page is left unmodified.
+
+
+@node One-line-auto-height page breaking
+@unnumberedsubsubsec One-line-auto-height page breaking
+
+@funindex ly:one-line-auto-height-breaking
+
+The @code{ly:one-line-auto-height-breaking} function works just like
+@code{ly:one-line-breaking} except the page height is automatically
+modified to fit the height of the music. Specifically, the
+@code{paper-height} variable in the @code{\paper} block is set so that
+it spans the height of the tallest score plus the @code{top-margin} and
+@code{bottom-margin}.
+
+Note that the @code{top-system-spacing} setting will affect the
+vertical position of the music. Set it to @code{##f} in a paper block
+to simply place the music between the top and bottom margins.
+
+
@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.
+
+When using 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 too
+short then the @code{Page_turn_engraver} can be used to @emph{disable}
+page turns by setting an appropriate value for the context property
+@code{minimumRepeatLengthForPageTurn}. In this case the
+@code{Page_turn_engraver} will only allows turns in repeats whose
+duration is longer than the value specified.
The page turning commands, @code{\pageTurn}, @code{\noPageTurn} and
-@code{\allowPageTurn}, may also be used at top-level, between scores and
-top-level markups.
+@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,,@code{@bs{}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
-
-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:
-
-@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.
-
-@lilypond[quote,verbatim]
-\paper {
- indent = #0
- ragged-right = ##t
- ragged-bottom = ##t
-}
-
-music = \relative c'' { c8 c c c }
-
-\score {
- \new Staff {
- \repeat unfold 2 { \music } \break
- \repeat unfold 4 { \music } \break
- \repeat unfold 6 { \music } \break
- \repeat unfold 8 { \music } \pageBreak
- \repeat unfold 8 { \music } \break
- \repeat unfold 6 { \music } \break
- \repeat unfold 4 { \music } \break
- \repeat unfold 2 { \music }
- }
- \layout {
- \context {
- \Score
- \override NonMusicalPaperColumn.line-break-permission = ##f
- \override NonMusicalPaperColumn.page-break-permission = ##f
- }
- }
-}
-@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}.
+Use only one @code{Page_turn_engraver} per score. If there are
+more, they will interfere with each other.
-@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
@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::
}
labelContext =
#(define-music-function
- (parser location context)
+ (context)
(string?)
#{ s1*0^\markup { \upright {\typewriter #context } } #})
@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:
}
@end lilypond
-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}.
+This score isolates both line-breaking 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. Also see @ref{Breaks}.
-Explicit @code{\breaks} evenly divide the music into six measures per
-line. Vertical spacing results from LilyPond's defaults. To set
-the vertical startpoint of each system explicitly, we can set
-the @code{Y-offset} pair in the @code{line-break-system-details}
-attribute of the @code{NonMusicalPaperColumn} grob:
+By using explicit @code{\break} commands, the music is divided into five
+measures per line. Vertical spacing is from LilyPond's own defaults but
+the vertical startpoint of each system is set explicitly using the
+@code{Y-offset} pair in the @code{line-break-system-details} attribute
+of the @code{NonMusicalPaperColumn} grob:
@lilypond[verbatim,quote,staffsize=16]
\header { tagline = ##f }
with the lower @code{outside-staff-priority} will be placed closer to
the staff.
-@lilypond[quote,ragged-right,relative=2,verbatim]
-c4_"Text"\pp
-r2.
-\once \override TextScript.outside-staff-priority = #1
-c4_"Text"\pp % this time the text will be closer to the staff
-r2.
-% by setting outside-staff-priority to a non-number,
-% we disable the automatic collision avoidance
-\once \override TextScript.outside-staff-priority = ##f
-\once \override DynamicLineSpanner.outside-staff-priority = ##f
-c4_"Text"\pp % now they will collide
+A listing of outside-staff-priorities may be found in
+@rlearning{The outside-staff-priority property}.
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ c4_"Text"\pp
+ r2.
+ \once \override TextScript.outside-staff-priority = #1
+ c4_"Text"\pp % this time the text will be closer to the staff
+ r2.
+ % by setting outside-staff-priority to a non-number,
+ % we disable the automatic collision avoidance
+ \once \override TextScript.outside-staff-priority = ##f
+ \once \override DynamicLineSpanner.outside-staff-priority = ##f
+ c4_"Text"\pp % now they will collide
+}
@end lilypond
The vertical padding around outside-staff objects
can be controlled with @code{outside-staff-padding}.
-@lilypond[quote,ragged-right,relative=2,verbatim,staffsize=18]
-\once \override TextScript.outside-staff-padding = #0
-a4-"outside-staff-padding = #0"
-\once \override TextScript.outside-staff-padding = #3
-d-"outside-staff-padding = #3"
-c-"default outside-staff-padding"
-b-"default outside-staff-padding"
-R1
+@lilypond[quote,ragged-right,verbatim,staffsize=18]
+\relative {
+ \once \override TextScript.outside-staff-padding = #0
+ a'4-"outside-staff-padding = #0"
+ \once \override TextScript.outside-staff-padding = #3
+ d-"outside-staff-padding = #3"
+ c-"default outside-staff-padding"
+ b-"default outside-staff-padding"
+ R1
+}
@end lilypond
increases the horizontal spacing required, and in this case moves the text up
to prevent it from getting too close to the ledger lines.
-@lilypond[quote,ragged-right,relative=2,verbatim]
-c4^"Word" c c''2
-R1
-\once \override TextScript.outside-staff-horizontal-padding = #1
-c,,4^"Word" c c''2
+@lilypond[quote,ragged-right,verbatim]
+\relative {
+ c''4^"Word" c c''2
+ R1
+ \once \override TextScript.outside-staff-horizontal-padding = #1
+ c,,4^"Word" c c''2
+}
@end lilypond
@seealso
@menu
* Horizontal spacing overview::
-* New spacing area::
+* New spacing section::
* Changing horizontal spacing::
-* Line length::
+* Line width::
* Proportional notation::
@end menu
8th notes; the eighth note is followed by 1 note head width (NHW).
The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
-@lilypond[quote,verbatim,relative=1]
-c2 c4. c8
-c4. c8 c4. c8
-c8 c c4 c c
+@lilypond[quote,verbatim]
+\relative c' {
+ c2 c4. c8
+ c4. c8 c4. c8
+ c8 c c4 c c
+}
@end lilypond
Normally, @code{spacing-increment} is set to 1.2 staff space, which is
measure, the shortest duration is determined. The most common shortest
duration is taken as the basis for the spacing, with the stipulation
that this shortest duration should always be equal to or shorter than
-an 8th note. The shortest duration is printed when you run
-@code{lilypond} with the @option{--verbose} option.
+an 8th note.
These durations may also be customized. If you set the
@code{common-shortest-duration} in @rinternals{SpacingSpanner}, then
the common shortest note. So if we were to add only a few 16th notes
to the example above, they would be followed by half a NHW:
-@lilypond[quote,verbatim,relative=2]
-c2 c4. c8 | c4. c16[ c] c4. c8 | c8 c c4 c c
+@lilypond[quote,verbatim]
+\relative { c''2 c4. c8 | c4. c16[ c] c4. c8 | c8 c c4 c c }
@end lilypond
+As explained in the @emph{Essay on automated music engraving}, stem
+directions will influence spacing (see @ressay{Optical spacing}) and can
+be adjusted using the @code{stem-spacing-correction} property of the
+@rinternals{NoteSpacing} object (which are generated for every
+@rinternals{Voice} context).
-In the @emph{Essay on automated music engraving}, it was explained
-that stem directions influence spacing (see
-@ressay{Optical spacing}). This is controlled with the
-@code{stem-spacing-correction} property in the
-@rinternals{NoteSpacing}, object. These are generated for every
-@rinternals{Voice} context. The @code{StaffSpacing} object
-(generated in @rinternals{Staff} context) contains the same
-property for controlling the stem/bar line spacing. The following
-example shows these corrections, once with default settings, and
-once with exaggerated corrections:
+The @code{StaffSpacing} object (generated in @rinternals{Staff} context)
+contains the same property for controlling the stem/bar line spacing.
+
+The following example shows this; once with the default settings and
+once with an exaggerated adjustment:
@lilypond[quote,ragged-right]
-{
- c'4 e''4 e'4 b'4 |
- b'4 e''4 b'4 e''4 |
+\fixed c' {
+ c4 e'4 e4 b4 |
+ b4 e'4 b4 e'4 |
\override Staff.NoteSpacing.stem-spacing-correction = #1.5
\override Staff.StaffSpacing.stem-spacing-correction = #1.5
- c'4 e''4 e'4 b'4 |
- b'4 e''4 b'4 e''4 |
+ c4 e'4 e4 b4 |
+ b4 e'4 b4 e'4 |
}
@end lilypond
No work-around exists for decreasing the amount of space.
-@node New spacing area
-@subsection New spacing area
+@node New spacing section
+@subsection New spacing section
@funindex \newSpacingSection
-@cindex new spacing area
-@cindex spacing area, new
+@cindex new spacing section
+@cindex spacing section, new
@cindex notes, spacing horizontally
-New sections with different spacing parameters can be started with
-@code{newSpacingSection}. This is useful when there are
-sections with a different notions of long and short notes.
-
-In the following example, the time signature change introduces a new
-section, and hence the 16ths notes are automatically spaced slightly
-wider.
-
-@lilypond[relative=1,verbatim,quote]
-\time 2/4
-c4 c8 c
-c8 c c4 c16[ c c8] c4
-\newSpacingSection
-\time 4/16
-c16[ c c8]
+New sections with different spacing parameters can be started with the
+@code{newSpacingSection} command. This is useful for sections with
+different notions of @q{long} and @q{short} notes. The
+@code{\newSpacingSection} command creates a new @code{SpacingSpanner}
+object at that musical moment.
+
+In the following example the time signature change introduces a new
+section, and the 16ths notes are automatically spaced slightly wider
+apart.
+
+@lilypond[verbatim,quote]
+\relative c' {
+ \time 2/4
+ c4 c8 c
+ c8 c c4 c16[ c c8] c4
+ \newSpacingSection
+ \time 4/16
+ c16[ c c8]
+}
@end lilypond
-The @code{\newSpacingSection} command creates a new
-@code{SpacingSpanner} object at that musical moment.
If the automatic spacing adjustments do not give the required spacing,
manual @code{\override}s may be applied to its properties. These must
be applied at the same musical moment as the @code{\newSpacingSection}
-command itself. They will then affect the spacing of all the following
+command itself and will then affect the spacing of all the following
music until the properties are changed in a new spacing section, for
-example,
-
-@lilypond[relative=1,verbatim,quote]
-\time 4/16
-c16[ c c8]
-\newSpacingSection
-\override Score.SpacingSpanner.spacing-increment = #2
-c16[ c c8]
-\newSpacingSection
-\revert Score.SpacingSpanner.spacing-increment
-c16[ c c8]
+example:
+
+@lilypond[verbatim,quote]
+\relative c' {
+ \time 4/16
+ c16[ c c8]
+ \newSpacingSection
+ \override Score.SpacingSpanner.spacing-increment = #2
+ c16[ c c8]
+ \newSpacingSection
+ \revert Score.SpacingSpanner.spacing-increment
+ c16[ c c8]
+}
@end lilypond
@lilypond[verbatim,line-width=12\cm]
\score {
- \relative c'' {
- g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
+ \relative {
+ g'4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
g4 e e2 | f4 d d2 | c4 e g g | c,1 |
d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
g4 e e2 | f4 d d2 | c4 e g g | c,1 |
@lilypond[verbatim,line-width=12\cm]
\score {
- \relative c'' {
- g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
+ \relative {
+ g'4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
g4 e e2 | f4 d d2 | c4 e g g | c,1 |
d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
g4 e e2 | f4 d d2 | c4 e g g | c,1 |
When @code{strict-note-spacing} is set, notes are spaced without
regard for clefs, bar lines, and grace notes,
-@lilypond[quote,ragged-right,relative=2,verbatim]
+@lilypond[quote,ragged-right,fragment,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 \relative {
+ c''8[ 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
entire score or turned off for the entire score. We can, however,
override this behavior and turn on different spacing features at
different places in the score. We do this with the command
-@code{\newSpacingSection}. See @ref{New spacing area}, for more info.
+@code{\newSpacingSection}. See @ref{New spacing section}, for more info.
Next we examine the effects of the @code{Separating_line_group_engraver} and
see why proportional scores frequently remove this engraver. The following
@seealso
Notation Reference:
-@ref{New spacing area}.
+@ref{New spacing section}.
Snippets:
@rlsr{Spacing}.
@item
Avoid (or reduce) objects that increase the vertical size of a
-system. For example, volta repeats (or alternate repeats) require
-extra space. If these repeats are spread over two systems, they
-will take up more space than one system with the volta repeats and
-another system without. For example, dynamics that @q{stick out} of
-a system can be moved closer to the staff:
-
-@lilypond[verbatim,quote,relative=1]
-e4 c g\f c
-e4 c g-\tweak X-offset #-2.7 \f c
+system. For example, volta brackets for alternative repeat endings
+require extra space. If these endings are spread over two systems,
+they take up more space than if they were on the same system.
+As another example, dynamics that @q{stick out} of a system
+can be moved closer to the staff:
+
+@lilypond[verbatim,quote]
+\relative e' {
+ e4 c g\f c
+ e4 c g-\tweak X-offset #-2.7 \f c
+}
@end lilypond
@item
@lilypond[verbatim,quote]
\score {
- \relative c'' {
- g4 e e2 |
+ \relative {
+ g'4 e e2 |
f4 d d2 |
c4 d e f |
g4 g g2 |
@lilypond[verbatim,quote]
\score {
- \relative c'' {
- g4 e e2 |
+ \relative {
+ g'4 e e2 |
f4 d d2 |
c4 d e f |
g4 g g2 |
projects / lilypond.git / blobdiff