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
@menu
* Line breaking::
* Page breaking::
-* Explicit 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
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
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
@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}
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
* 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.
+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
@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:
@predefined
-@funindex \pageBreak
@code{\pageBreak},
-@funindex \noPageBreak
-@code{\noPageBreak}.
+@code{\noPageBreak},
+@code{\autoPageBreaksOn},
+@code{\autoPageBreaksOff}.
@endpredefined
@seealso
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
@unnumberedsubsubsec Optimal page 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.
+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
more, they will interfere with each other.
-@node Explicit breaks
-@subsection Explicit breaks
-
-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
-
-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 {
- 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
-
-@snippets
-
-@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
-{using-an-extra-voice-for-breaks.ly}
-
@seealso
Notation Reference:
@ref{Vertical spacing}.
}
labelContext =
#(define-music-function
- (parser location context)
+ (context)
(string?)
#{ s1*0^\markup { \upright {\typewriter #context } } #})
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{Explicit breaks}.
+See @ref{Breaks}.
Explicit @code{\breaks} evenly divide the music into six measures per
line. Vertical spacing results from LilyPond's defaults. To set
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 |
projects / lilypond.git / blobdiff