diff options
| -rw-r--r-- | doc/user/engine.skb | 88 | ||||
| -rw-r--r-- | doc/user/htmle.skb | 3 | ||||
| -rw-r--r-- | doc/user/latexe.skb | 9 | ||||
| -rw-r--r-- | doc/user/xmle.skb | 11 |
4 files changed, 80 insertions, 31 deletions
diff --git a/doc/user/engine.skb b/doc/user/engine.skb index 30b8fd2..9fdf500 100644 --- a/doc/user/engine.skb +++ b/doc/user/engine.skb @@ -1,5 +1,6 @@ ;;; engine.skb -- The description of the Skribe engines ;;; +;;; Copyright 2008 Ludovic Courtès <ludo@gnu.org> ;;; Copyright 2003, 2004 Manuel Serrano ;;; ;;; @@ -19,42 +20,45 @@ ;;; USA. -(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")) - (stklos - (define *engine-src* "../src/stklos/engine.stk") - (define *types-src* "../src/stklos/types.stk"))) +(define *engine-src* "skribilo/engine.scm") ;*---------------------------------------------------------------------*/ ;* Engine */ ;*---------------------------------------------------------------------*/ (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 [Skribilo documents can be rendered, or output, in a variety of +different formats. When using the compiler, which format is used is +specified by the ,(tt [--target]) command-line option (see ,(numref +:text [Chapter] :ident "compiler")). This command-line option actually +specifies the ,(emph [engine]) or ``back-end'' to be used, which is +roughly a set of procedures that translate the input document into the +output format. For instance, passing ,(tt [--target=html]) to the +compiler instructs it to produce an HTML document using the ,(ref :text +(code "html") :mark "html-engine") engine.]) + + (p [This chapter describes procedures allowing the manipulation of +engines in Skribilo documents or modules (creation, customization, +etc.), as well as the available engines. Currently, the available +engines are:]) (resolve (lambda (n e env) (let* ((current-chapter (ast-chapter n)) (body (map (lambda (x) (if (pair? x) (car x) x)) (markup-body current-chapter))) - (sects (filter (lambda (x) (is-markup? x 'section)) + (sects (filter (lambda (x) + (and (is-markup? x 'section) + (markup-option x :file))) body))) (itemize - (map (lambda (x) - (let ((title (markup-option x :title))) - (item (ref :text title :section title)))) + (map (lambda (s) + (item (ref :text (markup-option s :title) + :handle (handle s)))) sects))))) - (section :title "Functions dealing with engines" + (section :title "Manipulating Engines" - (subsection :title "Creating engines" + (subsection :title "Creating Engines" (p [The function ,(code "make-engine") creates a brand new engine.]) (doc-markup 'make-engine @@ -85,7 +89,7 @@ given below:]) :source *engine-src* :idx *function-index*)) - (subsection :title "Retrieving engines" + (subsection :title "Retrieving Engines" (p [The ,(code "find-engine") function searches in the list of defined engines. It returns an ,(code "engine") object on success and ,(code "#f") @@ -98,7 +102,7 @@ on failure.]) :source *engine-src* :idx *function-index*)) - (subsection :title "Engine accessors" + (subsection :title "Engine Accessors" (p [The predicate ,(code "engine?") returns ,(code "#t") if its argument is an engine. Otherwise, it returns ,(code "#f"). In other words, ,(code "engine?") returns ,(code "#t") for objects created by @@ -120,7 +124,7 @@ argument is an engine. Otherwise, it returns ,(code "#f"). In other words, :source *engine-src* :idx *function-index*)) - (subsection :title "Engine customs" + (subsection :title "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 @@ -146,9 +150,45 @@ a custom.]) :common-args '() :skribe-source? #f :source *engine-src* - :idx *function-index*))) + :idx *function-index*)) + + (subsection :title [Writing New Engines] + + (p [Writing new engines (i.e., output formats) and making them +available to Skribilo is an easy task. Essentially, this boils down to +instantiating an engine using ,(markup-ref "make-engine") and +registering ,(emph [markup writers]) using the ,(tt [markup-writer]) +procedure for all supported markups (e.g., ,(tt [chapter]), ,(tt +[bold]), etc.),(footnote [FIXME: Markup writers are not currently +documented, but looking at the source of an engine will give you the +idea, trust me.]).]) + + (p [Most likely, you will want to make your new engine visible +so that ,(markup-ref "find-engine") and consequently the ,(tt +"--target") command-line option can find it. To that end, a few rules +must be followed: + +,(enumerate + (item [your engine must be enclosed in a Guile Scheme module under +the ,(tt [skribilo engine]) hierarchy; for instance, if the engine is +named ,(tt [foo]), then it should be in a module called ,(tt [(skribilo +engine foo)]);]) + (item [the engine itself as returned by ,(markup-ref "make-engine") +must be bound, in that module, to a variable called, say, ,(tt +[foo-engine]);]) + (item [finally, the ,(tt [(skribilo engine foo)]) module must be in +Guile's load path; for instance, you can adjust the ,(tt +[GUILE_LOAD_PATH]) environment variable.])) + +This is all it takes to extend Skribilo's set of engines!]))) ;; existing engines (include "htmle.skb") (include "latexe.skb") (include "xmle.skb")) + + +;;; Local Variables: +;;; coding: latin-1 +;;; ispell-local-dictionary: "american" +;;; End: diff --git a/doc/user/htmle.skb b/doc/user/htmle.skb index 4a517e9..47a5f97 100644 --- a/doc/user/htmle.skb +++ b/doc/user/htmle.skb @@ -24,7 +24,8 @@ (mark "html-engine") (index "HTML" :note "Engine") - (p [The HTML engine...]) + (p [The HTML engine produces---guess what!---HTML output. It can be +customized in various ways, as shown below.]) (subsection :title "HTML Customization" diff --git a/doc/user/latexe.skb b/doc/user/latexe.skb index c9fc50b..fe4b802 100644 --- a/doc/user/latexe.skb +++ b/doc/user/latexe.skb @@ -1,7 +1,7 @@ ;;; latexe.skb -- Documentation of the LaTeX engine. ;;; +;;; Copyright 2007, 2008 Ludovic Courtès <ludo@gnu.org> ;;; Copyright 2003, 2004 Manuel Serrano -;;; Copyright 2007 Ludovic Courtès <ludovic.courtes@laas.fr> ;;; ;;; ;;; This program is free software; you can redistribute it and/or modify @@ -23,10 +23,13 @@ ;*---------------------------------------------------------------------*/ ;* Document */ ;*---------------------------------------------------------------------*/ -(section :title "The LaTeX Engine" :file #t +(section :title "LaTeX Engine" :file #t (mark "latex-engine") (index "LaTeX" :note "Engine") - (p [The LaTeX engine...]) + + (p [Not surprisingly, the LaTeX engine produces ,(ref :url +"http://www.latex-project.org/" :text [LaTeX]) output, which can then be +used to produce high-quality PostScript of PDF files for printing.]) (subsection :title "LaTeX Customization" diff --git a/doc/user/xmle.skb b/doc/user/xmle.skb index bd01db3..93546b0 100644 --- a/doc/user/xmle.skb +++ b/doc/user/xmle.skb @@ -1,5 +1,6 @@ ;;; xmle.skb -- The documentation of the XML engine ;;; +;;; Copyright 2008 Ludovic Courtès <ludo@gnu.org> ;;; Copyright 2003, 2004 Manuel Serrano ;;; ;;; @@ -22,12 +23,16 @@ ;*---------------------------------------------------------------------*/ ;* Document */ ;*---------------------------------------------------------------------*/ -(section :title "XML engine" :file #t +(section :title "XML Engine" :file #t (mark "xml-engine") (index "XML" :note "Engine") - (p [The XML engine...]) + + (p [The XML engine produces a simple XML representation of Skribilo +documents that is essentially a one-to-one mapping of the input +document. For instance, ,(tt [chapter]) markups are turned into ,(tt +[<chapter>]) nodes, etc.]) - (subsection :title "The XML customization" + (subsection :title "XML Customization" (doc-engine 'xml `() |