I figured the new page breaking stuff might be more useful if people had
some idea of how to use it. Writing documentation is not something I've
had much practice with, so please point out any problems
2006-09-05 Joe Neeman <[EMAIL PROTECTED]>
* 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
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 <[EMAIL PROTECTED]>
+
+ * 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 <[EMAIL PROTECTED]>
* 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
[EMAIL PROTECTED] blank-page-force
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] blank-last-page-force
[EMAIL PROTECTED] blank-last-page-force
+The penalty for ending the score on an odd-numbered page.
+Default value is 0.
+
[EMAIL PROTECTED] page-spacing-weight
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] 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
[EMAIL PROTECTED]
- breakbefore = ##t
- piece = ""
[EMAIL PROTECTED]
+ #(define page-breaking ly:page-turn-breaking)
@}
@end example
+The old (pre-2.9.17) page breaking algorithm is called
[EMAIL PROTECTED] 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}
[EMAIL PROTECTED] Optimal page breaking
[EMAIL PROTECTED] Optimal page breaking
+
[EMAIL PROTECTED] 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
[EMAIL PROTECTED]:page-turn-breaking}, it has no concept of page turns.
+
+
[EMAIL PROTECTED] Optimal page turning
[EMAIL PROTECTED] Optimal page turning
+
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] will be inserted at the final ``special'' barline in
+the section.
+
[EMAIL PROTECTED] minimumPageTurnLength
+The @code{Page_turn_engraver} reads the context property
[EMAIL PROTECTED] to determine how long a note-free section must
+be before a page turn is considered. The default value for
[EMAIL PROTECTED] is @code{#(ly:make-moment 1 1)}. If you want
+to disable page turns, you can set it to something very large.
+
[EMAIL PROTECTED]
+\new Staff \with @{ \consists "Page_turn_engraver" @}
[EMAIL PROTECTED]
+ 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
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] 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:
+
[EMAIL PROTECTED]
+\new Staff \with @{ \consists "Page_turn_engraver" @}
[EMAIL PROTECTED]
+ a4 b c d |
+ R1 | % a page turn will be allowed here
+ a4 b \times 2/3 @{c d [EMAIL PROTECTED] |
+ R1 | % a page turn will NOT be allowed here
+ a1
[EMAIL PROTECTED]
[EMAIL PROTECTED] 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")
_______________________________________________
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
