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?
52 @chapter Spacing issues
54 The global paper layout is determined by three factors: the page layout, the
55 line breaks, and the spacing. These all influence each other. The
56 choice of spacing determines how densely each system of music is set.
57 This influences where line breaks are chosen, and thus ultimately, how
58 many pages a piece of music takes.
60 Globally speaking, this procedure happens in four steps: first,
61 flexible distances (@q{springs}) are chosen, based on durations. All
62 possible line breaking combinations are tried, and a @q{badness} score
63 is calculated for each. Then the height of each possible system is
64 estimated. Finally, a page breaking and line breaking combination is chosen
65 so that neither the horizontal nor the vertical spacing is too cramped
71 * Displaying spacing::
74 * Horizontal spacing::
75 * Page layout MOVED FROM LM::
80 @section Paper and pages
82 This section deals with the boundaries that define the area
83 that music can be printed inside.
92 @subsection Paper size
98 To change the paper size, there are two commands,
100 #(set-default-paper-size "a4")
102 #(set-paper-size "a4")
106 The first command sets the size of all pages. The second command sets the
108 of the pages that the @code{\paper} block applies to -- if the @code{\paper}
109 block is at the top of the file, then it will apply to all pages. If the
110 @code{\paper} block is inside a @code{\book}, then the paper size will only
113 Support for the following paper sizes are included by default,
114 @code{a6}, @code{a5}, @code{a4}, @code{a3}, @code{legal}, @code{letter},
115 @code{11x17} (also known as tabloid).
117 Extra sizes may be added by editing the definition for
118 @code{paper-alist} in the initialization file @file{scm/paper.scm}.
123 If the symbol @code{landscape} is supplied as an argument to
124 @code{set-default-paper-size}, the pages will be rotated by 90 degrees,
125 and wider line widths will be set correspondingly.
128 #(set-default-paper-size "a6" 'landscape)
131 Setting the paper size will adjust a number of @code{\paper} variables
132 (such as margins). To use a particular paper size with altered
133 @code{\paper} variables, set the paper size before setting the variables.
136 @node Page formatting
137 @subsection Page formatting
139 @cindex page formatting
144 LilyPond will do page layout, set margins, and add headers and
145 footers to each page.
147 The default layout responds to the following settings in the
154 @funindex first-page-number
155 @item first-page-number
156 The value of the page number of the first page. Default is@tie{}1.
158 @funindex print-first-page-number
159 @item print-first-page-number
160 If set to true, will print the page number in the first page. Default is
163 @funindex print-page-number
164 @item print-page-number
165 If set to false, page numbers will not be printed. Default is true.
167 @funindex paper-width
169 The width of the page. The default is taken from the current paper size,
170 see @ref{Paper size}.
172 @funindex paper-height
174 The height of the page. The default is taken from the current paper size,
175 see @ref{Paper size}.
179 Margin between header and top of the page. Default is@tie{}5mm.
181 @funindex bottom-margin
183 Margin between footer and bottom of the page. Default is@tie{}6mm.
185 @funindex left-margin
187 Margin between the left side of the page and the beginning of the
188 music. Unset by default, which means that the margins is determined
189 based on the @code{paper-width} and @code{line-width} to center the
194 The length of the systems. Default is @code{paper-width} minus @tie{}20mm.
196 @funindex head-separation
197 @item head-separation
198 Distance between the top-most music system and the page header. Default
201 @funindex foot-separation
202 @item foot-separation
203 Distance between the bottom-most music system and the page
204 footer. Default is@tie{}4mm.
206 @funindex page-top-space
208 Distance from the top of the printable area to the center of the first
209 staff. This only works for staves which are vertically small. Big staves
210 are set with the top of their bounding box aligned to the top of the
211 printable area. Default is@tie{}12mm.
213 @funindex ragged-bottom
215 If set to true, systems will not be spread vertically across the page. This
216 does not affect the last page. Default is false.
218 This should be set to true for pieces that have only two or three
219 systems per page, for example orchestral scores.
221 @funindex ragged-last-bottom
222 @item ragged-last-bottom
223 If set to false, systems will be spread vertically to fill the last
224 page. Default is true.
226 Pieces that amply fill two pages or more should have this set to
229 @funindex system-count
231 This variable, if set, specifies into how many lines a score should be
232 broken. Unset by default.
234 @funindex between-system-space
235 @item between-system-space
236 This dimensions determines the distance between systems. It is the
237 ideal distance between the center of the bottom staff of one system
238 and the center of the top staff of the next system. Default is@tie{}20mm.
240 Increasing this will provide a more even appearance of the page at the
241 cost of using more vertical space.
243 @funindex between-system-padding
244 @item between-system-padding
245 This dimension is the minimum amount of white space that will always
246 be present between the bottom-most symbol of one system, and the
247 top-most of the next system. Default is@tie{}4mm.
249 Increasing this will put systems whose bounding boxes almost touch
252 @funindex page-breaking-between-system-padding
253 @item page-breaking-between-system-padding
254 This variable tricks the page breaker into thinking that
255 @code{between-system-padding} is set to something different than it
256 really is. For example, if this variable is set to something substantially
257 larger than @code{between-system-padding}, then the page-breaker will put
258 fewer systems on each page.
260 @funindex horizontal-shift
261 @item horizontal-shift
262 All systems (including titles and system separators) are shifted by
263 this amount to the right. Page markup, such as headers and footers are
264 not affected by this. The purpose of this variable is to make space
265 for instrument names at the left. Default is@tie{}0.
267 @funindex after-title-space
268 @item after-title-space
269 Amount of space between the title and the first system. Default is@tie{}5mm.
271 @funindex before-title-space
272 @item before-title-space
273 Amount of space between the last system of the previous piece and the
274 title of the next. Default is@tie{}10mm.
276 @funindex between-title-space
277 @item between-title-space
278 Amount of space between consecutive titles (e.g., the title of the
279 book and the title of a piece). Default is@tie{}2mm.
281 @funindex printallheaders
282 @item printallheaders
283 Setting this to #t will print all headers for each \score in the
284 output. Normally only the piece and opus \headers are printed.
286 @funindex systemSeparatorMarkup
287 @item systemSeparatorMarkup
288 This contains a markup object, which will be inserted between
289 systems. This is often used for orchestral scores. Unset by default.
291 The markup command @code{\slashSeparator} is provided as a sensible
294 @lilypond[ragged-right]
295 #(set-default-paper-size "a6" 'landscape)
298 \relative { c1 \break c1 }
301 systemSeparatorMarkup = \slashSeparator
306 @funindex blank-page-force
307 @item blank-page-force
308 The penalty for having a blank page in the middle of a
309 score. This is not used by @code{ly:optimal-breaking} since it will
310 never consider blank pages in the middle of a score. Default value
313 @funindex blank-last-page-force
314 @item blank-last-page-force
315 The penalty for ending the score on an odd-numbered page.
318 @funindex page-spacing-weight
319 @item page-spacing-weight
320 The relative importance of page (vertical) spacing and line (horizontal)
321 spacing. High values will make page spacing more important. Default
324 @funindex auto-first-page-number
325 @item auto-first-page-number
326 The page breaking algorithm is affected by the first page number being
327 odd or even. If this variable is set to #t, the page breaking algorithm
328 will decide whether to start with an odd or even number. This will
329 result in the first page number remaining as is or being increased by one.
337 The header and footer are created by the functions make-footer and
338 make-header, defined in \paper. The default implementations are in
339 ly/paper-defaults.ly and ly/titling-init.ly.
341 The page layout itself is done by two functions in the \paper block,
342 page-music-height and page-make-stencil. The former tells the
343 line-breaking algorithm how much space can be spent on a page, the
344 latter creates the actual page given the system to put on it.
346 You can define paper block values in Scheme. In that case mm, in, pt,
347 and cm are variables defined in paper-defaults.ly with values in
348 millimeters. That is why the value 2 cm must be multiplied in the
353 #(define bottom-margin (* 2 cm))
365 ragged-last-bottom = ##t
369 This second example centers page numbers at the bottom of every page.
373 print-page-number = ##t
374 print-first-page-number = ##t
375 oddHeaderMarkup = \markup \fill-line @{ " " @}
376 evenHeaderMarkup = \markup \fill-line @{ " " @}
377 oddFooterMarkup = \markup @{ \fill-line @{
378 \bold \fontsize #3 \on-the-fly #print-page-number-check-first
379 \fromproperty #'page:page-number-string @} @}
380 evenFooterMarkup = \markup @{ \fill-line @{
381 \bold \fontsize #3 \on-the-fly #print-page-number-check-first
382 \fromproperty #'page:page-number-string @} @}
386 You can also define these values in Scheme. In that case @code{mm},
387 @code{in}, @code{pt}, and @code{cm} are variables defined in
388 @file{paper-defaults.ly} with values in millimeters. That is why the
389 value must be multiplied in the example
393 #(define bottom-margin (* 2 cm))
397 The header and footer are created by the functions @code{make-footer}
398 and @code{make-header}, defined in @code{\paper}. The default
399 implementations are in @file{ly/@/paper@/-defaults@/.ly} and
400 @file{ly/@/titling@/-init@/.ly}.
402 The page layout itself is done by two functions in the
403 @code{\paper} block, @code{page-music-height} and
404 @code{page-make-stencil}. The former tells the line-breaking algorithm
405 how much space can be spent on a page, the latter creates the actual
406 page given the system to put on it.
411 The option right-margin is defined but doesn't set the right margin
412 yet. The value for the right margin has to be defined adjusting the
413 values of @code{left-margin} and @code{line-width}.
415 The default page header puts the page number and the @code{instrument}
416 field from the @code{\header} block on a line.
418 The titles (from the @code{\header@{@}} section) are treated as a
419 system, so @code{ragged-bottom} and @code{ragged-last-bottom} will
420 add space between the titles and the first system of the score.
424 @section Music layout
427 * Setting the staff size::
432 @node Setting the staff size
433 @subsection Setting the staff size
435 @cindex font size, setting
436 @cindex staff size, setting
437 @funindex layout file
439 To set the staff size globally for all scores in a file (or
440 in a @code{book} block, to be precise), use @code{set-global-staff-size}.
443 #(set-global-staff-size 14)
447 This sets the global default size to 14pt staff height and scales all
450 To set the staff size individually for each score, use
455 #(layout-set-staff-size 15)
460 The Feta font provides musical symbols at eight different
461 sizes. Each font is tuned for a different staff size: at a smaller size
462 the font becomes heavier, to match the relatively heavier staff lines.
463 The recommended font sizes are listed in the following table:
466 @multitable @columnfractions .15 .2 .22 .2
469 @tab @b{staff height (pt)}
470 @tab @b{staff height (mm)}
512 @c modern rental material?
517 These fonts are available in any sizes. The context property
518 @code{fontSize} and the layout property @code{staff-space} (in
519 @rinternals{StaffSymbol}) can be used to tune the size for individual
520 staves. The sizes of individual staves are relative to the global size.
528 This manual: @ref{Selecting notation font size}.
533 @code{layout-set-staff-size} does not change the distance between the
538 @subsection Score layout
542 While @code{\paper} contains settings that relate to the page formatting
543 of the whole document, @code{\layout} contains settings for score-specific
550 \override VerticalAxisGroup #'minimum-Y-extent = #'(-6 . 6)
553 \override TextScript #'padding = #1.0
554 \override Glissando #'thickness = #3
562 This manual: @ref{Changing context default settings}.
565 @node Displaying spacing
566 @section Displaying spacing
568 @funindex annotate-spacing
569 @cindex Spacing, display of properties
571 To graphically display the dimensions of vertical properties that may
572 be altered for page formatting, set @code{annotate-spacing} in the
573 @code{\paper} block, like this
576 @c need to have \book{} otherwise we get the separate systems. -hwn
578 #(set-default-paper-size "a6" 'landscape)
582 \paper { annotate-spacing = ##t }
587 @c TODO: really bad vagueness due to bug in annotate-spacing. -gp
589 Some unit dimensions are measured in staff spaces, while others
590 are measured in millimeters.
592 (@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
593 @var{b} the upper edge of the interval.
602 * Optimal page breaking::
603 * Optimal page turning::
604 * Minimal page breaking::
606 * Using an extra voice for breaks::
610 @subsection Line breaking
613 @cindex breaking lines
615 Line breaks are normally computed automatically. They are chosen so
616 that lines look neither cramped nor loose, and that consecutive lines
617 have similar density.
619 Occasionally you might want to override the automatic breaks; you can
620 do this by specifying @code{\break}. This will force a line break at
621 this point. Line breaks can only occur at places where there are bar
622 lines. If you want to have a line break where there is no bar line,
623 you can force an invisible bar line by entering @code{\bar
624 ""}. Similarly, @code{\noBreak} forbids a line break at a
628 @cindex regular line breaks
629 @cindex four bar music.
631 For line breaks at regular intervals use @code{\break} separated by
632 skips and repeated with @code{\repeat}:
634 << \repeat unfold 7 @{
635 s1 \noBreak s1 \noBreak
636 s1 \noBreak s1 \break @}
637 @emph{the real music}
642 This makes the following 28 measures (assuming 4/4 time) be broken every
643 4 measures, and only there.
647 @code{\break}, and @code{\noBreak}.
653 Internals: @rinternals{LineBreakEvent}.
655 A linebreaking configuration can be saved as a @code{.ly} file
656 automatically. This allows vertical alignments to be stretched to
657 fit pages in a second formatting run. This is fairly new and
658 complicated. More details are available in
663 Line breaks can only occur if there is a @q{proper} bar line. A note
664 which is hanging over a bar line is not proper, such as
666 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
667 c4 c2 << c2 {s4 \break } >> % this does nothing
668 c2 c4 | % a break here would work
669 c4 c2 c4 ~ \break % as does this break
673 This can be avoided by removing the @code{Forbid_line_break_engraver}.
674 Note that manually forced line breaks have to be added in parallel
677 @lilypond[quote,ragged-right,verbatim]
679 \remove Forbid_line_break_engraver
681 c4 c2 << c2 {s4 \break } >> % now the break is allowed
686 Similarly, line breaks are normally forbidden when beams cross bar
687 lines. This behavior can be changed by setting
688 @code{\override Beam #'breakable = ##t}.
692 @subsection Page breaking
694 The default page breaking may be overridden by inserting
695 @code{\pageBreak} or @code{\noPageBreak} commands. These commands are
696 analogous to @code{\break} and @code{\noBreak}. They should be
697 inserted at a bar line. These commands force and forbid a page-break
698 from happening. Of course, the @code{\pageBreak} command also forces
701 The @code{\pageBreak} and @code{\noPageBreak} commands may also be
702 inserted at top-level, between scores and top-level markups.
704 Page breaks are computed by the @code{page-breaking} function. LilyPond
705 provides three algorithms for computing page breaks,
706 @code{ly:optimal-breaking}, @code{ly:page-turn-breaking} and
707 @code{ly:minimal-breaking}. The default is @code{ly:optimal-breaking},
708 but the value can be changed in the @code{\paper} block:
712 #(define page-breaking ly:page-turn-breaking)
716 The old page breaking algorithm is called
717 @code{optimal-page-breaks}. If you are having trouble with the new page
718 breakers, you can enable the old one as a workaround.
724 @funindex \noPageBreak
728 @node Optimal page breaking
729 @subsection Optimal page breaking
731 @funindex ly:optimal-breaking
733 The @code{ly:optimal-breaking} function is LilyPond's default method of
734 determining page breaks. It attempts to find a page breaking that minimizes
735 cramping and stretching, both horizontally and vertically. Unlike
736 @code{ly:page-turn-breaking}, it has no concept of page turns.
739 @node Optimal page turning
740 @subsection Optimal page turning
742 @funindex ly:page-turn-breaking
744 Often it is necessary to find a page breaking configuration so that there is
745 a rest at the end of every second page. This way, the musician can turn the
746 page without having to miss notes. The @code{ly:page-turn-breaking} function
747 attempts to find a page breaking minimizing cramping and stretching, but with
748 the additional restriction that it is only allowed to introduce page turns
751 There are two steps to using this page breaking function. First, you
752 must enable it in the @code{\paper} block, as explained in @ref{Page
753 breaking}. Then you must tell the function where you would like to allow
756 There are two ways to achieve the second step. First, you can specify each
757 potential page turn manually, by inserting @code{\allowPageTurn} into your
758 input file at the appropriate places.
760 If this is too tedious, you can add a @code{Page_turn_engraver} to a Staff or
761 Voice context. The @code{Page_turn_engraver} will scan the context for
762 sections without notes (note that it does not scan for rests; it scans for
763 the absence of notes. This is so that single-staff polyphony with rests in one
764 of the parts does not throw off the @code{Page_turn_engraver}). When it finds
765 a sufficiently long section without notes, the @code{Page_turn_engraver} will
766 insert an @code{\allowPageTurn} at the final bar line in that section, unless
767 there is a @q{special} bar line (such as a double bar), in which case the
768 @code{\allowPageTurn} will be inserted at the final @q{special} bar line in
771 @funindex minimumPageTurnLength
772 The @code{Page_turn_engraver} reads the context property
773 @code{minimumPageTurnLength} to determine how long a note-free section must
774 be before a page turn is considered. The default value for
775 @code{minimumPageTurnLength} is @code{#(ly:make-moment 1 1)}. If you want
776 to disable page turns, you can set it to something very large.
779 \new Staff \with @{ \consists "Page_turn_engraver" @}
782 R1 | % a page turn will be allowed here
784 \set Staff.minimumPageTurnLength = #(ly:make-moment 5 2)
785 R1 | % a page turn will not be allowed here
787 R1*2 | % a page turn will be allowed here
792 @funindex minimumRepeatLengthForPageTurn
793 The @code{Page_turn_engraver} detects volta repeats. It will only allow a page
794 turn during the repeat if there is enough time at the beginning and end of the
795 repeat to turn the page back. The @code{Page_turn_engraver} can also disable
796 page turns if the repeat is very short. If you set the context property
797 @code{minimumRepeatLengthForPageTurn} then the @code{Page_turn_engraver} will
798 only allow turns in repeats whose duration is longer than this value.
800 The page turning commands, @code{\pageTurn}, @code{\noPageTurn} and
801 @code{\allowPageTurn}, may also be used at top-level, between scores and
808 @funindex \noPageTurn
810 @funindex \allowPageTurn
811 @code{\allowPageTurn}
815 There should only be one @code{Page_turn_engraver} in a score. If there is more
816 than one, they will interfere with each other.
818 @node Minimal page breaking
819 @subsection Minimal page breaking
821 @funindex ly:minimal-breaking
823 The @code{ly:minimal-breaking} function performs minimal computations to
824 calculate the page breaking: it fills a page with as many systems as
825 possible before moving to the next one. Thus, it may be preferred for
826 scores with many pages, where the other page breaking functions could be
827 too slow or memory demanding, or a lot of texts. It is enabled using:
831 #(define page-breaking ly:minimal-breaking)
835 @node Explicit breaks
836 @subsection Explicit breaks
838 Lily sometimes rejects explicit @code{\break} and @code{\pageBreak}
839 commands. There are two commands to override this behavior:
842 \override NonMusicalPaperColumn #'line-break-permission = ##f
843 \override NonMusicalPaperColumn #'page-break-permission = ##f
846 When @code{line-break-permission} is overridden to false, Lily will insert
847 line breaks at explicit @code{\break} commands and nowhere else. When
848 @code{page-break-permission} is overridden to false, Lily will insert
849 page breaks at explicit @code{\pageBreak} commands and nowhere else.
851 @lilypond[quote,verbatim]
860 \override NonMusicalPaperColumn #'line-break-permission = ##f
861 \override NonMusicalPaperColumn #'page-break-permission = ##f
864 \repeat unfold 2 { c'8 c'8 c'8 c'8 } \break
865 \repeat unfold 4 { c'8 c'8 c'8 c'8 } \break
866 \repeat unfold 6 { c'8 c'8 c'8 c'8 } \break
867 \repeat unfold 8 { c'8 c'8 c'8 c'8 } \pageBreak
868 \repeat unfold 8 { c'8 c'8 c'8 c'8 } \break
869 \repeat unfold 6 { c'8 c'8 c'8 c'8 } \break
870 \repeat unfold 4 { c'8 c'8 c'8 c'8 } \break
871 \repeat unfold 2 { c'8 c'8 c'8 c'8 }
878 @node Using an extra voice for breaks
879 @subsection Using an extra voice for breaks
881 Line- and page-breaking information usually appears within note entry directly.
886 \repeat unfold 2 @{ c'4 c'4 c'4 c'4 @}
888 \repeat unfold 3 @{ c'4 c'4 c'4 c'4 @}
893 This makes @code{\break} and @code{\pageBreak} commands easy to enter but mixes
894 music entry with information that specifies how music should lay out
895 on the page. You can keep music entry and line- and page-breaking
896 information in two separate places by introducing an extra voice to
897 contain the breaks. This extra voice
898 contains only skips together with @code{\break}, @code{pageBreak} and other
899 breaking layout information.
901 @lilypond[quote,verbatim]
911 \repeat unfold 2 { c'4 c'4 c'4 c'4 }
912 \repeat unfold 3 { c'4 c'4 c'4 c'4 }
913 \repeat unfold 6 { c'4 c'4 c'4 c'4 }
914 \repeat unfold 5 { c'4 c'4 c'4 c'4 }
920 This pattern becomes especially helpful when overriding
921 @code{line-break-system-details} and the other useful but long properties of
922 @code{NonMusicalPaperColumnGrob}, as explained in @ref{Vertical spacing}.
924 @lilypond[quote,verbatim]
929 \overrideProperty "Score.NonMusicalPaperColumn"
930 #'line-break-system-details #'((Y-offset . 0))
933 \overrideProperty "Score.NonMusicalPaperColumn"
934 #'line-break-system-details #'((Y-offset . 35))
937 \overrideProperty "Score.NonMusicalPaperColumn"
938 #'line-break-system-details #'((Y-offset . 70))
941 \overrideProperty "Score.NonMusicalPaperColumn"
942 #'line-break-system-details #'((Y-offset . 105))
946 \repeat unfold 2 { c'4 c'4 c'4 c'4 }
947 \repeat unfold 3 { c'4 c'4 c'4 c'4 }
948 \repeat unfold 6 { c'4 c'4 c'4 c'4 }
949 \repeat unfold 5 { c'4 c'4 c'4 c'4 }
956 @node Vertical spacing
957 @section Vertical spacing
959 @cindex vertical spacing
960 @cindex spacing, vertical
962 Vertical spacing is controlled by three things: the amount of
963 space available (i.e., paper size and margins), the amount of
964 space between systems, and the amount of space between
965 staves inside a system.
968 * Vertical spacing inside a system::
969 * Vertical spacing between systems::
970 * Explicit staff and system positioning::
971 * Two-pass vertical spacing::
972 * Vertical collision avoidance::
976 @node Vertical spacing inside a system
977 @subsection Vertical spacing inside a system
979 @cindex distance between staves
980 @cindex staff distance
981 @cindex space between staves
982 @cindex space inside systems
984 The height of each system is determined automatically. To prevent
985 staves from bumping into each other, some minimum distances are set.
986 By changing these, you can put staves closer together. This
987 reduces the amount of space each system requires, and may result
988 in having more systems per page.
990 Normally staves are stacked vertically. To make staves maintain a
991 distance, their vertical size is padded. This is done with the
992 property @code{minimum-Y-extent}. When applied to a
993 @rinternals{VerticalAxisGroup}, it controls the size of a horizontal
994 line, such as a staff or a line of lyrics. @code{minimum-Y-extent}
995 takes a pair of numbers, so
996 if you want to make it smaller than its default @code{#'(-4 . 4)}
1000 \override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
1004 This sets the vertical size of the current staff to 3 staff spaces on
1005 either side of the center staff line. The value @code{(-3 . 3)} is
1006 interpreted as an interval, where the center line is the 0, so the
1007 first number is generally negative. The numbers need not match;
1008 for example, the staff can be made larger at the bottom by setting
1009 it to @code{(-6 . 4)}.
1011 After page breaks are determined, the vertical spacing within each
1012 system is reevaluated in order to fill the page more evenly; if a page
1013 has space left over, systems are stretched in order to fill that space.
1014 The amount of stretching can be configured though the @code{max-stretch}
1015 property of the @rinternals{VerticalAlignment} grob. By default,
1016 @code{max-stretch} is set to zero, disabling stretching. To enable
1017 stretching, a sane value for @code{max-stretch}
1018 is @code{ly:align-interface::calc-max-stretch}.
1020 In some situations, you may want to stretch most of a system while
1021 leaving some parts fixed. For example, if a piano part occurs in the
1022 middle of an orchestral score, you may want to leave the piano staves
1023 close to each other while stretching the rest of the score. The
1024 @code{keep-fixed-while-stretching} property of
1025 @rinternals{VerticalAxisGroup} can be used to achieve this. When set
1026 to @code{##t}, this property keeps its staff (or line of lyrics) from
1027 moving relative to the one directly above it. In the example above,
1028 you would override @code{keep-fixed-while-stretching} to @code{##t} in
1029 the second piano staff:
1032 #(set-default-paper-size "a6")
1033 #(set-global-staff-size 14.0)
1037 ragged-last-bottom = ##f
1042 \override VerticalAlignment #'max-stretch = #ly:align-interface::calc-max-stretch
1049 \new Staff {c' d' e' f'}
1050 \new Staff {c' d' e' f'}
1051 \new Staff {c' d' e' f'}
1056 \new Staff {c' d' e' f'}
1058 \override VerticalAxisGroup #'keep-fixed-while-stretching = ##t
1065 \new Staff {c' d' e' f'}
1066 \new Staff {c' d' e' f'}
1075 Internals: Vertical alignment of staves is handled by the
1076 @rinternals{VerticalAlignment} object. The context parameters
1077 specifying the vertical extent are described in connection with
1078 the @rinternals{Axis_group_engraver}.
1080 Example files: @c @lsr{spacing,page-spacing.ly},
1081 @c @lsr{spacing,alignment-vertical-spacing.ly}.
1084 @node Vertical spacing between systems
1085 @subsection Vertical spacing between systems
1087 Space between systems are controlled by four @code{\paper} variables,
1091 between-system-space = 1.5\cm
1092 between-system-padding = #1
1094 ragged-last-bottom=##f
1098 When only a couple of flat systems are placed on a page, the resulting
1099 vertical spacing may be non-elegant: one system at the top of the page,
1100 and the other at the bottom, with a huge gap between them. To avoid this
1101 situation, the space added between the systems can be limited. This
1102 feature is activated by setting to @code{#t} the
1103 @code{page-limit-inter-system-space} variable in the @code{\paper}
1104 block. The paper variable @code{page-limit-inter-system-space-factor}
1105 determines how much the space can be increased: for instance, the value
1106 @code{1.3} means that the space can be 30% larger than what it would be
1107 on a ragged-bottom page.
1109 In the following example, if the inter system space were not limited,
1110 the second system of page 1 would be placed at the page bottom. By
1111 activating the space limitation, the second system is placed closer to
1112 the first one. By setting @code{page-limit-inter-system-space-factor} to
1113 @code{1}, the spacing would the same as on a ragged-bottom page, like
1117 #(set-default-paper-size "a6")
1120 page-limit-inter-system-space = ##t
1121 page-limit-inter-system-space-factor = 1.3
1123 oddFooterMarkup = \markup "page bottom"
1124 evenFooterMarkup = \markup "page bottom"
1125 oddHeaderMarkup = \markup \fill-line {
1126 "page top" \fromproperty #'page:page-number-string }
1127 evenHeaderMarkup = \markup \fill-line {
1128 "page top" \fromproperty #'page:page-number-string }
1130 \new Staff << \repeat unfold 4 { g'4 g' g' g' \break }
1131 { s1*2 \pageBreak } >>
1135 @node Explicit staff and system positioning
1136 @subsection Explicit staff and system positioning
1138 One way to understand the @code{VerticalAxisGroup} and @code{\paper}
1139 settings explained in the previous two sections is as a collection of
1140 different settings that primarily concern the amount of vertical padding
1141 different staves and systems running down the page.
1143 It is possible to approach vertical spacing in a different way using
1144 @code{NonMusicalPaperColumn #'line-break-system-details}. Where
1145 @code{VerticalAxisGroup} and @code{\paper} settings specify vertical padding,
1146 @code{NonMusicalPaperColumn #'line-break-system-details} specifies exact
1147 vertical positions on the page.
1149 @code{NonMusicalPaperColumn #'line-break-system-details} accepts an associative
1150 list of five different settings:
1153 @item @code{X-offset}
1154 @item @code{Y-offset}
1155 @item @code{alignment-offsets}
1156 @item @code{alignment-extra-space}
1157 @item @code{fixed-alignment-extra-space}
1160 Grob overrides, including the overrides for @code{NonMusicalPaperColumn}
1161 below, can occur in any of three different places in an input file:
1164 @item in the middle of note entry directly
1165 @item in a @code{\context} block
1166 @item in the @code{\with} block
1169 When we override @code{NonMusicalPaperColumn}, we use the usual
1170 @code{\override} command in @code{\context} blocks and in the
1171 @code{\with} block. On the other hand, when we override
1172 @code{NonMusicalPaperColumn} in the middle of note entry,
1173 use the special @code{\overrideProperty} command. Here are some
1174 example @code{NonMusicalPaperColumn} overrides with the special
1175 @code{\overrideProperty} command:
1178 \overrideProperty NonMusicalPaperColumn
1179 #'line-break-system-details #'((X-offset . 20))
1181 \overrideProperty NonMusicalPaperColumn
1182 #'line-break-system-details #'((Y-offset . 40))
1184 \overrideProperty NonMusicalPaperColumn
1185 #'line-break-system-details #'((X-offset . 20) (Y-offset . 40))
1187 \override NonMusicalPaperColumn
1188 #'line-break-system-details #'((alignment-offsets . (0 -15)))
1190 \override NonMusicalPaperColumn
1191 #'line-break-system-details #'((X-offset . 20) (Y-offset . 40)
1192 (alignment-offsets . (0 -15)))
1195 To understand how each of these different settings work, we begin
1196 by looking at an example that includes no overrides at all.
1198 @lilypond[quote,ragged-right]
1206 \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
1209 \repeat unfold 18 { d'4 d'4 d'4 d'4 }
1214 This score isolates line- and page-breaking information in a dedicated
1215 voice. This technique of creating a breaks voice will help keep layout
1216 separate from music entry as our example becomes more complicated.
1217 See @ref{Using an extra voice for breaks}.
1219 Explicit @code{\breaks} evenly divide the music into six measures per
1220 line. Vertical spacing results from LilyPond's defaults. To set
1221 the vertical startpoint of each system explicitly, we can set
1222 the @code{Y-offset} pair in the @code{line-break-system-details}
1223 attribute of the @code{NonMusicalPaperColumn} grob:
1225 @lilypond[quote,ragged-right]
1229 \overrideProperty #"Score.NonMusicalPaperColumn"
1230 #'line-break-system-details #'((Y-offset . 0))
1232 \overrideProperty #"Score.NonMusicalPaperColumn"
1233 #'line-break-system-details #'((Y-offset . 40))
1235 \overrideProperty #"Score.NonMusicalPaperColumn"
1236 #'line-break-system-details #'((Y-offset . 80))
1239 \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
1242 \repeat unfold 18 { d'4 d'4 d'4 d'4 }
1247 Note that @code{line-break-system-details} takes an associative list of
1248 potentially many values, but that we set only one value here. Note,
1249 too, that the @code{Y-offset} property here determines the exact vertical
1250 position on the page at which each new system will render.
1252 Now that we have set the vertical startpoint of each system
1253 explicitly, we can also set the vertical startpoint of each staff
1254 within each system manually. We do this using the @code{alignment-offsets}
1255 subproperty of @code{line-break-system-details}.
1257 @lilypond[quote,ragged-right]
1261 \overrideProperty #"Score.NonMusicalPaperColumn"
1262 #'line-break-system-details #'((Y-offset . 20)
1263 (alignment-offsets . (0 -15)))
1265 \overrideProperty #"Score.NonMusicalPaperColumn"
1266 #'line-break-system-details #'((Y-offset . 60)
1267 (alignment-offsets . (0 -15)))
1269 \overrideProperty #"Score.NonMusicalPaperColumn"
1270 #'line-break-system-details #'((Y-offset . 100)
1271 (alignment-offsets . (0 -15)))
1274 \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
1277 \repeat unfold 18 { d'4 d'4 d'4 d'4 }
1282 Note that here we assign two different values to the
1283 @code{line-break-system-details} attribute of the
1284 @code{NonMusicalPaperColumn} grob. Though the
1285 @code{line-break-system-details} attribute alist accepts many
1286 additional spacing parameters (including, for example, a corresponding
1287 @code{X-offset} pair), we need only set the @code{Y-offset} and
1288 @code{alignment-offsets} pairs to control the vertical startpoint of
1289 every system and every staff. Finally, note that @code{alignment-offsets}
1290 specifies the vertical positioning of staves but not of staff groups.
1292 @lilypond[quote,ragged-right]
1296 \overrideProperty #"Score.NonMusicalPaperColumn"
1297 #'line-break-system-details #'((Y-offset . 0)
1298 (alignment-offsets . (0 -30 -40)))
1300 \overrideProperty #"Score.NonMusicalPaperColumn"
1301 #'line-break-system-details #'((Y-offset . 60)
1302 (alignment-offsets . (0 -10 -20)))
1304 \overrideProperty #"Score.NonMusicalPaperColumn"
1305 #'line-break-system-details #'((Y-offset . 100)
1306 (alignment-offsets . (0 -10, -40)))
1309 \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
1313 \repeat unfold 18 { d'4 d'4 d'4 d'4 }
1316 \repeat unfold 18 { e'4 e'4 e'4 e'4 }
1322 Some points to consider:
1325 @item When using @code{alignment-offsets}, lyrics count as a staff.
1327 @item The units of the numbers passed to @code{X-offset},
1328 @code{Y-offset} and @code{alignment-offsets} are interpreted as multiples
1329 of the distance between adjacent staff lines. Positive values move staves
1330 and lyrics up, negative values move staves and lyrics down.
1332 @item Because the @code{NonMusicalPaperColumn #'line-break-system-details}
1333 settings given here allow the positioning of staves and systems anywhere
1334 on the page, it is possible to violate paper or margin boundaries or even
1335 to print staves or systems on top of one another. Reasonable values
1336 passed to these different settings will avoid this.
1340 @node Two-pass vertical spacing
1341 @subsection Two-pass vertical spacing
1343 Warning: two-pass vertical spacing is deprecated and will be removed in
1344 a future version of LilyPond. Systems are now stretched automatically
1345 in a single pass. See @ref{Vertical spacing inside a system}.
1347 In order to automatically stretch systems so that they should fill the
1348 space left on a page, a two-pass technique can be used:
1351 @item In the first pass, the amount of vertical space used to increase
1352 the height of each system is computed and dumped to a file.
1353 @item In the second pass, spacing inside the systems are
1354 stretched according to the data in the page layout file.
1357 The @code{ragged-bottom} property adds space between systems, while
1358 the two-pass technique adds space between staves inside a system.
1360 To allow this behavior, a @code{tweak-key} variable has to be set in
1361 each score @code{\layout} block, and the tweaks included in each score
1362 music, using the @code{\scoreTweak} music function.
1366 %% include the generated page layout file:
1367 \includePageLayoutFile
1372 %% Include this score tweaks:
1373 \scoreTweak "scoreA"
1374 { \clef french c''1 \break c''1 }
1376 \new Staff { \clef soprano g'1 g'1 }
1377 \new Staff { \clef mezzosoprano e'1 e'1 }
1378 \new Staff { \clef alto g1 g1 }
1379 \new Staff { \clef bass c1 c1 }
1382 piece = "Score with tweaks"
1384 %% Define how to name the tweaks for this score:
1385 \layout { #(define tweak-key "scoreA") }
1390 For the first pass, the @code{dump-tweaks} option should be set to
1391 generate the page layout file.
1394 lilypond -dbackend=null -d dump-tweaks <file>.ly
1399 @node Vertical collision avoidance
1400 @subsection Vertical collision avoidance
1402 @funindex outside-staff-priority
1403 @funindex outside-staff-padding
1404 @funindex outside-staff-horizontal-padding
1406 Intuitively, there are some objects in musical notation that belong
1407 to the staff and there are other objects that should be placed outside
1408 the staff. Objects belonging outside the staff include things such as
1409 rehearsal marks, text and dynamic markings (from now on, these will
1410 be called outside-staff objects). LilyPond's rule for the
1411 vertical placement of outside-staff objects is to place them as close
1412 to the staff as possible but not so close that they collide with
1415 LilyPond uses the @code{outside-staff-priority} property to determine
1416 whether a grob is an outside-staff object: if @code{outside-staff-priority}
1417 is a number, the grob is an outside-staff object. In addition,
1418 @code{outside-staff-priority} tells LilyPond in which order the objects
1421 First, LilyPond places all the objects that do not belong outside
1422 the staff. Then it sorts the outside-staff objects according to their
1423 @code{outside-staff-priority} (in increasing order). One by one, LilyPond
1424 takes the outside-staff objects and places them so that they do
1425 not collide with any objects that have already been placed. That
1426 is, if two outside-staff grobs are competing for the same space, the one
1427 with the lower @code{outside-staff-priority} will be placed closer to
1430 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1433 \once \override TextScript #'outside-staff-priority = #1
1434 c4_"Text"\pp % this time the text will be closer to the staff
1436 % by setting outside-staff-priority to a non-number, we
1437 % disable the automatic collision avoidance
1438 \once \override TextScript #'outside-staff-priority = ##f
1439 \once \override DynamicLineSpanner #'outside-staff-priority = ##f
1440 c4_"Text"\pp % now they will collide
1443 The vertical padding between an outside-staff object and the
1444 previously-positioned grobs can be controlled with
1445 @code{outside-staff-padding}.
1447 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1448 \once \override TextScript #'outside-staff-padding = #0
1449 a'^"This text is placed very close to the note"
1450 \once \override TextScript #'outside-staff-padding = #3
1451 c^"This text is padded away from the previous text"
1452 c^"This text is placed close to the previous text"
1455 TODO: this example doesn't work any more ?
1457 By default, outside-staff objects are placed without regard to
1458 their horizontal distance from the previously-positioned grobs. This
1459 can lead to situations in which objects are placed very close to each
1460 other horizontally. Setting @code{outside-staff-horizontal-padding}
1461 causes an object to be offset vertically so that such a situation
1464 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1465 % the markup is too close to the following note
1468 % setting outside-staff-horizontal-padding fixes this
1470 \once \override TextScript #'outside-staff-horizontal-padding = #1
1477 @node Horizontal spacing
1478 @section Horizontal Spacing
1480 @cindex horizontal spacing
1481 @cindex spacing, horizontal
1484 * Horizontal spacing overview::
1485 * New spacing area::
1486 * Changing horizontal spacing::
1488 * Proportional notation::
1492 @node Horizontal spacing overview
1493 @subsection Horizontal spacing overview
1495 The spacing engine translates differences in durations into stretchable
1496 distances (@q{springs}) of differing lengths. Longer durations get
1497 more space, shorter durations get less. The shortest durations get a
1498 fixed amount of space (which is controlled by
1499 @code{shortest-duration-space} in the @rinternals{SpacingSpanner}
1500 object). The longer the duration, the more space it gets: doubling a
1501 duration adds a fixed amount (this amount is controlled by
1502 @code{spacing-increment}) of space to the note.
1504 For example, the following piece contains lots of half, quarter, and
1505 8th notes; the eighth note is followed by 1 note head width (NHW).
1506 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
1508 @lilypond[quote,fragment,verbatim,relative=1]
1509 c2 c4. c8 c4. c8 c4. c8 c8
1513 Normally, @code{spacing-increment} is set to 1.2 staff space, which is
1514 approximately the width of a note head, and
1515 @code{shortest-duration-space} is set to 2.0, meaning that the
1516 shortest note gets 2.4 staff space (2.0 times the
1517 @code{spacing-increment}) of horizontal space. This space is counted
1518 from the left edge of the symbol, so the shortest notes are generally
1519 followed by one NHW of space.
1521 If one would follow the above procedure exactly, then adding a single
1522 32nd note to a score that uses 8th and 16th notes, would widen up the
1523 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
1524 thus adding 1 NHW to every note. To prevent this, the shortest
1525 duration for spacing is not the shortest note in the score, but rather
1526 the one which occurs most frequently.
1529 The most common shortest duration is determined as follows: in every
1530 measure, the shortest duration is determined. The most common shortest
1531 duration is taken as the basis for the spacing, with the stipulation
1532 that this shortest duration should always be equal to or shorter than
1533 an 8th note. The shortest duration is printed when you run
1534 @code{lilypond} with the @code{--verbose} option.
1536 These durations may also be customized. If you set the
1537 @code{common-shortest-duration} in @rinternals{SpacingSpanner}, then
1538 this sets the base duration for spacing. The maximum duration for this
1539 base (normally an 8th), is set through @code{base-shortest-duration}.
1541 @funindex common-shortest-duration
1542 @funindex base-shortest-duration
1543 @funindex stem-spacing-correction
1546 Notes that are even shorter than the common shortest note are
1547 followed by a space that is proportional to their duration relative to
1548 the common shortest note. So if we were to add only a few 16th notes
1549 to the example above, they would be followed by half a NHW:
1551 @lilypond[quote,fragment,verbatim,relative=2]
1552 c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
1556 In the introduction (see @rlearning{Engraving}), it was explained that stem
1557 directions influence spacing. This is controlled with the
1558 @code{stem-spacing-correction} property in the
1559 @rinternals{NoteSpacing}, object. These are generated for every
1560 @rinternals{Voice} context. The @code{StaffSpacing} object
1561 (generated in @rinternals{Staff} context) contains the same property
1562 for controlling the stem/bar line spacing. The following example shows
1563 these corrections, once with default settings, and once with
1564 exaggerated corrections:
1566 @lilypond[quote,ragged-right]
1570 \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
1571 \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
1577 Proportional notation is supported; see @ref{Proportional notation}.
1582 Internals: @rinternals{SpacingSpanner}, @rinternals{NoteSpacing},
1583 @rinternals{StaffSpacing}, @rinternals{SeparationItem}, and
1584 @rinternals{SeparatingGroupSpanner}.
1589 There is no convenient mechanism to manually override spacing. The
1590 following work-around may be used to insert extra space into a score.
1592 \once \override Score.SeparationItem #'padding = #1
1595 No work-around exists for decreasing the amount of space.
1598 @node New spacing area
1599 @subsection New spacing area
1601 New sections with different spacing parameters can be started with
1602 @code{newSpacingSection}. This is useful when there are
1603 sections with a different notions of long and short notes.
1605 In the following example, the time signature change introduces a new
1606 section, and hence the 16ths notes are spaced wider.
1608 @lilypond[relative,fragment,verbatim,quote]
1611 c8 c c4 c16[ c c8] c4
1618 The @code{\newSpacingSection} command creates a new
1619 @rinternals{SpacingSpanner} object, and hence new @code{\override}s
1620 may be used in that location.
1623 @node Changing horizontal spacing
1624 @subsection Changing horizontal spacing
1626 Horizontal spacing may be altered with the
1627 @code{base-shortest-duration} property. Here
1628 we compare the same music; once without altering
1629 the property, and then altered. Larger values
1630 of @code{ly:make-moment} will produce smaller
1631 music. Note that @code{ly:make-moment} constructs
1632 a duration, so @code{1 4} is a longer duration
1635 @lilypond[verbatim,line-width=12\cm]
1638 g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
1639 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
1640 d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
1641 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
1646 @lilypond[verbatim,line-width=12\cm]
1649 g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
1650 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
1651 d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
1652 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
1657 \override SpacingSpanner
1658 #'base-shortest-duration = #(ly:make-moment 1 16)
1667 By default, spacing in tuplets depends on various non-duration
1668 factors (such as accidentals, clef changes, etc). To disregard
1669 such symbols and force uniform equal-duration spacing, use
1670 @code{Score.SpacingSpanner #'uniform-stretching}. This
1671 property can only be changed at the beginning of a score,
1673 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1675 \override SpacingSpanner #'uniform-stretching = ##t
1693 When @code{strict-note-spacing} is set, notes are spaced without
1694 regard for clefs, bar lines, and grace notes,
1696 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1697 \override Score.SpacingSpanner #'strict-note-spacing = ##t
1698 \new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c] c32[ c32] }
1703 @subsection Line length
1706 @cindex breaking pages
1709 @funindex line-width
1710 @funindex ragged-right
1711 @funindex ragged-last
1713 @c Although line-width can be set in \layout, it should be set in paper
1714 @c block, to get page layout right.
1715 @c Setting indent in \paper block makes not much sense, but it works.
1717 @c Bit verbose and vague, use examples?
1718 The most basic settings influencing the spacing are @code{indent} and
1719 @code{line-width}. They are set in the @code{\layout} block. They
1720 control the indentation of the first line of music, and the lengths of
1723 If @code{ragged-right} is set to true in the @code{\layout} block, then
1724 systems ends at their natural horizontal length, instead of being spread
1725 horizontally to fill the whole line. This is useful for
1726 short fragments, and for checking how tight the natural spacing is.
1729 @cindex vertical spacing
1731 The option @code{ragged-last} is similar to @code{ragged-right}, but
1732 only affects the last line of the piece. No restrictions are put on
1733 that line. The result is similar to formatting text paragraphs. In a
1734 paragraph, the last line simply takes its natural horizontal length.
1735 @c Note that for text there are several options for the last line.
1736 @c While Knuth TeX uses natural length, lead typesetters use the same
1737 @c stretch as the previous line. eTeX uses \lastlinefit to
1738 @c interpolate between both these solutions.
1749 @node Proportional notation
1750 @subsection Proportional notation
1752 LilyPond supports proportional notation, a type of horizontal spacing
1753 in which each note consumes an amount of horizontal space exactly
1754 equivalent to its rhythmic duration. This type of proportional spacing
1755 is comparable to horizontal spacing on top of graph paper. Some late
1756 20th- and early 21st-century scores use proportional notation to
1757 clarify complex rhythmic relationships or to facilitate the placement
1758 of timelines or other graphics directly in the score.
1760 LilyPond supports five different settings for proportional notation,
1761 which may be used together or alone:
1764 @item @code{proportionalNotationDuration}
1765 @item @code{uniform-stretching}
1766 @item @code{strict-note-spacing}
1767 @item @code{\remove Separating_line_group_engraver}
1768 @item @code{\override PaperColumn #'used = ##t}
1771 In the examples that follow, we explore these five different
1772 proportional notation settings and examine how these settings interact.
1774 We start with the following one-measure example, which uses classical
1775 spacing with ragged-right turned on.
1777 @lilypond[quote,verbatim,ragged-right]
1779 \new RhythmicStaff {
1783 c'16 c'16 c'16 c'16 c'16
1789 Notice that the half note which begins the measure takes up far less
1790 than half of the horizontal space of the measure. Likewise, the
1791 sixteenth notes and sixteenth-note quintuplets (or twentieth notes)
1792 which end the measure together take up far more than half the
1793 horizontal space of the measure.
1795 In classical engraving, this spacing may be exactly what we want
1796 because we can borrow horizontal space from the half note and conserve
1797 horizontal space across the measure as a whole.
1799 On the other hand, if we want to insert a measured timeline or other
1800 graphic above or below our score, we need proportional notation. We
1801 turn proportional notation on with the proportionalNotationDuration
1804 @lilypond[quote,verbatim,ragged-right]
1806 proportionalNotationDuration = #(ly:make-moment 1 20)
1808 \new RhythmicStaff {
1812 c'16 c'16 c'16 c'16 c'16
1818 The half note at the beginning of the measure and the faster notes in
1819 the second half of the measure now occupy equal amounts of horizontal
1820 space. We could place a measured timeline or graphic above or below
1823 The @code{proportionalNotationDuration} setting is a context setting that
1824 lives in @code{Score}. Recall that context settings appear in one of
1825 three locations in our input file -- in a @code{\with} block, in a
1826 @code{\context} block, or directly in music entry
1827 preceded by the @code{\set} command. As with all
1828 context settings, users can pick which of the three different
1829 locations they would like to set @code{proportionalNotationDuration}.
1831 The @code{proportionalNotationDuration} setting takes a single argument,
1832 which is the reference duration against which all music will be
1833 spaced. The LilyPond Scheme function make-moment takes two arguments
1834 -- a numerator and denominator which together express some fraction of
1835 a whole note. The call @code{#(ly:make-moment 1 20)} therefore produces a
1836 reference duration of a twentieth note. The values
1837 @code{#(ly:make-moment 1 16)}, @code{#(ly:make-moment 1 8)}, and
1838 @code{#(ly:make-moment 3 97)} are all possible as well.
1840 How do we select the right reference duration to pass to
1841 @code{proportionalNotationDuration}? Usually by a process of trial and error,
1842 beginning with a duration close to the fastest (or smallest) duration
1843 in the piece. Smaller reference durations space music loosely; larger
1844 reference durations space music tightly.
1846 @lilypond[quote,verbatim,ragged-right]
1848 proportionalNotationDuration = #(ly:make-moment 1 8)
1850 \new RhythmicStaff {
1854 c'16 c'16 c'16 c'16 c'16
1860 proportionalNotationDuration = #(ly:make-moment 1 16)
1862 \new RhythmicStaff {
1866 c'16 c'16 c'16 c'16 c'16
1872 proportionalNotationDuration = #(ly:make-moment 1 32)
1874 \new RhythmicStaff {
1878 c'16 c'16 c'16 c'16 c'16
1884 Note that too large a reference duration -- such as the eighth note,
1885 above -- spaces music too tightly and can cause note head collisions.
1886 Note also that proportional notation in general takes up more
1887 horizontal space that does classical spacing. Proportional spacing
1888 provides rhythmic clarity at the expense of horizontal space.
1890 Next we examine how to optimally space overlapping tuplets.
1892 We start by examining what happens to our original example, with
1893 classical spacing, when we add a second staff with a different type of
1896 @lilypond[quote,verbatim,ragged-right]
1898 \new RhythmicStaff {
1902 c'16 c'16 c'16 c'16 c'16
1905 \new RhythmicStaff {
1907 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
1913 The spacing is bad because the evenly notes of the bottom staff do not
1914 stretch uniformly. Classical engraving includes very few complex
1915 triplets and so classical engraving rules can generate this type of
1916 result. Setting @code{proportionalNotationDuration} remedies this
1917 situation considerably.
1919 @lilypond[quote,verbatim,ragged-right]
1921 proportionalNotationDuration = #(ly:make-moment 1 20)
1923 \new RhythmicStaff {
1927 c'16 c'16 c'16 c'16 c'16
1930 \new RhythmicStaff {
1932 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
1938 But if we look very carefully we can see that notes of the second half
1939 of the 9-tuplet space ever so slightly more widely than do the notes
1940 of the first half of the 9-tuplet. To ensure uniform stretching, we
1941 turn on @code{uniform-stretching}, which is a property of
1942 @code{SpacingSpanner}.
1944 @lilypond[quote,verbatim,ragged-right]
1946 proportionalNotationDuration = #(ly:make-moment 1 20)
1947 \override SpacingSpanner #'uniform-stretching = ##t
1949 \new RhythmicStaff {
1953 c'16 c'16 c'16 c'16 c'16
1956 \new RhythmicStaff {
1958 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
1964 Our two-staff example now spaces exactly, our rhythmic
1965 relationships are visually clear, and we can include a measured
1966 timeline or graphic if we want.
1968 Note that the LilyPond's proportional notation package expects
1969 that all proportional scores set the SpacingSpanner's
1970 'uniform-stretching attribute to ##t. Setting
1971 proportionalNotationDuration without also setting the
1972 SpacingSpanner's 'uniform-stretching attribute to ##t will, for
1973 example, cause Skips to consume an incorrect amount of horizontal
1976 The SpacingSpanner is an abstract grob that lives in the Score
1977 context. As with our settings of proportionalNotationDuration,
1978 overrides to the SpacingSpanner can occur in any of three
1979 different places in our input file – in the Score \with block, in
1980 a Score \context block, or in note entry directly.
1982 There is by default only one @code{SpacingSpanner} per @code{Score}. This
1983 means that, by default, @code{uniform-stretching} is either turned on for the
1984 entire score or turned off for the entire score. We can, however,
1985 override this behavior and turn on different spacing features at
1986 different places in the score. We do this with the command
1987 @code{\newSpacingSection}. See @ref{New spacing area}, for more info.
1989 Next we examine the effects of the @code{Separating_line_group_engraver} and
1990 see why proportional scores frequently remove this engraver. The following
1991 example shows that there is a small amount of @qq{preferatory} space
1992 just before the first note in each system.
1994 @lilypond[quote,verbatim,ragged-right]
2007 The amount of this preferatory space is the same whether after a time
2008 signature, a key signature or a clef. @code{Separating_line_group_engraver}
2009 is responsible for this space. Removing @code{Separating_line_group_engraver}
2010 reduces this space to zero.
2012 @lilypond[quote,verbatim,ragged-right]
2018 \remove Separating_line_group_engraver
2026 Nonmusical elements like time signatures, key signatures, clefs and
2027 accidentals are problematic in proportional notation. None of these
2028 elements has rhythmic duration. But all of these elements consume
2029 horizontal space. Different proportional scores approach these
2030 problems differently.
2032 It may be possible to avoid spacing problems with key signatures
2033 simply by not having any. This is a valid option since most
2034 proportional scores are contemporary music. The same may be true
2035 of time signatures, especially for those scores
2036 that include a measured timeline or other graphic. But these scores
2037 are exceptional and most proportional scores include at least some
2038 time signatures. Clefs and accidentals are even more essential.
2040 So what strategies exist for spacing nonmusical elements in a
2041 proportional context? One good option is the @code{strict-note-spacing}
2042 property of @code{SpacingSpanner}. Compare the two scores below:
2044 @lilypond[quote,verbatim,ragged-right]
2046 \set Score.proportionalNotationDuration = #(ly:make-moment 1 16)
2056 \set Score.proportionalNotationDuration = #(ly:make-moment 1 16)
2057 \override Score.SpacingSpanner #'strict-note-spacing = ##t
2067 Both scores are proportional, but the spacing in the first score
2068 is too loose because of the clef change. The spacing of the second
2069 score remains strict, however, because strict-note-spacing is
2070 turned on. Turning on strict-note-spacing causes the width of
2071 time signatures, key signatures, clefs and accidentals to play no
2072 part in the spacing algorithm.
2074 In addition to the settings given here, there are other settings
2075 that frequently appear in proportional scores. These include:
2078 @item @code{\override SpacingSpanner #'strict-grace-spacing = ##t}
2079 @item @code{tupletFullLength = ##t}
2080 @item @code{\override Beam #'breakable = ##t}
2081 @item @code{\override Glissando #'breakable = ##t}
2082 @item @code{\override TextSpanner #'breakable = ##t}
2083 @item @code{\remove Forbid_line_break_engraver in the Voice context}
2086 These settings space grace notes strictly, extend tuplet brackets to
2087 mark both rhythmic start- and stop-points, and allow spanning elements
2088 to break across systems and pages. See the respective parts of the manual
2089 for these related settings.
2093 @node Page layout MOVED FROM LM
2094 @section Page layout MOVED FROM LM
2097 * Introduction to layout::
2101 * Fitting music onto fewer pages::
2104 @node Introduction to layout
2105 @subsection Introduction to layout
2107 The global paper layout is determined by three factors:
2108 the page layout, the line breaks, and the spacing. These all
2109 influence each other. The choice of spacing determines how
2110 densely each system of music is set. This influences where line
2111 breaks are chosen, and thus ultimately, how many pages a piece
2114 Settings which influence layout may be placed in two blocks.
2115 The @code{\paper @{...@}} block is placed outside any
2116 @code{\score @{...@}} blocks and contains settings that
2117 relate to the entire document. The @code{\layout @{...@}}
2118 block is placed within a @code{\score @{...@}} block and
2119 contains settings for that particular score. If you have
2120 only one @code{\score @{...@}} block the two have the same
2121 effect. In general the commands shown in this section can
2122 be placed in either.
2124 Much more detail on the options for tweaking the laying out
2125 of music are contained in @ref{Spacing issues}.
2128 @subsection Global sizes
2130 TODO Check all these examples
2132 The default @strong{paper size} which LilyPond assumes in laying
2133 out the music is A4. This may be changed in two ways:
2136 #(set-default-paper-size "a6")
2139 #(set-paper-size "letter")
2144 The first command sets the size of all pages. The second command
2145 sets the size of the pages to which the \paper block applies -- if
2146 the \paper block is at the top of the file, then it will apply
2147 to all pages. Support for the following paper sizes is available:
2148 a6, a5, a4, a3, legal, letter, 11x17 (also known as tabloid).
2149 Setting the paper size automatically sets suitable margins and
2152 If the symbol @code{landscape} is supplied as an argument to
2153 @code{set-default-paper-size}, the pages will be rotated by 90
2154 degrees, and wider line widths will be set correspondingly, e.g.
2157 #(set-default-paper-size "a6" 'landscape)
2160 The default @strong{staff size} is set to 20 points.
2161 This may be changed in two ways:
2164 #(set-global-staff-size 14)
2167 #(set-global-staff-size 16)
2172 The first command sets the size in all pages. The second command
2173 sets the size in the pages to which the \paper block applies -
\96 if
2174 the \paper block is at the top of the file, then it will apply
2175 to all pages. All the fonts are automatically scaled to suit
2176 the new value of the staff size.
2179 @subsection Line breaks
2181 Line breaks are normally determined automatically. They are chosen
2182 so that lines look neither cramped nor loose, and consecutive
2183 lines have similar density. Occasionally you might want to
2184 override the automatic breaks; you can do this by specifying
2185 @code{\break}. This will force a line break at this point. However,
2186 line breaks can only occur at the end of @q{complete} bars, i.e.,
2187 where there are no notes or tuplets left @q{hanging} over the bar
2188 line. If you want to have a line break where there is no bar line,
2189 you can force an invisible bar line by entering @code{\bar ""},
2190 although again there must be no notes left hanging over in any of
2191 the staves at this point, or it will be ignored.
2193 The opposite command, @code{\noBreak}, forbids a line break at the
2194 bar line where it is inserted.
2196 The most basic settings influencing line spacing are @code{indent}
2197 and @code{line-width}. They are set in the @code{\layout} block.
2198 They control the indentation of the first line of music, and the
2199 lengths of the lines.
2201 If @code{ragged-right} is set to true in the @code{\layout} block,
2202 then systems end at their natural horizontal length, instead of
2203 being spread horizontally to fill the whole line. This is useful
2204 for short fragments, and for checking how tight the natural
2207 The option @code{ragged-last} is similar to @code{ragged-right},
2208 but affects only the last line of the piece.
2219 @subsection Page breaks
2221 The default page breaking may be overridden by inserting
2222 @code{\pageBreak} or @code{\noPageBreak} commands.
2223 These commands are analogous to the @code{\break} and
2224 @code{\noBreak} commands discussed above and force or forbid
2225 a page-break at the point where they are inserted.
2226 Of course, the @code{\pageBreak} command also forces a line break.
2227 Like @code{\break}, the @code{\pageBreak} command is effective only
2228 at the end of a @q{complete} bar as defined above. For more
2229 details see @ref{Page breaking} and following sections.
2231 There are also analogous settings to @code{ragged-right} and
2232 @code{ragged-last} which have the same effect on vertical spacing:
2233 @code{ragged-bottom} and @code{ragged-last-bottom}. If set to
2234 @code{##t} the systems on all pages or just the last page
2235 respectively will not be justified vertically.
2237 For more details see @ref{Vertical spacing}.
2239 @node Fitting music onto fewer pages
2240 @subsection Fitting music onto fewer pages
2242 Sometimes you can end up with one or two staves on a second
2243 (or third, or fourth...) page. This is annoying, especially
2244 if you look at previous pages and it looks like there is plenty
2245 of room left on those.
2247 When investigating layout issues, @code{annotate-spacing} is
2248 an invaluable tool. This command prints the values of various
2249 layout spacing commands; see @ref{Displaying spacing}, for more
2250 details. From the output of @code{annotate-spacing}, we can
2251 see which margins we may wish to alter.
2253 Other than margins, there are a few other options to save space:
2257 You may tell LilyPond to place systems as close together as
2258 possible (to fit as many systems as possible onto a page), but
2259 then to space those systems out so that there is no blank
2260 space at the bottom of the page.
2264 between-system-padding = #0.1
2265 between-system-space = #0.1
2266 ragged-last-bottom = ##f
2272 You may force the number of systems (i.e., if LilyPond wants
2273 to typeset some music with 11 systems, you could force it to
2283 Avoid (or reduce) objects which increase the vertical size of
2284 a system. For example, volta repeats (or alternate repeats)
2285 require extra space. If these repeats are spread over two
2286 systems, they will take up more space than one system with
2287 the volta repeats and another system without.
2289 Another example is moving dynamics which @q{stick out} of
2290 a system, as in the second bar here:
2292 @lilypond[verbatim,quote,fragment,ragged-right,relative=1]
2294 \override DynamicText #'extra-offset = #'( -2.2 . 2.0)
2299 Alter the horizontal spacing via @code{SpacingSpanner}. See
2300 @ref{Changing horizontal spacing}, for more details. Here's
2301 an example first showing the default behavior:
2303 @lilypond[verbatim,quote,ragged-right]
2316 and now with @code{common-shortest-duration} increased from the
2317 value of @code{1/4} (a quarter note is the most common in this
2318 example) to @code{1/2}:
2320 @lilypond[verbatim,quote,ragged-right]
2332 \override SpacingSpanner
2333 #'common-shortest-duration = #(ly:make-moment 1 2)
2340 Note that this override cannot be modified dynamically, so it must
2341 always be placed in a @code{\context@{..@}} block so that it applies
2344 TODO Add description of using \context in this way earlier if it is
2345 not already anywhere -td