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

NAME

8       doctools::toc - Holding tables of contents
9

SYNOPSIS

11       package require doctools::toc  ?2?
12
13       package require Tcl  8.4
14
15       package require doctools::toc::structure
16
17       package require struct::tree
18
19       package require snit
20
21       ::doctools::toc objectName
22
23       objectName method ?arg arg ...?
24
25       objectName destroy
26
27       objectName + reference id label docid desc
28
29       objectName + division id label ?docid?
30
31       objectName remove id
32
33       objectName up id
34
35       objectName next id
36
37       objectName prev id
38
39       objectName child id label ?...?
40
41       objectName element ?...?
42
43       objectName children id
44
45       objectName type id
46
47       objectName full-label id
48
49       objectName elabel id ?newlabel?
50
51       objectName description id ?newdesc?
52
53       objectName document id ?newdocid?
54
55       objectName title
56
57       objectName title text
58
59       objectName label
60
61       objectName label text
62
63       objectName importer
64
65       objectName importer object
66
67       objectName exporter
68
69       objectName exporter object
70
71       objectName deserialize = data ?format?
72
73       objectName deserialize += data ?format?
74
75       objectName serialize ?format?
76
77______________________________________________________________________________
78

DESCRIPTION

80       This  package  provides a class to contain and programmatically manipu‐
81       late tables of contents.
82
83       This is one of the three public pillars the  management  of  tables  of
84       contents resides on. The other two pillars are
85
86       [1]    Exporting tables of contents, and
87
88       [2]    Importing tables of contents
89
90       For  information  about  the  Concepts of tables of contents, and their
91       parts, see the same-named section.   For  information  about  the  data
92       structure  which is used to encode tables of contents as values see the
93       section ToC serialization format.  This is  the  only  format  directly
94       known  to this class. Conversions from and to any other format are han‐
95       dled by export and import manager objects. These may be attached  to  a
96       container, but do not have to be, it is merely a convenience.
97

CONCEPTS

99       [1]    A  table of contents consists of a (possibly empty) list of ele‐
100              ments.
101
102       [2]    Each element in the list is identified by its label.
103
104       [3]    Each element is either a reference, or a division.
105
106       [4]    Each reference has an associated document, identified by a  sym‐
107              bolic id, and a textual description.
108
109       [5]    Each  division  may have an associated document, identified by a
110              symbolic id.
111
112       [6]    Each division consists consists of a (possibly  empty)  list  of
113              elements,  with each element following the rules as specified in
114              item 2 and above.
115
116       A few notes
117
118       [1]    The above rules span up a tree of elements, with  references  as
119              the  leaf nodes, and divisions as the inner nodes, and each ele‐
120              ment representing an entry in the whole table of contents.
121
122       [2]    The identifying labels of any element E are unique within  their
123              division  (or  toc),  and the full label of any element E is the
124              list of labels for all nodes on the unique path from the root of
125              the tree to E, including E.
126

API

