1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
;;; 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") :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)
(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:
|
