[patch] top level page breaking directives

[Nicolas Sceaux]

Han-Wen, Joe,

Here is a patch which implements top-level page breaking directives, for
instance:

  %% these two markups must be on the same page
  \markup { ... }
  \forbidPageBreak
  \markup { ... }

  %% the markup and the score must be on the same new page
  %% that is, same as \header { breakbefore=##t } in the score block
  \forcePageBreak
  \markup { ... }
  \forbidPageBreak
  \score { ... }

Sketch:

 - \forbidPageBreak and \forcePageBreak are music expressions with
   special properties, and are turned into Page_markers by
   collect-music-for-book;

 - then, the Page_markers are added to the Book scores_ (together with
   the scores and markups);

 - finally, when the Paper_book meet such an element when traversing the
   Book scores_, it sets the previous element page break and page turn
   permissions, according the Paper_marker settings.

I'd be grateful if you could review this patch.
(I'm working on regression tests and documentation).

nicolas

diff --git a/lily/book.cc b/lily/book.cc
index bf28d1b..265632a 100644
--- a/lily/book.cc
+++ b/lily/book.cc
@@ -20,6 +20,7 @@ using namespace std;
 #include "warn.hh"
 #include "performance.hh"
 #include "paper-score.hh"
+#include "page-marker.hh"
 
 #include "ly-smobs.icc"
 
@@ -153,7 +154,8 @@ Book::process (Output_def *default_paper
              outputs = scm_cdr (outputs);
            }
        }
-      else if (Text_interface::is_markup (scm_car (s)))
+      else if (Text_interface::is_markup (scm_car (s))
+              || unsmob_page_marker (scm_car (s)))
        paper_book->add_score (scm_car (s));
       else
        assert (0);
diff --git a/lily/include/page-marker.hh b/lily/include/page-marker.hh
new file mode 100644
index 0000000..799e224
--- /dev/null
+++ b/lily/include/page-marker.hh
@@ -0,0 +1,30 @@
+/*
+  page-marker.hh -- declare Page_marker
+
+  source file of the GNU LilyPond music typesetter
+
+  (c) 2007 Nicolas Sceaux <address@hidden>
+*/
+
+#ifndef PAGE_MARKER_HH
+#define PAGE_MARKER_HH
+
+#include "smobs.hh"
+
+class Page_marker
+{
+  DECLARE_SMOBS (Page_marker);
+
+  SCM page_break_permission_; /* 'force, 'allow, or '() */
+  SCM page_turn_permission_;  /* 'force, 'allow, or '() */
+
+public:
+  Page_marker (SCM page_break_permission, SCM page_turn_permission);
+  
+  SCM page_break_permission ();
+  SCM page_turn_permission ();
+};
+
+DECLARE_UNSMOB (Page_marker, page_marker)
+
+#endif /* PAGE_MARKER_HH */
diff --git a/lily/page-marker-scheme.cc b/lily/page-marker-scheme.cc
new file mode 100644
index 0000000..41b4453
--- /dev/null
+++ b/lily/page-marker-scheme.cc
@@ -0,0 +1,19 @@
+/*
+  page-marker-scheme.cc -- implement Page_marker bindings.
+
+  source file of the GNU LilyPond music typesetter
+
+  (c) 2007 Nicolas Sceaux <address@hidden>
+*/
+
+#include "page-marker.hh"
+
+LY_DEFINE (ly_make_page_marker, "ly:make-page-marker",
+          2, 0, 0,
+          (SCM page_break_permission, SCM page_turn_permission),
+          "Return page marker with page breaking and turning permissions.")
+{
+  Page_marker *page_marker = new Page_marker (page_break_permission,
+                                             page_turn_permission);
+  return page_marker->unprotect ();
+}
diff --git a/lily/page-marker.cc b/lily/page-marker.cc
new file mode 100644
index 0000000..99eae98
--- /dev/null
+++ b/lily/page-marker.cc
@@ -0,0 +1,55 @@
+/*
+  page-marker.cc -- implement Page_marker
+
+  source file of the GNU LilyPond music typesetter
+
+  (c) 2007 Nicolas Sceaux <address@hidden>
+*/
+
+#include "page-marker.hh"
+#include "ly-smobs.icc"
+
+Page_marker::Page_marker (SCM page_break_permission, SCM page_turn_permission)
+{
+  page_break_permission_ = page_break_permission;
+  page_turn_permission_ = page_turn_permission;
+  smobify_self ();
+}
+
+Page_marker::~Page_marker ()
+{
+}
+
+IMPLEMENT_SMOBS (Page_marker);
+IMPLEMENT_DEFAULT_EQUAL_P (Page_marker);
+IMPLEMENT_TYPE_P (Page_marker, "ly:page-marker?");
+
+SCM
+Page_marker::mark_smob (SCM smob)
+{
+  Page_marker *pm = (Page_marker *) SCM_CELL_WORD_1 (smob);
+  scm_gc_mark (pm->page_break_permission_);
+  scm_gc_mark (pm->page_turn_permission_);
+  return SCM_EOL;
+}
+
+int
+Page_marker::print_smob (SCM smob, SCM port, scm_print_state*)
+{
+  Page_marker *pm = (Page_marker *) SCM_CELL_WORD_1 (smob);
+  (void)pm;
+  scm_puts ("#<Page_marker>", port);
+  return 1;
+}
+
+SCM
+Page_marker::page_break_permission ()
+{
+  return page_break_permission_;
+}
+
+SCM
+Page_marker::page_turn_permission ()
+{
+  return page_turn_permission_;
+}
diff --git a/lily/paper-book.cc b/lily/paper-book.cc
index c6bcccd..919231d 100644
--- a/lily/paper-book.cc
+++ b/lily/paper-book.cc
@@ -17,6 +17,7 @@
 #include "text-interface.hh"
 #include "warn.hh"
 #include "program-option.hh"
+#include "page-marker.hh"
 
 #include "ly-smobs.icc"
 
@@ -226,6 +227,30 @@ Paper_book::score_title (SCM header)
   return title;
 }
 
