1doctools::toc::import::json(n)Documentation toolsdoctools::toc::import::json(n)
2______________________________________________________________________________
6
8 doctools::toc::import::json - JSON import plugin
9
11 package require Tcl 8.4
12 package require doctools::toc::import::json ?0.1?
14 package require doctools::toc::structure
16 package require json
18 import string configuration
20______________________________________________________________________________
22
24 This package implements the doctools table of contents import plugin
25 for the parsing of JSON markup.
26 This is an internal package of doctools, for use by the higher level
28 management packages handling tables of contents, especially doc‐
29 tools::toc::import, the import manager.
30 Using it from a regular interpreter is possible, however only with con‐
32 tortions, and is not recommended. The proper way to use this function‐
33 ality is through the package doctools::toc::import and the import man‐
34 ager objects it provides.
35
37 The API provided by this package satisfies the specification of the
38 doctoc import plugin API version 2.
39 import string configuration
41 This command takes the string and parses it as JSON markup
42 encoding a table of contents, in the context of the specified
43 configuration (a dictionary). The result of the command is the
44 canonical serialization of that table of contents, in the form
45 specified in section ToC serialization format.
46
48 The JSON format used for tables of contents is a direct translation of
49 the ToC serialization format, mapping Tcl dictionaries as JSON objects
50 and Tcl lists as JSON arrays. For example, the Tcl serialization
51 doctools::toc {
54 items {
55 {reference {
56 desc {DocTools - Tables of Contents}
57 id introduction.man
58 label doctools::toc::introduction
59 }}
60 {division {
61 id processing.man
62 items {
63 {reference {
64 desc {doctoc serialization utilities}
65 id structure.man
66 label doctools::toc::structure
67 }}
68 {reference {
69 desc {Parsing text in doctoc format}
70 id parse.man
71 label doctools::toc::parse
72 }}
73 }
74 label Processing
75 }}
76 }
77 label {Table of Contents}
78 title TOC
79 }
80 is equivalent to the JSON string
82 {
85 "doctools::toc" : {
86 "items" : [{
87 "reference" : {
88 "desc" : "DocTools - Tables of Contents",
89 "id" : "introduction.man",
90 "label" : "doctools::toc::introduction"
91 }
92 },{
93 "division" : {
94 "id" : "processing.man",
95 "items" : [{
96 "reference" : {
97 "desc" : "doctoc serialization utilities",
98 "id" : "structure.man",
99 "label" : "doctools::toc::structure"
100 }
101 },{
102 "reference" : {
103 "desc" : "Parsing text in doctoc format",
104 "id" : "parse.man",
105 "label" : "doctools::toc::parse"
106 }
107 }],
108 "label" : "Processing"
109 }
110 }],
111 "label" : "Table of Contents",
112 "title" : "TOC"
113 }
114 }
115
118 Here we specify the format used by the doctools v2 packages to serial‐
119 ize tables of contents as immutable values for transport, comparison,
120 etc.
121 We distinguish between regular and canonical serializations. While a
123 table of contents may have more than one regular serialization only
124 exactly one of them will be canonical.
125 regular serialization
127 [1] The serialization of any table of contents is a nested
129 Tcl dictionary.
130 [2] This dictionary holds a single key, doctools::toc, and
132 its value. This value holds the contents of the table of
133 contents.
134 [3] The contents of the table of contents are a Tcl dictio‐
136 nary holding the title of the table of contents, a label,
137 and its elements. The relevant keys and their values are
138 title The value is a string containing the title of the
140 table of contents.
141 label The value is a string containing a label for the
143 table of contents.
144 items The value is a Tcl list holding the elements of
146 the table, in the order they are to be shown.
147 Each element is a Tcl list holding the type of the
149 item, and its description, in this order. An
150 alternative description would be that it is a Tcl
151 dictionary holding a single key, the item type,
152 mapped to the item description.
153 The two legal item types and their descriptions
155 are
156 reference
158 This item describes a single entry in the
159 table of contents, referencing a single
160 document. To this end its value is a Tcl
161 dictionary containing an id for the refer‐
162 enced document, a label, and a longer tex‐
163 tual description which can be associated
164 with the entry. The relevant keys and
165 their values are
166 id The value is a string containing the
168 id of the document associated with
169 the entry.
170 label The value is a string containing a
172 label for this entry. This string
173 also identifies the entry, and no
174 two entries (references and divi‐
175 sions) in the containing list are
176 allowed to have the same label.
177 desc The value is a string containing a
179 longer description for this entry.
180 division
182 This item describes a group of entries in
183 the table of contents, inducing a hierarchy
184 of entries. To this end its value is a Tcl
185 dictionary containing a label for the
186 group, an optional id to a document for the
187 whole group, and the list of entries in the
188 group. The relevant keys and their values
189 are
190 id The value is a string containing the
192 id of the document associated with
193 the whole group. This key is
194 optional.
195 label The value is a string containing a
197 label for the group. This string
198 also identifies the entry, and no
199 two entries (references and divi‐
200 sions) in the containing list are
201 allowed to have the same label.
202 items The value is a Tcl list holding the
204 elements of the group, in the order
205 they are to be shown. This list has
206 the same structure as the value for
207 the keyword items used to describe
208 the whole table of contents, see
209 above. This closes the recusrive
210 definition of the structure, with
211 divisions holding the same type of
212 elements as the whole table of con‐
213 tents, including other divisions.
214 canonical serialization
216 The canonical serialization of a table of contents has the for‐
217 mat as specified in the previous item, and then additionally
218 satisfies the constraints below, which make it unique among all
219 the possible serializations of this table of contents.
220 [1] The keys found in all the nested Tcl dictionaries are
222 sorted in ascending dictionary order, as generated by
223 Tcl's builtin command lsort -increasing -dict.
224
226 This document, and the package it describes, will undoubtedly contain
227 bugs and other problems. Please report such in the category doctools
228 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
229 also report any ideas for enhancements you may have for either package
230 and/or documentation.
231 When proposing code changes, please provide unified diffs, i.e the out‐
233 put of diff -u.
234 Note further that attachments are strongly preferred over inlined
236 patches. Attachments can be made by going to the Edit form of the
237 ticket immediately after its creation, and then using the left-most
238 button in the secondary navigation bar.
239
241 JSON, deserialization, doctools, import, table of contents, toc
242
244 Text formatter plugin
245
247 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
248tcllib 0.1 doctools::toc::import::json(n)