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

NAME

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

SYNOPSIS

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

DESCRIPTION

24       This  package  implements  the doctools keyword index import plugin for
25       the parsing of JSON markup.
26
27       This is an internal package of doctools, for use by  the  higher  level
28       management   packages   handling   keyword   indices,  especially  doc‐
29       tools::idx::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::idx::import and the import  man‐
34       ager objects it provides.
35

API

37       The API provided by this package satisfies the specification of the do‐
38       cidx import plugin API version 2.
39
40       import string configuration
41              This command takes the string and parses it as JSON  markup  en‐
42              coding a keyword index, in the context of the specified configu‐
43              ration (a dictionary). The result of the command is the  canoni‐
44              cal  serialization  of that keyword index, in the form specified
45              in section Keyword index serialization format.
46

JSON NOTATION OF KEYWORD INDICES

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

KEYWORD INDEX SERIALIZATION FORMAT

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

BUGS, IDEAS, FEEDBACK

173       This document, and the package it describes, will  undoubtedly  contain
174       bugs  and  other problems.  Please report such in the category doctools
175       of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].   Please
176       also  report any ideas for enhancements you may have for either package
177       and/or documentation.
178
179       When proposing code changes, please provide unified diffs, i.e the out‐
180       put of diff -u.
181
182       Note  further  that  attachments  are  strongly  preferred over inlined
183       patches. Attachments can be made by going  to  the  Edit  form  of  the
184       ticket  immediately  after  its  creation, and then using the left-most
185       button in the secondary navigation bar.
186

KEYWORDS

188       JSON, deserialization, doctools, import, index
189

CATEGORY

191       Text formatter plugin
192
194       Copyright (c) 2009-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
195
196
197
198
199tcllib                               0.2.1      doctools::idx::import::json(n)
Impressum