1doctools::idx(n) Documentation tools doctools::idx(n)
2______________________________________________________________________________
6
8 doctools::idx - Holding keyword indices
9
11 package require doctools::idx ?2?
12 package require Tcl 8.4
14 package require doctools::idx::structure
16 package require snit
18 ::doctools::idx objectName
20 objectName method ?arg arg ...?
22 objectName destroy
24 objectName key add name
26 objectName key remove name
28 objectName key references name
30 objectName keys
32 objectName reference add type key name label
34 objectName reference remove name
36 objectName reference label name
38 objectName reference keys name
40 objectName reference type name
42 objectName references
44 objectName title
46 objectName title text
48 objectName label
50 objectName label text
52 objectName importer
54 objectName importer object
56 objectName exporter
58 objectName exporter object
60 objectName deserialize = data ?format?
62 objectName deserialize += data ?format?
64 objectName serialize ?format?
66______________________________________________________________________________
68
70 This package provides a class to contain and programmatically manipu‐
71 late keyword indices
72 This is one of the three public pillars the management of keyword
74 indices resides on. The other two pillars are
75 [1] Exporting keyword indices, and
77 [2] Importing keyword indices
79 For information about the Concepts of keyword indices, and their parts,
81 see the same-named section. For information about the data structure
82 which is used to encode keyword indices as values see the section Key‐
83 word index serialization format. This is the only format directly
84 known to this class. Conversions from and to any other format are han‐
85 dled by export and import manager objects. These may be attached to a
86 container, but do not have to be, it is merely a convenience.
87
89 [1] A keyword index consists of a (possibly empty) set of keywords.
90 [2] Each keyword in the set is identified by its name.
92 [3] Each keyword has a (possibly empty) set of references.
94 [4] A reference can be associated with more than one keyword.
96 [5] A reference not associated with at least one keyword is not pos‐
98 sible however.
99 [6] Each reference is identified by its target, specified as either
101 an url or symbolic filename, depending on the type of reference
102 (url, or manpage).
103 [7] The type of a reference (url, or manpage) depends only on the
105 reference itself, and not the keywords it is associated with.
106 [8] In addition to a type each reference has a descriptive label as
108 well. This label depends only on the reference itself, and not
109 the keywords it is associated with.
110 A few notes
112 [1] Manpage references are intended to be used for references to the
114 documents the index is made for. Their target is a symbolic file
115 name identifying the document, and export plugins may replace
116 symbolic with actual file names, if specified.
117 [2] Url references are intended on the othre hand are inteded to be
119 used for links to anything else, like websites. Their target is
120 an url.
121 [3] While url and manpage references share a namespace for their
123 identifiers, this should be no problem, given that manpage iden‐
124 tifiers are symbolic filenames and as such they should never
125 look like urls, the identifiers for url references.
126
128 PACKAGE COMMANDS
129 ::doctools::idx objectName
130 This command creates a new container object with an associated
131 Tcl command whose name is objectName. This object command is
132 explained in full detail in the sections Object command and
133 Object methods. The object command will be created under the
134 current namespace if the objectName is not fully qualified, and
135 in the specified namespace otherwise.
136 OBJECT COMMAND
138 All objects created by the ::doctools::idx command have the following
139 general form:
140 objectName method ?arg arg ...?
142 The method method and its arg'uments determine the exact behav‐
143 ior of the command. See section Object methods for the detailed
144 specifications.
145 OBJECT METHODS
147 objectName destroy
148 This method destroys the object it is invoked for.
149 objectName key add name
151 This method adds the keyword name to the index. If the keyword
152 is already known nothing is done. The result of the method is
153 the empty string.
154 objectName key remove name
156 This method removes the keyword name from the index. If the key‐
157 word is already gone nothing is done. Any references for whom
158 this keyword was the last association are removed as well. The
159 result of the method is the empty string.
160 objectName key references name
162 This method returns a list containing the names of all refer‐
163 ences associated with the keyword name. An error is thrown in
164 the keyword is not known to the index. The order of the refer‐
165 ences in the list is undefined.
166 objectName keys
168 This method returns a list containing the names of all keywords
169 known to the index. The order of the keywords in the list is
170 undefined.
171 objectName reference add type key name label
173 This method adds the reference name to the index and associates
174 it with the keyword key. The other two arguments hold the type
175 and label of the reference, respectively. The type has to match
176 the stored information, should the reference exist already, i.e.
177 this information is immutable after the reference is known. The
178 only way to change it is delete and recreate the reference. The
179 label on the other hand is automatically updated to the value of
180 the argument, overwriting any previously stored information.
181 Should the reference exists already it is simply associated with
182 the key. If that is true already as well nothing is done, but
183 the label updated to the new value. The result of the method is
184 the empty string.
185 The type argument has be to one of manpage or url.
187 objectName reference remove name
189 The reference name is removed from the index. All associations
190 with keywords are released and the relevant reference labels
191 removed. The result of the method is the empty string.
192 objectName reference label name
194 This method returns the label associated with the reference
195 name. An error is thrown if the reference is not known.
196 objectName reference keys name
198 This method returns a list containing the names of all keywords
199 associated with the reference name. An error is thrown in the
200 reference is not known to the index. The order of the keywords
201 in the list is undefined.
202 objectName reference type name
204 This method returns the type of the reference name. An error is
205 thrown in the reference is not known to the index.
206 objectName references
208 This method returns a list containing the names of all refer‐
209 ences known to the index. The order of the references in the
210 list is undefined.
211 objectName title
213 Returns the currently defined title of the keyword index.
214 objectName title text
216 Sets the title of the keyword index to text, and returns it as
217 the result of the command.
218 objectName label
220 Returns the currently defined label of the keyword index.
221 objectName label text
223 Sets the label of the keyword index to text, and returns it as
224 the result of the command.
225 objectName importer
227 Returns the import manager object currently attached to the con‐
228 tainer, if any.
229 objectName importer object
231 Attaches the object as import manager to the container, and
232 returns it as the result of the command. Note that the object
233 is not put into ownership of the container. I.e., destruction of
234 the container will not destroy the object.
235 It is expected that object provides a method named import text
237 which takes a text and a format name, and returns the canonical
238 serialization of the keyword index contained in the text, assum‐
239 ing the given format.
240 objectName exporter
242 Returns the export manager object currently attached to the con‐
243 tainer, if any.
244 objectName exporter object
246 Attaches the object as export manager to the container, and
247 returns it as the result of the command. Note that the object
248 is not put into ownership of the container. I.e., destruction of
249 the container will not destroy the object.
250 It is expected that object provides a method named export object
252 which takes the container and a format name, and returns a text
253 encoding keyword index stored in the container, in the given
254 format. It is further expected that the object will use the con‐
255 tainer's method serialize to obtain the serialization of the
256 keyword index from which to generate the text.
257 objectName deserialize = data ?format?
259 This method replaces the contents of the index object with the
260 index contained in the data. If no format was specified it is
261 assumed to be the regular serialization of a keyword index.
262 Otherwise the object will use the attached import manager to
264 convert the data from the specified format to a serialization it
265 can handle. In that case an error will be thrown if the con‐
266 tainer has no import manager attached to it.
267 The result of the method is the empty string.
269 objectName deserialize += data ?format?
271 This method behaves like deserialize = in its essentials, except
272 that it merges the keyword index in the data to its contents
273 instead of replacing it. The method will throw an error if
274 merging is not possible, i.e. would produce an invalid index.
275 The existing content is left unchanged in that case.
276 The result of the method is the empty string.
278 objectName serialize ?format?
280 This method returns the keyword index contained in the object.
281 If no format is not specified the returned result is the canoni‐
282 cal serialization of its contents.
283 Otherwise the object will use the attached export manager to
285 convert the data to the specified format. In that case an error
286 will be thrown if the container has no export manager attached
287 to it.
288
290 Here we specify the format used by the doctools v2 packages to serial‐
291 ize keyword indices as immutable values for transport, comparison, etc.
292 We distinguish between regular and canonical serializations. While a
294 keyword index may have more than one regular serialization only exactly
295 one of them will be canonical.
296 regular serialization
298 [1] An index serialization is a nested Tcl dictionary.
300 [2] This dictionary holds a single key, doctools::idx, and
302 its value. This value holds the contents of the index.
303 [3] The contents of the index are a Tcl dictionary holding
305 the title of the index, a label, and the keywords and
306 references. The relevant keys and their values are
307 title The value is a string containing the title of the
309 index.
310 label The value is a string containing a label for the
312 index.
313 keywords
315 The value is a Tcl dictionary, using the keywords
316 known to the index as keys. The associated values
317 are lists containing the identifiers of the refer‐
318 ences associated with that particular keyword.
319 Any reference identifier used in these lists has
321 to exist as a key in the references dictionary,
322 see the next item for its definition.
323 references
325 The value is a Tcl dictionary, using the identi‐
326 fiers for the references known to the index as
327 keys. The associated values are 2-element lists
328 containing the type and label of the reference, in
329 this order.
330 Any key here has to be associated with at least
332 one keyword, i.e. occur in at least one of the
333 reference lists which are the values in the key‐
334 words dictionary, see previous item for its defi‐
335 nition.
336 [4] The type of a reference can be one of two values,
338 manpage
340 The identifier of the reference is interpreted as
341 symbolic file name, referring to one of the docu‐
342 ments the index was made for.
343 url The identifier of the reference is interpreted as
345 an url, referring to some external location, like
346 a website, etc.
347 canonical serialization
349 The canonical serialization of a keyword index has the format as
350 specified in the previous item, and then additionally satisfies
351 the constraints below, which make it unique among all the possi‐
352 ble serializations of the keyword index.
353 [1] The keys found in all the nested Tcl dictionaries are
355 sorted in ascending dictionary order, as generated by
356 Tcl's builtin command lsort -increasing -dict.
357 [2] The references listed for each keyword of the index, if
359 any, are listed in ascending dictionary order of their
360 labels, as generated by Tcl's builtin command lsort
361 -increasing -dict.
362
364 This document, and the package it describes, will undoubtedly contain
365 bugs and other problems. Please report such in the category doctools
366 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
367 also report any ideas for enhancements you may have for either package
368 and/or documentation.
369 When proposing code changes, please provide unified diffs, i.e the out‐
371 put of diff -u.
372 Note further that attachments are strongly preferred over inlined
374 patches. Attachments can be made by going to the Edit form of the
375 ticket immediately after its creation, and then using the left-most
376 button in the secondary navigation bar.
377
379 HTML, TMML, conversion, docidx markup, documentation, formatting, gen‐
380 eration, index, json, keyword index, latex, manpage, markup, nroff,
381 parsing, plugin, reference, tcler's wiki, text, url, wiki
382
384 Documentation tools
385
387 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
388tcllib 2 doctools::idx(n)