1 2[//000000001]: # (doctools::toc::export::json \- Documentation tools) 3[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') 4[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) 5[//000000004]: # (doctools::toc::export::json\(n\) 0\.1 tcllib "Documentation tools") 6 7<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a 8href="../../../toc.md">Table Of Contents</a> | <a 9href="../../../../index.md">Keyword Index</a> | <a 10href="../../../../toc0.md">Categories</a> | <a 11href="../../../../toc1.md">Modules</a> | <a 12href="../../../../toc2.md">Applications</a> ] <hr> 13 14# NAME 15 16doctools::toc::export::json \- JSON export plugin 17 18# <a name='toc'></a>Table Of Contents 19 20 - [Table Of Contents](#toc) 21 22 - [Synopsis](#synopsis) 23 24 - [Description](#section1) 25 26 - [API](#section2) 27 28 - [JSON notation of tables of contents](#section3) 29 30 - [Configuration](#section4) 31 32 - [ToC serialization format](#section5) 33 34 - [Bugs, Ideas, Feedback](#section6) 35 36 - [Keywords](#keywords) 37 38 - [Category](#category) 39 40 - [Copyright](#copyright) 41 42# <a name='synopsis'></a>SYNOPSIS 43 44package require Tcl 8\.4 45package require doctools::toc::export::json ?0\.1? 46package require textutil::adjust 47 48[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) 49 50# <a name='description'></a>DESCRIPTION 51 52This package implements the doctools table of contents export plugin for the 53generation of JSON markup\. 54 55This is an internal package of doctools, for use by the higher level management 56packages handling tables of contents, especially 57__[doctools::toc::export](toc\_export\.md)__, the export manager\. 58 59Using it from a regular interpreter is possible, however only with contortions, 60and is not recommended\. The proper way to use this functionality is through the 61package __[doctools::toc::export](toc\_export\.md)__ and the export 62manager objects it provides\. 63 64# <a name='section2'></a>API 65 66The API provided by this package satisfies the specification of the doctoc 67export plugin API version 2\. 68 69 - <a name='1'></a>__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* 70 71 This command takes the canonical serialization of a table of contents, as 72 specified in section [ToC serialization format](#section5), and 73 contained in *serial*, the *configuration*, a dictionary, and generates 74 JSON markup encoding the table\. The created string is then returned as the 75 result of the command\. 76 77# <a name='section3'></a>JSON notation of tables of contents 78 79The JSON format used for tables of contents is a direct translation of the [ToC 80serialization format](#section5), mapping Tcl dictionaries as JSON objects 81and Tcl lists as JSON arrays\. For example, the Tcl serialization 82 83 doctools::toc { 84 items { 85 {reference { 86 desc {DocTools - Tables of Contents} 87 id introduction.man 88 label doctools::toc::introduction 89 }} 90 {division { 91 id processing.man 92 items { 93 {reference { 94 desc {doctoc serialization utilities} 95 id structure.man 96 label doctools::toc::structure 97 }} 98 {reference { 99 desc {Parsing text in doctoc format} 100 id parse.man 101 label doctools::toc::parse 102 }} 103 } 104 label Processing 105 }} 106 } 107 label {Table of Contents} 108 title TOC 109 } 110 111is equivalent to the JSON string 112 113 { 114 "doctools::toc" : { 115 "items" : [{ 116 "reference" : { 117 "desc" : "DocTools - Tables of Contents", 118 "id" : "introduction.man", 119 "label" : "doctools::toc::introduction" 120 } 121 },{ 122 "division" : { 123 "id" : "processing.man", 124 "items" : [{ 125 "reference" : { 126 "desc" : "doctoc serialization utilities", 127 "id" : "structure.man", 128 "label" : "doctools::toc::structure" 129 } 130 },{ 131 "reference" : { 132 "desc" : "Parsing text in doctoc format", 133 "id" : "parse.man", 134 "label" : "doctools::toc::parse" 135 } 136 }], 137 "label" : "Processing" 138 } 139 }], 140 "label" : "Table of Contents", 141 "title" : "TOC" 142 } 143 } 144 145# <a name='section4'></a>Configuration 146 147The JSON export plugin recognizes the following configuration variables and 148changes its behaviour as they specify\. 149 150 - boolean *indented* 151 152 If this flag is set the plugin will break the generated JSON code across 153 lines and indent it according to its inner structure, with each key of a 154 dictionary on a separate line\. 155 156 If this flag is not set \(the default\), the whole JSON object will be written 157 on a single line, with minimum spacing between all elements\. 158 159 - boolean *aligned* 160 161 If this flag is set the generator ensures that the values for the keys in a 162 dictionary are vertically aligned with each other, for a nice table effect\. 163 To make this work this also implies that __indented__ is set\. 164 165 If this flag is not set \(the default\), the output is formatted as per the 166 value of __indented__, without trying to align the values for dictionary 167 keys\. 168 169*Note* that this plugin ignores the standard configuration variables 170__user__, __format__, __file__, and __map__ and their values\. 171 172# <a name='section5'></a>ToC serialization format 173 174Here we specify the format used by the doctools v2 packages to serialize tables 175of contents as immutable values for transport, comparison, etc\. 176 177We distinguish between *regular* and *canonical* serializations\. While a 178table of contents may have more than one regular serialization only exactly one 179of them will be *canonical*\. 180 181 - regular serialization 182 183 1. The serialization of any table of contents is a nested Tcl dictionary\. 184 185 1. This dictionary holds a single key, __doctools::toc__, and its 186 value\. This value holds the contents of the table of contents\. 187 188 1. The contents of the table of contents are a Tcl dictionary holding the 189 title of the table of contents, a label, and its elements\. The relevant 190 keys and their values are 191 192 * __title__ 193 194 The value is a string containing the title of the table of 195 contents\. 196 197 * __label__ 198 199 The value is a string containing a label for the table of contents\. 200 201 * __items__ 202 203 The value is a Tcl list holding the elements of the table, in the 204 order they are to be shown\. 205 206 Each element is a Tcl list holding the type of the item, and its 207 description, in this order\. An alternative description would be 208 that it is a Tcl dictionary holding a single key, the item type, 209 mapped to the item description\. 210 211 The two legal item types and their descriptions are 212 213 + __reference__ 214 215 This item describes a single entry in the table of contents, 216 referencing a single document\. To this end its value is a Tcl 217 dictionary containing an id for the referenced document, a 218 label, and a longer textual description which can be associated 219 with the entry\. The relevant keys and their values are 220 221 - __id__ 222 223 The value is a string containing the id of the document 224 associated with the entry\. 225 226 - __label__ 227 228 The value is a string containing a label for this entry\. 229 This string also identifies the entry, and no two entries 230 \(references and divisions\) in the containing list are 231 allowed to have the same label\. 232 233 - __desc__ 234 235 The value is a string containing a longer description for 236 this entry\. 237 238 + __division__ 239 240 This item describes a group of entries in the table of 241 contents, inducing a hierarchy of entries\. To this end its 242 value is a Tcl dictionary containing a label for the group, an 243 optional id to a document for the whole group, and the list of 244 entries in the group\. The relevant keys and their values are 245 246 - __id__ 247 248 The value is a string containing the id of the document 249 associated with the whole group\. This key is optional\. 250 251 - __label__ 252 253 The value is a string containing a label for the group\. 254 This string also identifies the entry, and no two entries 255 \(references and divisions\) in the containing list are 256 allowed to have the same label\. 257 258 - __items__ 259 260 The value is a Tcl list holding the elements of the group, 261 in the order they are to be shown\. This list has the same 262 structure as the value for the keyword __items__ used 263 to describe the whole table of contents, see above\. This 264 closes the recusrive definition of the structure, with 265 divisions holding the same type of elements as the whole 266 table of contents, including other divisions\. 267 268 - canonical serialization 269 270 The canonical serialization of a table of contents has the format as 271 specified in the previous item, and then additionally satisfies the 272 constraints below, which make it unique among all the possible 273 serializations of this table of contents\. 274 275 1. The keys found in all the nested Tcl dictionaries are sorted in 276 ascending dictionary order, as generated by Tcl's builtin command 277 __lsort \-increasing \-dict__\. 278 279# <a name='section6'></a>Bugs, Ideas, Feedback 280 281This document, and the package it describes, will undoubtedly contain bugs and 282other problems\. Please report such in the category *doctools* of the [Tcllib 283Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas 284for enhancements you may have for either package and/or documentation\. 285 286When proposing code changes, please provide *unified diffs*, i\.e the output of 287__diff \-u__\. 288 289Note further that *attachments* are strongly preferred over inlined patches\. 290Attachments can be made by going to the __Edit__ form of the ticket 291immediately after its creation, and then using the left\-most button in the 292secondary navigation bar\. 293 294# <a name='keywords'></a>KEYWORDS 295 296[JSON](\.\./\.\./\.\./\.\./index\.md\#json), 297[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), 298[export](\.\./\.\./\.\./\.\./index\.md\#export), 299[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), [table of 300contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), 301[toc](\.\./\.\./\.\./\.\./index\.md\#toc) 302 303# <a name='category'></a>CATEGORY 304 305Text formatter plugin 306 307# <a name='copyright'></a>COPYRIGHT 308 309Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> 310