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_mainfile
16 dt_fileid
18 dt_fmap symfname
20 dt_format
22 dt_imgdata key extensions
24 dt_imgdst key extensions
26 dt_imgsrc key extensions
28 dt_lnesting
30 dt_module
32 dt_read file
34 dt_source file
36 dt_user
38 ex_cappend text
40 ex_cget varname
42 ex_cis cname
44 ex_cname
46 ex_cpop cname
48 ex_cpush cname
50 ex_cset varname value
52 ex_lb ?newbracket?
54 ex_rb ?newbracket?
56 fmt_initialize
58 fmt_listvariables
60 fmt_numpasses
62 fmt_postprocess text
64 fmt_setup n
66 fmt_shutdown
68 fmt_varset varname text
70 fmt_plain_text text
72______________________________________________________________________________
74
76 This document is intended for plugin writers, i.e. developers wishing
77 to write a doctools formatting engine for some output format X.
78 It specifies the interaction between the doctools package and its plug‐
80 ins, i.e. the interface any doctools formatting engine has to comply
81 with.
82 This document deals with version 1 of the interface.
84 A reader who is on the other hand more interested in the markup lan‐
86 guage itself should start with the doctools language introduction and
87 proceed from there to the formal specifications, i.e. the doctools lan‐
88 guage syntax and the doctools language command reference.
89
91 The API for a doctools formatting engine consists of two major sec‐
92 tions.
93 On the one side we have a set of commands through which the plugin is
95 able to query the frontend. These commands are provided by the frontend
96 and linked into the plugin interpreter. Please see section FRONTEND
97 COMMANDS for their detailed specification.
98 And on the other side the plugin has to provide its own set of commands
100 which will then be called by the frontend in a specific sequence while
101 processing input. They, again, fall into two categories, management and
102 formatting. Please see section PLUGIN COMMANDS and its subsections for
103 their detailed specification.
104
106 This section specifies the set of commands through which a plugin, also
107 known as a doctools formatting engine, is able to query the frontend.
108 These commands are provided by the frontend and linked into the plugin
109 interpreter.
110 I.e. a doctools formatting engine can assume that all of the following
112 commands are present when any of its own commands (as specified in sec‐
113 tion PLUGIN COMMANDS) are executed.
114 Beyond that it can also assume that it has full access to its own safe
116 interpreter and thus is not able to damage the other parts of the pro‐
117 cessor, nor can it damage the filesystem. It is however able to either
118 kill or hang the whole process, by exiting, or running an infinite
119 loop.
120 Coming back to the imported commands, all the commands with prefix dt_
122 provide limited access to specific parts of the frontend, whereas the
123 commands with prefix ex_ provide access to the state of the textu‐
124 til::expander object which does the main parsing of the input within
125 the frontend. These commands should not be except under very special
126 circumstances.
127 dt_copyright
129 Query command. It returns a string containing the copyright
130 information the doctools processor was configured with. The rel‐
131 evant option is -copyright).
132 dt_file
134 Query command. It returns the full path of the file containing
135 the input currently processed by the engine. This may be an
136 included file.
137 dt_mainfile
139 Query command. It returns the full path of the toplevel file
140 containing the input currently processed by the engine.
141 dt_fileid
143 Query command. It returns the name of the file containing the
144 input currently processed by the engine, without path, nor
145 extension.
146 dt_fmap symfname
148 Query command. It returns the actual pathname to use in the out‐
149 put in place of the symbolic filename symfname. It will return
150 the unchanged input if no mapping was established for symfname.
151 The required mappings are established with the method map of a
153 frontend, as explained in section OBJECT METHODS of the documen‐
154 tation for the package doctools.
155 dt_format
157 Query command. It returns the name of the format associated with
158 the doctools formatting engine.
159 dt_imgdata key extensions
161 Query command. Access to the image map. Looks for an image
162 recorded under the key and having on the specified extension. If
163 a matching image is found its data is returned as the result of
164 the command. Otherwise an empty string is returned.
165 dt_imgdst key extensions
167 Query command. Access to the image map. Looks for an image
168 recorded under the key and having on the specified extension. If
169 a matching image is found its destination path in the output is
170 returned as the result of the command. Otherwise an empty string
171 is returned.
172 dt_imgsrc key extensions
174 Query command. Access to the image map. Looks for an image
175 recorded under the key and having on the specified extension. If
176 a matching image is found its origin path is returned as the
177 result of the command. Otherwise an empty string is returned.
178 dt_lnesting
180 Query command. It returns the number of lists currently open.
181 dt_module
183 Query command. It returns the name of the module the input cur‐
184 rently processed belongs to.
185 dt_read file
187 Controlled filesystem access. Returns contents of file for what‐
188 ever use desired by the plugin. Only files which are either in
189 the same directory as the file containing the engine, or below
190 it, can be loaded. Trying to load a file outside of this direc‐
191 tory causes an error.
192 dt_source file
194 Controlled filesystem access. This command allows the doctools
195 formatting engine to load additional Tcl code it may need. Only
196 files which are either in the same directory as the file con‐
197 taining the engine, or below it, can be loaded. Trying to load a
198 file outside of this directory causes an error.
199 dt_user
201 Query command. It returns the name of the current user as known
202 to the tcl interpreter the frontend controlling the formatting
203 engine resides in.
204 ex_cappend text
206 Appends a string to the output in the current context. This
207 command should rarely be used by macros or application code.
208 ex_cget varname
210 Retrieves the value of variable varname, defined in the current
211 context.
212 ex_cis cname
214 Determines whether or not the name of the current context is
215 cname.
216 ex_cname
218 Returns the name of the current context.
219 ex_cpop cname
221 Pops a context from the context stack, returning all accumulated
222 output in that context. The context must be named cname, or an
223 error results.
224 ex_cpush cname
226 Pushes a context named cname onto the context stack. The con‐
227 text must be popped by cpop before expansion ends or an error
228 results.
229 ex_cset varname value
231 Sets variable varname to value in the current context.
232 ex_lb ?newbracket?
234 Returns the current value of the left macro expansion bracket;
235 this is for use as or within a macro, when the bracket needs to
236 be included in the output text. If newbracket is specified, it
237 becomes the new bracket, and is returned.
238 ex_rb ?newbracket?
240 Returns the current value of the right macro expansion bracket;
241 this is for use as or within a macro, when the bracket needs to
242 be included in the output text. If newbracket is specified, it
243 becomes the new bracket, and is returned.
244
246 The plugin has to provide its own set of commands which will then be
247 called by the frontend in a specific sequence while processing input.
248 They fall into two categories, management and formatting. Their
249 expected names, signatures, and responsibilities are specified in the
250 following two subsections.
251 MANAGEMENT COMMANDS
253 The management commands a plugin has to provide are used by the fron‐
254 tend to
255 [1] initialize and shutdown the plugin
257 [2] determine the number of passes it has to make over the input
259 [3] initialize and shutdown each pass
261 [4] query and initialize engine parameters
263 After the plugin has been loaded and the frontend commands are estab‐
265 lished the commands will be called in the following sequence:
266 fmt_numpasses -> n
269 fmt_listvariables -> vars
270 fmt_varset var1 value1
272 fmt_varset var2 value2
273 ...
274 fmt_varset varK valueK
275 fmt_initialize
276 fmt_setup 1
277 ...
278 fmt_setup 2
279 ...
280 ...
281 fmt_setup n
282 ...
283 fmt_postprocess
284 fmt_shutdown
285 ...
286 I.e. first the number of passes and the set of available engine parame‐
288 ters is established, followed by calls setting the parameters. That
289 second part is optional.
290 After that the plugin is initialized, the specified number of passes
292 executed, the final result run through a global post processing step
293 and at last the plugin is shutdown again. This can be followed by more
294 conversions, restarting the sequence at fmt_varset.
295 In each of the passes, i.e. after the calls of fmt_setup the frontend
297 will process the input and call the formatting commands as markup is
298 encountered. This means that the sequence of formatting commands is
299 determined by the grammar of the doctools markup language, as specified
300 in the doctools language syntax specification.
301 A different way of looking at the sequence is:
303 · First some basic parameters are determined.
305 · Then everything starting at the first fmt_varset to fmt_shutdown
307 forms a run, the formatting of a single input. Each run can be
308 followed by more.
309 · Embedded within each run we have one or more passes, each start‐
311 ing with fmt_setup and going until either the next fmt_setup or
312 fmt_postprocess is reached.
313 If more than one pass is required to perform the formatting only
315 the output of the last pass is relevant. The output of all the
316 previous, preparatory passes is ignored.
317 The commands, their names, signatures, and responsibilities are, in
319 detail:
320 fmt_initialize
322 Initialization/Shutdown. This command is called at the begin‐
323 ning of every conversion run, as the first command of that run.
324 Note that a run is not a pass, but may consist of multiple
325 passes. It has to initialize the general state of the plugin,
326 beyond the initialization done during the load. No return value
327 is expected, and any returned value is ignored.
328 fmt_listvariables
330 Initialization/Shutdown and Engine parameters. Second command
331 is called after the plugin code has been loaded, i.e. immedi‐
332 ately after fmt_numpasses. It has to return a list containing
333 the names of the parameters the frontend can set to configure
334 the engine. This list can be empty.
335 fmt_numpasses
337 Initialization/Shutdown and Pass management. First command
338 called after the plugin code has been loaded. No other command
339 of the engine will be called before it. It has to return the
340 number of passes this engine requires to fully process the input
341 document. This value has to be an integer number greater or
342 equal to one.
343 fmt_postprocess text
345 Initialization/Shutdown. This command is called immediately
346 after the last pass in a run. Its argument is the result of the
347 conversion generated by that pass. It is provided to allow the
348 engine to perform any global modifications of the generated doc‐
349 ument. If no post-processing is required for a specific format
350 the command has to just return the argument.
351 Expected to return a value, the final result of formatting the
353 input.
354 fmt_setup n
356 Initialization/Shutdown and Pass management. This command is
357 called at the beginning of each pass over the input in a run.
358 Its argument is the number of the pass which has begun. Passes
359 are counted from 1 upward. The command has to set up the inter‐
360 nal state of the plugin for this particular pass. No return
361 value is expected, and any returned value is ignored.
362 fmt_shutdown
364 Initialization/Shutdown. This command is called at the end of
365 every conversion run. It is the last command called in a run. It
366 has to clean up of all the run-specific state in the plugin.
367 After the call the engine has to be in a state which allows the
368 initiation of another run without fear that information from the
369 last run is leaked into this new run. No return value is
370 expected, and any returned value is ignored.
371 fmt_varset varname text
373 Engine parameters. This command is called by the frontend to
374 set an engine parameter to a particular value. The parameter to
375 change is specified by varname, the value to set in text.
376 The command has to throw an error if an unknown varname is used.
378 Only the names returned by fmt_listvariables have to be consid‐
379 ered as known.
380 The values of all engine parameters have to persist between
382 passes and runs.
383 FORMATTING COMMANDS
385 The formatting commands have to implement the formatting for the output
386 format, for all the markup commands of the doctools markup language,
387 except lb, rb, vset, include, and comment. These exceptions are pro‐
388 cessed by the frontend and are never seen by the plugin. In return a
389 command for the formatting of plain text has to be provided, something
390 which has no markup in the input at all.
391 This means, that each of the 49 markup commands specified in the doc‐
393 tools language command reference and outside of the set of exceptions
394 listed above has an equivalent formatting command which takes the same
395 arguments as the markup command and whose name is the name of markup
396 command with the prefix fmt_ added to it.
397 All commands are expected to format their input in some way per the
399 semantics specified in the command reference and to return whatever
400 part of this that they deem necessary as their result, which will be
401 added to the output.
402 To avoid essentially duplicating the command reference we do not list
404 any of the command here and simply refer the reader to the doctools
405 language command reference for their signature and description. The
406 sole exception is the plain text formatter, which has no equivalent
407 markup command.
408 The calling sequence of formatting commands is not as rigid as for the
410 management commands, but determined by the grammar of the doctools
411 markup language, as specified in the doctools language syntax specifi‐
412 cation.
413 fmt_plain_text text
415 No associated markup command.
416 Called by the frontend for any plain text encountered in the
418 input. It has to perform any and all special processing required
419 for plain text.
420 The formatted text is expected as the result of the command, and
422 added to the output. If no special processing is required it has
423 to simply return its argument without change.
424
426 This document, and the package it describes, will undoubtedly contain
427 bugs and other problems. Please report such in the category doctools
428 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
429 also report any ideas for enhancements you may have for either package
430 and/or documentation.
431 When proposing code changes, please provide unified diffs, i.e the out‐
433 put of diff -u.
434 Note further that attachments are strongly preferred over inlined
436 patches. Attachments can be made by going to the Edit form of the
437 ticket immediately after its creation, and then using the left-most
438 button in the secondary navigation bar.
439
441 doctools, doctools_intro, doctools_lang_cmdref, doctools_lang_faq, doc‐
442 tools_lang_intro, doctools_lang_syntax
443
445 document, formatter, formatting engine, manpage, markup, semantic
446 markup
447
449 Documentation tools
450
452 Copyright (c) 2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>
453tcllib 1.1 doctools_plugin_apiref(n)