1doctools::idx::export(n) Documentation tools doctools::idx::export(n)
2______________________________________________________________________________
6
8 doctools::idx::export - Exporting keyword indices
9
11 package require doctools::idx::export ?0.2?
12 package require Tcl 8.4
14 package require doctools::config
16 package require doctools::idx::structure
18 package require snit
20 package require pluginmgr
22 ::doctools::idx::export objectName
24 objectName method ?arg arg ...?
26 objectName destroy
28 objectName export serial serial ?format?
30 objectName export object object ?format?
32 objectName config names
34 objectName config get
36 objectName config set name ?value?
38 objectName config unset pattern...
40 export serial configuration
42______________________________________________________________________________
44
46 This package provides a class to manage the plugins for the export of
47 keyword indices to other formats, i.e. their conversion to, for example
48 docidx, HTML, etc.
49 This is one of the three public pillars the management of keyword
51 indices resides on. The other two pillars are
52 [1] Importing keyword indices, and
54 [2] Holding keyword indices
56 For information about the Concepts of keyword indices, and their parts,
58 see the same-named section. For information about the data structure
59 which is the major input to the manager objects provided by this pack‐
60 age see the section Keyword index serialization format.
61 The plugin system of our class is based on the package pluginmgr, and
63 configured to look for plugins using
64 [1] the environment variable DOCTOOLS_IDX_EXPORT_PLUGINS,
66 [2] the environment variable DOCTOOLS_IDX_PLUGINS,
68 [3] the environment variable DOCTOOLS_PLUGINS,
70 [4] the path "~/.doctools/idx/export/plugin"
72 [5] the path "~/.doctools/idx/plugin"
74 [6] the path "~/.doctools/plugin"
76 [7] the path "~/.doctools/idx/export/plugins"
78 [8] the path "~/.doctools/idx/plugins"
80 [9] the path "~/.doctools/plugins"
82 [10] the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOC‐
84 TOOLS\IDX\EXPORT\PLUGINS"
85 [11] the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOC‐
87 TOOLS\IDX\PLUGINS"
88 [12] the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"
90 The last three are used only when the package is run on a machine using
92 Windows(tm) operating system.
93 The whole system is delivered with six predefined export plugins,
95 namely
96 docidx See docidx export plugin for details.
98 html See html export plugin for details.
100 json See json export plugin for details.
102 nroff See nroff export plugin for details.
104 text See text export plugin for details.
106 wiki See wiki export plugin for details.
108 Readers wishing to write their own export plugin for some format, i.e.
110 plugin writers reading and understanding the section containing the
111 Export plugin API v2 reference is an absolute necessity, as it speci‐
112 fies the interaction between this package and its plugins in detail.
113
115 [1] A keyword index consists of a (possibly empty) set of keywords.
116 [2] Each keyword in the set is identified by its name.
118 [3] Each keyword has a (possibly empty) set of references.
120 [4] A reference can be associated with more than one keyword.
122 [5] A reference not associated with at least one keyword is not pos‐
124 sible however.
125 [6] Each reference is identified by its target, specified as either
127 an url or symbolic filename, depending on the type of reference
128 (url, or manpage).
129 [7] The type of a reference (url, or manpage) depends only on the
131 reference itself, and not the keywords it is associated with.
132 [8] In addition to a type each reference has a descriptive label as
134 well. This label depends only on the reference itself, and not
135 the keywords it is associated with.
136 A few notes
138 [1] Manpage references are intended to be used for references to the
140 documents the index is made for. Their target is a symbolic file
141 name identifying the document, and export plugins may replace
142 symbolic with actual file names, if specified.
143 [2] Url references are intended on the othre hand are inteded to be
145 used for links to anything else, like websites. Their target is
146 an url.
147 [3] While url and manpage references share a namespace for their
149 identifiers, this should be no problem, given that manpage iden‐
150 tifiers are symbolic filenames and as such they should never
151 look like urls, the identifiers for url references.
152
154 PACKAGE COMMANDS
155 ::doctools::idx::export objectName
156 This command creates a new export manager object with an associ‐
157 ated Tcl command whose name is objectName. This object command
158 is explained in full detail in the sections Object command and
159 Object methods. The object command will be created under the
160 current namespace if the objectName is not fully qualified, and
161 in the specified namespace otherwise.
162 OBJECT COMMAND
164 All objects created by the ::doctools::idx::export command have the
165 following general form:
166 objectName method ?arg arg ...?
168 The method method and its arg'uments determine the exact behav‐
169 ior of the command. See section Object methods for the detailed
170 specifications.
171 OBJECT METHODS
173 objectName destroy
174 This method destroys the object it is invoked for.
175 objectName export serial serial ?format?
177 This method takes the canonical serialization of a keyword index
178 stored in serial and converts it to the specified format, using
179 the export plugin for the format. An error is thrown if no plug‐
180 in could be found for the format. The string generated by the
181 conversion process is returned as the result of this method.
182 If no format is specified the method defaults to docidx.
184 The specification of what a canonical serialization is can be
186 found in the section Keyword index serialization format.
187 The plugin has to conform to the interface specified in section
189 Export plugin API v2 reference.
190 objectName export object object ?format?
192 This method is a convenient wrapper around the export serial
193 method described by the previous item. It expects that object
194 is an object command supporting a serialize method returning the
195 canonical serialization of a keyword index. It invokes that
196 method, feeds the result into export serial and returns the
197 resulting string as its own result.
198 objectName config names
200 This method returns a list containing the names of all configu‐
201 ration variables currently known to the object.
202 objectName config get
204 This method returns a dictionary containing the names and values
205 of all configuration variables currently known to the object.
206 objectName config set name ?value?
208 This method sets the configuration variable name to the speci‐
209 fied value and returns the new value of the variable.
210 If no value is specified it simply returns the current value,
212 without changing it.
213 Note that while the user can set the predefined configuration
215 variables user and format doing so will have no effect, these
216 values will be internally overridden when invoking an import
217 plugin.
218 objectName config unset pattern...
220 This method unsets all configuration variables matching the
221 specified glob patterns. If no pattern is specified it will
222 unset all currently defined configuration variables.
223
225 Plugins are what this package uses to manage the support for any output
226 format beyond the Keyword index serialization format. Here we specify
227 the API the objects created by this package use to interact with their
228 plugins.
229 A plugin for this package has to follow the rules listed below:
231 [1] A plugin is a package.
233 [2] The name of a plugin package has the form doc‐
235 tools::idx::export::FOO, where FOO is the name of the format the
236 plugin will generate output for. This name is also the argument
237 to provide to the various export methods of export manager
238 objects to get a string encoding a keyword index in that format.
239 [3] The plugin can expect that the package doc‐
241 tools::idx::export::plugin is present, as indicator that it was
242 invoked from a genuine plugin manager.
243 [4] A plugin has to provide one command, with the signature shown
245 below.
246 export serial configuration
248 Whenever an export manager of doctools::idx has to gener‐
249 ate output for an index it will invoke this command.
250 string serial
252 This argument will contain the canonical serial‐
253 ization of the index for which to generate the
254 output. The specification of what a canonical
255 serialization is can be found in the section Key‐
256 word index serialization format.
257 dictionary configuration
259 This argument will contain the current configura‐
260 tion to apply to the generation, as a dictionary
261 mapping from variable names to values.
262 The following configuration variables have a pre‐
264 defined meaning all plugins have to obey, although
265 they can ignore this information at their discre‐
266 tion. Any other other configuration variables rec‐
267 ognized by a plugin will be described in the man‐
268 page for that plugin.
269 user This variable is expected to contain the
271 name of the user owning the process invok‐
272 ing the plugin.
273 format This variable is expected to contain the
275 name of the format whose plugin is invoked.
276 file This variable, if defined by the user of
278 the index object is expected to contain the
279 name of the input file for which the plugin
280 is generating its output for.
281 map This variable, if defined by the user of
283 the index object is expected to contain a
284 dictionary mapping from symbolic file names
285 used in the references of type manpage to
286 actual paths (or urls). A plugin has to be
287 able to handle the possibility that a sym‐
288 bolic name is without entry in this map‐
289 ping.
290 [5] A single usage cycle of a plugin consists of the invokations of
292 the command export. This call has to leave the plugin in a state
293 where another usage cycle can be run without problems.
294
296 Here we specify the format used by the doctools v2 packages to serial‐
297 ize keyword indices as immutable values for transport, comparison, etc.
298 We distinguish between regular and canonical serializations. While a
300 keyword index may have more than one regular serialization only exactly
301 one of them will be canonical.
302 regular serialization
304 [1] An index serialization is a nested Tcl dictionary.
306 [2] This dictionary holds a single key, doctools::idx, and
308 its value. This value holds the contents of the index.
309 [3] The contents of the index are a Tcl dictionary holding
311 the title of the index, a label, and the keywords and
312 references. The relevant keys and their values are
313 title The value is a string containing the title of the
315 index.
316 label The value is a string containing a label for the
318 index.
319 keywords
321 The value is a Tcl dictionary, using the keywords
322 known to the index as keys. The associated values
323 are lists containing the identifiers of the refer‐
324 ences associated with that particular keyword.
325 Any reference identifier used in these lists has
327 to exist as a key in the references dictionary,
328 see the next item for its definition.
329 references
331 The value is a Tcl dictionary, using the identi‐
332 fiers for the references known to the index as
333 keys. The associated values are 2-element lists
334 containing the type and label of the reference, in
335 this order.
336 Any key here has to be associated with at least
338 one keyword, i.e. occur in at least one of the
339 reference lists which are the values in the key‐
340 words dictionary, see previous item for its defi‐
341 nition.
342 [4] The type of a reference can be one of two values,
344 manpage
346 The identifier of the reference is interpreted as
347 symbolic file name, referring to one of the docu‐
348 ments the index was made for.
349 url The identifier of the reference is interpreted as
351 an url, referring to some external location, like
352 a website, etc.
353 canonical serialization
355 The canonical serialization of a keyword index has the format as
356 specified in the previous item, and then additionally satisfies
357 the constraints below, which make it unique among all the possi‐
358 ble serializations of the keyword index.
359 [1] The keys found in all the nested Tcl dictionaries are
361 sorted in ascending dictionary order, as generated by
362 Tcl's builtin command lsort -increasing -dict.
363 [2] The references listed for each keyword of the index, if
365 any, are listed in ascending dictionary order of their
366 labels, as generated by Tcl's builtin command lsort
367 -increasing -dict.
368
370 This document, and the package it describes, will undoubtedly contain
371 bugs and other problems. Please report such in the category doctools
372 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
373 also report any ideas for enhancements you may have for either package
374 and/or documentation.
375 When proposing code changes, please provide unified diffs, i.e the out‐
377 put of diff -u.
378 Note further that attachments are strongly preferred over inlined
380 patches. Attachments can be made by going to the Edit form of the
381 ticket immediately after its creation, and then using the left-most
382 button in the secondary navigation bar.
383
385 HTML, conversion, docidx, documentation, export, formatting, genera‐
386 tion, index, json, keyword index, manpage, markup, nroff, plugin, ref‐
387 erence, tcler's wiki, text, url, wiki
388
390 Documentation tools
391
393 Copyright (c) 2009-2018 Andreas Kupries <andreas_kupries@users.sourceforge.net>
394tcllib 0.2 doctools::idx::export(n)