+void
+set_page_permissions (SCM sys, SCM page_break_permission, SCM 
page_turn_permission)
+{
+  if (Paper_score *ps = dynamic_cast<Paper_score*> (unsmob_music_output (sys)))
+    {
+      vector<Grob*> cols = ps->get_columns ();
+      if (cols.size ())
+       {
+         Paper_column *col = dynamic_cast<Paper_column*> (cols.back ());
+         col->set_property ("page-break-permission", page_break_permission);
+         col->find_prebroken_piece (LEFT)->set_property 
("page-break-permission",
+                                                         
page_break_permission);
+         col->set_property ("page-turn-permission", page_turn_permission);
+         col->find_prebroken_piece (LEFT)->set_property 
("page-turn-permission",
+                                                         page_turn_permission);
+       }
+    }
+  else if (Prob *pb = unsmob_prob (sys))
+    {
+      pb->set_property ("page-break-permission", page_break_permission);
+      pb->set_property ("page-turn-permission",         page_turn_permission);
+    }
+}
+
 /* read the breakbefore property of a score block and set up the preceding
    system-spec to honour it. That is, SYM should be the system spec that
    immediately precedes the score (from which HEADER is taken)
@@ -240,25 +265,14 @@ set_system_penalty (SCM sys, SCM header)
          && scm_is_bool (SCM_VARIABLE_REF (force)))
        {
          bool b = to_boolean (SCM_VARIABLE_REF (force));
-         SCM sym = b ? ly_symbol2scm ("force") : SCM_EOL;
+         SCM page_break_permission = b ? ly_symbol2scm ("force") : SCM_EOL;
+         SCM page_turn_permission = b ? ly_symbol2scm ("allow") : SCM_EOL;
 
-         if (Paper_score *ps = dynamic_cast<Paper_score*> (unsmob_music_output 
(sys)))
-           {
-             vector<Grob*> cols = ps->get_columns ();
-             if (cols.size ())
-               {
-                 Paper_column *col = dynamic_cast<Paper_column*> (cols.back 
());
-                 col->set_property ("page-break-permission", sym);
-                 col->find_prebroken_piece (LEFT)->set_property 
("page-break-permission", sym);
-               }
-           }
-         else if (Prob *pb = unsmob_prob (sys))
-           pb->set_property ("page-break-permission", sym);
+         set_page_permissions (sys, page_break_permission, 
page_turn_permission);
        }
     }
 }
 
-
 SCM
 Paper_book::get_score_title (SCM header)
 {
@@ -311,6 +325,15 @@ Paper_book::get_system_specs ()
          if (header_0_ == SCM_EOL)
            header_0_ = header;
        }
+      else if (Page_marker *page_marker = unsmob_page_marker (scm_car (s)))
+       {
+         /* a page marker: set previous element page break 
+          * and page turn permissions */
+         if (scm_is_pair (system_specs))
+           set_page_permissions (scm_car (system_specs),
+                                 page_marker->page_break_permission (),
+                                 page_marker->page_turn_permission ());
+       }
       else if (Music_output *mop = unsmob_music_output (scm_car (s)))
        {
          if (Paper_score *pscore = dynamic_cast<Paper_score *> (mop))
@@ -344,9 +367,6 @@ Paper_book::get_system_specs ()
          
          // TODO: init props
          Prob *ps = make_paper_system (SCM_EOL);
-         /* we don't have a way of specifying page-{break,turn} on
-            markup blocks, so for now we just set everything turnable
-           and breakable by default */
          ps->set_property ("page-break-permission", ly_symbol2scm ("allow"));
          ps->set_property ("page-turn-permission", ly_symbol2scm ("allow"));
          
diff --git a/ly/music-functions-init.ly b/ly/music-functions-init.ly
index e6aad14..160a2a2 100644
--- a/ly/music-functions-init.ly
+++ b/ly/music-functions-init.ly
@@ -213,6 +213,21 @@ endSpanners =
        
        (ly:input-message location (_ "argument endSpanners is not an 
EventChord: ~a" music))))
 
+forbidPageBreak =
+#(define-music-function (location parser) ()
+   (_i "Forbid page break between two scores or top-level or markups.")
+   (make-music 'Music 
+              'page-marker #t
+              'page-break-permission '()
+              'page-turn-permission '()))
+
+forcePageBreak = #(define-music-function (location parser) ()
+   (_i "Force a page break between two scores or top-level or markups.")
+   (make-music 'Music 
+              'page-marker #t
+              'page-break-permission 'force
+              'page-turn-permission 'allow))
+
 featherDurations=
 #(define-music-function (parser location factor argument) (ly:moment? 
ly:music?)
    (_i "Rearrange durations in ARGUMENT so there is an
diff --git a/scm/lily-library.scm b/scm/lily-library.scm
index e6215b9..94f3218 100644
--- a/scm/lily-library.scm
+++ b/scm/lily-library.scm
@@ -65,9 +65,18 @@
 
 (define-public (collect-music-for-book parser music)
   ;; discard music if its 'void property is true.
-  (let ((void-music (ly:music-property music 'void)))
-    (if (or (null? void-music) (not void-music))
-        (collect-scores-for-book parser (scorify-music music parser)))))
+  (let ((void-music (ly:music-property music 'void))
+       (page-marker (ly:music-property music 'page-marker)))
+    (cond ((and (not (null? page-marker)) page-marker)
+          ;; a page break marker
+          (collect-scores-for-book
+           parser
+           (ly:make-page-marker
+            (ly:music-property music 'page-break-permission)
+            (ly:music-property music 'page-turn-permission))))
+          ((or (null? void-music) (not void-music))
+           ;; a regular music expression: make a score with this music
+           (collect-scores-for-book parser (scorify-music music parser))))))
 
 (define-public (scorify-music music parser)
   "Preprocess MUSIC."