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

NAME

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

SYNOPSIS

11       package require Tcl  8.4
12
13       package require doctools::idx::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 keyword index export plugin for
23       the generation of JSON markup.
24
25       This is an internal package of doctools, for use by  the  higher  level
26       management   packages   handling   keyword   indices,  especially  doc‐
27       tools::idx::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::idx::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       docidx export plugin API version 2.
37
38       export serial configuration
39              This command takes the  canonical  serialization  of  a  keyword
40              index,  as specified in section Keyword index serialization for‐
41              mat, and contained in serial, the configuration,  a  dictionary,
42              and  generates  JSON  markup  encoding  the  index.  The created
43              string is then returned as the result of the command.
44

JSON NOTATION OF KEYWORD INDICES

46       The JSON format used for keyword indices is a direct translation of the
47       Keyword  index  serialization  format, mapping Tcl dictionaries as JSON
48       objects and Tcl lists as JSON arrays.  For example, the Tcl  serializa‐
49       tion
50
51
52              doctools::idx {
53                label {Keyword Index}
54                keywords {
55                   changelog  {changelog.man cvs.man}
56                   conversion {doctools.man docidx.man doctoc.man apps/dtplite.man mpexpand.man}
57                   cvs        cvs.man
58                }
59                references {
60                   apps/dtplite.man {manpage dtplite}
61                   changelog.man    {manpage doctools::changelog}
62                   cvs.man          {manpage doctools::cvs}
63                   docidx.man       {manpage doctools::idx}
64                   doctoc.man       {manpage doctools::toc}
65                   doctools.man     {manpage doctools}
66                   mpexpand.man     {manpage mpexpand}
67                }
68                title {}
69              }
70
71       is equivalent to the JSON string
72
73
74              {
75                  "doctools::idx" : {
76                      "label"      : "Keyword Index",
77                      "keywords"   : {
78                          "changelog"  : ["changelog.man","cvs.man"],
79                          "conversion" : ["doctools.man","docidx.man","doctoc.man","apps\/dtplite.man","mpexpand.man"],
80                          "cvs"        : ["cvs.man"],
81                      },
82                      "references" : {
83                          "apps\/dtplite.man" : ["manpage","dtplite"],
84                          "changelog.man"     : ["manpage","doctools::changelog"],
85                          "cvs.man"           : ["manpage","doctools::cvs"],
86                          "docidx.man"        : ["manpage","doctools::idx"],
87                          "doctoc.man"        : ["manpage","doctools::toc"],
88                          "doctools.man"      : ["manpage","doctools"],
89                          "mpexpand.man"      : ["manpage","mpexpand"]
90                      },
91                      "title"      : ""
92                  }
93              }
94
95

CONFIGURATION

97       The JSON export plugin recognizes the following configuration variables
98       and changes its behaviour as they specify.
99
100       boolean indented
101              If this flag is set the plugin will  break  the  generated  JSON
102              code  across  lines  and indent it according to its inner struc‐
103              ture, with each key of a dictionary on a separate line.
104
105              If this flag is not set (the default),  the  whole  JSON  object
106              will  be  written on a single line, with minimum spacing between
107              all elements.
108
109       boolean aligned
110              If this flag is set the generator ensures that  the  values  for
111              the keys in a dictionary are vertically aligned with each other,
112              for a nice table effect. To make this  work  this  also  implies
113              that indented is set.
114
115              If  this  flag is not set (the default), the output is formatted
116              as per the value of indented, without trying to align the values
117              for dictionary keys.
118
119       Note  that  this  plugin  ignores  the standard configuration variables
120       user, format, file, and map and their values.
121

KEYWORD INDEX SERIALIZATION FORMAT

123       Here we specify the format used by the doctools v2 packages to  serial‐
124       ize keyword indices as immutable values for transport, comparison, etc.
125
126       We  distinguish  between  regular and canonical serializations. While a
127       keyword index may have more than one regular serialization only exactly
128       one of them will be canonical.
129
130       regular serialization
131
132              [1]    An index serialization is a nested Tcl dictionary.
133
134              [2]    This  dictionary  holds  a single key, doctools::idx, and
135                     its value. This value holds the contents of the index.
136
137              [3]    The contents of the index are a  Tcl  dictionary  holding
138                     the  title  of  the  index, a label, and the keywords and
139                     references. The relevant keys and their values are
140
141                     title  The value is a string containing the title of  the
142                            index.
143
144                     label  The  value  is a string containing a label for the
145                            index.
146
147                     keywords
148                            The value is a Tcl dictionary, using the  keywords
149                            known  to the index as keys. The associated values
150                            are lists containing the identifiers of the refer‐
151                            ences associated with that particular keyword.
152
153                            Any  reference  identifier used in these lists has
154                            to exist as a key in  the  references  dictionary,
155                            see the next item for its definition.
156
157                     references
158                            The  value  is a Tcl dictionary, using the identi‐
159                            fiers for the references known  to  the  index  as
160                            keys.  The  associated  values are 2-element lists
161                            containing the type and label of the reference, in
162                            this order.
163
164                            Any  key  here  has to be associated with at least
165                            one keyword, i.e. occur in at  least  one  of  the
166                            reference  lists  which are the values in the key‐
167                            words dictionary, see previous item for its  defi‐
168                            nition.
169
170              [4]    The type of a reference can be one of two values,
171
172                     manpage
173                            The  identifier of the reference is interpreted as
174                            symbolic file name, referring to one of the  docu‐
175                            ments the index was made for.
176
177                     url    The  identifier of the reference is interpreted as
178                            an url, referring to some external location,  like
179                            a website, etc.
180
181       canonical serialization
182              The canonical serialization of a keyword index has the format as
183              specified in the previous item, and then additionally  satisfies
184              the constraints below, which make it unique among all the possi‐
185              ble serializations of the keyword index.
186
187              [1]    The keys found in all the  nested  Tcl  dictionaries  are
188                     sorted  in  ascending  dictionary  order, as generated by
189                     Tcl's builtin command lsort -increasing -dict.
190
191              [2]    The references listed for each keyword of the  index,  if
192                     any,  are  listed  in ascending dictionary order of their
193                     labels, as  generated  by  Tcl's  builtin  command  lsort
194                     -increasing -dict.
195

BUGS, IDEAS, FEEDBACK

197       This  document,  and the package it describes, will undoubtedly contain
198       bugs and other problems.  Please report such in the  category  doctools
199       of  the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].  Please
200       also report any ideas for enhancements you may have for either  package
201       and/or documentation.
202
203       When proposing code changes, please provide unified diffs, i.e the out‐
204       put of diff -u.
205
206       Note further that  attachments  are  strongly  preferred  over  inlined
207       patches.  Attachments  can  be  made  by  going to the Edit form of the
208       ticket immediately after its creation, and  then  using  the  left-most
209       button in the secondary navigation bar.
210

KEYWORDS

212       JSON, doctools, export, index, serialization
213

CATEGORY

215       Text formatter plugin
216
218       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
219
220
221
222
223tcllib                                0.1       doctools::idx::export::json(n)
Impressum