Re: page breaking documentation

[Graham Percival]

Joe Neeman wrote:
> 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

Looks fairly good; I've made a few comments below, but once those are 
fixed the docs can be committed.

> 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

...

> @@ -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.

Please remove the version number, ie
+The old page breaking algorithm is called

Users will only see the manual for 2.9.18, so it's safe to merely say "old".


> @@ -956,11 +976,95 @@

...

> +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.

By "the absence of notes", do you mean "{r | R | s} in all parts", or do 
you mean "{s} in all parts" ?  That "does not scan for rests" is a bit 
confusing.  If you mean the first option, I suggest

+sections without notes (either @code{r} or @code{R} rests or
address@hidden skips.

> +This is so that single-staff polyphony with rests in one
> +of the parts does not throw off the @code{Page_turn_engraver}).


> 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.
- previous line

+than one, they will interfere with each other.

I personally like the word "stomp", but it `stomps' on our professional 
atmosphere.  :)


Cheers,
- Graham