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_source file
16
17       ex_cappend text
18
19       ex_cget varname
20
21       ex_cis cname
22
23       ex_cname
24
25       ex_cpop cname
26
27       ex_cpush cname
28
29       ex_cset varname value
30
31       ex_lb ?newbracket?
32
33       ex_rb ?newbracket?
34
35       idx_initialize
36
37       idx_listvariables
38
39       idx_numpasses
40
41       idx_postprocess text
42
43       idx_setup n
44
45       idx_shutdown
46
47       idx_varset varname text
48
49       fmt_plain_text text
50
51_________________________________________________________________
52

DESCRIPTION

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

OVERVIEW

69       The API for an index formatting engine consists of two major sections.
70
71       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
76       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

FRONTEND COMMANDS

83       This section specifies the set of commands through which a plugin, also
84       known  as  an  index  formatting engine, is able to query the frontend.
85       These commands are provided by the frontend and linked into the  plugin
86       interpreter.
87
88       I.e.  an  index  formatting engine can assume that all of the following
89       commands are present when any of its own commands (as specified in sec‐
90       tion PLUGIN COMMANDS) are executed.
91
92       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
98       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
105       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
110              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::idx.
113
114       dt_format
115              Query command. It returns the name of the format associated with
116              the index formatting engine.
117
118       dt_source file
119              Controlled filesystem access. This command allows the index 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
125       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
129       ex_cget varname
130              Retrieves the value of variable varname, defined in the  current
131              context.
132
133       ex_cis cname
134              Determines  whether  or  not  the name of the current context is
135              cname.
136
137       ex_cname
138              Returns the name of the current context.
139
140       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
145       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
150       ex_cset varname value
151              Sets variable varname to value in the current context.
152
153       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
159       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

PLUGIN COMMANDS

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
172   MANAGEMENT COMMANDS
173       The management commands a plugin has to provide are used by  the  fron‐
174       tend to
175
176       [1]    initialize and shutdown the plugin
177
178       [2]    determine the number of passes it has to make over the input
179
180       [3]    initialize and shutdown each pass
181
182       [4]    query and initialize engine parameters
183
184       After  the  plugin has been loaded and the frontend commands are estab‐
185       lished the commands will be called in the following sequence:
186
187           idx_numpasses -> n
188           idx_listvariables -> vars
189
190           idx_varset var1 value1
191           idx_varset var2 value2
192           ...
193           idx_varset varK valueK
194           idx_initialize
195           idx_setup 1
196           ...
197           idx_setup 2
198           ...
199           ...
200           idx_setup n
201           ...
202           idx_postprocess
203           idx_shutdown
204           ...
205
206       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
210       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 idx_varset.
214
215       In  each  of the passes, i.e. after the calls of idx_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 docidx markup language,  as  specified
219       in the docidx language syntax specification.
220
221       A different way of looking at the sequence is:
222
223       ·      First some basic parameters are determined.
224
225       ·      Then everything starting at the first idx_varset to idx_shutdown
226              forms a run, the formatting of a single input. Each run  can  be
227              followed by more.
228
229       ·      Embedded within each run we have one or more passes, each start‐
230              ing with idx_setup and going until either the next idx_setup  or
231              idx_postprocess is reached.
232
233              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
237       The  commands,  their  names,  signatures, and responsibilities are, in
238       detail:
239
240       idx_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
248       idx_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  idx_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
255       idx_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
263       idx_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
271              Expected  to  return a value, the final result of formatting the
272              input.
273
274       idx_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
282       idx_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
291       idx_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
296              The command has to throw an error if an unknown varname is used.
297              Only the names returned by idx_listvariables have to be  consid‐
298              ered as known.
299
300              The  values  of  all  engine  parameters have to persist between
301              passes and runs.
302
303   FORMATTING COMMANDS
304       The formatting commands have to implement the formatting for the output
305       format,  for  all  the  markup  commands of the docidx 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
311       This  means,  that  each  of  the five markup commands specified in the
312       docidx 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
317       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
322       To avoid essentially duplicating the command reference we do  not  list
323       any  of the command here and simply refer the reader to the docidx 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
328       The calling sequence of formatting commands is not as rigid as for  the
329       management commands, but determined by the grammar of the docidx markup
330       language, as specified in the docidx language syntax specification.
331
332       fmt_plain_text text
333              No associated markup command.
334
335              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
339              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

BUGS, IDEAS, FEEDBACK

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

SEE ALSO

350       docidx_intro,  docidx_lang_cmdref,  docidx_lang_faq, docidx_lang_intro,
351       docidx_lang_syntax, doctools::idx
352

KEYWORDS

354       formatting engine, index, index formatter,  keywords,  markup,  plugin,
355       semantic markup
356
358       Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
359
360
361
362
363doctools                              1.0              docidx_plugin_apiref(n)
Impressum