13. Skribilo User Manual — Engines
Contents↑ Skribilo User Manual

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 --target command-line option (see Chapter 14). This command-line option actually specifies the 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 --target=html to the compiler instructs it to produce an HTML document using the html engine.

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:

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 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).

13.1 Manipulating Engines

13.1.1 Creating Engines

The function make-engine creates a brand new engine.

(make-engine [:info '()] [:custom '()] [:symbol-table '()] [:delegate] [:filter] [:format "raw"] [:version 'unspecified] ident)
: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.
ident The name (a symbol) of the new engine.

The function copy-engine duplicates an existing engine.

(copy-engine [:custom] [:symbol-table] [:delegate] [:filter] [:version 'unspecified] ident e)
: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.
ident The name (a symbol) of the new engine.
e The old engine to be duplicated.

13.1.2 Retrieving Engines

The find-engine function searches in the list of defined engines. It returns an engine object on success and #f on failure.

(find-engine [:version 'unspecified] id)
:version An optional version number for the searched engine.
id The name (a symbol) of the engine to be searched.

13.1.3 Engine Accessors

The predicate engine? returns #t if its argument is an engine. Otherwise, it returns #f. In other words, engine? returns #t for objects created by make-engine, copy-engine, and find-engine.

(engine? obj)
obj The checked object.

The following functions return information about engines.

(engine-ident obj)
(engine-format obj)
(engine-customs obj)
(engine-filter obj)
(engine-symbol-table obj)
obj The engine.

13.1.4 Engine Customs

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 engine-custom returns the value of a custom or #f if that custom is not defined. The function engine-custom-set! defines or sets a new value for a custom.

(engine-custom e id)
e The engine (as returned by find-engine).
id The name of the custom.
(engine-custom-set! e id val)
e The engine (as returned by find-engine).
id The name of the custom.
val The new value of the custom.

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.

13.1.5 Writing New Engines

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 make-engine and registering markup writers using the markup-writer procedure for all supported markups (e.g., chapter, bold, etc.)1.

Most likely, you will want to make your new engine visible so that find-engine and consequently the --target command-line option can find it. To that end, a few rules must be followed:

  1. your engine must be enclosed in a Guile Scheme module under the skribilo engine hierarchy; for instance, if the engine is named foo, then it should be in a module called (skribilo engine foo);
  2. the engine itself as returned by make-engine must be bound, in that module, to a variable called, say, foo-engine;
  3. finally, the (skribilo engine foo) module must be in Guile's load path; for instance, you can adjust the 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 readers (see Section 2.5).

1FIXME: Markup writers are not currently documented, but looking at the source of an engine will give you the idea, trust me.
(made with skribilo)