doc: lout: Render examples in a colored box.

* doc/modules/skribilo/documentation/api.scm (le)[inline-definitions-proc]:
  Add @SkribiloExample.
* doc/modules/skribilo/documentation/manual.scm (example)[lout]: Use
  @SkribiloExample.
  (le): Set the `includes' custom to include `diag'.

* src/guile/skribilo/engine/lout.scm (frame): Mark the trick about
  @Floater.

3 files changed, 30 insertions, 10 deletions

diff --git a/doc/modules/skribilo/documentation/api.scm b/doc/modules/skribilo/documentation/api.scm
index 873e03a..8626282 100644
--- a/doc/modules/skribilo/documentation/api.scm
+++ b/doc/modules/skribilo/documentation/api.scm
@@ -93,9 +93,28 @@
   (let ((defs (engine-custom le 'inline-definitions-proc)))
     (engine-custom-set! le 'inline-definitions-proc
                         (lambda (e)
-                          (string-append (defs e) "\n"
-                                         "def @DocHeading right x\n{\n"
-                                         "{ Helvetica Base } @Font x\n}\n"))))
+                          (string-append
+                           (defs e) "\n"
+                           "def @DocHeading right x\n{\n"
+                           "{ Helvetica Base } @Font x\n}\n"
+
+                           "
+# The `example' markup.
+def @SkribiloExample named @Title {} right x {
+  @B { @Title }
+  @Floater
+    @OnePage { No }
+    @Location { Display }
+    @Format {
+      @Diag { @CurveBox
+                outlinestyle { noline }
+                paint { rgb 0.95 0.95 0.87 }
+                font { 0.9f }
+		break { 0.9fx }
+              @HExpand @Body } }
+  { x }
+}\n\n"
+                           ))))
 
   (markup-writer 'doc-markup
     :action (lambda (n e)
diff --git a/doc/modules/skribilo/documentation/manual.scm b/doc/modules/skribilo/documentation/manual.scm
index 40f3f7e..7768b85 100644
--- a/doc/modules/skribilo/documentation/manual.scm
+++ b/doc/modules/skribilo/documentation/manual.scm
@@ -1,7 +1,7 @@
 ;;; manual.scm  --  Skribilo manuals and documentation style.
 ;;; -*- coding: iso-8859-1 -*-
 ;;;
-;;; Copyright 2007, 2008, 2009  Ludovic Courtès <ludo@gnu.org>
+;;; Copyright 2007, 2008, 2009, 2012  Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright 2003, 2004  Manuel Serrano
 ;;;
 ;;;
@@ -83,12 +83,8 @@
                       (number (markup-option n :number))
                       (legend (markup-option n :legend)))
                   (evaluate-document (mark ident) e)
-                  (display "\n@LP\n5c @Wide @FullWidthRule\n@LP\n")
-                  (output (list (! "{ Schoolbook Bold 1.0f } @Font { $1 }"
-                                   (list (format #f "Example ~a. " number)
-                                         legend))
-                                (! "\n@LP\n")
-                                (markup-body n))
+                  (output (! "\n@LP\n@SkribiloExample @Title { Example $1.  $2 } { $3 }\n"
+                             number legend (markup-body n))
                           e)))))
 
 
@@ -162,6 +158,8 @@
    (engine-custom-set! le 'document-type 'book)
    (engine-custom-set! le 'document-include
                        "@Include { \"book-style.lout\" }")
+   (engine-custom-set! le 'includes
+                       "@SysInclude { tbl }\n@SysInclude { diag }\n")
    (engine-custom-set! le 'initial-language "English")
    (engine-custom-set! le 'initial-font "Palatino Base 10p")
    (engine-custom-set! le 'on-title-page (! "@Include { \"front-page.lout\" }")))
diff --git a/src/guile/skribilo/engine/lout.scm b/src/guile/skribilo/engine/lout.scm
index b194e25..95cbc4b 100644
--- a/src/guile/skribilo/engine/lout.scm
+++ b/src/guile/skribilo/engine/lout.scm
@@ -1712,6 +1712,9 @@
    ;; @Box won't span over several pages so this may cause
    ;; problems if large frames are used.  The workaround here consists
    ;; in using an @Tbl with one single cell.
+   ;; FIXME: The workaround seems broken since the manual states that "[p]age
+   ;; breaks cannot occur within rows" (Section 6.11, "Multi-page tables").
+   ;; Use @Floater instead, as for @SkribiloExample.
    :options '(:width :border :margin :bg)
    :before (lambda (n e)
 	     (let ((width (markup-option n :width))