1doctools::toc::export::json(n)Documentation toolsdoctools::toc::export::json(n)
2______________________________________________________________________________
6
8 doctools::toc::export::json - JSON export plugin
9
11 package require Tcl 8.4
12 package require doctools::toc::export::json ?0.1?
14 package require textutil::adjust
16 export serial configuration
18______________________________________________________________________________
20
22 This package implements the doctools table of contents export plugin
23 for the generation of JSON markup.
24 This is an internal package of doctools, for use by the higher level
26 management packages handling tables of contents, especially doc‐
27 tools::toc::export, the export manager.
28 Using it from a regular interpreter is possible, however only with con‐
30 tortions, and is not recommended. The proper way to use this function‐
31 ality is through the package doctools::toc::export and the export man‐
32 ager objects it provides.
33
35 The API provided by this package satisfies the specification of the
36 doctoc export plugin API version 2.
37 export serial configuration
39 This command takes the canonical serialization of a table of
40 contents, as specified in section ToC serialization format, and
41 contained in serial, the configuration, a dictionary, and gener‐
42 ates JSON markup encoding the table. The created string is then
43 returned as the result of the command.
44
46 The JSON format used for tables of contents is a direct translation of
47 the ToC serialization format, mapping Tcl dictionaries as JSON objects
48 and Tcl lists as JSON arrays. For example, the Tcl serialization
49 doctools::toc {
52 items {
53 {reference {
54 desc {DocTools - Tables of Contents}
55 id introduction.man
56 label doctools::toc::introduction
57 }}
58 {division {
59 id processing.man
60 items {
61 {reference {
62 desc {doctoc serialization utilities}
63 id structure.man
64 label doctools::toc::structure
65 }}
66 {reference {
67 desc {Parsing text in doctoc format}
68 id parse.man
69 label doctools::toc::parse
70 }}
71 }
72 label Processing
73 }}
74 }
75 label {Table of Contents}
76 title TOC
77 }
78 is equivalent to the JSON string
80 {
83 "doctools::toc" : {
84 "items" : [{
85 "reference" : {
86 "desc" : "DocTools - Tables of Contents",
87 "id" : "introduction.man",
88 "label" : "doctools::toc::introduction"
89 }
90 },{
91 "division" : {
92 "id" : "processing.man",
93 "items" : [{
94 "reference" : {
95 "desc" : "doctoc serialization utilities",
96 "id" : "structure.man",
97 "label" : "doctools::toc::structure"
98 }
99 },{
100 "reference" : {
101 "desc" : "Parsing text in doctoc format",
102 "id" : "parse.man",
103 "label" : "doctools::toc::parse"
104 }
105 }],
106 "label" : "Processing"
107 }
108 }],
109 "label" : "Table of Contents",
110 "title" : "TOC"
111 }
112 }
113
116 The JSON export plugin recognizes the following configuration variables
117 and changes its behaviour as they specify.
118 boolean indented
120 If this flag is set the plugin will break the generated JSON
121 code across lines and indent it according to its inner struc‐
122 ture, with each key of a dictionary on a separate line.
123 If this flag is not set (the default), the whole JSON object
125 will be written on a single line, with minimum spacing between
126 all elements.
127 boolean aligned
129 If this flag is set the generator ensures that the values for
130 the keys in a dictionary are vertically aligned with each other,
131 for a nice table effect. To make this work this also implies
132 that indented is set.
133 If this flag is not set (the default), the output is formatted
135 as per the value of indented, without trying to align the values
136 for dictionary keys.
137 Note that this plugin ignores the standard configuration variables
139 user, format, file, and map and their values.
140
142 Here we specify the format used by the doctools v2 packages to serial‐
143 ize tables of contents as immutable values for transport, comparison,
144 etc.
145 We distinguish between regular and canonical serializations. While a
147 table of contents may have more than one regular serialization only ex‐
148 actly one of them will be canonical.
149 regular serialization
151 [1] The serialization of any table of contents is a nested
153 Tcl dictionary.
154 [2] This dictionary holds a single key, doctools::toc, and
156 its value. This value holds the contents of the table of
157 contents.
158 [3] The contents of the table of contents are a Tcl dictio‐
160 nary holding the title of the table of contents, a label,
161 and its elements. The relevant keys and their values are
162 title The value is a string containing the title of the
164 table of contents.
165 label The value is a string containing a label for the
167 table of contents.
168 items The value is a Tcl list holding the elements of
170 the table, in the order they are to be shown.
171 Each element is a Tcl list holding the type of the
173 item, and its description, in this order. An al‐
174 ternative description would be that it is a Tcl
175 dictionary holding a single key, the item type,
176 mapped to the item description.
177 The two legal item types and their descriptions
179 are
180 reference
182 This item describes a single entry in the
183 table of contents, referencing a single
184 document. To this end its value is a Tcl
185 dictionary containing an id for the refer‐
186 enced document, a label, and a longer tex‐
187 tual description which can be associated
188 with the entry. The relevant keys and
189 their values are
190 id The value is a string containing the
192 id of the document associated with
193 the entry.
194 label The value is a string containing a
196 label for this entry. This string
197 also identifies the entry, and no
198 two entries (references and divi‐
199 sions) in the containing list are
200 allowed to have the same label.
201 desc The value is a string containing a
203 longer description for this entry.
204 division
206 This item describes a group of entries in
207 the table of contents, inducing a hierarchy
208 of entries. To this end its value is a Tcl
209 dictionary containing a label for the
210 group, an optional id to a document for the
211 whole group, and the list of entries in the
212 group. The relevant keys and their values
213 are
214 id The value is a string containing the
216 id of the document associated with
217 the whole group. This key is op‐
218 tional.
219 label The value is a string containing a
221 label for the group. This string
222 also identifies the entry, and no
223 two entries (references and divi‐
224 sions) in the containing list are
225 allowed to have the same label.
226 items The value is a Tcl list holding the
228 elements of the group, in the order
229 they are to be shown. This list has
230 the same structure as the value for
231 the keyword items used to describe
232 the whole table of contents, see
233 above. This closes the recusrive
234 definition of the structure, with
235 divisions holding the same type of
236 elements as the whole table of con‐
237 tents, including other divisions.
238 canonical serialization
240 The canonical serialization of a table of contents has the for‐
241 mat as specified in the previous item, and then additionally
242 satisfies the constraints below, which make it unique among all
243 the possible serializations of this table of contents.
244 [1] The keys found in all the nested Tcl dictionaries are
246 sorted in ascending dictionary order, as generated by
247 Tcl's builtin command lsort -increasing -dict.
248
250 This document, and the package it describes, will undoubtedly contain
251 bugs and other problems. Please report such in the category doctools
252 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
253 also report any ideas for enhancements you may have for either package
254 and/or documentation.
255 When proposing code changes, please provide unified diffs, i.e the out‐
257 put of diff -u.
258 Note further that attachments are strongly preferred over inlined
260 patches. Attachments can be made by going to the Edit form of the
261 ticket immediately after its creation, and then using the left-most
262 button in the secondary navigation bar.
263
265 JSON, doctools, export, serialization, table of contents, toc
266
268 Text formatter plugin
269
271 Copyright (c) 2009-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
272tcllib 0.1 doctools::toc::export::json(n)