diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/modules/skribilo/documentation/api.scm | 11 | ||||
| -rw-r--r-- | doc/modules/skribilo/documentation/env.scm | 3 | ||||
| -rw-r--r-- | doc/modules/skribilo/documentation/extension.scm | 2 | ||||
| -rw-r--r-- | doc/modules/skribilo/documentation/manual.scm | 34 | ||||
| -rw-r--r-- | doc/user/engine.skb | 113 | ||||
| -rw-r--r-- | doc/user/slide.skb | 3 | ||||
| -rw-r--r-- | doc/user/user.skb | 3 |
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") |