128   PACKAGE COMMANDS
129       ::doctools::toc 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::toc 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 + reference id label docid desc
151              This  method  adds  a new reference element to the table of con‐
152              tents, under the element specified via its handle id. This  par‐
153              ent  element has to be a division element, or the root. An error
154              is thrown otherwise.  The new element will be externally identi‐
155              fied  by  its label, which has to be be unique within the parent
156              element. An error is thrown otherwise.
157
158              As a reference element it will refer to a document identified by
159              the symbolic docid. This reference must not be the empty string,
160              an error is thrown otherwise.  Beyond the label the element also
161              has a longer descriptive string, supplied via desc.
162
163              The result of the method is the handle (id) of the new element.
164
165       objectName + division id label ?docid?
166              This  method  adds  a  new division element to the table of con‐
167              tents, under the element specified via its handle id. This  par‐
168              ent  element has to be a division element, or the root. An error
169              is thrown otherwise.  The new element will be externally identi‐
170              fied  by  its label, which has to be be unique within the parent
171              element. An error is thrown otherwise.
172
173              As a division element it is can refer to a document,  identified
174              by the symbolic docid, but may choose not to.
175
176              The result of the method is the handle (id) of the new element.
177
178       objectName remove id
179              This method removes the element identified by the handle id from
180              the table of contents.  If the element is a division all of  its
181              children, if any, are removed as well. The root element/division
182              of the table of contents cannot be  removed  however,  only  its
183              children.
184
185              The result of the method is the empty string.
186
187       objectName up id
188              This  method  returns  the  handle of the parent for the element
189              identified by its handle id, or the empty string if id  referred
190              to the root element.
191
192       objectName next id
193              This method returns the handle of the right sibling for the ele‐
194              ment identified by its handle id, or the handle of the parent if
195              the  element has no right sibling, or the empty string if id re‐
196              ferred to the root element.
197
198       objectName prev id
199              This method returns the handle of the left sibling for the  ele‐
200              ment identified by its handle id, or the handle of the parent if
201              the element has no left sibling, or the empty string if  id  re‐
202              ferred to the root element.
203
204       objectName child id label ?...?
205              This method returns the handle of a child of the element identi‐
206              fied by its handle id. The child itself is identified by  a  se‐
207              ries of labels.
208
209       objectName element ?...?
210              This  method  returns  the handle of the element identified by a
211              series of labels, starting from the root of the  table  of  con‐
212              tents.  The  series  of  labels is allowed to be empty, in which
213              case the handle of the root element is returned.
214
215       objectName children id
216              This method returns a list containing the handles of  all  chil‐
217              dren  of  the element identified by the handle id, from first to
218              last, in that order.
219
220       objectName type id
221              This method returns the type of the element,  either  reference,
222              or division.
223
224       objectName full-label id
225              This  method is the complement of the method element, converting
226              the handle id of an element into a list of labels full identify‐
227              ing the element within the whole table of contents.
228
229       objectName elabel id ?newlabel?
230              This  method  queries  and/or  changes  the label of the element
231              identified by the handle id. If the argument newlabel is present
232              then the label is changed to that value. Regardless of this, the
233              result of the method is the current value of the label.
234
235              If the label is changed the new label has to  be  unique  within
236              the containing division, or an error is thrown.
237
238              Further,  of  the  id refers to the root element of the table of
239              contents, then using this method  is  equivalent  to  using  the
240              method  label,  i.e.  it  is  accessing the global label for the
241              whole table.
242
243       objectName description id ?newdesc?
244              This method queries and/or changes the description of  the  ele‐
245              ment  identified  by  the  handle id. If the argument newdesc is
246              present then the description is changed to that  value.  Regard‐
247              less  of  this, the result of the method is the current value of
248              the description.
249
250              The element this method operates on has to be a  reference  ele‐
251              ment, or an error will be thrown.
252
253       objectName document id ?newdocid?
254              This method queries and/or changes the document reference of the
255              element identified by the handle id.  If the  argument  newdocid
256              is  present  then  the description is changed to that value. Re‐
257              gardless of this, the result of the method is the current  value
258              of the document reference.
259
260              Setting  the  reference  to the empty string means unsetting it,
261              and is allowed only for division elements.  Conversely,  if  the
262              result is the empty string then the element has no document ref‐
263              erence, and this can happen only for division elements.
264
265       objectName title
266              Returns the currently defined title of the table of contents.
267
268       objectName title text
269              Sets the title of the table of contents to text, and returns  it
270              as the result of the command.
271
272       objectName label
273              Returns the currently defined label of the table of contents.
274
275       objectName label text
276              Sets  the label of the table of contents to text, and returns it
277              as the result of the command.
278
279       objectName importer
280              Returns the import manager object currently attached to the con‐
281              tainer, if any.
282
283       objectName importer object
284              Attaches  the object as import manager to the container, and re‐
285              turns it as the result of the command.  Note that the object  is
286              not  put  into  ownership of the container. I.e., destruction of
287              the container will not destroy the object.
288
289              It is expected that object provides a method named  import  text
290              which  takes a text and a format name, and returns the canonical
291              serialization of the table of contents contained  in  the  text,
292              assuming the given format.
293
294       objectName exporter
295              Returns the export manager object currently attached to the con‐
296              tainer, if any.
297
298       objectName exporter object
299              Attaches the object as export manager to the container, and  re‐
300              turns  it as the result of the command.  Note that the object is
301              not put into ownership of the container.  I.e.,  destruction  of
302              the container will not destroy the object.
303
304              It is expected that object provides a method named export object
305              which takes the container and a format name, and returns a  text
306              encoding table of contents stored in the container, in the given
307              format. It is further expected that the object will use the con‐
308              tainer's method serialize to obtain the serialization of the ta‐
309              ble of contents from which to generate the text.
310
311       objectName deserialize = data ?format?
312              This method replaces the contents of the table object  with  the
313              table  contained  in  the data. If no format was specified it is
314              assumed to be the regular serialization of a table of contents.
315
316              Otherwise the object will use the  attached  import  manager  to
317              convert the data from the specified format to a serialization it
318              can handle.  In that case an error will be thrown  if  the  con‐
319              tainer has no import manager attached to it.
320
321              The result of the method is the empty string.
322
323       objectName deserialize += data ?format?
324              This method behaves like deserialize = in its essentials, except
325              that it merges the table of contents in the data to its contents
326              instead  of  replacing  it.   The  method will throw an error if
327              merging is not possible, i.e. would produce  an  invalid  table.
328              The existing content is left unchanged in that case.
329
330              The result of the method is the empty string.
331
332       objectName serialize ?format?
333              This  method  returns the table of contents contained in the ob‐
334              ject. If no format is not specified the returned result  is  the
335              canonical serialization of its contents.
336
337              Otherwise  the  object  will  use the attached export manager to
338              convert the data to the specified format.  In that case an error
339              will  be  thrown if the container has no export manager attached
340              to it.
341

