;;; engine.skb -- The description of the Skribe engines ;;; -*- coding: iso-8859-1 -*- ;;; ;;; Copyright 2008, 2009 Ludovic Courtès ;;; 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 . ;*---------------------------------------------------------------------*/ ;* 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: