;;; engine.skb -- The description of the Skribe engines
;;; -*- coding: iso-8859-1 -*-
;;;
;;; Copyright 2008, 2009 Ludovic Courtès <ludo@gnu.org>
;;; Copyright 2003, 2004 Manuel Serrano
;;;
;;;
;;; This file is part of Skribilo.
;;;
;;; Skribilo is free software: you can redistribute it and/or modify
;;; it under the terms of the GNU General Public License as published by
;;; the Free Software Foundation, either version 3 of the License, or
;;; (at your option) any later version.
;;;
;;; Skribilo is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with Skribilo. If not, see <http://www.gnu.org/licenses/>.
;*---------------------------------------------------------------------*/
;* Engine */
;*---------------------------------------------------------------------*/
(chapter :title "Engines"
:ident "engines"
(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") :ident "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)
(and (is-markup? x 'section)
(markup-option x :file)))
body)))
(itemize
(map (lambda (s)
(item (ref :text (markup-option s :title)
:handle (handle s))))
sects)))))
[Engine customization provides tight control over the output produced
for each particular engine. In particular, it allows the style for each
output to be fine-tuned, be it HTML, PDF ,(it [via]) Lout, or anything
else. However, note that such fine-tuning usually requires good
knowledge of the output format (e.g., HTML/CSS, Lout, LaTeX).])
(section :title "Manipulating Engines"
(subsection :title "Creating Engines"
(p [The function ,(code "make-engine") creates a brand new engine.])
(doc-markup 'make-engine
'((ident [The name (a symbol) of the new engine.])
(:version [The version number.])
(:format [The output format (a string) of this engine.])
(:filter [A string filter (a function).])
(:delegate [A delegate engine.])
(:symbol-table [The engine symbol table.])
(:custom [The engine custom list.])
(:info [Miscellaneous.]))
:common-args '()
:skribe-source? #f
:source *engine-src*
:idx *function-index*)
(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.]))
:common-args '()
:skribe-source? #f
:source *engine-src*
:idx *function-index*))
(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")
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.]))
:common-args '()
:skribe-source? #f
:source *engine-src*
:idx *function-index*))
(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
,(code "make-engine"), ,(code "copy-engine"), and ,(code "find-engine").])
(doc-markup 'engine?
'((obj [The checked object.]))
:common-args '()
:skribe-source? #f
:source *engine-src*
:idx *function-index*)
(p [The following functions return information about engines.])
(doc-markup 'engine-ident
'((obj [The engine.]))
:common-args '()
:others '(engine-format engine-customs engine-filter engine-symbol-table)
:skribe-source? #f
:source *engine-src*
:idx *function-index*))
(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
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"))).])
(id [The name of the custom.]))
:common-args '()
:skribe-source? #f
:source *engine-src*
:idx *function-index*)
(doc-markup 'engine-custom-set!
`((e ,[The engine (as returned by
,(ref :mark "find-engine" :text (code "find-engine"))).])
(id [The name of the custom.])
(val [The new value of the custom.]))
:common-args '()
:skribe-source? #f
:source *engine-src*
:idx *function-index*)
(p [In the documentation of available engines that follows, a
list of available customs is shown for each engine, along with each
custom's default value and a description.]))
(subsection :title [Writing New Engines]
:ident "custom-engine"
(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! Note that
this mechanism is the same as that of ,(emph [readers]) (see ,(numref
:text [Section] :ident "custom-syntax")).])))
;; existing engines
(include "htmle.skb")
(include "loute.skb")
(include "latexe.skb")
(include "contexte.skb")
(include "infoe.skb")
(include "xmle.skb"))
;;; Local Variables:
;;; ispell-local-dictionary: "american"
;;; End:
