+ LilyPond is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ LilyPond is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with LilyPond. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+/*
+ This is a utility class for page-breaking algorithms. There are some complex
+ parts of this class, some of which are useful to understand if you intend
+ to write a page breaking algorithm (ie. a subclass of Page_breaking). Most
+ of these complexities were introduced in order to break the problem of
+ page-breaking into simpler subproblems and to hide some of the bookkeeping
+ complexities of page breaking from the page breaking algorithms.
+
+ COMPRESSED LINES
+ There are several functions that actually distribute systems across pages
+ (for example, the space_systems_XXX and pack_systems_XXX functions). If
+ each of these functions had to handle \noPageBreak, it would be a mess.
+ Therefore, we handle \noPageBreak by "compressing" the list of systems
+ before doing any layout: we concatenate any two systems separated by a
+ \noPageBreak into a single system. The page-breaking functions can do their
+ magic without encountering a \noPageBreak; we then "uncompress" the systems
+ at the end. We almost always work with cached_line_details_, which are
+ "compressed."
+
+ CHUNKS
+ The basic operation of a page breaking algorithm is to repeatedly request
+ some systems from the line-breaker and place those systems on some pages.
+ With each repetition, the page breaking algorithm asks the line-breaker for
+ some systems that it thinks will help it achieve a better layout. The
+ Page_breaking class provides functionality to facilitate this in the case
+ that the page breaking algorithm only cares about the number of systems.
+
+ Even if a page breaking algorithm only cares number of systems, there may
+ be many ways to satisfy its request. For example, in a piece with 2 scores
+ and a request for 10 systems, we could return 5 systems from each score or
+ 4 from the first and 6 from the second. Even within a score, we might
+ want to try several different line breaking configurations with a fixed
+ system count; if there is a forced \pageBreak, for example, we might wish
+ to tweak the number of systems on both sides of the \pageBreak independently.
+
+ The Page_breaking class takes care of finding these configurations. It
+ divides the piece into "chunks" and sets up the line-breaker in such a way
+ that the number of systems in each chunk can be modified independently.
+ Chunks never cross score boundaries; each title and markup is its own chunk.
+ When a page breaking algorithm requests a number of systems, the Page_breaker
+ stores an array of potential configurations, which the page breaking
+ algorithm can iterate over using current_configuration(vsize).
+
+ LINE_DIVISION
+ A Line_division is simply a way of storing the exact way in which the
+ total number of systems is distributed among chunks. Note that a
+ Line_division may not (in fact, usually will not) describe all of the chunks
+ in the entire book. Rather, it will describe the subset of chunks that lie
+ between some fixed starting and ending point. This subset of chunks changes
+ whenever a page breaking algorithm asks to consider a different pair of
+ starting and ending breakpoints. In particular, a Line_division should be
+ discarded after a call to set_current_breakpoints, since that Line_division
+ refers to a subset of chunks which might be different from the current
+ subset of chunks under consideration.
+
+ HOW TO WRITE A PAGE BREAKING ALGORITHM
+ All page breakers supported by this class work more-or-less in the same way.
+ First, they request a particular number of systems by saying
+ set_current_breakpoints (0, last_break_position (), system_count)
+ (never mind what the first two arguments do, I'll get to them later).
+ Alternatively, you can do
+ set_to_ideal_line_configuration (0, last_break_position ()),
+ and the number of systems will be automatically chosen according to what
+ the line breaker wants.
+
+ If there are multiple scores, there will be many different ways to achieve
+ a certain number of lines. You can see how many alternatives are available
+ with current_configuration_count (). For every i from 0 to
+ current_configuration_count ()-1, you can see the line division of the
+ corresponding configuration with current_configuration (i), or you can try
+ out various page configurations with one of the space_systems_xxx or
+ pack_systems_xxx functions. The first argument to each of these functions
+ is the configuration index.
+
+ When you're done trying out configurations and you've picked the one
+ you want, do
+ break_into_pieces (0, last_break_position (), line_division_that_you_want);
+ return make_pages (systems_per_page, systems ());
+ where systems_per_page is a vector of numbers telling how many systems are
+ on each page. You can get your systems_per_page vector by looking inside
+ the Page_spacing_results that are returned by space_systems_xxx or
+ pack_systems_xxx.
+
+ A note on performance: set_current_breakpoints is EXPONENTIALLY SLOW unless
+ you constrain it by giving it a lower or an upper bound on the configurations
+ it looks for. Optimal_page_breaking, for example, works by trying
+ out a bunch of configurations, increasing the system count by one, trying
+ again and so on. Each time we increase the system count, we assume that the
+ best new configurations are going to be elementwise larger than the
+ best configuration for the previous system count (in other words, we're going
+ to get a new configuration just by adding an extra line to sone score
+ and leaving the rest the same). Therefore, we pass the best previous line
+ division as an lower bound to set_current_breakpoints.
+
+ Now you should be in a position to understand Optimal_page_breaking::solve.
+ Go ahead and read that before finding out, in the next paragraph,
+ what the first two arguments to set_current_breakpoints do.
+
+ "BREAKS"
+ Sometimes, it's useful to run this whole page-breaking machinery on a subset
+ of the book. To do this, you can mark certain "breaks" in the book (a poor
+ choice of name, perhaps, since a "break" here is different from a page break)
+ and you can run page breaking between any two breaks. You mark your breaks
+ by providing a Break_predicate (and, if you want, a Prob_break_predicate)
+ to Page_breaking's constructor. You then choose a subset of your book
+ by passing the starting and ending breaks to set_current_breakpoints. You
+ can see an example of this in Page_turn_page_breaking, where there is a break
+ everywhere that a page turn is allowed.