1doctools::toc(n) Documentation tools doctools::toc(n)
2______________________________________________________________________________
6
8 doctools::toc - Holding tables of contents
9
11 package require doctools::toc ?2?
12 package require Tcl 8.4
14 package require doctools::toc::structure
16 package require struct::tree
18 package require snit
20 ::doctools::toc objectName
22 objectName method ?arg arg ...?
24 objectName destroy
26 objectName + reference id label docid desc
28 objectName + division id label ?docid?
30 objectName remove id
32 objectName up id
34 objectName next id
36 objectName prev id
38 objectName child id label ?...?
40 objectName element ?...?
42 objectName children id
44 objectName type id
46 objectName full-label id
48 objectName elabel id ?newlabel?
50 objectName description id ?newdesc?
52 objectName document id ?newdocid?
54 objectName title
56 objectName title text
58 objectName label
60 objectName label text
62 objectName importer
64 objectName importer object
66 objectName exporter
68 objectName exporter object
70 objectName deserialize = data ?format?
72 objectName deserialize += data ?format?
74 objectName serialize ?format?
76______________________________________________________________________________
78
80 This package provides a class to contain and programmatically manipu‐
81 late tables of contents.
82 This is one of the three public pillars the management of tables of
84 contents resides on. The other two pillars are
85 [1] Exporting tables of contents, and
87 [2] Importing tables of contents
89 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
99 [1] A table of contents consists of a (possibly empty) list of ele‐
100 ments.
101 [2] Each element in the list is identified by its label.
103 [3] Each element is either a reference, or a division.
105 [4] Each reference has an associated document, identified by a sym‐
107 bolic id, and a textual description.
108 [5] Each division may have an associated document, identified by a
110 symbolic id.
111 [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 A few notes
117 [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 [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
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 OBJECT COMMAND
138 All objects created by the ::doctools::toc 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 + 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 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 The result of the method is the handle (id) of the new element.
164 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 As a division element it is can refer to a document, identified
174 by the symbolic docid, but may choose not to.
175 The result of the method is the handle (id) of the new element.
177 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 The result of the method is the empty string.
186 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 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 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 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 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 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 objectName type id
221 This method returns the type of the element, either reference,
222 or division.
223 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 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 If the label is changed the new label has to be unique within
236 the containing division, or an error is thrown.
237 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 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 The element this method operates on has to be a reference ele‐
251 ment, or an error will be thrown.
252 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 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 objectName title
266 Returns the currently defined title of the table of contents.
267 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 objectName label
273 Returns the currently defined label of the table of contents.
274 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 objectName importer
280 Returns the import manager object currently attached to the con‐
281 tainer, if any.
282 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 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 objectName exporter
295 Returns the export manager object currently attached to the con‐
296 tainer, if any.
297 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 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 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 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 The result of the method is the empty string.
322 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 The result of the method is the empty string.
331 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 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
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 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 regular serialization
352 [1] The serialization of any table of contents is a nested
354 Tcl dictionary.
355 [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 [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 title The value is a string containing the title of the
365 table of contents.
366 label The value is a string containing a label for the
368 table of contents.
369 items The value is a Tcl list holding the elements of
371 the table, in the order they are to be shown.
372 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 The two legal item types and their descriptions
380 are
381 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 id The value is a string containing the
393 id of the document associated with
394 the entry.
395 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 desc The value is a string containing a
404 longer description for this entry.
405 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 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 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 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 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 [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
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 When proposing code changes, please provide unified diffs, i.e the out‐
458 put of diff -u.
459 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
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
471 Documentation tools
472
474 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
475tcllib 2 doctools::toc(n)