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