Guide, node Updating translation committishes..
@end ignore
-@c \version "2.16.0"
+@c \version "2.17.6"
@ignore
GDP TODO list
Could we add a sentence:
"Use instead the pair fontSize = #@var{N}
- \override StaffSymbol #'staff-space = #(magstep
+ \override StaffSymbol.staff-space = #(magstep
@var{N})
inside the Staff context to change the size of the font and the
distance between
@code{\paper} variables that deal with page layout are discussed
in later sections. The markup definitions that deal with headers,
footers, and titles are discussed in
-@ref{Custom headers footers and titles}.
+@ref{Custom titles headers and footers}.
Most @code{\paper} variables will only work in a @code{\paper}
block. The few that will also work in a @code{\layout} block are
@seealso
Notation Reference:
@ref{Paper size and automatic scaling},
-@ref{Custom headers footers and titles},
+@ref{Custom titles headers and footers},
@ref{The \layout block}.
Installed Files:
#(set-default-paper-size "a6" 'landscape)
@end example
-The music output will @emph{not} be rotated, just the paper size.
+Swapping the paper dimensions @emph{without} having the print rotated
+(like when printing to postcard size, or creating graphics for inclusion
+rather than a standalone document) can be achieved by appending
+@samp{landscape} to the name of the paper size itself:
+
+@example
+#(set-default-paper-size "a6landscape")
+@end example
+
+When the paper size ends with an explicit @samp{landscape} or
+@samp{portrait}, the presence of a @code{'landscape} symbol @emph{only}
+affects print orientation, not the paper dimensions used for layout.
@seealso
Notation Reference:
@node \paper variables for line breaking
@unnumberedsubsubsec @code{\paper} variables for line breaking
-@c TODO: Mention that ly:optimal-breaking is on by default? -mp
-
@table @code
@item max-systems-per-page
@table @code
-@item blank-after-score-page-force
-@funindex blank-after-score-page-force
-
-The penalty for having a blank page after the end of one score and
-before the next. By default, this is smaller than
-@code{blank-page-force}, so that we prefer blank pages after
-scores to blank pages within a score.
-
-@item blank-last-page-force
-@funindex blank-last-page-force
-
-The penalty for ending the score on an odd-numbered page.
-
-@item blank-page-force
-@funindex blank-page-force
-
-The penalty for having a blank page in the middle of a
-score. This is not used by @code{ly:optimal-breaking} since it will
-never consider blank pages in the middle of a score.
-
@item page-breaking
@funindex page-breaking
The page-breaking algorithm to use. Choices are
-@code{ly:minimal-breaking}, @code{ly:page-turn-breaking}, and
-@code{ly:optimal-breaking}.
+@code{ly:minimal-breaking}, @code{ly:page-turn-breaking},
+@code{ly:one-line-breaking} and @code{ly:optimal-breaking}
+(the default).
@item page-breaking-system-system-spacing
@funindex page-breaking-system-system-spacing
@end table
+The following variables are effective only when @code{page-breaking}
+is set to @code{ly:page-turn-breaking}. Page breaks are then chosen
+to minimize the number of page turns. Since page turns are required
+on moving from an odd-numbered page to an even-numbered one, a
+layout in which the last page is odd-numbered will usually be
+favoured. Places where page turns are preferred can be indicated
+manually by inserting @code{\allowPageTurn} or automatically by
+including the @code{Page_turn_engraver} (see @ref{Optimal page turning}).
+
+If there are insufficient choices available for making suitable page
+turns, LilyPond may insert a blank page either within a score, between
+scores (if there are two or more scores), or by ending a score on an
+even-numbered page. The values of the following three variables may
+be increased to make these actions less likely.
+
+The values are penalties, i.e. the higher the value the less likely
+will be the associated action relative to other choices.
+
+@table @code
+
+@item blank-page-penalty
+@funindex blank-page-penalty
+
+The penalty for having a blank page in the middle of a score. If
+@code{blank-page-penalty} is large and @code{ly:page-turn-breaking} is
+selected, then LilyPond will be less likely to insert a page in the
+middle of a score. Instead, it will space out the music further to
+fill the blank page and the following one. Default: 5.
+
+@item blank-last-page-penalty
+@funindex blank-last-page-penalty
+
+The penalty for ending the score on an even-numbered page. If
+@code{blank-last-page-penalty} is large and
+@code{ly:page-turn-breaking} is selected, then LilyPond will be less
+likely to produce a score in which the last page is even-numbered.
+Instead, it will adjust the spacing in order to use one page more or
+one page less. Default: 0.
+
+@item blank-after-score-page-penalty
+@funindex blank-after-score-page-penalty
+
+The penalty for having a blank page after the end of one score and
+before the next. By default, this is smaller than
+@code{blank-page-penalty}, so that blank pages after scores are
+inserted in preference to blank pages within a score. Default: 2.
+
+@end table
+
+
@seealso
Notation Reference:
@ref{Page breaking},
indent = 2\cm
\context @{
\StaffGroup
- \override StaffGrouper #'staff-staff-spacing #'basic-distance = #8
+ \override StaffGrouper.staff-staff-spacing.basic-distance = #8
@}
\context @{
\Voice
- \override TextScript #'padding = #1
- \override Glissando #'thickness = #3
+ \override TextScript.padding = #1
+ \override Glissando.thickness = #3
@}
@}
@end example
\layout @{
\context @{
\Voice
- \override TextScript #'color = #magenta
- \override Glissando #'thickness = #1.5
+ \override TextScript.color = #magenta
+ \override Glissando.thickness = #1.5
@}
@}
@end example
layoutVariable = \layout @{
\context @{
\Voice
- \override NoteHead #'font-size = #4
+ \override NoteHead.font-size = #4
@}
@}
@end example
\layoutVariable
\context @{
\Voice
- \override NoteHead #'color = #red
+ \override NoteHead.color = #red
@}
@}
@end example
@lilypond[quote,ragged-right,verbatim]
\new Voice \with {
- \remove Forbid_line_break_engraver
+ \remove "Forbid_line_break_engraver"
} \relative c'' {
<<
{ c2. \times 2/3 { c4 c c } c2. | }
Similarly, line breaks are normally forbidden when beams cross bar
lines. This behavior can be changed by setting
-@code{\override Beam #'breakable = ##t}:
+@code{\override Beam.breakable = ##t}:
@lilypond[quote,ragged-right,relative=2,verbatim]
-\override Beam #'breakable = ##t
+\override Beam.breakable = ##t
c2. c8[ c | \break
c8 c] c2. |
@end lilypond
>>
@end example
-@c TODO Check this
-A linebreaking configuration can be saved as a @file{.ly} file
-automatically. This allows vertical alignments to be stretched to
-fit pages in a second formatting run. This is fairly new and
-complicated. More details are available in
-@rlsr{Spacing}.
-
@predefined
@funindex \break
@endpredefined
@seealso
+Notation Reference:
+@ref{\paper variables for line breaking}.
+
Snippets:
@rlsr{Spacing}.
commands. There are two commands to override this behavior:
@example
-\override NonMusicalPaperColumn #'line-break-permission = ##f
-\override NonMusicalPaperColumn #'page-break-permission = ##f
+\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
\layout {
\context {
\Score
- \override NonMusicalPaperColumn #'line-break-permission = ##f
- \override NonMusicalPaperColumn #'page-break-permission = ##f
+ \override NonMusicalPaperColumn.line-break-permission = ##f
+ \override NonMusicalPaperColumn.page-break-permission = ##f
}
}
}
\score {
\new Staff <<
\new Voice {
- \overrideProperty "Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 0))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 0))
s1 * 2 \break
- \overrideProperty "Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 35))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 35))
s1 * 3 \break
- \overrideProperty "Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 70))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 70))
s1 * 6 \break
- \overrideProperty "Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 105))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 105))
s1 * 5 \break
}
\new Voice {
#(define zero-space '((padding . -inf.0) (basic-distance . 0)))
alignToZero = \with {
- \override VerticalAxisGroup #'nonstaff-relatedstaff-spacing = #zero-space
- \override VerticalAxisGroup #'nonstaff-nonstaff-spacing = #zero-space
+ \override VerticalAxisGroup.nonstaff-relatedstaff-spacing = #zero-space
+ \override VerticalAxisGroup.nonstaff-nonstaff-spacing = #zero-space
}
lowerCaseChords = \with {
chordNameLowercaseMinor = ##t
}
staffAffinityDown = \with {
- \override VerticalAxisGroup #'staff-affinity = #DOWN
+ \override VerticalAxisGroup.staff-affinity = #DOWN
}
labelContext =
#(define-music-function
\lowerCaseChords }
\context { \FretBoards \alignToZero \staffAffinityDown }
\context { \Score
- \override BarLine #'stencil = ##f
- \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 BarLine.stencil = ##f
+ \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
}
}
@example
\new Staff \with @{
- \override VerticalAxisGroup #'default-staff-staff-spacing
- #'basic-distance = #10
+ \override VerticalAxisGroup.default-staff-staff-spacing.basic-distance = #10
@} @{ @dots{} @}
\new Staff \with @{
- \override VerticalAxisGroup #'default-staff-staff-spacing =
+ \override VerticalAxisGroup.default-staff-staff-spacing =
#'((basic-distance . 10)
(minimum-distance . 9)
(padding . 1)
\layout @{
\context @{
\Staff
- \override VerticalAxisGroup #'default-staff-staff-spacing
- #'basic-distance = #10
+ \override VerticalAxisGroup.default-staff-staff-spacing.basic-distance = #10
@}
@}
@end example
\layout {
\context {
\Staff
- \override VerticalAxisGroup #'default-staff-staff-spacing =
+ \override VerticalAxisGroup.default-staff-staff-spacing =
#'((basic-distance . 8)
(minimum-distance . 7)
(padding . 1))
% By setting 'padding to a negative value, staves can be made to
% collide. The lowest acceptable value for 'basic-distance is 0.
\new Staff \with {
- \override VerticalAxisGroup #'default-staff-staff-spacing =
+ \override VerticalAxisGroup.default-staff-staff-spacing =
#'((basic-distance . 3.5)
(padding . -10))
} { \clef bass g2 r | }
\layout {
\context {
\Score
- \override StaffGrouper #'staff-staff-spacing #'padding = #0
- \override StaffGrouper #'staff-staff-spacing #'basic-distance = #1
+ \override StaffGrouper.staff-staff-spacing.padding = #0
+ \override StaffGrouper.staff-staff-spacing.basic-distance = #1
}
}
<<
\new PianoStaff \with {
- \override StaffGrouper #'staffgroup-staff-spacing #'basic-distance = #20
+ \override StaffGrouper.staffgroup-staff-spacing.basic-distance = #20
} <<
\new Staff { c'1 }
\new Staff { c'1 }
\layout {
\context {
\Lyrics
- \override VerticalAxisGroup
- #'nonstaff-nonstaff-spacing #'stretchability = #1000
+ \override VerticalAxisGroup.nonstaff-nonstaff-spacing.stretchability = #1000
}
}
\new StaffGroup
<<
\new Staff \with {
- \override VerticalAxisGroup #'staff-staff-spacing = #'((basic-distance . 30))
+ \override VerticalAxisGroup.staff-staff-spacing = #'((basic-distance . 30))
} { c'1 }
\new Lyrics \with {
- \override VerticalAxisGroup #'staff-affinity = #UP
+ \override VerticalAxisGroup.staff-affinity = #UP
} \lyricmode { up }
\new Lyrics \with {
- \override VerticalAxisGroup #'staff-affinity = #CENTER
+ \override VerticalAxisGroup.staff-affinity = #CENTER
} \lyricmode { center }
\new Lyrics \with {
- \override VerticalAxisGroup #'staff-affinity = #DOWN
+ \override VerticalAxisGroup.staff-affinity = #DOWN
} \lyricmode { down }
\new Staff { c'1 }
>>
@code{\overrideProperty} command:
@example
-\overrideProperty NonMusicalPaperColumn
- #'line-break-system-details #'((X-offset . 20))
+\overrideProperty NonMusicalPaperColumn.line-break-system-details #'((X-offset . 20))
-\overrideProperty NonMusicalPaperColumn
- #'line-break-system-details #'((Y-offset . 40))
+\overrideProperty NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 40))
-\overrideProperty NonMusicalPaperColumn
- #'line-break-system-details #'((X-offset . 20)
+\overrideProperty NonMusicalPaperColumn.line-break-system-details #'((X-offset . 20)
(Y-offset . 40))
-\overrideProperty NonMusicalPaperColumn
- #'line-break-system-details #'((alignment-distances . (15)))
+\overrideProperty NonMusicalPaperColumn.line-break-system-details #'((alignment-distances . (15)))
-\overrideProperty NonMusicalPaperColumn
- #'line-break-system-details #'((X-offset . 20)
+\overrideProperty NonMusicalPaperColumn.line-break-system-details #'((X-offset . 20)
(Y-offset . 40)
(alignment-distances . (15)))
@end example
<<
\new Staff <<
\new Voice {
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 0))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 0))
s1*5 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 40))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 40))
s1*5 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 80))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 80))
s1*5 \break
}
\new Voice { \repeat unfold 15 { c'4 c' c' c' } }
<<
\new Staff <<
\new Voice {
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 20)
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 20)
(alignment-distances . (15)))
s1*5 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 60)
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 60)
(alignment-distances . (15)))
s1*5 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 100)
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 100)
(alignment-distances . (15)))
s1*5 \break
}
<<
\new Staff <<
\new Voice {
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 0)
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 0)
(alignment-distances . (30 10)))
s1*5 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 60)
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 60)
(alignment-distances . (10 10)))
s1*5 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 100)
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 100)
(alignment-distances . (10 30)))
s1*5 \break
}
@lilypond[quote,ragged-right,relative=2,verbatim]
c4_"Text"\pp
r2.
-\once \override TextScript #'outside-staff-priority = #1
+\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
+\once \override TextScript.outside-staff-priority = ##f
+\once \override DynamicLineSpanner.outside-staff-priority = ##f
c4_"Text"\pp % now they will collide
@end lilypond
@code{outside-staff-padding}.
@lilypond[quote,ragged-right,relative=2,verbatim,staffsize=18]
-\once \override TextScript #'outside-staff-padding = #0
+\once \override TextScript.outside-staff-padding = #0
a'^"This text is placed very close to the note"
-\once \override TextScript #'outside-staff-padding = #3
+\once \override TextScript.outside-staff-padding = #3
c^"This text is padded away from the previous text"
c^"This text is placed close to the previous text"
@end lilypond
c''2
% setting outside-staff-horizontal-padding fixes this
R1
-\once \override TextScript #'outside-staff-horizontal-padding = #1
+\once \override TextScript.outside-staff-horizontal-padding = #1
c,,4^"Text"
c4
c''2
{
c'4 e''4 e'4 b'4 |
b'4 e''4 b'4 e''4 |
- \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
- \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
+ \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 |
}
adjusting the padding value as necessary.
@example
- \override Score.NonMusicalPaperColumn #'padding = #10
+ \override Score.NonMusicalPaperColumn.padding = #10
@end example
No work-around exists for decreasing the amount of space.
\layout {
\context {
\Score
- \override SpacingSpanner
- #'base-shortest-duration = #(ly:make-moment 1 16)
+ \override SpacingSpanner.base-shortest-duration = #(ly:make-moment 1 16)
}
}
}
\layout {
\context {
\Score
- \override SpacingSpanner #'uniform-stretching = ##t
+ \override SpacingSpanner.uniform-stretching = ##t
}
}
}
regard for clefs, bar lines, and grace notes,
@lilypond[quote,ragged-right,relative=2,verbatim]
-\override Score.SpacingSpanner #'strict-note-spacing = ##t
+\override Score.SpacingSpanner.strict-note-spacing = ##t
\new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c] c32[ c32] }
@end lilypond
@item @code{proportionalNotationDuration}
@item @code{uniform-stretching}
@item @code{strict-note-spacing}
-@item @code{\remove Separating_line_group_engraver}
-@item @code{\override PaperColumn #'used = ##t}
+@item @code{\remove "Separating_line_group_engraver"}
+@item @code{\override PaperColumn.used = ##t}
@end itemize
In the examples that follow, we explore these five different
\context {
\Score
proportionalNotationDuration = #(ly:make-moment 1 20)
- \override SpacingSpanner #'uniform-stretching = ##t
+ \override SpacingSpanner.uniform-stretching = ##t
}
}
}
}
\new Staff \with {
- \remove Separating_line_group_engraver
+ \remove "Separating_line_group_engraver"
} {
c'1
\break
\new Staff {
\set Score.proportionalNotationDuration = #(ly:make-moment 1 16)
- \override Score.SpacingSpanner #'strict-note-spacing = ##t
+ \override Score.SpacingSpanner.strict-note-spacing = ##t
c''8
c''8
c''8
that frequently appear in proportional scores. These include:
@itemize
-@item @code{\override SpacingSpanner #'strict-grace-spacing = ##t}
+@item @code{\override SpacingSpanner.strict-grace-spacing = ##t}
@item @code{tupletFullLength = ##t}
-@item @code{\override Beam #'breakable = ##t}
-@item @code{\override Glissando #'breakable = ##t}
-@item @code{\override TextSpanner #'breakable = ##t}
-@item @code{\remove Forbid_line_break_engraver in the Voice context}
+@item @code{\override Beam.breakable = ##t}
+@item @code{\override Glissando.breakable = ##t}
+@item @code{\override TextSpanner.breakable = ##t}
+@item @code{\remove "Forbid_line_break_engraver" in the Voice context}
@end itemize
These settings space grace notes strictly, extend tuplet brackets to
@lilypond[verbatim,quote,relative=1]
e4 c g\f c
-e4 c g-\tweak #'X-offset #-2.7 -\tweak #'Y-offset #2.5 \f c
+e4 c g-\tweak X-offset #-2.7 -\tweak Y-offset #2.5 \f c
@end lilypond
@item
\layout {
\context {
\Score
- \override SpacingSpanner
- #'common-shortest-duration = #(ly:make-moment 1 2)
+ \override SpacingSpanner.common-shortest-duration = #(ly:make-moment 1 2)
}
}
}