Guide, node Updating translation committishes..
@end ignore
-@c \version "2.19.12"
+@c \version "2.19.22"
@ignore
GDP TODO list
@item line-width
@funindex line-width
-The horizontal extent of the staff lines in unindented, non-ragged
-systems, equal to
+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)}
-when unset. If @code{line-width} is set, and both
-@code{left-margin} and @code{right-margin} are unset, then the
+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}. This variable
-can also be set in a @code{\layout} block.
+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
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
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 ""}}:
-@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
@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 | }
>>
}
lines. This behavior can be changed by setting
@code{\override Beam.breakable = ##t}:
-@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
* Optimal page breaking::
* Minimal page breaking::
* One-line page breaking::
+* One-line-auto-height page breaking::
* Optimal page turning::
@end menu
@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
+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:
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.
+on a single line. No titles or margins are typeset; only the score is
+displayed.
-The page width will be adjusted so that the longest score fits on
+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 will be
-ignored, although @code{left-margin} and @code{right-margin} will
-still be honored. The height of the page will be left unmodified.
+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
}
labelContext =
#(define-music-function
- (parser location context)
+ (context)
(string?)
#{ s1*0^\markup { \upright {\typewriter #context } } #})
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
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
once with exaggerated corrections:
@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
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]
+@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
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]
+@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
@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 |