aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/modules/skribilo/documentation/api.scm11
-rw-r--r--doc/modules/skribilo/documentation/env.scm3
-rw-r--r--doc/modules/skribilo/documentation/extension.scm2
-rw-r--r--doc/modules/skribilo/documentation/manual.scm34
-rw-r--r--doc/user/engine.skb113
-rw-r--r--doc/user/slide.skb3
-rw-r--r--doc/user/user.skb3
7 files changed, 106 insertions, 63 deletions
diff --git a/doc/modules/skribilo/documentation/api.scm b/doc/modules/skribilo/documentation/api.scm
index 84108c9..d369b1a 100644
--- a/doc/modules/skribilo/documentation/api.scm
+++ b/doc/modules/skribilo/documentation/api.scm
@@ -27,7 +27,6 @@
:use-module (skribilo output)
:use-module (skribilo lib) ;; `define-markup'
:use-module (skribilo utils keywords)
- :use-module (skribilo utils compat)
:use-module (skribilo utils syntax) ;; `%skribilo-module-reader'
:use-module (skribilo package base)
@@ -44,7 +43,7 @@
;*---------------------------------------------------------------------*/
;* Html configuration */
;*---------------------------------------------------------------------*/
-(let* ((he (find-engine 'html))
+(let* ((he (lookup-engine-class 'html))
(tro (markup-writer-get 'tr he)))
(markup-writer 'tr he
:class 'api-table-header
@@ -71,7 +70,7 @@
;*---------------------------------------------------------------------*/
;* LaTeX configuration */
;*---------------------------------------------------------------------*/
-(let* ((le (find-engine 'latex))
+(let* ((le (lookup-engine-class 'latex))
(tro (markup-writer-get 'tr le)))
(markup-writer 'tr le
:class 'api-table-prototype
@@ -93,8 +92,8 @@
(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))
+ (let* ((path %load-path)
+ (f (search-path path file))
(read (if skribe-source? (make-reader 'skribe)
%skribilo-module-reader)))
(if (not (string? f))
@@ -371,7 +370,7 @@
(define (opt-engine-support opt)
;; find the engines providing a writer for id
(map (lambda (e)
- (let* ((id (engine-ident e))
+ (let* ((id (engine-class-ident e))
(s (symbol->string id)))
(if (engine-format? "latex")
(list s " ")
diff --git a/doc/modules/skribilo/documentation/env.scm b/doc/modules/skribilo/documentation/env.scm
index 569f194..0510796 100644
--- a/doc/modules/skribilo/documentation/env.scm
+++ b/doc/modules/skribilo/documentation/env.scm
@@ -44,4 +44,5 @@
(define-public *disp-color* "#ccffcc")
(define-public *header-color* "#cccccc")
-(define-public *api-engines* (map find-engine '(html latex xml)))
+(define-public *api-engines* (map lookup-engine-class
+ '(html lout latex xml)))
diff --git a/doc/modules/skribilo/documentation/extension.scm b/doc/modules/skribilo/documentation/extension.scm
index e012cb2..a7e5c20 100644
--- a/doc/modules/skribilo/documentation/extension.scm
+++ b/doc/modules/skribilo/documentation/extension.scm
@@ -29,7 +29,7 @@
;* extension */
;*---------------------------------------------------------------------*/
(define-markup (extension #!rest opt
- #!key (ident (symbol->string (gensym 'extension)))
+ #!key (ident (symbol->string (gensym "extension")))
(class "extension")
title html-title ending author description
(env '()))
diff --git a/doc/modules/skribilo/documentation/manual.scm b/doc/modules/skribilo/documentation/manual.scm
index f2a6cdd..97501d8 100644
--- a/doc/modules/skribilo/documentation/manual.scm
+++ b/doc/modules/skribilo/documentation/manual.scm
@@ -26,8 +26,8 @@
:use-module (skribilo lib) ;; `define-markup'
:use-module (skribilo resolve)
:use-module (skribilo output)
+ :use-module (skribilo evaluator)
:use-module (skribilo utils keywords)
- :use-module (skribilo utils compat)
:use-module (skribilo utils syntax) ;; `when'
:use-module (skribilo documentation env)
@@ -52,20 +52,20 @@
;*---------------------------------------------------------------------*/
;* Base configuration */
;*---------------------------------------------------------------------*/
-(let ((be (find-engine 'base)))
+(let ((be (lookup-engine-class 'base)))
(markup-writer 'example be
:options '(:legend :number)
:action (lambda (n e)
(let ((ident (markup-ident n))
(number (markup-option n :number))
(legend (markup-option n :legend)))
- (skribe-eval (mark ident) e)
- (skribe-eval (center
- (markup-body n)
- (if number
- (bold (format #f "Ex. ~a: " number)))
- legend)
- e)))))
+ (evaluate-document (mark ident) e)
+ (evaluate-document
+ (center (markup-body n)
+ (if number
+ (bold (format #f "Ex. ~a: " number)))
+ legend)
+ e)))))
;*---------------------------------------------------------------------*/
;* html-browsing-extra ... */
@@ -95,7 +95,7 @@
;*---------------------------------------------------------------------*/
;* Html configuration */
;*---------------------------------------------------------------------*/
-(let* ((he (find-engine 'html))
+(let* ((he (lookup-engine-class 'html))
(bd (markup-writer-get 'bold he)))
(markup-writer 'bold he
:class 'api-proto-ident
@@ -108,7 +108,7 @@
;*---------------------------------------------------------------------*/
;* LaTeX */
;*---------------------------------------------------------------------*/
-(let* ((le (find-engine 'latex))
+(let* ((le (lookup-engine-class 'latex))
(opckg (engine-custom le 'usepackage))
(lpckg "\\usepackage{fullpage}\n\\usepackage{eurosym}\n")
(npckg (if (string? opckg)
@@ -190,7 +190,7 @@
(define-markup (example #!rest opts #!key legend class)
(new container
(markup 'example)
- (ident (symbol->string (gensym 'example)))
+ (ident (symbol->string (gensym "example")))
(class class)
(required-options '(:legend :number))
(options `((:number
@@ -290,19 +290,19 @@
(pref (eq? (engine-custom e 'index-page-ref) #t))
(loc (ast-loc n))
;; FIXME: Since we don't support
- ;; `:&skribe-eval-location', we could set up a
- ;; `parameterize' thing around `skribe-eval' to provide
+ ;; `:&evaluate-document-location', we could set up a
+ ;; `parameterize' thing around `evaluate-document' to provide
;; it with the right location information.
(t (cond
((null? ie)
"")
((or (not (integer? nc)) (= nc 1))
- (table :width 100. ;;:&skribe-eval-location loc
+ (table :width 100. ;;:&evaluate-document-location loc
(make-column ie pref)))
(else
- (table :width 100. ;;:&skribe-eval-location loc
+ (table :width 100. ;;:&evaluate-document-location loc
(make-sub-tables ie nc pref))))))
- (output (skribe-eval t e) e))))
+ (evaluate-document t e))))
;*---------------------------------------------------------------------*/
;* compiler-command ... */
diff --git a/doc/user/engine.skb b/doc/user/engine.skb
index 30b8fd2..183f26d 100644
--- a/doc/user/engine.skb
+++ b/doc/user/engine.skb
@@ -1,6 +1,7 @@
-;;; engine.skb -- The description of the Skribe engines
+;;; engine.skb -- Description of Skribilo engines.
;;;
;;; Copyright 2003, 2004 Manuel Serrano
+;;; Copyright 2006 Ludovic Courtès <ludovic.courtes@laas.fr>
;;;
;;;
;;; This program is free software; you can redistribute it and/or modify
@@ -35,10 +36,10 @@
;*---------------------------------------------------------------------*/
(chapter :title "Engines"
- (p [When Skribe produces a document in a given format, it uses a
-specialize engine. For instance, when a Web page is made from a Skribe
-document, the HTML engine is used. The engines provided by Skribe are
-given below:])
+ (p [When Skribilo produces a document in a given format, it uses a
+specialized engine. For instance, when a Web page is made from a
+Skribilo document, an HTML engine is used. The engine classes provided
+by Skribe are given below:])
(resolve (lambda (n e env)
(let* ((current-chapter (ast-chapter n))
@@ -51,52 +52,91 @@ given below:])
(let ((title (markup-option x :title)))
(item (ref :text title :section title))))
sects)))))
-
- (section :title "Functions dealing with engines"
+
+ (p [Skribilo differentiates an ,(emph [engine class]) from an ,(emph
+[engine]). An engine class defines the overall behavior of a type of
+engine (e.g., HTML, Lout, LaTeX, etc.). This includes, for instance,
+information about how to produce particular symbols and how to produce
+various markups in the particular format represented by the engine class
+(e.g., a ,(code [code]) markup can be rendered using the ,(code
+[<code>]) tag in HTML). Conversely, an engine is an ,(emph [instance])
+of an engine class. Therefore, the behavior of an engine is mostly
+defined by its class, but engines can have their own settings (e.g.,
+their own ,(ref :text (emph [customs]) :ident "engine-customs")) that
+can defer from the default settings specified by their class.])
+ (p [Skribe users will notice that this is slightly different from
+Skribe's notion of an engine which encompasses both notions (or, in
+other words, Skribe only allow the instantiation of one engine for each
+engine class). A compatibility layer is available in the ,(code
+"(skribilo utils compat)") module.])
+
+ (section :title "Functions Dealing With Engines"
- (subsection :title "Creating engines"
- (p [The function ,(code "make-engine") creates a brand new engine.])
+ (subsection :title "Creating Engine Classes"
+ (p [The function ,(code "make-engine-class") creates a brand
+new engine class.])
- (doc-markup 'make-engine
- '((ident [The name (a symbol) of the new engine.])
+ (doc-markup 'make-engine-class
+ '((ident [The name (a symbol) of the new engine class.])
(:version [The version number.])
- (:format [The output format (a string) of this engine.])
+ (:format [The output format (a string) of this engine class.])
(:filter [A string filter (a function).])
- (:delegate [A delegate engine.])
- (:symbol-table [The engine symbol table.])
- (:custom [The engine custom list.])
- (:info [Miscellaneous.]))
+ (:delegate [A delegate engine class.])
+ (:symbol-table [The engine class symbol table.])
+ (:custom [The engine class custom list and default values.])
+ (:info [Miscellaneous information.]))
:common-args '()
:skribe-source? #f
:source *engine-src*
:idx *function-index*)
+
+ (p [Once an engine class has been created or ,(ref :text
+[retrieved] :ident "engine-lookup"), it can be instantiated using ,(code
+"make-engine"):])
+ (doc-markup 'make-engine
+ '((engine-class [The engine class that is to be
+instantiated.]))
+ :common-args '()
+ :skribe-source? #f
+ :source *engine-src*
+ :idx *function-index*)
+
+ (p [Each engine has its own values for its customs (initially
+the default values that were specified in the ,(code ":custom")
+parameter passed when creating its class). Thus, it is possible to have
+several engines of a same class that peacefully coexist, even with
+different customs.])
+
(p [The function ,(code "copy-engine") duplicates an existing engine.])
(doc-markup 'copy-engine
- '((ident [The name (a symbol) of the new engine.])
- (e [The old engine to be duplicated.])
- (:version [The version number.])
- (:filter [A string filter (a function).])
- (:delegate [A delegate engine.])
- (:symbol-table [The engine symbol table.])
- (:custom [The engine custom list.]))
+ '((e [The engine to be duplicated.]))
:common-args '()
:skribe-source? #f
:source *engine-src*
:idx *function-index*))
- (subsection :title "Retrieving engines"
+ (subsection :title "Retrieving Engines"
+ :ident "engine-lookup"
- (p [The ,(code "find-engine") function searches in the list of defined
-engines. It returns an ,(code "engine") object on success and ,(code "#f")
-on failure.])
- (doc-markup 'find-engine
- '((id [The name (a symbol) of the engine to be searched.])
- (:version [An optional version number for the searched engine.]))
+ (p [It is customary to fetch an engine class from Skribilo's
+directory (e.g., the ,(ref :text [HTML engine] :ident "html-engine"),
+the ,(ref :text [LaTeX engine] :ident "latex-engine")) using ,(code
+"lookup-engine-class") (for instance, this is what the ,(code
+"--target") option of the ,(code "skribilo") program does).])
+
+ (doc-markup 'lookup-engine-class
+ '((id [The name (a symbol) of the engine class that is looked
+for.])
+ (:version [The version number.]))
:common-args '()
:skribe-source? #f
:source *engine-src*
- :idx *function-index*))
+ :idx *function-index*)
+
+ (p [This function is roughly equivalent to Skribe's ,(code
+"find-engine"), with the noticeable difference that ,(code
+"find-engine") returns an engine rather than an engine class.]))
(subsection :title "Engine accessors"
(p [The predicate ,(code "engine?") returns ,(code "#t") if its
@@ -115,12 +155,13 @@ argument is an engine. Otherwise, it returns ,(code "#f"). In other words,
(doc-markup 'engine-ident
'((obj [The engine.]))
:common-args '()
- :others '(engine-format engine-customs engine-filter engine-symbol-table)
+ :others '(engine-format engine-filter engine-symbol-table)
:skribe-source? #f
:source *engine-src*
:idx *function-index*))
- (subsection :title "Engine customs"
+ (subsection :title "Engine Customs"
+ :ident "engine-customs"
(p [Engine customs are locations where dynamic informations relative
to engines can be stored. Engine custom can be seen a global variables that
@@ -128,10 +169,10 @@ are specific to engines. The function ,(code "engine-custom") returns the
value of a custom or ,(code "#f") if that custom is not defined. The
function ,(code "engine-custom-set!") defines or sets a new value for
a custom.])
-
+
(doc-markup 'engine-custom
`((e ,[The engine (as returned by
-,(ref :mark "find-engine" :text (code "find-engine"))).])
+,(ref :mark "make-engine" :text (code "make-engine"))).])
(id [The name of the custom.]))
:common-args '()
:skribe-source? #f
@@ -140,7 +181,7 @@ a custom.])
(doc-markup 'engine-custom-set!
`((e ,[The engine (as returned by
-,(ref :mark "find-engine" :text (code "find-engine"))).])
+,(ref :mark "make-engine" :text (code "make-engine"))).])
(id [The name of the custom.])
(val [The new value of the custom.]))
:common-args '()
diff --git a/doc/user/slide.skb b/doc/user/slide.skb
index f937a75..35332f2 100644
--- a/doc/user/slide.skb
+++ b/doc/user/slide.skb
@@ -191,7 +191,8 @@ output format does not support embedded application.]))
:options '(:title :ident
:number :toc :vspace)
:action dummy-slide-output)
- (markup-writer 'slide-vspace
+ (markup-writer 'slide-vspace e
+ :options '(:alt)
:action dummy-slide-vspace-output)
(markup-writer 'slide-embed
:options '(:command :arguments :alt)
diff --git a/doc/user/user.skb b/doc/user/user.skb
index 5cfe209..4a249fb 100644
--- a/doc/user/user.skb
+++ b/doc/user/user.skb
@@ -32,7 +32,8 @@
;* Packages */
;*---------------------------------------------------------------------*/
(use-modules (skribilo package eq)
- (skribilo package pie))
+ (skribilo package pie)
+ (skribilo package slide))
;; Load the compile-time configuration file.
(load "doc-config.scm")
generated by cgit v1.2.3 (git 2.49.0) at 2025-07-04 05:25:24 +0000