1docidx_api(n) Documentation tools docidx_api(n)
2______________________________________________________________________________
6
8 docidx_api - Specification of the Interface to Index Formatting Engines
9
11 idx_numpasses
12 idx_initialize
14 idx_setup n
16 idx_postprocess text
18 idx_shutdown
20 idx_listvariables
22 idx_varset varname text
24 fmt_plain_text text
26 fmt_comment text
28 fmt_index_begin text title
30 fmt_index_end
32 fmt_key text
34 fmt_manpage file text
36 fmt_url url text
38 dt_format
40 dt_fmap symfname
42 dt_source file
44 ex_cappend
46 ex_cget
48 ex_cis
50 ex_cname
52 ex_cpop
54 ex_cpush
56 ex_cset
58 ex_lb
60 ex_rb
62_________________________________________________________________
64
66 This document specifies version 1 of the interface an index formatting
67 engine has to comply with to be usable by the package doctools::idx.
68 The specification of the docidx format all index formatting engines
69 have to process can be found in the companion document docidx_fmt.
70
72 EXPORTED COMMANDS
73 Each index formatting engine has to provide a number of commands
74 through which objects created by the package doctools::idx will upon
75 the functionality of the engine. These commands are described here.
76 Management commands
78 idx_numpasses
80 This command is called by a docidx object immediately
81 after it has loaded the engine. No other command of the
82 engine will be called before it. It has to return the
83 number of passes this engine requires to fully process
84 the input document. This value has to be an integer num‐
85 ber greater or equal to one.
86 idx_initialize
88 This command is called at the beginning of every conver‐
89 sion run, as the first command of that run. Note that a
90 run is not a pass, but may consist of multiple passes.
91 See idx_numpasses. The command has to initialize the gen‐
92 eral state of the index formatting engine, beyond the
93 initialization done during the load.
94 idx_setup n
96 This command is called at the beginning of each pass over
97 the input in a run. Its argument is the number of the
98 pass which has begun. Passes are counted from 1 upward.
99 The command has to set up the internal state of the index
100 formatting engine for this particular pass.
101 idx_postprocess text
103 This command is called immediately after the last pass in
104 a run. Its argument is the result of the conversion gen‐
105 erated by that pass. It is provided to allow the engine
106 to perform any global last-ditch modifications of the
107 generated document. The text returned by this command
108 will be the final result of the conversion.
109 An engine for a format which requires no postprocessing
111 can simply return the argument without change.
112 idx_shutdown
114 This command is called at the end of every conversion
115 run. It is the last command called in a run. It has to
116 clean up of all the run-specific state in the index for‐
117 matting engine. After the call the engine has to be in a
118 state which allows the initiation of another run without
119 fear that information from the last run is leaked into
120 this new run.
121 idx_listvariables
123 This command is called by a docidx object after it has
124 loaded the engine (after idx_numpasses). It has to return
125 a list containing the names of the engine parameters pro‐
126 vided by the engine. This list can be empty.
127 idx_varset varname text
129 This command is called whenever the docidx object wishes
130 to set an engine parameter to a particular value. The
131 parameter to change is specified by varname, the value to
132 set in text.
133 The command has to throw an error if an unknown varname
135 is used. Only the names returned by idx_listvariables are
136 considered known.
137 The values of all engine parameters have to persist
139 between passes and runs.
140 Formatting commands
143 The commands listed in this section are responsible for the con‐
144 version of the input into the wanted output. Their names are
145 the names of the associated markup command, with prefix fmt_
146 added to them. Not all markup commands have associated format‐
147 ting commands. The two exceptions are vset and include. These
148 markup commands are processed by the docidx object itself.
149 A detailed documentation of the markup commands can be found in
151 the companion document docidx_fmt. It is the formal specifica‐
152 tion of the docidx format.
153 Note: The formatting commands can expect that they are only
155 called in an order allowed by the format specification.
156 fmt_plain_text text
158 This command has no associated markup command. It is
159 called for any plain text encountered by the processor in
160 the input. It has to perform any special processing
161 required for plain text. The text returned as its result
162 is added to the output. If no special processing is
163 required it has to simply return its argument without
164 change.
165 fmt_comment text
167 This command has to format the text as a comment and
168 return the formatted string. It has to return the empty
169 string if the output format has no way of formatting com‐
170 ments.
171 fmt_index_begin text title
173 This command has to format the label text and the associ‐
174 ated title string as the start of the generated index and
175 return the formatted string.
176 fmt_index_end
178 This command has to generate the end of the generated
179 index and return the formatted string.
180 fmt_key text
182 This commands has to format the keyword text at the
183 beginning of a list of documents and other entities which
184 belong to it and return the formatted string.
185 fmt_manpage file text
187 This command has to format a document reference and
188 return the formatted string. The document referenced by
189 the entry is specified through its symbolic name file,
190 whereas the label to use for the link is provided by
191 text. Use the command dt_fmap to convert the symbolic
192 name to the actual link. It is described in section
193 IMPORTED ENVIRONMENT.
194 fmt_url url text
196 This is the second command to describe an index element.
197 It has to format an url reference and return the format‐
198 ted string. The label to use is provided by text, like
199 for fmt_manpage. The place to link to is however not
200 given through a symbolic name, but the exact uri to use
201 in the output.
202 IMPORTED ENVIRONMENT
204 The implementation of an index formatting engine can make the following
205 assumptions about the environment it is executed in:
206 [1] That it has full access to its own safe interpreter. In other
208 words, the engine cannot damage the other parts of the proces‐
209 sor, nor can it damage the filesystem.
210 [2] That the following commands are provided by the docidx object
212 controlling the engine:
213 Doctools commands
215 dt_format
217 This command returns the name of the format cur‐
218 rently executing.
219 dt_fmap symfname
221 This command returns the actual name to use in the
222 output in place of the symbolic filename symfname.
223 It will return the unchanged input if no mapping
224 was found for symfname.
225 dt_source file
227 This command allows the index formatting engine to
228 load additional tcl code. Only files which are
229 either in the same directory as the file contain‐
230 ing the engine, or below it, can be loaded. Trying
231 to load a file outside of this directory causes an
232 error.
233 Expander commands
236 All of the commands below are methods of the expander
237 object (without the prefix ex_) handling the current
238 input. This gives the engine limited access to the state
239 of the expander. Their arguments and results are
240 described in the documentation for the package expander.
241 ex_cappend
243 ex_cget
245 ex_cis
247 ex_cname
249 ex_cpop
251 ex_cpush
253 ex_cset
255 ex_lb
257 ex_rb
259 Other commands
262 The file "_idx_common.tcl" contains default implementa‐
263 tions of fmt_plaint_text and all the idx_ commands listed
264 in section EXPORTED COMMANDS. It resides in the subdi‐
265 rectory "mpformats" containing all the predefined for‐
266 mats. This means that all external formats (i.e. not pro‐
267 vided by the package doctools::idx) cannot use it immedi‐
268 ately, but have to have a copy at their location.
269
271 docidx, docidx_fmt
272
274 HTML, LaTeX, TMML, generic markup, index, keyword index, keywords,
275 markup, nroff
276
278 Copyright (c) 2003-2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
279doctools 1.0 docidx_api(n)