1doctools::idx(n)              Documentation tools             doctools::idx(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       doctools::idx - Holding keyword indices
9

SYNOPSIS

11       package require doctools::idx  ?2?
12
13       package require Tcl  8.4
14
15       package require doctools::idx::structure
16
17       package require snit
18
19       ::doctools::idx objectName
20
21       objectName method ?arg arg ...?
22
23       objectName destroy
24
25       objectName key add name
26
27       objectName key remove name
28
29       objectName key references name
30
31       objectName keys
32
33       objectName reference add type key name label
34
35       objectName reference remove name
36
37       objectName reference label name
38
39       objectName reference keys name
40
41       objectName reference type name
42
43       objectName references
44
45       objectName title
46
47       objectName title text
48
49       objectName label
50
51       objectName label text
52
53       objectName importer
54
55       objectName importer object
56
57       objectName exporter
58
59       objectName exporter object
60
61       objectName deserialize = data ?format?
62
63       objectName deserialize += data ?format?
64
65       objectName serialize ?format?
66
67______________________________________________________________________________
68

DESCRIPTION

70       This  package  provides a class to contain and programmatically manipu‐
71       late keyword indices
72
73       This is one of the three public pillars the management of  keyword  in‐
74       dices resides on. The other two pillars are
75
76       [1]    Exporting keyword indices, and
77
78       [2]    Importing keyword indices
79
80       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

CONCEPTS

89       [1]    A keyword index consists of a (possibly empty) set of keywords.
90
91       [2]    Each keyword in the set is identified by its name.
92
93       [3]    Each keyword has a (possibly empty) set of references.
94
95       [4]    A reference can be associated with more than one keyword.
96
97       [5]    A reference not associated with at least one keyword is not pos‐
98              sible however.
99
100       [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
104       [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
107       [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
111       A few notes
112
113       [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
118       [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
122       [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

API

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 ex‐
132              plained in full detail in the sections Object command and Object
133              methods. The object command will be created  under  the  current
134              namespace  if  the objectName is not fully qualified, and in the
135              specified namespace otherwise.
136
137   OBJECT COMMAND
138       All objects created by the ::doctools::idx command have  the  following
139       general form:
140
141       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
146   OBJECT METHODS
147       objectName destroy
148              This method destroys the object it is invoked for.
149
150       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
155       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
161       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
167       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 un‐
170              defined.
171
172       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
186              The type argument has be to one of manpage or url.
187
188       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 re‐
191              moved.  The result of the method is the empty string.
192
193       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
197       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
203       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
207       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
212       objectName title
213              Returns the currently defined title of the keyword index.
214
215       objectName title text
216              Sets  the  title of the keyword index to text, and returns it as
217              the result of the command.
218
219       objectName label
220              Returns the currently defined label of the keyword index.
221
222       objectName label text
223              Sets the label of the keyword index to text, and returns  it  as
224              the result of the command.
225
226       objectName importer
227              Returns the import manager object currently attached to the con‐
228              tainer, if any.
229
230       objectName importer object
231              Attaches the object as import manager to the container, and  re‐
232              turns  it as the result of the command.  Note that the object is
233              not put into ownership of the container.  I.e.,  destruction  of
234              the container will not destroy the object.
235
236              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
241       objectName exporter
242              Returns the export manager object currently attached to the con‐
243              tainer, if any.
244
245       objectName exporter object
246              Attaches  the object as export manager to the container, and re‐
247              turns it as the result of the command.  Note that the object  is
248              not  put  into  ownership of the container. I.e., destruction of
249              the container will not destroy the object.
250
251              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
258       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
263              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
268              The result of the method is the empty string.
269
270       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 in‐
273              stead of replacing it.  The method will throw an error if  merg‐
274              ing  is  not  possible, i.e. would produce an invalid index. The
275              existing content is left unchanged in that case.
276
277              The result of the method is the empty string.
278
279       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
284              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

KEYWORD INDEX SERIALIZATION FORMAT

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
293       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
297       regular serialization
298
299              [1]    An index serialization is a nested Tcl dictionary.
300
301              [2]    This dictionary holds a single  key,  doctools::idx,  and
302                     its value. This value holds the contents of the index.
303
304              [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
308                     title  The  value is a string containing the title of the
309                            index.
310
311                     label  The value is a string containing a label  for  the
312                            index.
313
314                     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
320                            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
324                     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
331                            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
337              [4]    The type of a reference can be one of two values,
338
339                     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
344                     url    The identifier of the reference is interpreted  as
345                            an  url, referring to some external location, like
346                            a website, etc.
347
348       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
354              [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
358              [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 -in‐
361                     creasing -dict.
362

BUGS, IDEAS, FEEDBACK

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
370       When proposing code changes, please provide unified diffs, i.e the out‐
371       put of diff -u.
372
373       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

KEYWORDS

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

CATEGORY

384       Documentation tools
385
387       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
388
389
390
391
392tcllib                                 2                      doctools::idx(n)
Impressum