summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLudovic Courtès2009-05-27 22:20:56 +0200
committerLudovic Courtès2009-05-27 22:20:56 +0200
commitadfc4299a872d1bc571eb7d4be2db8bc010fb10a (patch)
tree55fb7b75cd0131e98b61d1cb2244aa58137160f5
parentc9157a3905fc17a70d36ec46db809efb91c14887 (diff)
downloadskribilo-adfc4299a872d1bc571eb7d4be2db8bc010fb10a.tar.gz
skribilo-adfc4299a872d1bc571eb7d4be2db8bc010fb10a.tar.lz
skribilo-adfc4299a872d1bc571eb7d4be2db8bc010fb10a.zip
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'.
-rw-r--r--NEWS1
-rw-r--r--doc/user/pie.skb56
-rw-r--r--src/guile/skribilo/package/pie.scm11
-rw-r--r--src/guile/skribilo/package/pie/lout.scm4
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