1doctools_plugin_apiref(n) Documentation tools doctools_plugin_apiref(n)
2______________________________________________________________________________
6
8 doctools_plugin_apiref - doctools plugin API reference
9
11 dt_copyright
12 dt_file
14 dt_fileid
16 dt_fmap symfname
18 dt_format
20 dt_lnesting
22 dt_module
24 dt_source file
26 dt_user
28 ex_cappend text
30 ex_cget varname
32 ex_cis cname
34 ex_cname
36 ex_cpop cname
38 ex_cpush cname
40 ex_cset varname value
42 ex_lb ?newbracket?
44 ex_rb ?newbracket?
46 fmt_initialize
48 fmt_listvariables
50 fmt_numpasses
52 fmt_postprocess text
54 fmt_setup n
56 fmt_shutdown
58 fmt_varset varname text
60 fmt_plain_text text
62_________________________________________________________________
64
66 This document is intended for plugin writers, i.e. developers wishing
67 to write a doctools formatting engine for some output format X.
68 It specifies the interaction between the doctools package and its plug‐
70 ins, i.e. the interface any doctools formatting engine has to comply
71 with.
72 This document deals with version 1 of the interface.
74 A reader who is on the other hand more interested in the markup lan‐
76 guage itself should start with the doctools language introduction and
77 proceed from there to the formal specifications, i.e. the doctools lan‐
78 guage syntax and the doctools language command reference.
79
81 The API for a doctools formatting engine consists of two major sec‐
82 tions.
83 On the one side we have a set of commands through which the plugin is
85 able to query the frontend. These commands are provided by the frontend
86 and linked into the plugin interpreter. Please see section FRONTEND
87 COMMANDS for their detailed specification.
88 And on the other side the plugin has to provide its own set of commands
90 which will then be called by the frontend in a specific sequence while
91 processing input. They, again, fall into two categories, management and
92 formatting. Please see section PLUGIN COMMANDS and its subsections for
93 their detailed specification.
94
96 This section specifies the set of commands through which a plugin, also
97 known as a doctools formatting engine, is able to query the frontend.
98 These commands are provided by the frontend and linked into the plugin
99 interpreter.
100 I.e. a doctools formatting engine can assume that all of the following
102 commands are present when any of its own commands (as specified in sec‐
103 tion PLUGIN COMMANDS) are executed.
104 Beyond that it can also assume that it has full access to its own safe
106 interpreter and thus is not able to damage the other parts of the pro‐
107 cessor, nor can it damage the filesystem. It is however able to either
108 kill or hang the whole process, by exiting, or running an infinite
109 loop.
110 Coming back to the imported commands, all the commands with prefix dt_
112 provide limited access to specific parts of the frontend, whereas the
113 commands with prefix ex_ provide access to the state of the textu‐
114 til::expander object which does the main parsing of the input within
115 the frontend. These commands should not be except under very special
116 circumstances.
117 dt_copyright
119 Query command. It returns a string containing the copyright
120 information the doctools processor was configured with. The rel‐
121 evant option is -copyright).
122 dt_file
124 Query command. It returns the full path of the file containing
125 the input currently processed by the engine.
126 dt_fileid
128 Query command. It returns the name of the file containing the
129 input currently processed by the engine, without path, nor
130 extension.
131 dt_fmap symfname
133 Query command. It returns the actual pathname to use in the out‐
134 put in place of the symbolic filename symfname. It will return
135 the unchanged input if no mapping was established for symfname.
136 The required mappings are established with the method map of a
138 frontend, as explained in section OBJECT METHODS of the documen‐
139 tation for the package doctools.
140 dt_format
142 Query command. It returns the name of the format associated with
143 the doctools formatting engine.
144 dt_lnesting
146 Query command. It returns the number of lists currently open.
147 dt_module
149 Query command. It returns the name of the module the input cur‐
150 rently processed belongs to.
151 dt_source file
153 Controlled filesystem access. This command allows the doctools
154 formatting engine to load additional Tcl code it may need. Only
155 files which are either in the same directory as the file con‐
156 taining the engine, or below it, can be loaded. Trying to load a
157 file outside of this directory causes an error.
158 dt_user
160 Query command. It returns the name of the current user as known
161 to the tcl interpreter the frontend controlling the formatting
162 engine resides in.
163 ex_cappend text
165 Appends a string to the output in the current context. This
166 command should rarely be used by macros or application code.
167 ex_cget varname
169 Retrieves the value of variable varname, defined in the current
170 context.
171 ex_cis cname
173 Determines whether or not the name of the current context is
174 cname.
175 ex_cname
177 Returns the name of the current context.
178 ex_cpop cname
180 Pops a context from the context stack, returning all accumulated
181 output in that context. The context must be named cname, or an
182 error results.
183 ex_cpush cname
185 Pushes a context named cname onto the context stack. The con‐
186 text must be popped by cpop before expansion ends or an error
187 results.
188 ex_cset varname value
190 Sets variable varname to value in the current context.
191 ex_lb ?newbracket?
193 Returns the current value of the left macro expansion bracket;
194 this is for use as or within a macro, when the bracket needs to
195 be included in the output text. If newbracket is specified, it
196 becomes the new bracket, and is returned.
197 ex_rb ?newbracket?
199 Returns the current value of the right macro expansion bracket;
200 this is for use as or within a macro, when the bracket needs to
201 be included in the output text. If newbracket is specified, it
202 becomes the new bracket, and is returned.
203
205 The plugin has to provide its own set of commands which will then be
206 called by the frontend in a specific sequence while processing input.
207 They fall into two categories, management and formatting. Their
208 expected names, signatures, and responsibilities are specified in the
209 following two subsections.
210 MANAGEMENT COMMANDS
212 The management commands a plugin has to provide are used by the fron‐
213 tend to
214 [1] initialize and shutdown the plugin
216 [2] determine the number of passes it has to make over the input
218 [3] initialize and shutdown each pass
220 [4] query and initialize engine parameters
222 After the plugin has been loaded and the frontend commands are estab‐
224 lished the commands will be called in the following sequence:
225 fmt_numpasses -> n
227 fmt_listvariables -> vars
228 fmt_varset var1 value1
230 fmt_varset var2 value2
231 ...
232 fmt_varset varK valueK
233 fmt_initialize
234 fmt_setup 1
235 ...
236 fmt_setup 2
237 ...
238 ...
239 fmt_setup n
240 ...
241 fmt_postprocess
242 fmt_shutdown
243 ...
244 I.e. first the number of passes and the set of available engine parame‐
246 ters is established, followed by calls setting the parameters. That
247 second part is optional.
248 After that the plugin is initialized, the specified number of passes
250 executed, the final result run through a global post processing step
251 and at last the plugin is shutdown again. This can be followed by more
252 conversions, restarting the sequence at fmt_varset.
253 In each of the passes, i.e. after the calls of fmt_setup the frontend
255 will process the input and call the formatting commands as markup is
256 encountered. This means that the sequence of formatting commands is
257 determined by the grammar of the doctools markup language, as specified
258 in the doctools language syntax specification.
259 A different way of looking at the sequence is:
261 · First some basic parameters are determined.
263 · Then everything starting at the first fmt_varset to fmt_shutdown
265 forms a run, the formatting of a single input. Each run can be
266 followed by more.
267 · Embedded within each run we have one or more passes, each start‐
269 ing with fmt_setup and going until either the next fmt_setup or
270 fmt_postprocess is reached.
271 If more than one pass is required to perform the formatting only
273 the output of the last pass is relevant. The output of all the
274 previous, preparatory passes is ignored.
275 The commands, their names, signatures, and responsibilities are, in
277 detail:
278 fmt_initialize
280 Initialization/Shutdown. This command is called at the begin‐
281 ning of every conversion run, as the first command of that run.
282 Note that a run is not a pass, but may consist of multiple
283 passes. It has to initialize the general state of the plugin,
284 beyond the initialization done during the load. No return value
285 is expected, and any returned value is ignored.
286 fmt_listvariables
288 Initialization/Shutdown and Engine parameters. Second command
289 is called after the plugin code has been loaded, i.e. immedi‐
290 ately after fmt_numpasses. It has to return a list containing
291 the names of the parameters the frontend can set to configure
292 the engine. This list can be empty.
293 fmt_numpasses
295 Initialization/Shutdown and Pass management. First command
296 called after the plugin code has been loaded. No other command
297 of the engine will be called before it. It has to return the
298 number of passes this engine requires to fully process the input
299 document. This value has to be an integer number greater or
300 equal to one.
301 fmt_postprocess text
303 Initialization/Shutdown. This command is called immediately
304 after the last pass in a run. Its argument is the result of the
305 conversion generated by that pass. It is provided to allow the
306 engine to perform any global modifications of the generated doc‐
307 ument. If no post-processing is required for a specific format
308 the command has to just return the argument.
309 Expected to return a value, the final result of formatting the
311 input.
312 fmt_setup n
314 Initialization/Shutdown and Pass management. This command is
315 called at the beginning of each pass over the input in a run.
316 Its argument is the number of the pass which has begun. Passes
317 are counted from 1 upward. The command has to set up the inter‐
318 nal state of the plugin for this particular pass. No return
319 value is expected, and any returned value is ignored.
320 fmt_shutdown
322 Initialization/Shutdown. This command is called at the end of
323 every conversion run. It is the last command called in a run. It
324 has to clean up of all the run-specific state in the plugin.
325 After the call the engine has to be in a state which allows the
326 initiation of another run without fear that information from the
327 last run is leaked into this new run. No return value is
328 expected, and any returned value is ignored.
329 fmt_varset varname text
331 Engine parameters. This command is called by the frontend to
332 set an engine parameter to a particular value. The parameter to
333 change is specified by varname, the value to set in text.
334 The command has to throw an error if an unknown varname is used.
336 Only the names returned by fmt_listvariables have to be consid‐
337 ered as known.
338 The values of all engine parameters have to persist between
340 passes and runs.
341 FORMATTING COMMANDS
343 The formatting commands have to implement the formatting for the output
344 format, for all the markup commands of the doctools markup language,
345 except lb, rb, vset, include, and comment. These exceptions are pro‐
346 cessed by the frontend and are never seen by the plugin. In return a
347 command for the formatting of plain text has to be provided, something
348 which has no markup in the input at all.
349 This means, that each of the 49 markup commands specified in the doc‐
351 tools language command reference and outside of the set of exceptions
352 listed above has an equivalent formatting command which takes the same
353 arguments as the markup command and whose name is the name of markup
354 command with the prefix fmt_ added to it.
355 All commands are expected to format their input in some way per the
357 semantics specified in the command reference and to return whatever
358 part of this that they deem necessary as their result, which will be
359 added to the output.
360 To avoid essentially duplicating the command reference we do not list
362 any of the command here and simply refer the reader to the doctools
363 language command reference for their signature and description. The
364 sole exception is the plain text formatter, which has no equivalent
365 markup command.
366 The calling sequence of formatting commands is not as rigid as for the
368 management commands, but determined by the grammar of the doctools
369 markup language, as specified in the doctools language syntax specifi‐
370 cation.
371 fmt_plain_text text
373 No associated markup command.
374 Called by the frontend for any plain text encountered in the
376 input. It has to perform any and all special processing required
377 for plain text.
378 The formatted text is expected as the result of the command, and
380 added to the output. If no special processing is required it has
381 to simply return its argument without change.
382
384 This document, will undoubtedly contain bugs and other problems.
385 Please report such in the category doctools of the Tcllib SF Trackers
386 [http://sourceforge.net/tracker/?group_id=12883]. Please also report
387 any ideas for enhancements you may have.
388
390 doctools, doctools_intro, doctools_lang_cmdref, doctools_lang_faq, doc‐
391 tools_lang_intro, doctools_lang_syntax
392
394 document, formatter, formatting engine, manpage, markup, semantic
395 markup
396
398 Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
399doctools 1.0 doctools_plugin_apiref(n)