1doctools::toc::export::json(n)Documentation toolsdoctools::toc::export::json(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       doctools::toc::export::json - JSON export plugin
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require doctools::toc::export::json  ?0.1?
14
15       package require textutil::adjust
16
17       export serial configuration
18
19______________________________________________________________________________
20

DESCRIPTION

22       This  package  implements  the doctools table of contents export plugin
23       for the generation of JSON markup.
24
25       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
29       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

API

35       The  API  provided  by  this package satisfies the specification of the
36       doctoc export plugin API version 2.
37
38       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

JSON NOTATION OF TABLES OF CONTENTS

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
50
51              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
79       is equivalent to the JSON string
80
81
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                      },{
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
114

CONFIGURATION

116       The JSON export plugin recognizes the following configuration variables
117       and changes its behaviour as they specify.
118
119       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
124              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
128       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
134              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
138       Note that this plugin  ignores  the  standard  configuration  variables
139       user, format, file, and map and their values.
140

TOC SERIALIZATION FORMAT

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
146       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
150       regular serialization
151
152              [1]    The  serialization  of  any table of contents is a nested
153                     Tcl dictionary.
154
155              [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
159              [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
163                     title  The value is a string containing the title of  the
164                            table of contents.
165
166                     label  The  value  is a string containing a label for the
167                            table of contents.
168
169                     items  The value is a Tcl list holding  the  elements  of
170                            the table, in the order they are to be shown.
171
172                            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
178                            The  two  legal  item types and their descriptions
179                            are
180
181                            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
191                                   id     The value is a string containing the
192                                          id of the document  associated  with
193                                          the entry.
194
195                                   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
202                                   desc   The value is a string  containing  a
203                                          longer description for this entry.
204
205                            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
215                                   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
220                                   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
227                                   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
239       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
245              [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

BUGS, IDEAS, FEEDBACK

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
256       When proposing code changes, please provide unified diffs, i.e the out‐
257       put of diff -u.
258
259       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

KEYWORDS

265       JSON, doctools, export, serialization, table of contents, toc
266

CATEGORY

268       Text formatter plugin
269
271       Copyright (c) 2009-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
272
273
274
275
276tcllib                                0.1       doctools::toc::export::json(n)
Impressum