TOC SERIALIZATION FORMAT

343       Here we specify the format used by the doctools v2 packages to  serial‐
344       ize  tables  of contents as immutable values for transport, comparison,
345       etc.
346
347       We distinguish between regular and canonical serializations.   While  a
348       table of contents may have more than one regular serialization only ex‐
349       actly one of them will be canonical.
350
351       regular serialization
352
353              [1]    The serialization of any table of contents  is  a  nested
354                     Tcl dictionary.
355
356              [2]    This  dictionary  holds  a single key, doctools::toc, and
357                     its value. This value holds the contents of the table  of
358                     contents.
359
360              [3]    The  contents  of the table of contents are a Tcl dictio‐
361                     nary holding the title of the table of contents, a label,
362                     and its elements. The relevant keys and their values are
363
364                     title  The  value is a string containing the title of the
365                            table of contents.
366
367                     label  The value is a string containing a label  for  the
368                            table of contents.
369
370                     items  The  value  is  a Tcl list holding the elements of
371                            the table, in the order they are to be shown.
372
373                            Each element is a Tcl list holding the type of the
374                            item,  and  its description, in this order. An al‐
375                            ternative description would be that it  is  a  Tcl
376                            dictionary  holding  a  single key, the item type,
377                            mapped to the item description.
378
379                            The two legal item types  and  their  descriptions
380                            are
381
382                            reference
383                                   This  item  describes a single entry in the
384                                   table of  contents,  referencing  a  single
385                                   document.   To  this end its value is a Tcl
386                                   dictionary containing an id for the  refer‐
387                                   enced  document, a label, and a longer tex‐
388                                   tual description which  can  be  associated
389                                   with  the  entry.   The  relevant  keys and
390                                   their values are
391
392                                   id     The value is a string containing the
393                                          id  of  the document associated with
394                                          the entry.
395
396                                   label  The value is a string  containing  a
397                                          label  for  this  entry. This string
398                                          also identifies the  entry,  and  no
399                                          two  entries  (references  and divi‐
400                                          sions) in the  containing  list  are
401                                          allowed to have the same label.
402
403                                   desc   The  value  is a string containing a
404                                          longer description for this entry.
405
406                            division
407                                   This item describes a group of  entries  in
408                                   the table of contents, inducing a hierarchy
409                                   of entries.  To this end its value is a Tcl
410                                   dictionary   containing  a  label  for  the
411                                   group, an optional id to a document for the
412                                   whole group, and the list of entries in the
413                                   group.  The relevant keys and their  values
414                                   are
415
416                                   id     The value is a string containing the
417                                          id of the document  associated  with
418                                          the  whole  group.  This  key is op‐
419                                          tional.
420
421                                   label  The value is a string  containing  a
422                                          label  for  the  group.  This string
423                                          also identifies the  entry,  and  no
424                                          two  entries  (references  and divi‐
425                                          sions) in the  containing  list  are
426                                          allowed to have the same label.
427
428                                   items  The  value is a Tcl list holding the
429                                          elements of the group, in the  order
430                                          they are to be shown.  This list has
431                                          the same structure as the value  for
432                                          the  keyword  items used to describe
433                                          the whole  table  of  contents,  see
434                                          above.  This  closes  the  recusrive
435                                          definition of  the  structure,  with
436                                          divisions  holding  the same type of
437                                          elements as the whole table of  con‐
438                                          tents, including other divisions.
439
440       canonical serialization
441              The  canonical serialization of a table of contents has the for‐
442              mat as specified in the previous  item,  and  then  additionally
443              satisfies  the constraints below, which make it unique among all
444              the possible serializations of this table of contents.
445
446              [1]    The keys found in all the  nested  Tcl  dictionaries  are
447                     sorted  in  ascending  dictionary  order, as generated by
448                     Tcl's builtin command lsort -increasing -dict.
449

BUGS, IDEAS, FEEDBACK

451       This document, and the package it describes, will  undoubtedly  contain
452       bugs  and  other problems.  Please report such in the category doctools
453       of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].   Please
454       also  report any ideas for enhancements you may have for either package
455       and/or documentation.
456
457       When proposing code changes, please provide unified diffs, i.e the out‐
458       put of diff -u.
459
460       Note  further  that  attachments  are  strongly  preferred over inlined
461       patches. Attachments can be made by going  to  the  Edit  form  of  the
462       ticket  immediately  after  its  creation, and then using the left-most
463       button in the secondary navigation bar.
464

KEYWORDS

466       HTML, TMML, conversion, doctoc markup, documentation, formatting,  gen‐
467       eration, json, latex, markup, nroff, parsing, plugin, reference, table,
468       table of contents, tcler's wiki, text, wiki
469

CATEGORY

471       Documentation tools
472
474       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
475
476
477
478
479tcllib                                 2                      doctools::toc(n)
Impressum