Index: ChangeLog =================================================================== RCS file: /sources/lilypond/lilypond/ChangeLog,v retrieving revision 1.5293 diff -u -r1.5293 ChangeLog --- ChangeLog 4 Sep 2006 17:08:02 -0000 1.5293 +++ ChangeLog 5 Sep 2006 06:34:50 -0000 @@ -1,3 +1,13 @@ +2006-09-05 Joe Neeman + + * lily/page-turn-engraver.cc (penalty): minPageTurnLength -> + minimumPageTurnLength + + * scm/define-context-properties.scm (all-user-translation-properties): + add minimumPageTurnLength and minimumRepeatLengthForPageTurn + + * Documentation/user/page.itely: update page breaking documentation + 2006-09-04 Michael Welsh Duggan * lily/tie-performer.cc: remove unused last_event_ property. Index: Documentation/user/page.itely =================================================================== RCS file: /sources/lilypond/lilypond/Documentation/user/page.itely,v retrieving revision 1.8 diff -u -r1.8 page.itely --- Documentation/user/page.itely 27 Aug 2006 06:54:06 -0000 1.8 +++ Documentation/user/page.itely 5 Sep 2006 06:34:50 -0000 @@ -14,15 +14,13 @@ This influences where line breaks are chosen, and thus ultimately, how many pages a piece of music takes. -Globally spoken, this procedure happens in three steps: first, +Globally speaking, this procedure happens in four steps: first, flexible distances (``springs'') are chosen, based on durations. All -possible line breaking combinations are tried, and the one with the -best results -- a layout that has uniform density and requires as -little stretching or cramping as possible -- is chosen. - -After spacing and linebreaking, the systems are distributed across -pages, taking into account the size of the page, and the size of the -titles. +possible line breaking combinations are tried, and a ``badness'' score +is calculated for each. Then the height of each possible system is +estimated. Finally, a page breaking and line breaking combination is chosen +so that neither the horizontal nor the vertical spacing is too cramped +or stretched. @menu * Paper and pages:: @@ -244,6 +242,23 @@ } @end lilypond address@hidden blank-page-force address@hidden blank-page-force +The penalty for having a blank page in the middle of a +score. This is not used by @code{ly:optimal-breaking} since it will +never consider blank pages in the middle of a score. Default value +is 10. + address@hidden blank-last-page-force address@hidden blank-last-page-force +The penalty for ending the score on an odd-numbered page. +Default value is 0. + address@hidden page-spacing-weight address@hidden page-spacing-weight +The relative importance of page (vertical) spacing and line (horizontal) +spacing. High values will make page spacing more important. Default +value is 1. @end table @end quotation @@ -858,6 +873,8 @@ @menu * Line breaking:: * Page breaking:: +* Optimal page breaking:: +* Optimal page turning:: @end menu @node Line breaking @@ -904,7 +921,7 @@ @seealso -Internals: @internalsref{BreakEvent}. +Internals: @internalsref{LineBreakEvent}. A linebreaking configuration can now be saved as a @code{.ly} file automatically. This allows vertical alignments to be stretched to @@ -935,19 +952,22 @@ from happening. Of course, the @code{\pageBreak} command also forces a line break. -Page breaks are computed by the @code{page-breaking} function in the address@hidden block. - -To force a new page for a new piece (in a collection of pieces or a -piece in several movements), use @code{breakbefore} in the header. +Page breaks are computed by the @code{page-breaking} function. +LilyPond provides two algorithms for computing page +breaks, @code{ly:optimal-breaking} and @code{ly:page-turn-breaking}. The +default is @code{ly:optimal-breaking}, but the value can be changed in +the @code{\paper} block: @example address@hidden - breakbefore = ##t - piece = "" address@hidden + #(define page-breaking ly:page-turn-breaking) @} @end example +The old (pre-2.9.17) page breaking algorithm is called address@hidden If you are having trouble with the new page +breakers, you can enable the old one as a workaround. + @refcommands @funindex \pageBreak @@ -956,11 +976,95 @@ @code{\noPageBreak} address@hidden Optimal page breaking address@hidden Optimal page breaking + address@hidden ly:optimal-breaking + +The @code{ly:optimal-breaking} function is LilyPond's default method of +determining page breaks. It attempts to find a page breaking that minimizes +cramping and stretching, both horizontally and vertically. Unlike address@hidden:page-turn-breaking}, it has no concept of page turns. + + address@hidden Optimal page turning address@hidden Optimal page turning + address@hidden ly:page-turn-breaking + +Often it is necessary to find a page breaking configuration so that there is +a rest at the end of every second page. This way, the musician can turn the +page without having to miss notes. The @code{ly:page-turn-breaking} function +attempts to find a page breaking minimizing cramping and stretching, but with +the additional restriction that it is only allowed to introduce page turns +in specified places. + +There are two steps to using this page breaking function. First, you must +enable it in the @code{\paper} block. Then, you must tell the function +where you would like to allow page breaks. + +There are two ways to achieve the second step. First, you can specify each +potential page turn manually, by inserting @code{\allowPageTurn} into your +input file at the appropriate places. + +If this is too tedious, you can add a @code{Page_turn_engraver} to a Staff or +Voice context. The @code{Page_turn_engraver} will scan the context for +sections without notes (note that it does not scan for rests; it scans for +the absence of notes. This is so that single-staff polyphony with rests in one +of the parts does not throw off the @code{Page_turn_engraver}). When it finds +a sufficiently long section without notes, the @code{Page_turn_engraver} will +insert an @code{\allowPageTurn} at the final barline in that section, unless +there is a ``special'' barline (such as a double bar), in which case the address@hidden will be inserted at the final ``special'' barline in +the section. + address@hidden minimumPageTurnLength +The @code{Page_turn_engraver} reads the context property address@hidden to determine how long a note-free section must +be before a page turn is considered. The default value for address@hidden is @code{#(ly:make-moment 1 1)}. If you want +to disable page turns, you can set it to something very large. + address@hidden +\new Staff \with @{ \consists "Page_turn_engraver" @} address@hidden + a4 b c d | + R1 | % a page turn will be allowed here + a4 b c d | + \set Staff.minimumPageTurnLength = #(ly:make-moment 5 2) + R1 | % a page turn will not be allowed here + a4 b r2 | + R1*2 | % a page turn will be allowed here + a1 address@hidden address@hidden example + address@hidden minimumRepeatLengthForPageTurn +The @code{Page_turn_engraver} detects volta repeats. It will only allow a page +turn during the repeat if there is enough time at the beginning and end of the +repeat to turn the page back. The @code{Page_turn_engraver} can also disable +page turns if the repeat is very short. If you set the context property address@hidden then the @code{Page_turn_engraver} will +only allow turns in repeats whose duration is longer than this value. + @refbugs -The @code{breakbefore=##t} header requires that there is a @code{piece} -header as well. It may be used as a normal header, or left blank -(@code{=""}) as in the example above, but it must be present. +The @code{Page_turn_engraver} does not respect time-scaled music. For example, the +following example does not behave as expected: + address@hidden +\new Staff \with @{ \consists "Page_turn_engraver" @} address@hidden + a4 b c d | + R1 | % a page turn will be allowed here + a4 b \times 2/3 @{c d address@hidden | + R1 | % a page turn will NOT be allowed here + a1 address@hidden address@hidden example + +There should only be one @code{Page_turn_engraver} in a score. If there is more +than one, they will stomp on each other. @node Displaying spacing Index: lily/page-turn-engraver.cc =================================================================== RCS file: /sources/lilypond/lilypond/lily/page-turn-engraver.cc,v retrieving revision 1.1 diff -u -r1.1 page-turn-engraver.cc --- lily/page-turn-engraver.cc 8 Aug 2006 10:01:22 -0000 1.1 +++ lily/page-turn-engraver.cc 5 Sep 2006 06:34:51 -0000 @@ -43,7 +43,7 @@ Real Page_turn_engraver::penalty (Rational rest_len) { - Rational min_turn = robust_scm2moment (get_property ("minPageTurnLength"), Moment (1)).main_part_; + Rational min_turn = robust_scm2moment (get_property ("minimumPageTurnLength"), Moment (1)).main_part_; return (rest_len < min_turn) ? infinity_f : 0; } Index: scm/define-context-properties.scm =================================================================== RCS file: /sources/lilypond/lilypond/scm/define-context-properties.scm,v retrieving revision 1.84 diff -u -r1.84 define-context-properties.scm --- scm/define-context-properties.scm 23 Aug 2006 21:19:36 -0000 1.84 +++ scm/define-context-properties.scm 5 Sep 2006 06:34:52 -0000 @@ -313,6 +313,9 @@ (midiMaximumVolume ,number? "Analogous to @code{midiMinimumVolume}.") (minimumFret ,number? "The tablature auto string-selecting mechanism selects the highest string with a fret at least @code{minimumFret}") + (minimumPageTurnLength ,ly:moment? "Minimum length of a rest for a page turn to be allowed") + (minimumRepeatLengthForPageTurn ,ly:moment? "Minimum length of a repeated section for a page +turn to be allowed within that section") (minimumVerticalExtent ,number-pair? "minimum vertical extent, same format as @var{verticalExtent}") (output ,ly:music-output? "The output produced by a score-level translator during music interpretation")