summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLudovic Courtes2006-01-17 22:50:23 +0000
committerLudovic Courtes2006-01-17 22:50:23 +0000
commit46c709dc1f242fa680d4425da4dfc9314686e9cc (patch)
tree93535db7d12eae5cb86a7c1af64bafe07f5d3275 /doc
parent2d8fa88ef04b3a6141a2b03a9671a7dd0fcc1f60 (diff)
downloadskribilo-46c709dc1f242fa680d4425da4dfc9314686e9cc.tar.gz
skribilo-46c709dc1f242fa680d4425da4dfc9314686e9cc.tar.lz
skribilo-46c709dc1f242fa680d4425da4dfc9314686e9cc.zip
Towards a self-hosted user manual.
* doc/skr/api.skr: Use `(skribilo reader)' and `(skribilo utils syntax)'. (api-search-definition): Added a SKRIBE-SOURCE? argument. Determine the appropriate reader based on its value. (keyword->symbol): Removed. (define-markup?): Fixed. (make-engine?): Fixed (but unverified). (make-engine-custom): Likewise. (sym/kw?): New. (define-markup-formals): Fixed. (define-markup-options): Likewise. (define-markup-rest): Likewise. (doc-markup): Added a SKRIBE-SOURCE? argument. (doc-engine): Likewise. * doc/user/*.skb: Updated the `:source' arguments to `doc-markup' and `doc-engine'. * src/guile/skribilo/utils/compat.scm (hashtable-update!): Fixed according to the Bigloo manual. git-archimport-id: lcourtes@laas.fr--2005-mobile/skribilo--devel--1.2--patch-26
Diffstat (limited to 'doc')
-rw-r--r--doc/skr/api.skr124
-rw-r--r--doc/user/bib.skb11
-rw-r--r--doc/user/engine.skb14
-rw-r--r--doc/user/htmle.skb2
-rw-r--r--doc/user/image.skb4
-rw-r--r--doc/user/index.skb2
-rw-r--r--doc/user/latexe.skb2
-rw-r--r--doc/user/lib.skb12
-rw-r--r--doc/user/package.skb8
-rw-r--r--doc/user/sectioning.skb2
-rw-r--r--doc/user/slide.skb8
-rw-r--r--doc/user/xmle.skb10
12 files changed, 112 insertions, 87 deletions
diff --git a/doc/skr/api.skr b/doc/skr/api.skr
index 70016b9..6d0c5bd 100644
--- a/doc/skr/api.skr
+++ b/doc/skr/api.skr
@@ -9,7 +9,9 @@
;* The Skribe style for documenting Lisp APIs. */
;*=====================================================================*/
-(use-modules (ice-9 match))
+(use-modules (ice-9 match)
+ (skribilo reader) ;; `make-reader'
+ (skribilo utils syntax)) ;; `%skribilo-module-reader'
;*---------------------------------------------------------------------*/
;* Html configuration */
@@ -60,9 +62,13 @@
;* ------------------------------------------------------------- */
;* Find a definition inside a source file. */
;*---------------------------------------------------------------------*/
-(define (api-search-definition id file pred)
+(define* (api-search-definition id file pred :optional (skribe-source? #t))
+ ;; If SKRIBE-SOURCE? is true, then assume Skribe syntax. Otherwise, use
+ ;; the ``Skribilo module syntax''.
(let* ((path (append %load-path (skribe-path)))
- (f (find-file/path file path)))
+ (f (find-file/path file path))
+ (read (if skribe-source? (make-reader 'skribe)
+ %skribilo-module-reader)))
(if (not (string? f))
(skribe-error 'api-search-definition
(format #f "can't find source file `~a' in path"
@@ -73,7 +79,7 @@
(let loop ((exp (read)))
(if (eof-object? exp)
(skribe-error 'api-search-definition
- (format #t
+ (format #f
"can't find `~a' definition" id)
file)
(or (pred id exp) (loop (read))))))))))
@@ -93,29 +99,20 @@
(or (and (null? d1) (null? d2))
(list d1 d2))))
-;*---------------------------------------------------------------------*/
-;* keyword->symbol ... */
-;*---------------------------------------------------------------------*/
-(define (keyword->symbol kwd)
- (let ((s (keyword->string kwd)))
- (if (char=? #\: (string-ref s 0))
- ;; Bigloo
- (string->symbol (substring s 1 (string-length s)))
- ;; STklos
- (string->symbol s))))
;*---------------------------------------------------------------------*/
;* define-markup? ... */
;*---------------------------------------------------------------------*/
(define (define-markup? id o)
(match o
- ((or 'define-markup 'define 'define-inline
- (? (lambda (x) (eq? x id)))
- (? (lambda (x) (or (pair? x) (null? x)))))
+ (((or 'define-markup 'define 'define-inline)
+ ((? (lambda (x) (eq? x id)))
+ . (? (lambda (x) (or (pair? x) (null? x)))))
+ . _)
o)
- ((define-simple-markup (? (lambda (x) (eq? x id))))
+ (('define-simple-markup (? (lambda (x) (eq? x id))))
o)
- ((define-simple-container (? (lambda (x) (eq? x id))))
+ (('define-simple-container (? (lambda (x) (eq? x id))))
o)
(else
#f)))
@@ -125,13 +122,14 @@
;*---------------------------------------------------------------------*/
(define (make-engine? id o)
(match o
- (((or make-engine copy-engine) (quote (? (lambda (x) (eq? x id)))) . ?-)
+ (((or 'make-engine 'copy-engine)
+ (quote (? (lambda (x) (eq? x id)))) _)
o)
- ((quasiquote . ?-)
+ ((`_)
#f)
- ((quote . ?-)
+ ((_)
#f)
- ((?a . ?d)
+ ((a d)
(or (make-engine? id a) (make-engine? id d)))
(else
#f)))
@@ -141,13 +139,16 @@
;*---------------------------------------------------------------------*/
(define (make-engine-custom def)
(match (memq :custom def)
- ((:custom (quote ?custom) . ?-)
+ ((:custom `custom _)
custom)
- ((:custom ?custom . ?-)
+ ((:custom custom _)
(eval custom))
- (else
+ (else
'())))
+(define (sym/kw? x)
+ (or (symbol? x) (keyword? x)))
+
;*---------------------------------------------------------------------*/
;* define-markup-formals ... */
;* ------------------------------------------------------------- */
@@ -156,26 +157,24 @@
;*---------------------------------------------------------------------*/
(define (define-markup-formals def)
(match def
- ((?- (?- . ?args) . ?-)
- (if (symbol? args)
- (list args)
- (let loop ((args args)
- (res '()))
- (cond
- ((null? args)
- (reverse! res))
- ((symbol? args)
- (reverse! (cons args res)))
- ((not (symbol? (car args)))
- (reverse! res))
- (else
- (loop (cdr args) (cons (car args) res)))))))
- ((define-simple-markup ?-)
+ ((_ (id args ___) _ ___)
+ (let loop ((args args)
+ (res '()))
+ (cond
+ ((null? args)
+ (reverse! res))
+ ((symbol? args)
+ (reverse! (cons args res)))
+ ((not (symbol? (car args)))
+ (reverse! res))
+ (else
+ (loop (cdr args) (cons (car args) res))))))
+ (('define-simple-markup _)
'())
- ((define-simple-container ?-)
+ (('define-simple-container _)
'())
(else
- (skribe-error 'define-markup-formals
+ (skribe-error 'define-markup-formals
"Illegal `define-markup' form"
def))))
@@ -186,19 +185,19 @@
;*---------------------------------------------------------------------*/
(define (define-markup-options def)
(match def
- ((?- (?- . ?args) . ?-)
+ (('define-markup (args ___) _)
(if (not (list? args))
'()
(let ((keys (memq #!key args)))
(if (pair? keys)
- (cdr keys)
+ (cdr keys) ;; FIXME: do we need to filter ((key val)...)?
'()))))
- ((define-simple-markup ?-)
+ (('define-simple-markup _)
'((ident #f) (class #f)))
- ((define-simple-container ?-)
+ (('define-simple-container _)
'((ident #f) (class #f)))
(else
- (skribe-error 'define-markup-formals
+ (skribe-error 'define-markup-formals
"Illegal `define-markup' form"
def))))
@@ -209,7 +208,7 @@
;*---------------------------------------------------------------------*/
(define (define-markup-rest def)
(match def
- ((?- (?- . ?args) . ?-)
+ (('define-markup (args ___) _)
(if (not (pair? args))
args
(let ((l (last-pair args)))
@@ -224,12 +223,12 @@
def)
(cadr rest))
#f))))))
- ((define-simple-markup ?-)
+ (('define-simple-markup _)
'node)
- ((define-simple-container ?-)
+ (('define-simple-container _)
'node)
(else
- (skribe-error 'define-markup-formals
+ (skribe-error 'define-markup-rest
"Illegal `define-markup' form"
def))))
@@ -254,10 +253,10 @@
(d2 (cadr d)))
(if (pair? d1)
(skribe-error 'doc-markup
- (format "~a: missing descriptions" id)
+ (format #f "~a: missing descriptions" id)
d1)
(skribe-error 'doc-markup
- (format "~a: extra descriptions" id)
+ (format #f "~a: extra descriptions" id)
d2))))))
;*---------------------------------------------------------------------*/
@@ -294,7 +293,8 @@
(list " " (keyword opt))))
(define (formal f)
(list " " (param f)))
- (code (list (bold "(") (bold :class 'api-proto-ident (format "~a" id)))
+ (code (list (bold "(") (bold :class 'api-proto-ident
+ (format #f "~a" id)))
(map option (sort options
(lambda (s1 s2)
(cond
@@ -331,6 +331,7 @@
(force-engines '())
(engines *api-engines*)
(sui #f)
+ (skribe-source? #t)
&skribe-eval-location)
(define (opt-engine-support opt)
;; find the engines providing a writer for id
@@ -372,9 +373,11 @@
((and (not def) (not source))
(skribe-error 'doc-markup "source or def must be specified" id))
(else
- (let* ((d (or def (api-search-definition id source define-markup?)))
+ (let* ((d (or def (api-search-definition id source define-markup?
+ skribe-source?)))
(od (map (lambda (o)
- (api-search-definition o source define-markup?))
+ (api-search-definition o source define-markup?
+ skribe-source?))
others))
(args (append common-args args))
(formals (define-markup-formals d))
@@ -545,6 +548,7 @@
#!key
(idx *custom-index*)
source
+ (skribe-source? #t)
(def #f))
(cond
((and def source)
@@ -552,7 +556,8 @@
((and (not def) (not source))
(skribe-error 'doc-engine "source or def must be specified" id))
(else
- (let* ((d (or def (api-search-definition id source make-engine?)))
+ (let* ((d (or def (api-search-definition id source make-engine?
+ skribe-source?)))
(c (make-engine-custom d)))
(doc-check-arguments id c args)
(cond
@@ -571,7 +576,8 @@
(td :align 'left :valign 'top
(list (index (symbol->string (car r))
:index idx
- :note (format "~a custom" id))
+ :note (format #f "~a custom"
+ id))
(symbol->string (car r))))
(let ((def (assq (car r) c)))
(td :valign 'top
diff --git a/doc/user/bib.skb b/doc/user/bib.skb
index a006a9b..c5357af 100644
--- a/doc/user/bib.skb
+++ b/doc/user/bib.skb
@@ -51,7 +51,8 @@ if its argument is a bibliography table as returned by
:see-also '(make-bib-table default-bib-table bibliography the-bibliography)
:force-engines *api-engines*
:common-args '()
- :source "../src/bigloo/bib.bgl")
+ :skribe-source? #f
+ :source "skribilo/biblio.scm")
(p [The function ,(code "default-bib-table") returns a global, pre-existing
bibliography-table:])
@@ -60,7 +61,8 @@ bibliography-table:])
:see-also '(bib-table? make-bib-table bibliography the-bibliography)
:force-engines *api-engines*
:common-args '()
- :source "../src/bigloo/bib.bgl")
+ :skribe-source? #f
+ :source "skribilo/biblio.scm")
(p [The function ,(code "make-bib-table") constructs a new
bibliography-table:])
@@ -69,7 +71,8 @@ bibliography-table:])
:see-also '(bib-table? default-bib-table bibliography the-bibliography)
:force-engines *api-engines*
:common-args '()
- :source "../src/bigloo/bib.bgl"))
+ :skribe-source? #f
+ :source "skribilo/biblio.scm"))
;*---------------------------------------------------------------------*/
;* bibliography ... @label bibliography@ */
@@ -204,7 +207,7 @@ pre-existing functions for sorting entries:])
(doc-markup 'bib-sort/authors
'((l [The list of entries.]))
:force-engines *api-engines*
- :source "../src/common/bib.scm"
+ :source "skribilo/skribe/bib.scm"
:others '(bib-sort/idents bib-sort/dates)
:common-args '())
diff --git a/doc/user/engine.skb b/doc/user/engine.skb
index 06be3c4..b8a5b47 100644
--- a/doc/user/engine.skb
+++ b/doc/user/engine.skb
@@ -11,6 +11,9 @@
;; @indent: (put 'doc-markup 'skribe-indent 'skribe-indent-function)@
(cond-expand
+ (guile
+ (define *engine-src* "skribilo/engine.scm")
+ (define *types-src* #f))
(bigloo
(define *engine-src* "../src/bigloo/engine.scm")
(define *types-src* "../src/bigloo/types.scm"))
@@ -55,6 +58,7 @@ given below:])
(:custom [The engine custom list.])
(:info [Miscellaneous.]))
:common-args '()
+ :skribe-source? #f
:source *engine-src*
:idx *function-index*)
@@ -68,6 +72,7 @@ given below:])
(:symbol-table [The engine symbol table.])
(:custom [The engine custom list.]))
:common-args '()
+ :skribe-source? #f
:source *engine-src*
:idx *function-index*))
@@ -80,6 +85,7 @@ on failure.])
'((id [The name (a symbol) of the engine to be searched.])
(:version [An optional version number for the searched engine.]))
:common-args '()
+ :skribe-source? #f
:source *engine-src*
:idx *function-index*))
@@ -91,7 +97,8 @@ argument is an engine. Otherwise, it returns ,(code "#f"). In other words,
(doc-markup 'engine?
'((obj [The checked object.]))
:common-args '()
- :source *types-src*
+ :skribe-source? #f
+ :source *engine-src*
:idx *function-index*)
(p [The following functions return information about engines.])
@@ -100,7 +107,8 @@ argument is an engine. Otherwise, it returns ,(code "#f"). In other words,
'((obj [The engine.]))
:common-args '()
:others '(engine-format engine-customs engine-filter engine-symbol-table)
- :source *types-src*
+ :skribe-source? #f
+ :source *engine-src*
:idx *function-index*))
(subsection :title "Engine customs"
@@ -117,6 +125,7 @@ a custom.])
,(ref :mark "find-engine" :text (code "find-engine"))).])
(id [The name of the custom.]))
:common-args '()
+ :skribe-source? #f
:source *engine-src*
:idx *function-index*)
@@ -126,6 +135,7 @@ a custom.])
(id [The name of the custom.])
(val [The new value of the custom.]))
:common-args '()
+ :skribe-source? #f
:source *engine-src*
:idx *function-index*)))
diff --git a/doc/user/htmle.skb b/doc/user/htmle.skb
index b5d0b0e..5e556cc 100644
--- a/doc/user/htmle.skb
+++ b/doc/user/htmle.skb
@@ -106,6 +106,6 @@ the document.])
(source-bracket-color "The source bracket color.")
(source-type-color "The source type color.")
(image-format "The image formats for this engine."))
- :source "skr/html.skr")))
+ :source "skribilo/engine/html.scm")))
diff --git a/doc/user/image.skb b/doc/user/image.skb
index d08ad18..ce448df 100644
--- a/doc/user/image.skb
+++ b/doc/user/image.skb
@@ -73,7 +73,9 @@ returns the name of the new converted image. On failure, it returns
searched in the ,(ref :mark "skribe-image-path" :text "image path").])
(formats [A list of formats into which images are converted to.]))
:common-args '()
- :source "../src/bigloo/lib.bgl"
+ :skribe-source? #f
+ :source #f ;;"skribilo/runtime.scm"
+ :def '(define-markup (convert-image file formats) ...)
:see-also '(skribe-image-path)
:idx *function-index*)))
diff --git a/doc/user/index.skb b/doc/user/index.skb
index dd5e8fa..6c9ee1c 100644
--- a/doc/user/index.skb
+++ b/doc/user/index.skb
@@ -50,7 +50,7 @@ that pre-exists to all execution.])
(doc-markup 'default-index
'()
:common-args '()
- :source "src/common/index.scm"))
+ :source "skribilo/skribe/index.scm"))
;*---------------------------------------------------------------------*/
;* Index ... @label index@ */
diff --git a/doc/user/latexe.skb b/doc/user/latexe.skb
index f53737b..860bacd 100644
--- a/doc/user/latexe.skb
+++ b/doc/user/latexe.skb
@@ -45,7 +45,7 @@
(hyperref-usepackage "The LaTeX package for hyperref.")
(image-format "The image formats for this engine.")
(index-page-ref "Indexes use page references."))
- :source "skr/latex.skr"))
+ :source "skribilo/engine/latex.scm"))
(subsection :title "LaTeX documentclass"
diff --git a/doc/user/lib.skb b/doc/user/lib.skb
index 499ca61..e2921fa 100644
--- a/doc/user/lib.skb
+++ b/doc/user/lib.skb
@@ -40,7 +40,8 @@ in the ,(ref :mark "skribe-path" :text "Skribe path").])
(:path ,[The optional path where to find the file. The default
path is ,(markup-ref "skribe-path").])
(#!rest opt... [Additional user options.]))
- :source "../src/bigloo/eval.scm"
+ :skribe-source? #f
+ :source "skribilo/evaluator.scm"
:common-args '()
:see-also '(skribe-load-options skribe-path skribe-path-set!)
:idx *function-index*)
@@ -49,7 +50,8 @@ in the ,(ref :mark "skribe-path" :text "Skribe path").])
,(markup-ref "skribe-load")])
(doc-markup 'skribe-load-options
'()
- :source "../src/bigloo/eval.scm"
+ :skribe-source? #f-
+ :source "skribilo/evaluator.scm"
:common-args '()
:see-also '(skribe-load)
:idx *function-index*)
@@ -61,7 +63,8 @@ when the Skribe compiler is invoked (see Chapter
(doc-markup 'skribe-path
'()
- :source "../src/bigloo/eval.scm"
+ :skribe-source? #f
+ :source "skribilo/evaluator.scm"
:common-args '()
:others '(skribe-image-path skribe-bib-path skribe-source-path)
:see-also '(include skribe-load image source bibliography skribe-path-set! skribe-image-path-set! skribe-bib-path-set! skribe-source-path-set!)
@@ -70,7 +73,8 @@ when the Skribe compiler is invoked (see Chapter
(p [The function ,(code "skribe-path-set!") sets a new path.])
(doc-markup 'skribe-path-set!
'((path [A list of strings which is the new Skribe search path.]))
- :source "../src/bigloo/eval.scm"
+ :skribe-source? #f
+ :source "skribilo/evaluator.scm"
:common-args '()
:others '(skribe-image-path-set! skribe-bib-path-set! skribe-source-path-set!)
:see-also '(skribe-path skribe-image-path skribe-bib-path skribe-source-path)
diff --git a/doc/user/package.skb b/doc/user/package.skb
index ad989d0..b3fe6c3 100644
--- a/doc/user/package.skb
+++ b/doc/user/package.skb
@@ -47,7 +47,7 @@ markup ,(code "abstract"):])
:idx-note "acmproc"
:idx-suffix " (acmproc)"
:force-engines *api-engines*
- :source "../skr/acmproc.skr"))
+ :source "skribilo/package/acmproc.scm"))
(subsection :title (tt "jfp.skr") :ident "jfp"
(index :index *package-index* "jfp.skr" :note "package")
@@ -61,7 +61,7 @@ markup ,(code "abstract"):])
:idx-note "jfp"
:idx-suffix " (jfp)"
:force-engines *api-engines*
- :source "../skr/jfp.skr"))
+ :source "skribilo/package/jfp.scm"))
(subsection :title (tt "lncs.skr") :ident "lncs"
(index :index *package-index* "lncs.skr" :note "package")
@@ -75,7 +75,7 @@ markup ,(code "abstract"):])
:idx-note "lncs"
:idx-suffix " (lncs)"
:force-engines *api-engines*
- :source "../skr/lncs.skr")))
+ :source "skribilo/package/lncs.scm")))
;*---------------------------------------------------------------------*/
;* french */
@@ -102,7 +102,7 @@ This package is to be used to authoring simple letters. It redefines the
:idx-note "letter"
:idx-suffix " (letter)"
:force-engines *api-engines*
- :source "../skr/letter.skr"))
+ :source "skribilo/package/letter.scm"))
;*---------------------------------------------------------------------*/
;* Web */
diff --git a/doc/user/sectioning.skb b/doc/user/sectioning.skb
index 48bbc45..5f1dc3f 100644
--- a/doc/user/sectioning.skb
+++ b/doc/user/sectioning.skb
@@ -101,7 +101,7 @@ paragraphs.])
(p [The function ,(code "p") is an alias for ,(code "paragraph").])
(doc-markup 'p
'((#!rest node... "The nodes of the paragraph."))
- :source "../skr/skribe.skr"
+ :source "skribilo/skribe/api.scm"
:see-also '(document chapter section paragraph)))
;*--- blockquote -----------------------------------------------------*/
diff --git a/doc/user/slide.skb b/doc/user/slide.skb
index c1111ee..0137e84 100644
--- a/doc/user/slide.skb
+++ b/doc/user/slide.skb
@@ -44,7 +44,7 @@ the vertical space size between the title and the body of the slide.])
list ,(code "(split blinds box wipe dissolve glitter)").])
(:bg [The background color of the slide.])
(:image [The background image of the slide.]))
- :source "../skr/slide.skr"))
+ :source "skribilo/package/slide.scm"))
;*---------------------------------------------------------------------*/
;* slide-pause */
@@ -57,7 +57,7 @@ projection.])
(doc-markup 'slide-pause
'()
:common-args '()
- :source "../skr/slide.skr"))
+ :source "skribilo/package/slide.scm"))
;*---------------------------------------------------------------------*/
;* slide-vspace ... */
@@ -70,7 +70,7 @@ projection.])
'((:unit [The unit of the space.])
(#!rest val [The size of the vertical space.]))
:common-args '()
- :source "../skr/slide.skr"))
+ :source "skribilo/package/slide.scm"))
;*---------------------------------------------------------------------*/
;* slide-embed ... */
@@ -92,7 +92,7 @@ to the embedded application.])
(:alt [An alternative Skribe expression to be used if the
output format does not support embedded application.]))
:common-args '()
- :source "../skr/slide.skr"))
+ :source "skribilo/package/slide.scm"))
;*---------------------------------------------------------------------*/
;* Example */
diff --git a/doc/user/xmle.skb b/doc/user/xmle.skb
index 4a1ee78..a1279c7 100644
--- a/doc/user/xmle.skb
+++ b/doc/user/xmle.skb
@@ -13,13 +13,13 @@
;*---------------------------------------------------------------------*/
;* Document */
;*---------------------------------------------------------------------*/
-(section :title "Xml engine" :file #t
+(section :title "XML engine" :file #t
(mark "xml-engine")
- (index "Xml" :note "Engine")
- (p [The Xml engine...])
+ (index "XML" :note "Engine")
+ (p [The XML engine...])
- (subsection :title "The Xml customization"
+ (subsection :title "The XML customization"
(doc-engine 'xml
`()
- :source "skr/xml.skr")))
+ :source "skribilo/engine/xml.scm")))