From adfc4299a872d1bc571eb7d4be2db8bc010fb10a Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Wed, 27 May 2009 22:20:56 +0200 Subject: 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'. --- NEWS | 1 + doc/user/pie.skb | 56 +++++++++++++++++++++++++++++++-- src/guile/skribilo/package/pie.scm | 11 +++++-- src/guile/skribilo/package/pie/lout.scm | 4 ++- 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 +;;; Copyright 2005, 2006, 2007, 2009 Ludovic Courtès ;;; ;;; ;;; 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 -- cgit v1.2.3