1doctools::toc::structure(n) Documentation tools doctools::toc::structure(n)
2______________________________________________________________________________
6
8 doctools::toc::structure - Doctoc serialization utilities
9
11 package require doctools::toc::structure ?0.1?
12 package require Tcl 8.4
14 package require logger
16 package require snit
18 ::doctools::toc::structure verify serial ?canonvar?
20 ::doctools::toc::structure verify-as-canonical serial
22 ::doctools::toc::structure canonicalize serial
24 ::doctools::toc::structure print serial
26 ::doctools::toc::structure merge seriala serialb
28______________________________________________________________________________
30
32 This package provides commands to work with the serializations of
33 tables of contents as managed by the doctools system v2, and specified
34 in section ToC serialization format.
35 This is an internal package of doctools, for use by the higher level
37 packages handling tables of contents and their conversion into and out
38 of various other formats, like documents written using doctoc markup.
39
41 ::doctools::toc::structure verify serial ?canonvar?
42 This command verifies that the content of serial is a valid reg‐
43 ular serialization of a table of contents and will throw an
44 error if that is not the case. The result of the command is the
45 empty string.
46 If the argument canonvar is specified it is interpreted as the
48 name of a variable in the calling context. This variable will be
49 written to if and only if serial is a valid regular serializa‐
50 tion. Its value will be a boolean, with True indicating that the
51 serialization is not only valid, but also canonical. False will
52 be written for a valid, but non-canonical serialization.
53 For the specification of regular and canonical serializations
55 see the section ToC serialization format.
56 ::doctools::toc::structure verify-as-canonical serial
58 This command verifies that the content of serial is a valid
59 canonical serialization of a table of contents and will throw an
60 error if that is not the case. The result of the command is the
61 empty string.
62 For the specification of canonical serializations see the sec‐
64 tion ToC serialization format.
65 ::doctools::toc::structure canonicalize serial
67 This command assumes that the content of serial is a valid regu‐
68 lar serialization of a table of contents and will throw an error
69 if that is not the case.
70 It will then convert the input into the canonical serialization
72 of the contained table of contents and return it as its result.
73 If the input is already canonical it will be returned unchanged.
74 For the specification of regular and canonical serializations
76 see the section ToC serialization format.
77 ::doctools::toc::structure print serial
79 This command assumes that the argument serial contains a valid
80 regular serialization of a table of contents and returns a
81 string containing that table in a human readable form.
82 The exact format of this form is not specified and cannot be
84 relied on for parsing or other machine-based activities.
85 For the specification of regular serializations see the section
87 ToC serialization format.
88 ::doctools::toc::structure merge seriala serialb
90 This command accepts the regular serializations of two tables of
91 contents and uses them to create their union. The result of the
92 command is the canonical serialization of this unified table of
93 contents.
94 Title and label of the resulting table are taken from the table
96 contained in serialb.
97 The whole table and its divisions are merged recursively in the
99 same manner:
100 [1] All reference elements which occur in both divisions
102 (identified by their label) are unified with document
103 id's and descriptions taken from the second table.
104 [2] All division elements which occur in both divisions
106 (identified by their label) are unified with the optional
107 document id taken from the second table, if any, or from
108 the first if none is in the second. The elements in the
109 division are merged recursively using the same algorithm
110 as described in this list.
111 [3] Type conflicts between elements, i.e. finding two ele‐
113 ments with the same label but different types result in a
114 merge error.
115 [4] All elements found in the second division but not in the
117 first are added to the end of the list of elements in the
118 merge result.
119 For the specification of regular and canonical serializations see the
121 section ToC serialization format.
122
124 Here we specify the format used by the doctools v2 packages to serial‐
125 ize tables of contents as immutable values for transport, comparison,
126 etc.
127 We distinguish between regular and canonical serializations. While a
129 table of contents may have more than one regular serialization only
130 exactly one of them will be canonical.
131 regular serialization
133 [1] The serialization of any table of contents is a nested
135 Tcl dictionary.
136 [2] This dictionary holds a single key, doctools::toc, and
138 its value. This value holds the contents of the table of
139 contents.
140 [3] The contents of the table of contents are a Tcl dictio‐
142 nary holding the title of the table of contents, a label,
143 and its elements. The relevant keys and their values are
144 title The value is a string containing the title of the
146 table of contents.
147 label The value is a string containing a label for the
149 table of contents.
150 items The value is a Tcl list holding the elements of
152 the table, in the order they are to be shown.
153 Each element is a Tcl list holding the type of the
155 item, and its description, in this order. An
156 alternative description would be that it is a Tcl
157 dictionary holding a single key, the item type,
158 mapped to the item description.
159 The two legal item types and their descriptions
161 are
162 reference
164 This item describes a single entry in the
165 table of contents, referencing a single
166 document. To this end its value is a Tcl
167 dictionary containing an id for the refer‐
168 enced document, a label, and a longer tex‐
169 tual description which can be associated
170 with the entry. The relevant keys and
171 their values are
172 id The value is a string containing the
174 id of the document associated with
175 the entry.
176 label The value is a string containing a
178 label for this entry. This string
179 also identifies the entry, and no
180 two entries (references and divi‐
181 sions) in the containing list are
182 allowed to have the same label.
183 desc The value is a string containing a
185 longer description for this entry.
186 division
188 This item describes a group of entries in
189 the table of contents, inducing a hierarchy
190 of entries. To this end its value is a Tcl
191 dictionary containing a label for the
192 group, an optional id to a document for the
193 whole group, and the list of entries in the
194 group. The relevant keys and their values
195 are
196 id The value is a string containing the
198 id of the document associated with
199 the whole group. This key is
200 optional.
201 label The value is a string containing a
203 label for the group. This string
204 also identifies the entry, and no
205 two entries (references and divi‐
206 sions) in the containing list are
207 allowed to have the same label.
208 items The value is a Tcl list holding the
210 elements of the group, in the order
211 they are to be shown. This list has
212 the same structure as the value for
213 the keyword items used to describe
214 the whole table of contents, see
215 above. This closes the recusrive
216 definition of the structure, with
217 divisions holding the same type of
218 elements as the whole table of con‐
219 tents, including other divisions.
220 canonical serialization
222 The canonical serialization of a table of contents has the for‐
223 mat as specified in the previous item, and then additionally
224 satisfies the constraints below, which make it unique among all
225 the possible serializations of this table of contents.
226 [1] The keys found in all the nested Tcl dictionaries are
228 sorted in ascending dictionary order, as generated by
229 Tcl's builtin command lsort -increasing -dict.
230
232 This document, and the package it describes, will undoubtedly contain
233 bugs and other problems. Please report such in the category doctools
234 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
235 also report any ideas for enhancements you may have for either package
236 and/or documentation.
237 When proposing code changes, please provide unified diffs, i.e the out‐
239 put of diff -u.
240 Note further that attachments are strongly preferred over inlined
242 patches. Attachments can be made by going to the Edit form of the
243 ticket immediately after its creation, and then using the left-most
244 button in the secondary navigation bar.
245
247 deserialization, doctoc, doctools, serialization
248
250 Documentation tools
251
253 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
254tcllib 0.1 doctools::toc::structure(n)