doc: Document `pie' markups.

* doc/user/pie.skb (Syntax): Document markups.

* src/guile/skribilo/package/pie.scm (pie, slice, sliceweight): Add
  `:class' option.
  (pie, slice, sliceweight)[writers]: Add `:options'.

4 files changed, 65 insertions, 7 deletions

diff --git a/NEWS b/NEWS
index ca23411..a066fcb 100644
--- a/NEWS
+++ b/NEWS
@@ -30,6 +30,7 @@ This allows compilation with the compiler of "Guile-VM", i.e., the
 future Guile 2.x.
 
 ** New test suite (run "make check")
+** Various documentation fixes, improvements and additions
 
 * New in Skribilo 0.9.1
 
diff --git a/doc/user/pie.skb b/doc/user/pie.skb
index 34b489f..70fa08d 100644
--- a/doc/user/pie.skb
+++ b/doc/user/pie.skb
@@ -67,6 +67,56 @@ of ,(tt [pie]) can be used to create pie charts no entirely filled.])
 	(example-produce
 	  (example :legend "Specifying the layout of a pie chart"
 	     (prgm :file "src/pie2.skb"))
-	  (disp (include "src/pie2.skb"))))))
-	
-;;; arch-tag: 60382016-3a63-4466-83e0-46a259cb39ab
+	  (disp (include "src/pie2.skb"))))
+   
+      (p [The available markups and their options are described below.])
+      
+      (doc-markup 'pie
+      		  `((:title         ,[The title of the pie chart.])
+		    (:initial-angle ,[The initial angle of the pie, in degrees.])
+		    (:total         ,[If a number, specifies the
+"weight" of the whole pie; in this case, if the pie's slices don't add
+up to that number, then part of the pie is shown as empty.  If ,(code
+[#f]), the total that is used is the sum of the weight of each slice.])
+                    (:radius        ,[The pie's radius.  How this value
+is interpreted depends on the engine used.])
+                    (:fingers?      ,[Indicates whether to add "fingers"
+(arrows) from labels to slices when labels are outside of slices.])
+	            (:labels        ,[A symbol indicating where slice
+labels are rendered: ,(code [outside]) to have them appear outside of
+the pie, ,(code [inside]) to have them appear inside the pie, and ,(code
+[legend]) to have them appear in a separate legend.]))
+	           :source "skribilo/package/pie.scm"
+		   :see-also '(slice))
+      
+      (doc-markup 'slice
+      		  `((#!rest label ,[The label of the node.  It can
+contain arbitrary markup, notably instances of ,(markup-ref
+"sliceweight").  However, some engines, such as the Ploticus-based
+rendering, are not able to render markup other than ,(markup-ref
+"sliceweight"); consequently, they render the label as though it were
+markup-free.])
+		    (:weight      ,[An integer indicating the weight of this
+slice.])
+	            (:color       ,[The background color of the slice.])
+		    (:detach?     ,[Indicates whether the slice should be
+detached from the pie.]))
+	           :source "skribilo/package/pie.scm"
+		   :see-also '(pie sliceweight))
+      
+      (p [As seen in the examples above, the body of a ,(markup-ref
+"slice") markup can contain instances of ,(markup-ref "sliceweight") to
+represent the weight of the slice:])
+      
+      (doc-markup 'sliceweight
+            	  `((:percentage? ,[Indicates whether the slice's weight
+should be shown as a percentage of the total pie weight or as a raw
+weight.]))
+	           :see-also '(slice)
+		   :source "skribilo/package/pie.scm")))
+      
+
+;; Local Variables:
+;; coding: latin-1
+;; ispell-local-dictionary: "american"
+;; End:
diff --git a/src/guile/skribilo/package/pie.scm b/src/guile/skribilo/package/pie.scm
index f99c725..2834076 100644
--- a/src/guile/skribilo/package/pie.scm
+++ b/src/guile/skribilo/package/pie.scm
@@ -44,7 +44,7 @@
 ;;;
 
 (define-markup (pie :rest opts
-		    :key (ident #f) (title "Pie Chart")
+		    :key (ident #f) (class "pie") (title "Pie Chart")
 		    (initial-angle 0) (total #f) (radius 3)
 		    (fingers? #t) (labels 'outside)
 		    (class "pie"))
@@ -56,7 +56,8 @@
 	(body (the-body opts))))
 
 (define-markup (slice :rest opts
-		      :key (ident #f) (weight 1) (color "white") (detach? #f))
+		      :key (ident #f) (class "pie-slice")
+                           (weight 1) (color "white") (detach? #f))
    (new container
 	(markup 'slice)
 	(ident (or ident (symbol->string (gensym "slice"))))
@@ -68,7 +69,8 @@
 	(body (the-body opts))))
 
 (define-markup (sliceweight :rest opts
-			    :key (ident #f) (percentage? #f))
+			    :key (ident #f) (class "pie-sliceweight")
+                                 (percentage? #f))
    (new markup
 	(markup 'sliceweight)
 	(ident (or ident (symbol->string (gensym "sliceweight"))))
@@ -251,6 +253,7 @@ the string \"hello\".  Implement `sliceweight' markups too."
 		   `("colors: " ,@colors "\n")))))
 
 (markup-writer 'pie (find-engine 'base)
+  :options '(:title :initial-angle :total :radius :labels)
   :action (lambda (node engine)
 	    (let* ((fmt (select-output-format engine))
 		   (pie-file (string-append (markup-ident node) "."
@@ -291,11 +294,13 @@ the string \"hello\".  Implement `sliceweight' markups too."
 			engine))))
 
 (markup-writer 'slice (find-engine 'base)
+  :options '(:weight :color :detach?)
   :action (lambda (node engine)
 	    ;; Nothing to do here
 	    (error "slice: this writer should never be invoked")))
 
 (markup-writer 'sliceweight (find-engine 'base)
+  :options '(:percentage?)
   :action (lambda (node engine)
 	    ;; Nothing to do here.
 	    (error "sliceweight: this writer should never be invoked")))
diff --git a/src/guile/skribilo/package/pie/lout.scm b/src/guile/skribilo/package/pie/lout.scm
index fe3c674..085cfc2 100644
--- a/src/guile/skribilo/package/pie/lout.scm
+++ b/src/guile/skribilo/package/pie/lout.scm
@@ -1,6 +1,6 @@
 ;;; lout.scm  --  Lout implementation of the `pie' package.
 ;;;
-;;; Copyright 2005, 2006, 2007  Ludovic Courtès <ludovic.courtes@laas.fr>
+;;; Copyright 2005, 2006, 2007, 2009  Ludovic Courtès <ludo@gnu.org>
 ;;;
 ;;;
 ;;; This program is free software; you can redistribute it and/or modify
@@ -49,6 +49,7 @@
 ;;;
 
 (markup-writer 'pie (find-engine 'lout)
+   :options '(:title :initial-angle :total :radius :labels :fingers?)
    :before (lambda (node engine)
 	      (let* ((weights (map (lambda (slice)
 				     (markup-option slice :weight))
@@ -121,6 +122,7 @@
 (markup-writer 'sliceweight (find-engine 'base)
    ;; This writer should work for every engine, provided the `pie' markup has
    ;; a proper `&total-weight' option.
+   :options '(:percentage?)
    :action (lambda (node engine)
 	      (let ((pct? (markup-option node :percentage?)))
 		 (output (number->string