1docidx_plugin_apiref(n)       Documentation tools      docidx_plugin_apiref(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       docidx_plugin_apiref - docidx plugin API reference
9

SYNOPSIS

11       dt_fmap symfname
12
13       dt_format
14
15       dt_read file
16
17       dt_source file
18
19       ex_cappend text
20
21       ex_cget varname
22
23       ex_cis cname
24
25       ex_cname
26
27       ex_cpop cname
28
29       ex_cpush cname
30
31       ex_cset varname value
32
33       ex_lb ?newbracket?
34
35       ex_rb ?newbracket?
36
37       idx_initialize
38
39       idx_listvariables
40
41       idx_numpasses
42
43       idx_postprocess text
44
45       idx_setup n
46
47       idx_shutdown
48
49       idx_varset varname text
50
51       fmt_plain_text text
52
53______________________________________________________________________________
54

DESCRIPTION

56       This  document  is intended for plugin writers, i.e. developers wishing
57       to write an index formatting engine for some output format X.
58
59       It specifies the interaction between the doctools::idx package and  its
60       plugins,  i.e.  the interface any index formatting engine has to comply
61       with.
62
63       This document deals with version 1 of the interface.
64
65       A reader who is on the other hand more interested in  the  markup  lan‐
66       guage  itself  should  start  with the docidx language introduction and
67       proceed from there to the formal specifications, i.e. the  docidx  lan‐
68       guage syntax and the docidx language command reference.
69

OVERVIEW

71       The API for an index formatting engine consists of two major sections.
72
73       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
78       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

FRONTEND COMMANDS

85       This section specifies the set of commands through which a plugin, also
86       known  as  an  index  formatting engine, is able to query the frontend.
87       These commands are provided by the frontend and linked into the  plugin
88       interpreter.
89
90       I.e.  an  index  formatting engine can assume that all of the following
91       commands are present when any of its own commands (as specified in sec‐
92       tion PLUGIN COMMANDS) are executed.
93
94       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
100       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
107       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
112              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::idx.
115
116       dt_format
117              Query command. It returns the name of the format associated with
118              the index formatting engine.
119
120       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
127       dt_source file
128              Controlled filesystem access. This command allows the index 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
134       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
138       ex_cget varname
139              Retrieves the value of variable varname, defined in the  current
140              context.
141
142       ex_cis cname
143              Determines  whether  or  not  the name of the current context is
144              cname.
145
146       ex_cname
147              Returns the name of the current context.
148
149       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
154       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
159       ex_cset varname value
160              Sets variable varname to value in the current context.
161
162       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
168       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

PLUGIN COMMANDS

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
181   MANAGEMENT COMMANDS
182       The management commands a plugin has to provide are used by  the  fron‐
183       tend to
184
185       [1]    initialize and shutdown the plugin
186
187       [2]    determine the number of passes it has to make over the input
188
189       [3]    initialize and shutdown each pass
190
191       [4]    query and initialize engine parameters
192
193       After  the  plugin has been loaded and the frontend commands are estab‐
194       lished the commands will be called in the following sequence:
195
196
197                  idx_numpasses -> n
198                  idx_listvariables -> vars
199
200                  idx_varset var1 value1
201                  idx_varset var2 value2
202                  ...
203                  idx_varset varK valueK
204                  idx_initialize
205                  idx_setup 1
206                  ...
207                  idx_setup 2
208                  ...
209                  ...
210                  idx_setup n
211                  ...
212                  idx_postprocess
213                  idx_shutdown
214                  ...
215
216       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
220       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 idx_varset.
224
225       In  each  of the passes, i.e. after the calls of idx_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 docidx markup language,  as  specified
229       in the docidx language syntax specification.
230
231       A different way of looking at the sequence is:
232
233       ·      First some basic parameters are determined.
234
235       ·      Then everything starting at the first idx_varset to idx_shutdown
236              forms a run, the formatting of a single input. Each run  can  be
237              followed by more.
238
239       ·      Embedded within each run we have one or more passes, each start‐
240              ing with idx_setup and going until either the next idx_setup  or
241              idx_postprocess is reached.
242
243              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
247       The  commands,  their  names,  signatures, and responsibilities are, in
248       detail:
249
250       idx_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
258       idx_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  idx_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
265       idx_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
273       idx_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
281              Expected  to  return a value, the final result of formatting the
282              input.
283
284       idx_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
292       idx_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
301       idx_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
306              The command has to throw an error if an unknown varname is used.
307              Only the names returned by idx_listvariables have to be  consid‐
308              ered as known.
309
310              The  values  of  all  engine  parameters have to persist between
311              passes and runs.
312
313   FORMATTING COMMANDS
314       The formatting commands have to implement the formatting for the output
315       format,  for  all  the  markup  commands of the docidx 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
321       This  means,  that  each  of  the five markup commands specified in the
322       docidx 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
327       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
332       To avoid essentially duplicating the command reference we do  not  list
333       any  of the command here and simply refer the reader to the docidx 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
338       The calling sequence of formatting commands is not as rigid as for  the
339       management commands, but determined by the grammar of the docidx markup
340       language, as specified in the docidx language syntax specification.
341
342       fmt_plain_text text
343              No associated markup command.
344
345              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
349              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

BUGS, IDEAS, FEEDBACK

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
360       When proposing code changes, please provide unified diffs, i.e the out‐
361       put of diff -u.
362
363       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

SEE ALSO

369       docidx_intro, docidx_lang_cmdref,  docidx_lang_faq,  docidx_lang_intro,
370       docidx_lang_syntax, doctools::idx
371

KEYWORDS

373       formatting  engine,  index,  index formatter, keywords, markup, plugin,
374       semantic markup
375

CATEGORY

377       Documentation tools
378
380       Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
381
382
383
384
385tcllib                                1.0              docidx_plugin_apiref(n)
Impressum