doc: Update & improve engine documentation.

* doc/user/engine.skb (Engines): Rewrote intro, fixed `resolve'.
  (Functions dealing with engines): Renamed to...
  (Manipulating Engines): New.
  [Writing New Engines]: New.

* doc/user/{htmle,xmle,latexe}.skb: Add intro.

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
 	 `()