1doctoc_plugin_apiref(n) Documentation tools doctoc_plugin_apiref(n)
2______________________________________________________________________________
6
8 doctoc_plugin_apiref - doctoc plugin API reference
9
11 dt_fmap symfname
12 dt_format
14 dt_source file
16 ex_cappend text
18 ex_cget varname
20 ex_cis cname
22 ex_cname
24 ex_cpop cname
26 ex_cpush cname
28 ex_cset varname value
30 ex_lb ?newbracket?
32 ex_rb ?newbracket?
34 toc_initialize
36 toc_listvariables
38 toc_numpasses
40 toc_postprocess text
42 toc_setup n
44 toc_shutdown
46 toc_varset varname text
48 fmt_plain_text text
50_________________________________________________________________
52
54 This document is intended for plugin writers, i.e. developers wishing
55 to write a toc formatting engine for some output format X.
56 It specifies the interaction between the doctools::toc package and its
58 plugins, i.e. the interface any toc formatting engine has to comply
59 with.
60 This document deals with version 1 of the interface.
62 A reader who is on the other hand more interested in the markup lan‐
64 guage itself should start with the doctoc language introduction and
65 proceed from there to the formal specifications, i.e. the doctoc lan‐
66 guage syntax and the doctoc language command reference.
67
69 The API for a toc formatting engine consists of two major sections.
70 On the one side we have a set of commands through which the plugin is
72 able to query the frontend. These commands are provided by the frontend
73 and linked into the plugin interpreter. Please see section FRONTEND
74 COMMANDS for their detailed specification.
75 And on the other side the plugin has to provide its own set of commands
77 which will then be called by the frontend in a specific sequence while
78 processing input. They, again, fall into two categories, management and
79 formatting. Please see section PLUGIN COMMANDS and its subsections for
80 their detailed specification.
81
83 This section specifies the set of commands through which a plugin, also
84 known as a toc formatting engine, is able to query the frontend. These
85 commands are provided by the frontend and linked into the plugin inter‐
86 preter.
87 I.e. a toc formatting engine can assume that all of the following com‐
89 mands are present when any of its own commands (as specified in section
90 PLUGIN COMMANDS) are executed.
91 Beyond that it can also assume that it has full access to its own safe
93 interpreter and thus is not able to damage the other parts of the pro‐
94 cessor, nor can it damage the filesystem. It is however able to either
95 kill or hang the whole process, by exiting, or running an infinite
96 loop.
97 Coming back to the imported commands, all the commands with prefix dt_
99 provide limited access to specific parts of the frontend, whereas the
100 commands with prefix ex_ provide access to the state of the textu‐
101 til::expander object which does the main parsing of the input within
102 the frontend. These commands should not be except under very special
103 circumstances.
104 dt_fmap symfname
106 Query command. It returns the actual pathname to use in the out‐
107 put in place of the symbolic filename symfname. It will return
108 the unchanged input if no mapping was established for symfname.
109 The required mappings are established with the method map of a
111 frontend, as explained in section OBJECT METHODS of the documen‐
112 tation for the package doctools::toc.
113 dt_format
115 Query command. It returns the name of the format associated with
116 the toc formatting engine.
117 dt_source file
119 Controlled filesystem access. This command allows the toc for‐
120 matting engine to load additional Tcl code it may need. Only
121 files which are either in the same directory as the file con‐
122 taining the engine, or below it, can be loaded. Trying to load a
123 file outside of this directory causes an error.
124 ex_cappend text
126 Appends a string to the output in the current context. This
127 command should rarely be used by macros or application code.
128 ex_cget varname
130 Retrieves the value of variable varname, defined in the current
131 context.
132 ex_cis cname
134 Determines whether or not the name of the current context is
135 cname.
136 ex_cname
138 Returns the name of the current context.
139 ex_cpop cname
141 Pops a context from the context stack, returning all accumulated
142 output in that context. The context must be named cname, or an
143 error results.
144 ex_cpush cname
146 Pushes a context named cname onto the context stack. The con‐
147 text must be popped by cpop before expansion ends or an error
148 results.
149 ex_cset varname value
151 Sets variable varname to value in the current context.
152 ex_lb ?newbracket?
154 Returns the current value of the left macro expansion bracket;
155 this is for use as or within a macro, when the bracket needs to
156 be included in the output text. If newbracket is specified, it
157 becomes the new bracket, and is returned.
158 ex_rb ?newbracket?
160 Returns the current value of the right macro expansion bracket;
161 this is for use as or within a macro, when the bracket needs to
162 be included in the output text. If newbracket is specified, it
163 becomes the new bracket, and is returned.
164
166 The plugin has to provide its own set of commands which will then be
167 called by the frontend in a specific sequence while processing input.
168 They fall into two categories, management and formatting. Their
169 expected names, signatures, and responsibilities are specified in the
170 following two subsections.
171 MANAGEMENT COMMANDS
173 The management commands a plugin has to provide are used by the fron‐
174 tend to
175 [1] initialize and shutdown the plugin
177 [2] determine the number of passes it has to make over the input
179 [3] initialize and shutdown each pass
181 [4] query and initialize engine parameters
183 After the plugin has been loaded and the frontend commands are estab‐
185 lished the commands will be called in the following sequence:
186 toc_numpasses -> n
188 toc_listvariables -> vars
189 toc_varset var1 value1
191 toc_varset var2 value2
192 ...
193 toc_varset varK valueK
194 toc_initialize
195 toc_setup 1
196 ...
197 toc_setup 2
198 ...
199 ...
200 toc_setup n
201 ...
202 toc_postprocess
203 toc_shutdown
204 ...
205 I.e. first the number of passes and the set of available engine parame‐
207 ters is established, followed by calls setting the parameters. That
208 second part is optional.
209 After that the plugin is initialized, the specified number of passes
211 executed, the final result run through a global post processing step
212 and at last the plugin is shutdown again. This can be followed by more
213 conversions, restarting the sequence at toc_varset.
214 In each of the passes, i.e. after the calls of toc_setup the frontend
216 will process the input and call the formatting commands as markup is
217 encountered. This means that the sequence of formatting commands is
218 determined by the grammar of the doctoc markup language, as specified
219 in the doctoc language syntax specification.
220 A different way of looking at the sequence is:
222 · First some basic parameters are determined.
224 · Then everything starting at the first toc_varset to toc_shutdown
226 forms a run, the formatting of a single input. Each run can be
227 followed by more.
228 · Embedded within each run we have one or more passes, each start‐
230 ing with toc_setup and going until either the next toc_setup or
231 toc_postprocess is reached.
232 If more than one pass is required to perform the formatting only
234 the output of the last pass is relevant. The output of all the
235 previous, preparatory passes is ignored.
236 The commands, their names, signatures, and responsibilities are, in
238 detail:
239 toc_initialize
241 Initialization/Shutdown. This command is called at the begin‐
242 ning of every conversion run, as the first command of that run.
243 Note that a run is not a pass, but may consist of multiple
244 passes. It has to initialize the general state of the plugin,
245 beyond the initialization done during the load. No return value
246 is expected, and any returned value is ignored.
247 toc_listvariables
249 Initialization/Shutdown and Engine parameters. Second command
250 is called after the plugin code has been loaded, i.e. immedi‐
251 ately after toc_numpasses. It has to return a list containing
252 the names of the parameters the frontend can set to configure
253 the engine. This list can be empty.
254 toc_numpasses
256 Initialization/Shutdown and Pass management. First command
257 called after the plugin code has been loaded. No other command
258 of the engine will be called before it. It has to return the
259 number of passes this engine requires to fully process the input
260 document. This value has to be an integer number greater or
261 equal to one.
262 toc_postprocess text
264 Initialization/Shutdown. This command is called immediately
265 after the last pass in a run. Its argument is the result of the
266 conversion generated by that pass. It is provided to allow the
267 engine to perform any global modifications of the generated doc‐
268 ument. If no post-processing is required for a specific format
269 the command has to just return the argument.
270 Expected to return a value, the final result of formatting the
272 input.
273 toc_setup n
275 Initialization/Shutdown and Pass management. This command is
276 called at the beginning of each pass over the input in a run.
277 Its argument is the number of the pass which has begun. Passes
278 are counted from 1 upward. The command has to set up the inter‐
279 nal state of the plugin for this particular pass. No return
280 value is expected, and any returned value is ignored.
281 toc_shutdown
283 Initialization/Shutdown. This command is called at the end of
284 every conversion run. It is the last command called in a run. It
285 has to clean up of all the run-specific state in the plugin.
286 After the call the engine has to be in a state which allows the
287 initiation of another run without fear that information from the
288 last run is leaked into this new run. No return value is
289 expected, and any returned value is ignored.
290 toc_varset varname text
292 Engine parameters. This command is called by the frontend to
293 set an engine parameter to a particular value. The parameter to
294 change is specified by varname, the value to set in text.
295 The command has to throw an error if an unknown varname is used.
297 Only the names returned by toc_listvariables have to be consid‐
298 ered as known.
299 The values of all engine parameters have to persist between
301 passes and runs.
302 FORMATTING COMMANDS
304 The formatting commands have to implement the formatting for the output
305 format, for all the markup commands of the doctoc markup language,
306 except lb, rb, vset, include, and comment. These exceptions are pro‐
307 cessed by the frontend and are never seen by the plugin. In return a
308 command for the formatting of plain text has to be provided, something
309 which has no markup in the input at all.
310 This means, that each of the five markup commands specified in the doc‐
312 toc language command reference and outside of the set of exceptions
313 listed above has an equivalent formatting command which takes the same
314 arguments as the markup command and whose name is the name of markup
315 command with the prefix fmt_ added to it.
316 All commands are expected to format their input in some way per the
318 semantics specified in the command reference and to return whatever
319 part of this that they deem necessary as their result, which will be
320 added to the output.
321 To avoid essentially duplicating the command reference we do not list
323 any of the command here and simply refer the reader to the doctoc lan‐
324 guage command reference for their signature and description. The sole
325 exception is the plain text formatter, which has no equivalent markup
326 command.
327 The calling sequence of formatting commands is not as rigid as for the
329 management commands, but determined by the grammar of the doctoc markup
330 language, as specified in the doctoc language syntax specification.
331 fmt_plain_text text
333 No associated markup command.
334 Called by the frontend for any plain text encountered in the
336 input. It has to perform any and all special processing required
337 for plain text.
338 The formatted text is expected as the result of the command, and
340 added to the output. If no special processing is required it has
341 to simply return its argument without change.
342
344 This document, will undoubtedly contain bugs and other problems.
345 Please report such in the category doctools of the Tcllib SF Trackers
346 [http://sourceforge.net/tracker/?group_id=12883]. Please also report
347 any ideas for enhancements you may have.
348
350 doctoc_intro, doctoc_lang_cmdref, doctoc_lang_faq, doctoc_lang_intro,
351 doctoc_lang_syntax, doctools::toc
352
354 formatting engine, markup, plugin, semantic markup, table of contents,
355 toc, toc formatter
356
358 Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
359doctools 1.0 doctoc_plugin_apiref(n)