1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
15 Negative numbers are allowed:
16 > Are you sure? The following works well
18 > first-page-number = -2
20 > and prints page number -1 on the second page, for example.
23 - default paper size is A4.
26 In 5.2.1 the @refbugs (line 495 in spacing.itely on master) it
29 "@code{layout-set-staff-size} does not change the distance between
33 Could we add a sentence:
34 "Use instead the pair fontSize = #@var{N}
35 \override StaffSymbol #'staff-space = #(magstep
37 inside the Staff context to change the size of the font and the
39 staff lines accordingly."
41 Actually I found, that the @internalsref{StaffSymbol} at line 481
42 sends to an uncomplete
43 documentation. The property staff-space is not explained here. I
44 thought Y-extent might be of
45 help, but it is in turn explained by x-space which again is
46 missing from the list. Who has the
47 knowledge to fix this?
51 http://code.google.com/p/lilypond/issues/detail?id=68
56 @chapter Spacing issues
58 The global paper layout is determined by three factors: the page layout, the
59 line breaks, and the spacing. These all influence each other. The
60 choice of spacing determines how densely each system of music is set.
61 This influences where line breaks are chosen, and thus ultimately, how
62 many pages a piece of music takes.
64 Globally speaking, this procedure happens in four steps: first,
65 flexible distances (@q{springs}) are chosen, based on durations. All
66 possible line breaking combinations are tried, and a @q{badness} score
67 is calculated for each. Then the height of each possible system is
68 estimated. Finally, a page breaking and line breaking combination is chosen
69 so that neither the horizontal nor the vertical spacing is too cramped
72 Settings which influence layout may be placed in two blocks.
73 The @code{\paper @{...@}} block is placed outside any
74 @code{\score @{...@}} blocks and contains settings that
75 relate to the entire document. The @code{\layout @{...@}}
76 block is placed within a @code{\score @{...@}} block and
77 contains settings for that particular score. If you have
78 only one @code{\score @{...@}} block the two have the same
79 effect. In general the commands shown in this chapter can
85 * Displaying spacing::
88 * Horizontal spacing::
89 * Fitting music onto fewer pages::
94 @section Paper and pages
96 This section deals with the boundaries that define the area
97 within which music can be printed.
106 @subsection Paper size
112 To change the paper size, there are two commands,
114 #(set-default-paper-size "a4")
118 #(set-paper-size "a4")
122 The first command sets the size of all pages. The second command sets the
124 of the pages that the @code{\paper} block applies to -- if the @code{\paper}
125 block is at the top of the file, then it will apply to all pages. If the
126 @code{\paper} block is inside a @code{\book}, then the paper size will only
129 Support for the following paper sizes are included by default,
130 @code{a6}, @code{a5}, @code{a4}, @code{a3}, @code{legal}, @code{letter},
131 @code{11x17} (also known as tabloid).
133 @c TODO Add new paper sizes -td
135 Extra sizes may be added by editing the definition for
136 @code{paper-alist} in the initialization file @file{scm/paper.scm}.
141 If the symbol @code{landscape} is supplied as an argument to
142 @code{set-default-paper-size}, the pages will be rotated by 90 degrees,
143 and wider line widths will be set correspondingly.
146 #(set-default-paper-size "a6" 'landscape)
149 Setting the paper size will adjust a number of @code{\paper} variables
150 (such as margins). To use a particular paper size with altered
151 @code{\paper} variables, set the paper size before setting the variables.
154 @node Page formatting
155 @subsection Page formatting
157 @cindex page formatting
162 LilyPond will do page layout, set margins, and add headers and
163 footers to each page.
165 The default layout responds to the following settings in the
172 @funindex first-page-number
173 @item first-page-number
174 The value of the page number of the first page. Default is@tie{}1.
176 @funindex print-first-page-number
177 @item print-first-page-number
178 If set to true, will print the page number in the first page. Default is
181 @funindex print-page-number
182 @item print-page-number
183 If set to false, page numbers will not be printed. Default is true.
185 @funindex paper-width
187 The width of the page. The default is taken from the current paper size,
188 see @ref{Paper size}.
190 @funindex paper-height
192 The height of the page. The default is taken from the current paper size,
193 see @ref{Paper size}.
197 Margin between header and top of the page. Default is@tie{}5mm.
199 @funindex bottom-margin
201 Margin between footer and bottom of the page. Default is@tie{}6mm.
203 @funindex left-margin
205 Margin between the left side of the page and the beginning of the
206 music. Unset by default, which means that the margins is determined
207 based on the @code{paper-width} and @code{line-width} to center the
212 The length of the systems. Default is @code{paper-width} minus @tie{}20mm.
214 @funindex head-separation
215 @item head-separation
216 Distance between the top-most music system and the page header. Default
219 @funindex foot-separation
220 @item foot-separation
221 Distance between the bottom-most music system and the page
222 footer. Default is@tie{}4mm.
224 @funindex page-top-space
226 Distance from the top of the printable area to the center of the first
227 staff. This only works for staves which are vertically small. Big staves
228 are set with the top of their bounding box aligned to the top of the
229 printable area. Default is@tie{}12mm.
231 @funindex ragged-bottom
233 If set to true, systems will not be spread vertically across the page. This
234 does not affect the last page. Default is false.
236 This should be set to true for pieces that have only two or three
237 systems per page, for example orchestral scores.
239 @funindex ragged-last-bottom
240 @item ragged-last-bottom
241 If set to false, systems will be spread vertically to fill the last
242 page. Default is true.
244 Pieces that amply fill two pages or more should have this set to
247 @funindex system-count
249 This variable, if set, specifies into how many lines a score should be
250 broken. Unset by default.
252 @funindex between-system-space
253 @item between-system-space
254 This dimensions determines the distance between systems. It is the
255 ideal distance between the center of the bottom staff of one system
256 and the center of the top staff of the next system. Default is@tie{}20mm.
258 Increasing this will provide a more even appearance of the page at the
259 cost of using more vertical space.
261 @funindex between-system-padding
262 @item between-system-padding
263 This dimension is the minimum amount of white space that will always
264 be present between the bottom-most symbol of one system, and the
265 top-most of the next system. Default is@tie{}4mm.
267 Increasing this will put systems whose bounding boxes almost touch
270 @funindex page-breaking-between-system-padding
271 @item page-breaking-between-system-padding
272 This variable tricks the page breaker into thinking that
273 @code{between-system-padding} is set to something different than it
274 really is. For example, if this variable is set to something substantially
275 larger than @code{between-system-padding}, then the page-breaker will put
276 fewer systems on each page.
278 @funindex horizontal-shift
279 @item horizontal-shift
280 All systems (including titles and system separators) are shifted by
281 this amount to the right. Page markup, such as headers and footers are
282 not affected by this. The purpose of this variable is to make space
283 for instrument names at the left. Default is@tie{}0.
285 @funindex after-title-space
286 @item after-title-space
287 Amount of space between the title and the first system. Default is@tie{}5mm.
289 @funindex before-title-space
290 @item before-title-space
291 Amount of space between the last system of the previous piece and the
292 title of the next. Default is@tie{}10mm.
294 @funindex between-title-space
295 @item between-title-space
296 Amount of space between consecutive titles (e.g., the title of the
297 book and the title of a piece). Default is@tie{}2mm.
299 @funindex printallheaders
300 @item printallheaders
301 Setting this to #t will print all headers for each \score in the
302 output. Normally only the piece and opus \headers are printed.
304 @funindex systemSeparatorMarkup
305 @item systemSeparatorMarkup
306 This contains a markup object, which will be inserted between
307 systems. This is often used for orchestral scores. Unset by default.
309 The markup command @code{\slashSeparator} is provided as a sensible
312 @lilypond[ragged-right]
313 #(set-default-paper-size "a6" 'landscape)
316 \relative { c1 \break c1 }
319 systemSeparatorMarkup = \slashSeparator
324 @funindex blank-page-force
325 @item blank-page-force
326 The penalty for having a blank page in the middle of a
327 score. This is not used by @code{ly:optimal-breaking} since it will
328 never consider blank pages in the middle of a score. Default value
331 @funindex blank-last-page-force
332 @item blank-last-page-force
333 The penalty for ending the score on an odd-numbered page.
336 @funindex page-spacing-weight
337 @item page-spacing-weight
338 The relative importance of page (vertical) spacing and line (horizontal)
339 spacing. High values will make page spacing more important. Default
342 @funindex auto-first-page-number
343 @item auto-first-page-number
344 The page breaking algorithm is affected by the first page number being
345 odd or even. If this variable is set to #t, the page breaking algorithm
346 will decide whether to start with an odd or even number. This will
347 result in the first page number remaining as is or being increased by one.
355 The header and footer are created by the functions make-footer and
356 make-header, defined in \paper. The default implementations are in
357 ly/paper-defaults.ly and ly/titling-init.ly.
359 The page layout itself is done by two functions in the \paper block,
360 page-music-height and page-make-stencil. The former tells the
361 line-breaking algorithm how much space can be spent on a page, the
362 latter creates the actual page given the system to put on it.
364 You can define paper block values in Scheme. In that case mm, in, pt,
365 and cm are variables defined in paper-defaults.ly with values in
366 millimeters. That is why the value 2 cm must be multiplied in the
371 #(define bottom-margin (* 2 cm))
383 ragged-last-bottom = ##t
387 This second example centers page numbers at the bottom of every page.
391 print-page-number = ##t
392 print-first-page-number = ##t
393 oddHeaderMarkup = \markup \fill-line @{ " " @}
394 evenHeaderMarkup = \markup \fill-line @{ " " @}
395 oddFooterMarkup = \markup @{ \fill-line @{
396 \bold \fontsize #3 \on-the-fly #print-page-number-check-first
397 \fromproperty #'page:page-number-string @} @}
398 evenFooterMarkup = \markup @{ \fill-line @{
399 \bold \fontsize #3 \on-the-fly #print-page-number-check-first
400 \fromproperty #'page:page-number-string @} @}
404 You can also define these values in Scheme. In that case @code{mm},
405 @code{in}, @code{pt}, and @code{cm} are variables defined in
406 @file{paper-defaults.ly} with values in millimeters. That is why the
407 value must be multiplied in the example
411 #(define bottom-margin (* 2 cm))
415 The header and footer are created by the functions @code{make-footer}
416 and @code{make-header}, defined in @code{\paper}. The default
417 implementations are in @file{ly/@/paper@/-defaults@/.ly} and
418 @file{ly/@/titling@/-init@/.ly}.
420 The page layout itself is done by two functions in the
421 @code{\paper} block, @code{page-music-height} and
422 @code{page-make-stencil}. The former tells the line-breaking algorithm
423 how much space can be spent on a page, the latter creates the actual
424 page given the system to put on it.
429 The option right-margin is defined but doesn't set the right margin
430 yet. The value for the right margin has to be defined adjusting the
431 values of @code{left-margin} and @code{line-width}.
433 The default page header puts the page number and the @code{instrument}
434 field from the @code{\header} block on a line.
436 The titles (from the @code{\header@{@}} section) are treated as a
437 system, so @code{ragged-bottom} and @code{ragged-last-bottom} will
438 add space between the titles and the first system of the score.
442 @section Music layout
445 * Setting the staff size::
450 @node Setting the staff size
451 @subsection Setting the staff size
453 @cindex font size, setting
454 @cindex staff size, setting
455 @funindex layout file
457 The default @strong{staff size} is set to 20 points.
458 This may be changed in two ways:
460 To set the staff size globally for all scores in a file (or
461 in a @code{book} block, to be precise), use @code{set-global-staff-size}.
464 #(set-global-staff-size 14)
468 This sets the global default size to 14pt staff height and scales all
471 To set the staff size individually for each score, use
476 #(layout-set-staff-size 15)
481 The Feta font provides musical symbols at eight different
482 sizes. Each font is tuned for a different staff size: at a smaller size
483 the font becomes heavier, to match the relatively heavier staff lines.
484 The recommended font sizes are listed in the following table:
487 @multitable @columnfractions .15 .2 .22 .2
490 @tab @b{staff height (pt)}
491 @tab @b{staff height (mm)}
533 @c modern rental material?
538 These fonts are available in any sizes. The context property
539 @code{fontSize} and the layout property @code{staff-space} (in
540 @rinternals{StaffSymbol}) can be used to tune the size for individual
541 staves. The sizes of individual staves are relative to the global size.
549 This manual: @ref{Selecting notation font size}.
554 @code{layout-set-staff-size} does not change the distance between the
559 @subsection Score layout
563 While @code{\paper} contains settings that relate to the page formatting
564 of the whole document, @code{\layout} contains settings for score-specific
571 \override VerticalAxisGroup #'minimum-Y-extent = #'(-6 . 6)
574 \override TextScript #'padding = #1.0
575 \override Glissando #'thickness = #3
583 This manual: @ref{Changing context default settings}.
586 @node Displaying spacing
587 @section Displaying spacing
589 @funindex annotate-spacing
590 @cindex Spacing, display of properties
592 To graphically display the dimensions of vertical properties that may
593 be altered for page formatting, set @code{annotate-spacing} in the
594 @code{\paper} block, like this
597 @c need to have \book{} otherwise we get the separate systems. -hwn
599 #(set-default-paper-size "a6" 'landscape)
603 \paper { annotate-spacing = ##t }
608 @c TODO: really bad vagueness due to bug in annotate-spacing. -gp
610 Some unit dimensions are measured in staff spaces, while others
611 are measured in millimeters.
613 (@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
614 @var{b} the upper edge of the interval.
623 * Optimal page breaking::
624 * Optimal page turning::
625 * Minimal page breaking::
627 * Using an extra voice for breaks::
631 @subsection Line breaking
634 @cindex breaking lines
636 Line breaks are normally determined automatically. They are chosen
637 so that lines look neither cramped nor loose, and consecutive
638 lines have similar density. Occasionally you might want to
639 override the automatic breaks; you can do this by specifying
640 @code{\break}. This will force a line break at this point. However,
641 line breaks can only occur at the end of @q{complete} bars, i.e.,
642 where there are no notes or tuplets left @q{hanging} over the bar
643 line. If you want to have a line break where there is no bar line,
644 you can force an invisible bar line by entering @code{\bar ""},
645 although again there must be no notes left hanging over in any of
646 the staves at this point, or it will be ignored.
648 The opposite command, @code{\noBreak}, forbids a line break at the
649 bar line where it is inserted.
651 The most basic settings influencing line spacing are @code{indent}
652 and @code{line-width}. They are set in the @code{\layout} block.
653 They control the indentation of the first line of music, and the
654 lengths of the lines.
656 If @code{ragged-right} is set to true in the @code{\layout} block,
657 then systems end at their natural horizontal length, instead of
658 being spread horizontally to fill the whole line. This is useful
659 for short fragments, and for checking how tight the natural
662 @c TODO Check and add para on default for ragged-right
664 The option @code{ragged-last} is similar to @code{ragged-right},
665 but affects only the last line of the piece.
677 @cindex regular line breaks
678 @cindex four bar music.
680 For line breaks at regular intervals use @code{\break} separated by
681 skips and repeated with @code{\repeat}. For example, this would
682 cause the following 28 measures (assuming 4/4 time) to be broken
683 every 4 measures, and only there:
686 << \repeat unfold 7 @{
687 s1 \noBreak s1 \noBreak
688 s1 \noBreak s1 \break @}
689 @emph{the real music}
695 @code{\break}, and @code{\noBreak}.
701 Internals: @rinternals{LineBreakEvent}.
704 A linebreaking configuration can be saved as a @code{.ly} file
705 automatically. This allows vertical alignments to be stretched to
706 fit pages in a second formatting run. This is fairly new and
707 complicated. More details are available in
712 Line breaks can only occur if there is a @q{proper} bar line. A note
713 which is hanging over a bar line is not proper, such as
715 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
716 c4 c2 << c2 {s4 \break } >> % this does nothing
717 c2 c4 | % a break here would work
718 c4 c2 c4 ~ \break % as does this break
722 This can be avoided by removing the @code{Forbid_line_break_engraver}.
723 Note that manually forced line breaks have to be added in parallel
726 @lilypond[quote,ragged-right,verbatim]
728 \remove Forbid_line_break_engraver
730 c4 c2 << c2 {s4 \break } >> % now the break is allowed
735 Similarly, line breaks are normally forbidden when beams cross bar
736 lines. This behavior can be changed by setting
737 @code{\override Beam #'breakable = ##t}.
741 @subsection Page breaking
743 The default page breaking may be overridden by inserting
744 @code{\pageBreak} or @code{\noPageBreak} commands. These commands are
745 analogous to @code{\break} and @code{\noBreak}. They should be
746 inserted at a bar line. These commands force and forbid a page-break
747 from happening. Of course, the @code{\pageBreak} command also forces
750 The @code{\pageBreak} and @code{\noPageBreak} commands may also be
751 inserted at top-level, between scores and top-level markups.
753 There are also analogous settings to @code{ragged-right} and
754 @code{ragged-last} which have the same effect on vertical spacing:
755 @code{ragged-bottom} and @code{ragged-last-bottom}. If set to
756 @code{##t} the systems on all pages or just the last page
757 respectively will not be justified vertically.
759 For more details see @ref{Vertical spacing}.
761 Page breaks are computed by the @code{page-breaking} function. LilyPond
762 provides three algorithms for computing page breaks,
763 @code{ly:optimal-breaking}, @code{ly:page-turn-breaking} and
764 @code{ly:minimal-breaking}. The default is @code{ly:optimal-breaking},
765 but the value can be changed in the @code{\paper} block:
769 #(define page-breaking ly:page-turn-breaking)
773 @c TODO Check this -td
774 The old page breaking algorithm is called
775 @code{optimal-page-breaks}. If you are having trouble with the new page
776 breakers, you can enable the old one as a workaround.
782 @funindex \noPageBreak
786 @node Optimal page breaking
787 @subsection Optimal page breaking
789 @funindex ly:optimal-breaking
791 The @code{ly:optimal-breaking} function is LilyPond's default method of
792 determining page breaks. It attempts to find a page breaking that minimizes
793 cramping and stretching, both horizontally and vertically. Unlike
794 @code{ly:page-turn-breaking}, it has no concept of page turns.
797 @node Optimal page turning
798 @subsection Optimal page turning
800 @funindex ly:page-turn-breaking
802 Often it is necessary to find a page breaking configuration so that there is
803 a rest at the end of every second page. This way, the musician can turn the
804 page without having to miss notes. The @code{ly:page-turn-breaking} function
805 attempts to find a page breaking minimizing cramping and stretching, but with
806 the additional restriction that it is only allowed to introduce page turns
809 There are two steps to using this page breaking function. First, you
810 must enable it in the @code{\paper} block, as explained in @ref{Page
811 breaking}. Then you must tell the function where you would like to allow
814 There are two ways to achieve the second step. First, you can specify each
815 potential page turn manually, by inserting @code{\allowPageTurn} into your
816 input file at the appropriate places.
818 If this is too tedious, you can add a @code{Page_turn_engraver} to a Staff or
819 Voice context. The @code{Page_turn_engraver} will scan the context for
820 sections without notes (note that it does not scan for rests; it scans for
821 the absence of notes. This is so that single-staff polyphony with rests in one
822 of the parts does not throw off the @code{Page_turn_engraver}). When it finds
823 a sufficiently long section without notes, the @code{Page_turn_engraver} will
824 insert an @code{\allowPageTurn} at the final bar line in that section, unless
825 there is a @q{special} bar line (such as a double bar), in which case the
826 @code{\allowPageTurn} will be inserted at the final @q{special} bar line in
829 @funindex minimumPageTurnLength
830 The @code{Page_turn_engraver} reads the context property
831 @code{minimumPageTurnLength} to determine how long a note-free section must
832 be before a page turn is considered. The default value for
833 @code{minimumPageTurnLength} is @code{#(ly:make-moment 1 1)}. If you want
834 to disable page turns, you can set it to something very large.
837 \new Staff \with @{ \consists "Page_turn_engraver" @}
840 R1 | % a page turn will be allowed here
842 \set Staff.minimumPageTurnLength = #(ly:make-moment 5 2)
843 R1 | % a page turn will not be allowed here
845 R1*2 | % a page turn will be allowed here
850 @funindex minimumRepeatLengthForPageTurn
851 The @code{Page_turn_engraver} detects volta repeats. It will only allow a page
852 turn during the repeat if there is enough time at the beginning and end of the
853 repeat to turn the page back. The @code{Page_turn_engraver} can also disable
854 page turns if the repeat is very short. If you set the context property
855 @code{minimumRepeatLengthForPageTurn} then the @code{Page_turn_engraver} will
856 only allow turns in repeats whose duration is longer than this value.
858 The page turning commands, @code{\pageTurn}, @code{\noPageTurn} and
859 @code{\allowPageTurn}, may also be used at top-level, between scores and
866 @funindex \noPageTurn
868 @funindex \allowPageTurn
869 @code{\allowPageTurn}
873 There should only be one @code{Page_turn_engraver} in a score. If there is more
874 than one, they will interfere with each other.
876 @node Minimal page breaking
877 @subsection Minimal page breaking
879 @funindex ly:minimal-breaking
881 The @code{ly:minimal-breaking} function performs minimal computations to
882 calculate the page breaking: it fills a page with as many systems as
883 possible before moving to the next one. Thus, it may be preferred for
884 scores with many pages, where the other page breaking functions could be
885 too slow or memory demanding, or a lot of texts. It is enabled using:
889 #(define page-breaking ly:minimal-breaking)
893 @node Explicit breaks
894 @subsection Explicit breaks
896 Lily sometimes rejects explicit @code{\break} and @code{\pageBreak}
897 commands. There are two commands to override this behavior:
900 \override NonMusicalPaperColumn #'line-break-permission = ##f
901 \override NonMusicalPaperColumn #'page-break-permission = ##f
904 When @code{line-break-permission} is overridden to false, Lily will insert
905 line breaks at explicit @code{\break} commands and nowhere else. When
906 @code{page-break-permission} is overridden to false, Lily will insert
907 page breaks at explicit @code{\pageBreak} commands and nowhere else.
909 @lilypond[quote,verbatim]
918 \override NonMusicalPaperColumn #'line-break-permission = ##f
919 \override NonMusicalPaperColumn #'page-break-permission = ##f
922 \repeat unfold 2 { c'8 c'8 c'8 c'8 } \break
923 \repeat unfold 4 { c'8 c'8 c'8 c'8 } \break
924 \repeat unfold 6 { c'8 c'8 c'8 c'8 } \break
925 \repeat unfold 8 { c'8 c'8 c'8 c'8 } \pageBreak
926 \repeat unfold 8 { c'8 c'8 c'8 c'8 } \break
927 \repeat unfold 6 { c'8 c'8 c'8 c'8 } \break
928 \repeat unfold 4 { c'8 c'8 c'8 c'8 } \break
929 \repeat unfold 2 { c'8 c'8 c'8 c'8 }
936 @node Using an extra voice for breaks
937 @subsection Using an extra voice for breaks
939 Line- and page-breaking information usually appears within note entry directly.
944 \repeat unfold 2 @{ c'4 c'4 c'4 c'4 @}
946 \repeat unfold 3 @{ c'4 c'4 c'4 c'4 @}
951 This makes @code{\break} and @code{\pageBreak} commands easy to enter but mixes
952 music entry with information that specifies how music should lay out
953 on the page. You can keep music entry and line- and page-breaking
954 information in two separate places by introducing an extra voice to
955 contain the breaks. This extra voice
956 contains only skips together with @code{\break}, @code{pageBreak} and other
957 breaking layout information.
959 @lilypond[quote,verbatim]
969 \repeat unfold 2 { c'4 c'4 c'4 c'4 }
970 \repeat unfold 3 { c'4 c'4 c'4 c'4 }
971 \repeat unfold 6 { c'4 c'4 c'4 c'4 }
972 \repeat unfold 5 { c'4 c'4 c'4 c'4 }
978 This pattern becomes especially helpful when overriding
979 @code{line-break-system-details} and the other useful but long properties of
980 @code{NonMusicalPaperColumnGrob}, as explained in @ref{Vertical spacing}.
982 @lilypond[quote,verbatim]
987 \overrideProperty "Score.NonMusicalPaperColumn"
988 #'line-break-system-details #'((Y-offset . 0))
991 \overrideProperty "Score.NonMusicalPaperColumn"
992 #'line-break-system-details #'((Y-offset . 35))
995 \overrideProperty "Score.NonMusicalPaperColumn"
996 #'line-break-system-details #'((Y-offset . 70))
999 \overrideProperty "Score.NonMusicalPaperColumn"
1000 #'line-break-system-details #'((Y-offset . 105))
1004 \repeat unfold 2 { c'4 c'4 c'4 c'4 }
1005 \repeat unfold 3 { c'4 c'4 c'4 c'4 }
1006 \repeat unfold 6 { c'4 c'4 c'4 c'4 }
1007 \repeat unfold 5 { c'4 c'4 c'4 c'4 }
1014 @node Vertical spacing
1015 @section Vertical spacing
1017 @cindex vertical spacing
1018 @cindex spacing, vertical
1020 Vertical spacing is controlled by three things: the amount of
1021 space available (i.e., paper size and margins), the amount of
1022 space between systems, and the amount of space between
1023 staves inside a system.
1026 * Vertical spacing inside a system::
1027 * Vertical spacing between systems::
1028 * Explicit staff and system positioning::
1029 * Two-pass vertical spacing::
1030 * Vertical collision avoidance::
1034 @node Vertical spacing inside a system
1035 @subsection Vertical spacing inside a system
1037 @cindex distance between staves
1038 @cindex staff distance
1039 @cindex space between staves
1040 @cindex space inside systems
1042 The height of each system is determined automatically. To prevent
1043 staves from bumping into each other, some minimum distances are set.
1044 By changing these, you can put staves closer together. This
1045 reduces the amount of space each system requires, and may result
1046 in having more systems per page.
1048 Normally staves are stacked vertically. To make staves maintain a
1049 distance, their vertical size is padded. This is done with the
1050 property @code{minimum-Y-extent}. When applied to a
1051 @rinternals{VerticalAxisGroup}, it controls the size of a horizontal
1052 line, such as a staff or a line of lyrics. @code{minimum-Y-extent}
1053 takes a pair of numbers, so
1054 if you want to make it smaller than its default @code{#'(-4 . 4)}
1058 \override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
1062 This sets the vertical size of the current staff to 3 staff spaces on
1063 either side of the center staff line. The value @code{(-3 . 3)} is
1064 interpreted as an interval, where the center line is the 0, so the
1065 first number is generally negative. The numbers need not match;
1066 for example, the staff can be made larger at the bottom by setting
1067 it to @code{(-6 . 4)}.
1069 After page breaks are determined, the vertical spacing within each
1070 system is reevaluated in order to fill the page more evenly; if a page
1071 has space left over, systems are stretched in order to fill that space.
1072 The amount of stretching can be configured though the @code{max-stretch}
1073 property of the @rinternals{VerticalAlignment} grob. By default,
1074 @code{max-stretch} is set to zero, disabling stretching. To enable
1075 stretching, a sane value for @code{max-stretch}
1076 is @code{ly:align-interface::calc-max-stretch}.
1078 In some situations, you may want to stretch most of a system while
1079 leaving some parts fixed. For example, if a piano part occurs in the
1080 middle of an orchestral score, you may want to leave the piano staves
1081 close to each other while stretching the rest of the score. The
1082 @code{keep-fixed-while-stretching} property of
1083 @rinternals{VerticalAxisGroup} can be used to achieve this. When set
1084 to @code{##t}, this property keeps its staff (or line of lyrics) from
1085 moving relative to the one directly above it. In the example above,
1086 you would override @code{keep-fixed-while-stretching} to @code{##t} in
1087 the second piano staff:
1090 #(set-default-paper-size "a6")
1091 #(set-global-staff-size 14.0)
1095 ragged-last-bottom = ##f
1100 \override VerticalAlignment #'max-stretch = #ly:align-interface::calc-max-stretch
1107 \new Staff {c' d' e' f'}
1108 \new Staff {c' d' e' f'}
1109 \new Staff {c' d' e' f'}
1114 \new Staff {c' d' e' f'}
1116 \override VerticalAxisGroup #'keep-fixed-while-stretching = ##t
1123 \new Staff {c' d' e' f'}
1124 \new Staff {c' d' e' f'}
1133 Internals: Vertical alignment of staves is handled by the
1134 @rinternals{VerticalAlignment} object. The context parameters
1135 specifying the vertical extent are described in connection with
1136 the @rinternals{Axis_group_engraver}.
1138 Example files: @c @lsr{spacing,page-spacing.ly},
1139 @c @lsr{spacing,alignment-vertical-spacing.ly}.
1142 @node Vertical spacing between systems
1143 @subsection Vertical spacing between systems
1145 Space between systems are controlled by four @code{\paper} variables,
1149 between-system-space = 1.5\cm
1150 between-system-padding = #1
1152 ragged-last-bottom=##f
1156 When only a couple of flat systems are placed on a page, the resulting
1157 vertical spacing may be non-elegant: one system at the top of the page,
1158 and the other at the bottom, with a huge gap between them. To avoid this
1159 situation, the space added between the systems can be limited. This
1160 feature is activated by setting to @code{#t} the
1161 @code{page-limit-inter-system-space} variable in the @code{\paper}
1162 block. The paper variable @code{page-limit-inter-system-space-factor}
1163 determines how much the space can be increased: for instance, the value
1164 @code{1.3} means that the space can be 30% larger than what it would be
1165 on a ragged-bottom page.
1167 In the following example, if the inter system space were not limited,
1168 the second system of page 1 would be placed at the page bottom. By
1169 activating the space limitation, the second system is placed closer to
1170 the first one. By setting @code{page-limit-inter-system-space-factor} to
1171 @code{1}, the spacing would the same as on a ragged-bottom page, like
1175 #(set-default-paper-size "a6")
1178 page-limit-inter-system-space = ##t
1179 page-limit-inter-system-space-factor = 1.3
1181 oddFooterMarkup = \markup "page bottom"
1182 evenFooterMarkup = \markup "page bottom"
1183 oddHeaderMarkup = \markup \fill-line {
1184 "page top" \fromproperty #'page:page-number-string }
1185 evenHeaderMarkup = \markup \fill-line {
1186 "page top" \fromproperty #'page:page-number-string }
1188 \new Staff << \repeat unfold 4 { g'4 g' g' g' \break }
1189 { s1*2 \pageBreak } >>
1193 @node Explicit staff and system positioning
1194 @subsection Explicit staff and system positioning
1196 One way to understand the @code{VerticalAxisGroup} and @code{\paper}
1197 settings explained in the previous two sections is as a collection of
1198 different settings that primarily concern the amount of vertical padding
1199 different staves and systems running down the page.
1201 It is possible to approach vertical spacing in a different way using
1202 @code{NonMusicalPaperColumn #'line-break-system-details}. Where
1203 @code{VerticalAxisGroup} and @code{\paper} settings specify vertical padding,
1204 @code{NonMusicalPaperColumn #'line-break-system-details} specifies exact
1205 vertical positions on the page.
1207 @code{NonMusicalPaperColumn #'line-break-system-details} accepts an associative
1208 list of five different settings:
1211 @item @code{X-offset}
1212 @item @code{Y-offset}
1213 @item @code{alignment-offsets}
1214 @item @code{alignment-extra-space}
1215 @item @code{fixed-alignment-extra-space}
1218 Grob overrides, including the overrides for @code{NonMusicalPaperColumn}
1219 below, can occur in any of three different places in an input file:
1222 @item in the middle of note entry directly
1223 @item in a @code{\context} block
1224 @item in the @code{\with} block
1227 When we override @code{NonMusicalPaperColumn}, we use the usual
1228 @code{\override} command in @code{\context} blocks and in the
1229 @code{\with} block. On the other hand, when we override
1230 @code{NonMusicalPaperColumn} in the middle of note entry,
1231 use the special @code{\overrideProperty} command. Here are some
1232 example @code{NonMusicalPaperColumn} overrides with the special
1233 @code{\overrideProperty} command:
1236 \overrideProperty NonMusicalPaperColumn
1237 #'line-break-system-details #'((X-offset . 20))
1239 \overrideProperty NonMusicalPaperColumn
1240 #'line-break-system-details #'((Y-offset . 40))
1242 \overrideProperty NonMusicalPaperColumn
1243 #'line-break-system-details #'((X-offset . 20) (Y-offset . 40))
1245 \override NonMusicalPaperColumn
1246 #'line-break-system-details #'((alignment-offsets . (0 -15)))
1248 \override NonMusicalPaperColumn
1249 #'line-break-system-details #'((X-offset . 20) (Y-offset . 40)
1250 (alignment-offsets . (0 -15)))
1253 To understand how each of these different settings work, we begin
1254 by looking at an example that includes no overrides at all.
1256 @lilypond[quote,ragged-right]
1264 \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
1267 \repeat unfold 18 { d'4 d'4 d'4 d'4 }
1272 This score isolates line- and page-breaking information in a dedicated
1273 voice. This technique of creating a breaks voice will help keep layout
1274 separate from music entry as our example becomes more complicated.
1275 See @ref{Using an extra voice for breaks}.
1277 Explicit @code{\breaks} evenly divide the music into six measures per
1278 line. Vertical spacing results from LilyPond's defaults. To set
1279 the vertical startpoint of each system explicitly, we can set
1280 the @code{Y-offset} pair in the @code{line-break-system-details}
1281 attribute of the @code{NonMusicalPaperColumn} grob:
1283 @lilypond[quote,ragged-right]
1287 \overrideProperty #"Score.NonMusicalPaperColumn"
1288 #'line-break-system-details #'((Y-offset . 0))
1290 \overrideProperty #"Score.NonMusicalPaperColumn"
1291 #'line-break-system-details #'((Y-offset . 40))
1293 \overrideProperty #"Score.NonMusicalPaperColumn"
1294 #'line-break-system-details #'((Y-offset . 80))
1297 \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
1300 \repeat unfold 18 { d'4 d'4 d'4 d'4 }
1305 Note that @code{line-break-system-details} takes an associative list of
1306 potentially many values, but that we set only one value here. Note,
1307 too, that the @code{Y-offset} property here determines the exact vertical
1308 position on the page at which each new system will render.
1310 Now that we have set the vertical startpoint of each system
1311 explicitly, we can also set the vertical startpoint of each staff
1312 within each system manually. We do this using the @code{alignment-offsets}
1313 subproperty of @code{line-break-system-details}.
1315 @lilypond[quote,ragged-right]
1319 \overrideProperty #"Score.NonMusicalPaperColumn"
1320 #'line-break-system-details #'((Y-offset . 20)
1321 (alignment-offsets . (0 -15)))
1323 \overrideProperty #"Score.NonMusicalPaperColumn"
1324 #'line-break-system-details #'((Y-offset . 60)
1325 (alignment-offsets . (0 -15)))
1327 \overrideProperty #"Score.NonMusicalPaperColumn"
1328 #'line-break-system-details #'((Y-offset . 100)
1329 (alignment-offsets . (0 -15)))
1332 \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
1335 \repeat unfold 18 { d'4 d'4 d'4 d'4 }
1340 Note that here we assign two different values to the
1341 @code{line-break-system-details} attribute of the
1342 @code{NonMusicalPaperColumn} grob. Though the
1343 @code{line-break-system-details} attribute alist accepts many
1344 additional spacing parameters (including, for example, a corresponding
1345 @code{X-offset} pair), we need only set the @code{Y-offset} and
1346 @code{alignment-offsets} pairs to control the vertical startpoint of
1347 every system and every staff. Finally, note that @code{alignment-offsets}
1348 specifies the vertical positioning of staves but not of staff groups.
1350 @lilypond[quote,ragged-right]
1354 \overrideProperty #"Score.NonMusicalPaperColumn"
1355 #'line-break-system-details #'((Y-offset . 0)
1356 (alignment-offsets . (0 -30 -40)))
1358 \overrideProperty #"Score.NonMusicalPaperColumn"
1359 #'line-break-system-details #'((Y-offset . 60)
1360 (alignment-offsets . (0 -10 -20)))
1362 \overrideProperty #"Score.NonMusicalPaperColumn"
1363 #'line-break-system-details #'((Y-offset . 100)
1364 (alignment-offsets . (0 -10, -40)))
1367 \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
1371 \repeat unfold 18 { d'4 d'4 d'4 d'4 }
1374 \repeat unfold 18 { e'4 e'4 e'4 e'4 }
1380 Some points to consider:
1383 @item When using @code{alignment-offsets}, lyrics count as a staff.
1385 @item The units of the numbers passed to @code{X-offset},
1386 @code{Y-offset} and @code{alignment-offsets} are interpreted as multiples
1387 of the distance between adjacent staff lines. Positive values move staves
1388 and lyrics up, negative values move staves and lyrics down.
1390 @item Because the @code{NonMusicalPaperColumn #'line-break-system-details}
1391 settings given here allow the positioning of staves and systems anywhere
1392 on the page, it is possible to violate paper or margin boundaries or even
1393 to print staves or systems on top of one another. Reasonable values
1394 passed to these different settings will avoid this.
1398 @node Two-pass vertical spacing
1399 @subsection Two-pass vertical spacing
1401 Warning: two-pass vertical spacing is deprecated and will be removed in
1402 a future version of LilyPond. Systems are now stretched automatically
1403 in a single pass. See @ref{Vertical spacing inside a system}.
1405 In order to automatically stretch systems so that they should fill the
1406 space left on a page, a two-pass technique can be used:
1409 @item In the first pass, the amount of vertical space used to increase
1410 the height of each system is computed and dumped to a file.
1411 @item In the second pass, spacing inside the systems are
1412 stretched according to the data in the page layout file.
1415 The @code{ragged-bottom} property adds space between systems, while
1416 the two-pass technique adds space between staves inside a system.
1418 To allow this behavior, a @code{tweak-key} variable has to be set in
1419 each score @code{\layout} block, and the tweaks included in each score
1420 music, using the @code{\scoreTweak} music function.
1424 %% include the generated page layout file:
1425 \includePageLayoutFile
1430 %% Include this score tweaks:
1431 \scoreTweak "scoreA"
1432 { \clef french c''1 \break c''1 }
1434 \new Staff { \clef soprano g'1 g'1 }
1435 \new Staff { \clef mezzosoprano e'1 e'1 }
1436 \new Staff { \clef alto g1 g1 }
1437 \new Staff { \clef bass c1 c1 }
1440 piece = "Score with tweaks"
1442 %% Define how to name the tweaks for this score:
1443 \layout { #(define tweak-key "scoreA") }
1448 For the first pass, the @code{dump-tweaks} option should be set to
1449 generate the page layout file.
1452 lilypond -dbackend=null -d dump-tweaks <file>.ly
1457 @node Vertical collision avoidance
1458 @subsection Vertical collision avoidance
1460 @funindex outside-staff-priority
1461 @funindex outside-staff-padding
1462 @funindex outside-staff-horizontal-padding
1464 Intuitively, there are some objects in musical notation that belong
1465 to the staff and there are other objects that should be placed outside
1466 the staff. Objects belonging outside the staff include things such as
1467 rehearsal marks, text and dynamic markings (from now on, these will
1468 be called outside-staff objects). LilyPond's rule for the
1469 vertical placement of outside-staff objects is to place them as close
1470 to the staff as possible but not so close that they collide with
1473 LilyPond uses the @code{outside-staff-priority} property to determine
1474 whether a grob is an outside-staff object: if @code{outside-staff-priority}
1475 is a number, the grob is an outside-staff object. In addition,
1476 @code{outside-staff-priority} tells LilyPond in which order the objects
1479 First, LilyPond places all the objects that do not belong outside
1480 the staff. Then it sorts the outside-staff objects according to their
1481 @code{outside-staff-priority} (in increasing order). One by one, LilyPond
1482 takes the outside-staff objects and places them so that they do
1483 not collide with any objects that have already been placed. That
1484 is, if two outside-staff grobs are competing for the same space, the one
1485 with the lower @code{outside-staff-priority} will be placed closer to
1488 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1491 \once \override TextScript #'outside-staff-priority = #1
1492 c4_"Text"\pp % this time the text will be closer to the staff
1494 % by setting outside-staff-priority to a non-number,
1495 % we disable the automatic collision avoidance
1496 \once \override TextScript #'outside-staff-priority = ##f
1497 \once \override DynamicLineSpanner #'outside-staff-priority = ##f
1498 c4_"Text"\pp % now they will collide
1501 The vertical padding between an outside-staff object and the
1502 previously-positioned grobs can be controlled with
1503 @code{outside-staff-padding}.
1505 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1506 \once \override TextScript #'outside-staff-padding = #0
1507 a'^"This text is placed very close to the note"
1508 \once \override TextScript #'outside-staff-padding = #3
1509 c^"This text is padded away from the previous text"
1510 c^"This text is placed close to the previous text"
1513 TODO: this example doesn't work any more ?
1515 By default, outside-staff objects are placed without regard to
1516 their horizontal distance from the previously-positioned grobs. This
1517 can lead to situations in which objects are placed very close to each
1518 other horizontally. Setting @code{outside-staff-horizontal-padding}
1519 causes an object to be offset vertically so that such a situation
1522 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1523 % the markup is too close to the following note
1526 % setting outside-staff-horizontal-padding fixes this
1528 \once \override TextScript #'outside-staff-horizontal-padding = #1
1535 @node Horizontal spacing
1536 @section Horizontal Spacing
1538 @cindex horizontal spacing
1539 @cindex spacing, horizontal
1542 * Horizontal spacing overview::
1543 * New spacing area::
1544 * Changing horizontal spacing::
1546 * Proportional notation::
1550 @node Horizontal spacing overview
1551 @subsection Horizontal spacing overview
1553 The spacing engine translates differences in durations into stretchable
1554 distances (@q{springs}) of differing lengths. Longer durations get
1555 more space, shorter durations get less. The shortest durations get a
1556 fixed amount of space (which is controlled by
1557 @code{shortest-duration-space} in the @rinternals{SpacingSpanner}
1558 object). The longer the duration, the more space it gets: doubling a
1559 duration adds a fixed amount (this amount is controlled by
1560 @code{spacing-increment}) of space to the note.
1562 For example, the following piece contains lots of half, quarter, and
1563 8th notes; the eighth note is followed by 1 note head width (NHW).
1564 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
1566 @lilypond[quote,fragment,verbatim,relative=1]
1567 c2 c4. c8 c4. c8 c4. c8 c8
1571 Normally, @code{spacing-increment} is set to 1.2 staff space, which is
1572 approximately the width of a note head, and
1573 @code{shortest-duration-space} is set to 2.0, meaning that the
1574 shortest note gets 2.4 staff space (2.0 times the
1575 @code{spacing-increment}) of horizontal space. This space is counted
1576 from the left edge of the symbol, so the shortest notes are generally
1577 followed by one NHW of space.
1579 If one would follow the above procedure exactly, then adding a single
1580 32nd note to a score that uses 8th and 16th notes, would widen up the
1581 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
1582 thus adding 1 NHW to every note. To prevent this, the shortest
1583 duration for spacing is not the shortest note in the score, but rather
1584 the one which occurs most frequently.
1587 The most common shortest duration is determined as follows: in every
1588 measure, the shortest duration is determined. The most common shortest
1589 duration is taken as the basis for the spacing, with the stipulation
1590 that this shortest duration should always be equal to or shorter than
1591 an 8th note. The shortest duration is printed when you run
1592 @code{lilypond} with the @code{--verbose} option.
1594 These durations may also be customized. If you set the
1595 @code{common-shortest-duration} in @rinternals{SpacingSpanner}, then
1596 this sets the base duration for spacing. The maximum duration for this
1597 base (normally an 8th), is set through @code{base-shortest-duration}.
1599 @funindex common-shortest-duration
1600 @funindex base-shortest-duration
1601 @funindex stem-spacing-correction
1604 Notes that are even shorter than the common shortest note are
1605 followed by a space that is proportional to their duration relative to
1606 the common shortest note. So if we were to add only a few 16th notes
1607 to the example above, they would be followed by half a NHW:
1609 @lilypond[quote,fragment,verbatim,relative=2]
1610 c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
1614 In the introduction (see @rlearning{Engraving}), it was explained that stem
1615 directions influence spacing. This is controlled with the
1616 @code{stem-spacing-correction} property in the
1617 @rinternals{NoteSpacing}, object. These are generated for every
1618 @rinternals{Voice} context. The @code{StaffSpacing} object
1619 (generated in @rinternals{Staff} context) contains the same property
1620 for controlling the stem/bar line spacing. The following example shows
1621 these corrections, once with default settings, and once with
1622 exaggerated corrections:
1624 @lilypond[quote,ragged-right]
1628 \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
1629 \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
1635 Proportional notation is supported; see @ref{Proportional notation}.
1640 Internals: @rinternals{SpacingSpanner}, @rinternals{NoteSpacing},
1641 @rinternals{StaffSpacing}, @rinternals{SeparationItem}, and
1642 @rinternals{SeparatingGroupSpanner}.
1647 There is no convenient mechanism to manually override spacing. The
1648 following work-around may be used to insert extra space into a score.
1650 \once \override Score.SeparationItem #'padding = #1
1653 No work-around exists for decreasing the amount of space.
1656 @node New spacing area
1657 @subsection New spacing area
1659 New sections with different spacing parameters can be started with
1660 @code{newSpacingSection}. This is useful when there are
1661 sections with a different notions of long and short notes.
1663 In the following example, the time signature change introduces a new
1664 section, and hence the 16ths notes are spaced wider.
1666 @lilypond[relative,fragment,verbatim,quote]
1669 c8 c c4 c16[ c c8] c4
1676 The @code{\newSpacingSection} command creates a new
1677 @rinternals{SpacingSpanner} object, and hence new @code{\override}s
1678 may be used in that location.
1681 @node Changing horizontal spacing
1682 @subsection Changing horizontal spacing
1684 Horizontal spacing may be altered with the
1685 @code{base-shortest-duration} property. Here
1686 we compare the same music; once without altering
1687 the property, and then altered. Larger values
1688 of @code{ly:make-moment} will produce smaller
1689 music. Note that @code{ly:make-moment} constructs
1690 a duration, so @code{1 4} is a longer duration
1693 @lilypond[verbatim,line-width=12\cm]
1696 g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
1697 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
1698 d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
1699 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
1704 @lilypond[verbatim,line-width=12\cm]
1707 g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
1708 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
1709 d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
1710 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
1715 \override SpacingSpanner
1716 #'base-shortest-duration = #(ly:make-moment 1 16)
1725 By default, spacing in tuplets depends on various non-duration
1726 factors (such as accidentals, clef changes, etc). To disregard
1727 such symbols and force uniform equal-duration spacing, use
1728 @code{Score.SpacingSpanner #'uniform-stretching}. This
1729 property can only be changed at the beginning of a score,
1731 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1733 \override SpacingSpanner #'uniform-stretching = ##t
1751 When @code{strict-note-spacing} is set, notes are spaced without
1752 regard for clefs, bar lines, and grace notes,
1754 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1755 \override Score.SpacingSpanner #'strict-note-spacing = ##t
1756 \new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c] c32[ c32] }
1761 @subsection Line length
1764 @cindex breaking pages
1767 @funindex line-width
1768 @funindex ragged-right
1769 @funindex ragged-last
1771 @c Although line-width can be set in \layout, it should be set in paper
1772 @c block, to get page layout right.
1773 @c Setting indent in \paper block makes not much sense, but it works.
1775 @c Bit verbose and vague, use examples?
1776 The most basic settings influencing the spacing are @code{indent} and
1777 @code{line-width}. They are set in the @code{\layout} block. They
1778 control the indentation of the first line of music, and the lengths of
1781 If @code{ragged-right} is set to true in the @code{\layout} block, then
1782 systems ends at their natural horizontal length, instead of being spread
1783 horizontally to fill the whole line. This is useful for
1784 short fragments, and for checking how tight the natural spacing is.
1787 @cindex vertical spacing
1789 The option @code{ragged-last} is similar to @code{ragged-right}, but
1790 only affects the last line of the piece. No restrictions are put on
1791 that line. The result is similar to formatting text paragraphs. In a
1792 paragraph, the last line simply takes its natural horizontal length.
1793 @c Note that for text there are several options for the last line.
1794 @c While Knuth TeX uses natural length, lead typesetters use the same
1795 @c stretch as the previous line. eTeX uses \lastlinefit to
1796 @c interpolate between both these solutions.
1807 @node Proportional notation
1808 @subsection Proportional notation
1810 LilyPond supports proportional notation, a type of horizontal spacing
1811 in which each note consumes an amount of horizontal space exactly
1812 equivalent to its rhythmic duration. This type of proportional spacing
1813 is comparable to horizontal spacing on top of graph paper. Some late
1814 20th- and early 21st-century scores use proportional notation to
1815 clarify complex rhythmic relationships or to facilitate the placement
1816 of timelines or other graphics directly in the score.
1818 LilyPond supports five different settings for proportional notation,
1819 which may be used together or alone:
1822 @item @code{proportionalNotationDuration}
1823 @item @code{uniform-stretching}
1824 @item @code{strict-note-spacing}
1825 @item @code{\remove Separating_line_group_engraver}
1826 @item @code{\override PaperColumn #'used = ##t}
1829 In the examples that follow, we explore these five different
1830 proportional notation settings and examine how these settings interact.
1832 We start with the following one-measure example, which uses classical
1833 spacing with ragged-right turned on.
1835 @lilypond[quote,verbatim,ragged-right]
1837 \new RhythmicStaff {
1841 c'16 c'16 c'16 c'16 c'16
1847 Notice that the half note which begins the measure takes up far less
1848 than half of the horizontal space of the measure. Likewise, the
1849 sixteenth notes and sixteenth-note quintuplets (or twentieth notes)
1850 which end the measure together take up far more than half the
1851 horizontal space of the measure.
1853 In classical engraving, this spacing may be exactly what we want
1854 because we can borrow horizontal space from the half note and conserve
1855 horizontal space across the measure as a whole.
1857 On the other hand, if we want to insert a measured timeline or other
1858 graphic above or below our score, we need proportional notation. We
1859 turn proportional notation on with the proportionalNotationDuration
1862 @lilypond[quote,verbatim,ragged-right]
1864 proportionalNotationDuration = #(ly:make-moment 1 20)
1866 \new RhythmicStaff {
1870 c'16 c'16 c'16 c'16 c'16
1876 The half note at the beginning of the measure and the faster notes in
1877 the second half of the measure now occupy equal amounts of horizontal
1878 space. We could place a measured timeline or graphic above or below
1881 The @code{proportionalNotationDuration} setting is a context setting that
1882 lives in @code{Score}. Recall that context settings appear in one of
1883 three locations in our input file -- in a @code{\with} block, in a
1884 @code{\context} block, or directly in music entry
1885 preceded by the @code{\set} command. As with all
1886 context settings, users can pick which of the three different
1887 locations they would like to set @code{proportionalNotationDuration}.
1889 The @code{proportionalNotationDuration} setting takes a single argument,
1890 which is the reference duration against which all music will be
1891 spaced. The LilyPond Scheme function make-moment takes two arguments
1892 -- a numerator and denominator which together express some fraction of
1893 a whole note. The call @code{#(ly:make-moment 1 20)} therefore produces a
1894 reference duration of a twentieth note. The values
1895 @code{#(ly:make-moment 1 16)}, @code{#(ly:make-moment 1 8)}, and
1896 @code{#(ly:make-moment 3 97)} are all possible as well.
1898 How do we select the right reference duration to pass to
1899 @code{proportionalNotationDuration}? Usually by a process of trial and error,
1900 beginning with a duration close to the fastest (or smallest) duration
1901 in the piece. Smaller reference durations space music loosely; larger
1902 reference durations space music tightly.
1904 @lilypond[quote,verbatim,ragged-right]
1906 proportionalNotationDuration = #(ly:make-moment 1 8)
1908 \new RhythmicStaff {
1912 c'16 c'16 c'16 c'16 c'16
1918 proportionalNotationDuration = #(ly:make-moment 1 16)
1920 \new RhythmicStaff {
1924 c'16 c'16 c'16 c'16 c'16
1930 proportionalNotationDuration = #(ly:make-moment 1 32)
1932 \new RhythmicStaff {
1936 c'16 c'16 c'16 c'16 c'16
1942 Note that too large a reference duration -- such as the eighth note,
1943 above -- spaces music too tightly and can cause note head collisions.
1944 Note also that proportional notation in general takes up more
1945 horizontal space that does classical spacing. Proportional spacing
1946 provides rhythmic clarity at the expense of horizontal space.
1948 Next we examine how to optimally space overlapping tuplets.
1950 We start by examining what happens to our original example, with
1951 classical spacing, when we add a second staff with a different type of
1954 @lilypond[quote,verbatim,ragged-right]
1956 \new RhythmicStaff {
1960 c'16 c'16 c'16 c'16 c'16
1963 \new RhythmicStaff {
1965 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
1971 The spacing is bad because the evenly notes of the bottom staff do not
1972 stretch uniformly. Classical engraving includes very few complex
1973 triplets and so classical engraving rules can generate this type of
1974 result. Setting @code{proportionalNotationDuration} remedies this
1975 situation considerably.
1977 @lilypond[quote,verbatim,ragged-right]
1979 proportionalNotationDuration = #(ly:make-moment 1 20)
1981 \new RhythmicStaff {
1985 c'16 c'16 c'16 c'16 c'16
1988 \new RhythmicStaff {
1990 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
1996 But if we look very carefully we can see that notes of the second half
1997 of the 9-tuplet space ever so slightly more widely than do the notes
1998 of the first half of the 9-tuplet. To ensure uniform stretching, we
1999 turn on @code{uniform-stretching}, which is a property of
2000 @code{SpacingSpanner}.
2002 @lilypond[quote,verbatim,ragged-right]
2004 proportionalNotationDuration = #(ly:make-moment 1 20)
2005 \override SpacingSpanner #'uniform-stretching = ##t
2007 \new RhythmicStaff {
2011 c'16 c'16 c'16 c'16 c'16
2014 \new RhythmicStaff {
2016 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
2022 Our two-staff example now spaces exactly, our rhythmic
2023 relationships are visually clear, and we can include a measured
2024 timeline or graphic if we want.
2026 Note that the LilyPond's proportional notation package expects
2027 that all proportional scores set the SpacingSpanner's
2028 'uniform-stretching attribute to ##t. Setting
2029 proportionalNotationDuration without also setting the
2030 SpacingSpanner's 'uniform-stretching attribute to ##t will, for
2031 example, cause Skips to consume an incorrect amount of horizontal
2034 The SpacingSpanner is an abstract grob that lives in the Score
2035 context. As with our settings of proportionalNotationDuration,
2036 overrides to the SpacingSpanner can occur in any of three
2037 different places in our input file – in the Score \with block, in
2038 a Score \context block, or in note entry directly.
2040 There is by default only one @code{SpacingSpanner} per @code{Score}. This
2041 means that, by default, @code{uniform-stretching} is either turned on for the
2042 entire score or turned off for the entire score. We can, however,
2043 override this behavior and turn on different spacing features at
2044 different places in the score. We do this with the command
2045 @code{\newSpacingSection}. See @ref{New spacing area}, for more info.
2047 Next we examine the effects of the @code{Separating_line_group_engraver} and
2048 see why proportional scores frequently remove this engraver. The following
2049 example shows that there is a small amount of @qq{preferatory} space
2050 just before the first note in each system.
2052 @lilypond[quote,verbatim,ragged-right]
2065 The amount of this preferatory space is the same whether after a time
2066 signature, a key signature or a clef. @code{Separating_line_group_engraver}
2067 is responsible for this space. Removing @code{Separating_line_group_engraver}
2068 reduces this space to zero.
2070 @lilypond[quote,verbatim,ragged-right]
2076 \remove Separating_line_group_engraver
2084 Nonmusical elements like time signatures, key signatures, clefs and
2085 accidentals are problematic in proportional notation. None of these
2086 elements has rhythmic duration. But all of these elements consume
2087 horizontal space. Different proportional scores approach these
2088 problems differently.
2090 It may be possible to avoid spacing problems with key signatures
2091 simply by not having any. This is a valid option since most
2092 proportional scores are contemporary music. The same may be true
2093 of time signatures, especially for those scores
2094 that include a measured timeline or other graphic. But these scores
2095 are exceptional and most proportional scores include at least some
2096 time signatures. Clefs and accidentals are even more essential.
2098 So what strategies exist for spacing nonmusical elements in a
2099 proportional context? One good option is the @code{strict-note-spacing}
2100 property of @code{SpacingSpanner}. Compare the two scores below:
2102 @lilypond[quote,verbatim,ragged-right]
2104 \set Score.proportionalNotationDuration = #(ly:make-moment 1 16)
2114 \set Score.proportionalNotationDuration = #(ly:make-moment 1 16)
2115 \override Score.SpacingSpanner #'strict-note-spacing = ##t
2125 Both scores are proportional, but the spacing in the first score
2126 is too loose because of the clef change. The spacing of the second
2127 score remains strict, however, because strict-note-spacing is
2128 turned on. Turning on strict-note-spacing causes the width of
2129 time signatures, key signatures, clefs and accidentals to play no
2130 part in the spacing algorithm.
2132 In addition to the settings given here, there are other settings
2133 that frequently appear in proportional scores. These include:
2136 @item @code{\override SpacingSpanner #'strict-grace-spacing = ##t}
2137 @item @code{tupletFullLength = ##t}
2138 @item @code{\override Beam #'breakable = ##t}
2139 @item @code{\override Glissando #'breakable = ##t}
2140 @item @code{\override TextSpanner #'breakable = ##t}
2141 @item @code{\remove Forbid_line_break_engraver in the Voice context}
2144 These settings space grace notes strictly, extend tuplet brackets to
2145 mark both rhythmic start- and stop-points, and allow spanning elements
2146 to break across systems and pages. See the respective parts of the manual
2147 for these related settings.
2150 @node Fitting music onto fewer pages
2151 @section Fitting music onto fewer pages
2153 Sometimes you can end up with one or two staves on a second
2154 (or third, or fourth...) page. This is annoying, especially
2155 if you look at previous pages and it looks like there is plenty
2156 of room left on those.
2158 When investigating layout issues, @code{annotate-spacing} is
2159 an invaluable tool. This command prints the values of various
2160 layout spacing commands; see @ref{Displaying spacing}, for more
2161 details. From the output of @code{annotate-spacing}, we can
2162 see which margins we may wish to alter.
2164 Other than margins, there are a few other options to save space:
2168 You may tell LilyPond to place systems as close together as
2169 possible (to fit as many systems as possible onto a page), but
2170 then to space those systems out so that there is no blank
2171 space at the bottom of the page.
2175 between-system-padding = #0.1
2176 between-system-space = #0.1
2177 ragged-last-bottom = ##f
2183 You may force the number of systems (i.e., if LilyPond wants
2184 to typeset some music with 11 systems, you could force it to
2194 Avoid (or reduce) objects which increase the vertical size of
2195 a system. For example, volta repeats (or alternate repeats)
2196 require extra space. If these repeats are spread over two
2197 systems, they will take up more space than one system with
2198 the volta repeats and another system without.
2200 Another example is moving dynamics which @q{stick out} of
2201 a system, as in the second bar here:
2203 @lilypond[verbatim,quote,fragment,ragged-right,relative=1]
2205 \override DynamicText #'extra-offset = #'( -2.2 . 2.0)
2210 Alter the horizontal spacing via @code{SpacingSpanner}. See
2211 @ref{Changing horizontal spacing}, for more details. Here's
2212 an example first showing the default behavior:
2214 @lilypond[verbatim,quote,ragged-right]
2227 and now with @code{common-shortest-duration} increased from the
2228 value of @code{1/4} (a quarter note is the most common in this
2229 example) to @code{1/2}:
2231 @lilypond[verbatim,quote,ragged-right]
2243 \override SpacingSpanner
2244 #'common-shortest-duration = #(ly:make-moment 1 2)
2251 Note that this override cannot be modified dynamically, so it must
2252 always be placed in a @code{\context@{..@}} block so that it applies