1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin doctoc_plugin_apiref n 1.0] 3[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] 4[moddesc {Documentation tools}] 5[titledesc {doctoc plugin API reference}] 6[category {Documentation tools}] 7[description] 8[para] 9 10This document is intended for [term {plugin writers}], i.e. developers 11wishing to write a toc [term {formatting engine}] for some output 12format X. 13 14[para] 15 16It specifies the interaction between the [package doctools::toc] 17package and its plugins, i.e. the interface any toc formatting engine 18has to comply with. 19 20[para] 21 22This document deals with version 1 of the interface. 23 24[para] 25 26A reader who is on the other hand more interested in the markup 27language itself should start with the 28 29[term {doctoc language introduction}] and proceed from there to the 30formal specifications, i.e. the [term {doctoc language syntax}] and 31the [term {doctoc language command reference}]. 32 33 34 35[section OVERVIEW] 36 37The API for a toc formatting engine consists of two major sections. 38 39[para] 40 41On the one side we have a set of commands through which the plugin is 42able to query the frontend. These commands are provided by the 43frontend and linked into the plugin interpreter. Please see section 44[sectref {FRONTEND COMMANDS}] for their detailed specification. 45 46[para] 47 48And on the other side the plugin has to provide its own set of 49commands which will then be called by the frontend in a specific 50sequence while processing input. They, again, fall into two 51categories, management and formatting. 52 53Please see section [sectref {PLUGIN COMMANDS}] and its subsections for 54their detailed specification. 55 56 57 58[section {FRONTEND COMMANDS}] 59 60This section specifies the set of commands through which a plugin, 61also known as a toc formatting engine, is able to query the 62frontend. These commands are provided by the frontend and linked into 63the plugin interpreter. 64 65[para] 66 67I.e. a toc formatting engine can assume that all of the following 68commands are present when any of its own commands (as specified in 69section [sectref {PLUGIN COMMANDS}]) are executed. 70 71[para] 72 73Beyond that it can also assume that it has full access to its own safe 74interpreter and thus is not able to damage the other parts of the 75processor, nor can it damage the filesystem. 76 77It is however able to either kill or hang the whole process, by 78exiting, or running an infinite loop. 79 80[para] 81 82Coming back to the imported commands, all the commands with prefix 83[emph dt_] provide limited access to specific parts of the frontend, 84whereas the commands with prefix [emph ex_] provide access to the 85state of the [package textutil::expander] object which does the main 86parsing of the input within the frontend. These commands should not be 87except under very special circumstances. 88 89[para] 90 91[list_begin definitions] 92 93[call [cmd dt_fmap] [arg symfname]] 94 95Query command. It returns the actual pathname to use in the output in 96place of the symbolic filename [arg symfname]. It will return the 97unchanged input if no mapping was established for [arg symfname]. 98 99[para] 100 101The required mappings are established with the method [method map] of 102a frontend, as explained in section [sectref-external {OBJECT METHODS}] 103of the documentation for the package [package doctools::toc]. 104 105[call [cmd dt_format]] 106 107Query command. It returns the name of the format associated with the 108toc formatting engine. 109 110[call [cmd dt_read] [arg file]] 111 112Controlled filesystem access. Returns contents of [arg file] for 113whatever use desired by the plugin. 114 115Only files which are either in the same directory as the file 116containing the engine, or below it, can be loaded. Trying to load a 117file outside of this directory causes an error. 118 119[call [cmd dt_source] [arg file]] 120 121Controlled filesystem access. This command allows the toc formatting 122engine to load additional Tcl code it may need. 123 124Only files which are either in the same directory as the file 125containing the engine, or below it, can be loaded. Trying to load a 126file outside of this directory causes an error. 127 128[call [cmd ex_cappend] [arg text]] 129Appends a string to the output in the current context. This command 130should rarely be used by macros or application code. 131 132[call [cmd ex_cget] [arg varname]] 133Retrieves the value of variable [arg varname], defined in the current 134context. 135 136[call [cmd ex_cis] [arg cname]] 137Determines whether or not the name of the current context is 138[arg cname]. 139 140[call [cmd ex_cname]] 141Returns the name of the current context. 142 143[call [cmd ex_cpop] [arg cname]] 144Pops a context from the context stack, returning all accumulated 145output in that context. The context must be named [arg cname], or an 146error results. 147 148[call [cmd ex_cpush] [arg cname]] 149Pushes a context named [arg cname] onto the context stack. The 150context must be popped by [method cpop] before expansion ends or an 151error results. 152 153[call [cmd ex_cset] [arg varname] [arg value]] 154Sets variable [arg varname] to [arg value] in the current context. 155 156[call [cmd ex_lb] [opt [arg newbracket]]] 157Returns the current value of the left macro expansion bracket; this is 158for use as or within a macro, when the bracket needs to be included in 159the output text. If [arg newbracket] is specified, it becomes the new 160bracket, and is returned. 161 162[call [cmd ex_rb] [opt [arg newbracket]]] 163Returns the current value of the right macro expansion bracket; this 164is for use as or within a macro, when the bracket needs to be included 165in the output text. If [arg newbracket] is specified, it becomes the 166new bracket, and is returned. 167 168[list_end] 169 170[section {PLUGIN COMMANDS}] 171 172The plugin has to provide its own set of commands which will then be 173called by the frontend in a specific sequence while processing 174input. They fall into two categories, management and formatting. Their 175expected names, signatures, and responsibilities are specified in the 176following two subsections. 177 178 179 180[subsection {Management commands}] 181 182The management commands a plugin has to provide are used by the 183frontend to 184 185[list_begin enumerated] 186[enum] initialize and shutdown the plugin 187[enum] determine the number of passes it has 188 to make over the input 189[enum] initialize and shutdown each pass 190[enum] query and initialize engine parameters 191[list_end] 192[para] 193 194After the plugin has been loaded and the frontend commands are 195established the commands will be called in the following sequence: 196 197[example { 198 toc_numpasses -> n 199 toc_listvariables -> vars 200 201 toc_varset var1 value1 202 toc_varset var2 value2 203 ... 204 toc_varset varK valueK 205 toc_initialize 206 toc_setup 1 207 ... 208 toc_setup 2 209 ... 210 ... 211 toc_setup n 212 ... 213 toc_postprocess 214 toc_shutdown 215 ... 216}] 217 218I.e. first the number of passes and the set of available engine 219parameters is established, followed by calls setting the 220parameters. That second part is optional. 221 222[para] 223 224After that the plugin is initialized, the specified number of passes 225executed, the final result run through a global post processing step 226and at last the plugin is shutdown again. This can be followed by more 227conversions, restarting the sequence at [cmd toc_varset]. 228 229[para] 230 231In each of the passes, i.e. after the calls of [cmd toc_setup] the 232frontend will process the input and call the formatting commands as 233markup is encountered. This means that the sequence of formatting 234commands is determined by the grammar of the doctoc markup language, 235as specified in the [term {doctoc language syntax}] specification. 236 237[para] 238 239A different way of looking at the sequence is: 240 241[list_begin itemized] 242[item] First some basic parameters are determined. 243 244[item] Then everything starting at the first [cmd toc_varset] to 245[cmd toc_shutdown] forms a [term run], the formatting of a 246single input. Each run can be followed by more. 247 248[item] Embedded within each run we have one or more [term passes], 249each starting with [cmd toc_setup] and going until either the next 250[cmd toc_setup] or [cmd toc_postprocess] is reached. 251 252[para] 253 254If more than one pass is required to perform the formatting only the 255output of the last pass is relevant. The output of all the previous, 256preparatory passes is ignored. 257 258[list_end] 259[para] 260 261The commands, their names, signatures, and responsibilities are, in 262detail: 263 264[list_begin definitions] 265 266[call [cmd toc_initialize]] 267[emph Initialization/Shutdown]. 268 269This command is called at the beginning of every conversion run, as 270the first command of that run. Note that a run is not a pass, but may 271consist of multiple passes. 272 273It has to initialize the general state of the plugin, beyond the 274initialization done during the load. No return value is expected, and 275any returned value is ignored. 276 277 278[call [cmd toc_listvariables]] 279[emph Initialization/Shutdown] and [emph {Engine parameters}]. 280 281Second command is called after the plugin code has been loaded, 282i.e. immediately after [cmd toc_numpasses]. 283 284It has to return a list containing the names of the parameters the 285frontend can set to configure the engine. This list can be empty. 286 287 288[call [cmd toc_numpasses]] 289[emph Initialization/Shutdown] and [emph {Pass management}]. 290 291First command called after the plugin code has been loaded. No other 292command of the engine will be called before it. 293 294It has to return the number of passes this engine requires to fully 295process the input document. This value has to be an integer number 296greater or equal to one. 297 298 299[call [cmd toc_postprocess] [arg text]] 300[emph Initialization/Shutdown]. 301 302This command is called immediately after the last pass in a run. Its 303argument is the result of the conversion generated by that pass. It is 304provided to allow the engine to perform any global modifications of 305the generated document. If no post-processing is required for a 306specific format the command has to just return the argument. 307 308[para] 309 310Expected to return a value, the final result of formatting the input. 311 312 313[call [cmd toc_setup] [arg n]] 314[emph Initialization/Shutdown] and [emph {Pass management}]. 315 316This command is called at the beginning of each pass over the input in 317a run. Its argument is the number of the pass which has begun. Passes 318are counted from [const 1] upward. 319 320The command has to set up the internal state of the plugin for this 321particular pass. No return value is expected, and any returned value 322is ignored. 323 324 325[call [cmd toc_shutdown]] 326[emph Initialization/Shutdown]. 327 328This command is called at the end of every conversion run. It is the 329last command called in a run. It has to clean up of all the 330run-specific state in the plugin. 331 332After the call the engine has to be in a state which allows the 333initiation of another run without fear that information from the last 334run is leaked into this new run. 335 336No return value is expected, and any returned value is ignored. 337 338 339[call [cmd toc_varset] [arg varname] [arg text]] 340[emph {Engine parameters}]. 341 342This command is called by the frontend to set an engine parameter to a 343particular value. 344 345The parameter to change is specified by [arg varname], the value to 346set in [arg text]. 347 348[para] 349 350The command has to throw an error if an unknown [arg varname] is 351used. Only the names returned by [cmd toc_listvariables] have to be 352considered as known. 353 354[para] 355 356The values of all engine parameters have to persist between passes and 357runs. 358 359[list_end] 360 361 362 363[subsection {Formatting commands}] 364 365The formatting commands have to implement the formatting for the 366output format, for all the markup commands of the doctoc markup 367language, except [cmd lb], [cmd rb], [cmd vset], [cmd include], and 368[cmd comment]. These exceptions are processed by the frontend and are 369never seen by the plugin. In return a command for the formatting of 370plain text has to be provided, something which has no markup in the 371input at all. 372 373[para] 374 375This means, that each of the five markup commands specified in the 376[term {doctoc language command reference}] and outside of the set of 377exceptions listed above has an equivalent formatting command which 378takes the same arguments as the markup command and whose name is the 379name of markup command with the prefix [emph fmt_] added to it. 380 381[para] 382 383All commands are expected to format their input in some way per the 384semantics specified in the command reference and to return whatever 385part of this that they deem necessary as their result, which will be 386added to the output. 387 388[para] 389 390To avoid essentially duplicating the command reference we do not list 391any of the command here and simply refer the reader to the 392[term {doctoc language command reference}] for their signature and 393description. The sole exception is the plain text formatter, which has 394no equivalent markup command. 395 396[para] 397 398The calling sequence of formatting commands is not as rigid as for the 399management commands, but determined by the grammar of the doctoc 400markup language, as specified in the [term {doctoc language syntax}] 401specification. 402 403[para] 404 405[list_begin definitions] 406 407[call [cmd fmt_plain_text] [arg text]] 408[emph {No associated markup command}]. 409 410[para] Called by the frontend for any plain text encountered in the 411input. It has to perform any and all special processing required for 412plain text. 413 414[para] The formatted text is expected as the result of the command, 415and added to the output. If no special processing is required it has 416to simply return its argument without change. 417 418[list_end] 419 420 421 422[section {BUGS, IDEAS, FEEDBACK}] 423 424This document, will undoubtedly contain bugs and other problems. 425 426Please report such in the category [emph doctools] of the 427[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 428 429Please also report any ideas for enhancements you may have. 430 431[see_also doctoc_intro] 432[see_also doctoc_lang_intro] 433[see_also doctoc_lang_syntax] 434[see_also doctoc_lang_cmdref] 435[see_also doctoc_lang_faq] 436[see_also doctools::toc] 437[keywords markup {semantic markup} plugin toc {table of contents}] 438[keywords {formatting engine} {toc formatter}] 439[manpage_end] 440