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

NAME

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

SYNOPSIS

11       package require Tcl  8.4
12
13       package require doctools::toc::import::json  ?0.1?
14
15       package require doctools::toc::structure
16
17       package require json
18
19       import string configuration
20
21______________________________________________________________________________
22

DESCRIPTION

24       This  package  implements  the doctools table of contents import plugin
25       for the parsing of JSON markup.
26
27       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
31       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

API

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

JSON NOTATION OF TABLES OF CONTENTS

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
52
53              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
81       is equivalent to the JSON string
82
83
84              {
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
116

TOC SERIALIZATION FORMAT

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
122       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
126       regular serialization
127
128              [1]    The serialization of any table of contents  is  a  nested
129                     Tcl dictionary.
130
131              [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
135              [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
139                     title  The  value is a string containing the title of the
140                            table of contents.
141
142                     label  The value is a string containing a label  for  the
143                            table of contents.
144
145                     items  The  value  is  a Tcl list holding the elements of
146                            the table, in the order they are to be shown.
147
148                            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
154                            The two legal item types  and  their  descriptions
155                            are
156
157                            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
167                                   id     The value is a string containing the
168                                          id  of  the document associated with
169                                          the entry.
170
171                                   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
178                                   desc   The  value  is a string containing a
179                                          longer description for this entry.
180
181                            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
191                                   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
196                                   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
203                                   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
215       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
221              [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

BUGS, IDEAS, FEEDBACK

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
232       When proposing code changes, please provide unified diffs, i.e the out‐
233       put of diff -u.
234
235       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

KEYWORDS

241       JSON, deserialization, doctools, import, table of contents, toc
242

CATEGORY

244       Text formatter plugin
245
247       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
248
249
250
251
252tcllib                                0.1       doctools::toc::import::json(n)
Impressum