1doctools::idx::import::docidx(nD)ocumentation toodlosctools::idx::import::docidx(n)
2______________________________________________________________________________
6
8 doctools::idx::import::docidx - docidx import plugin
9
11 package require Tcl 8.4
12 package require doctools::idx::import::docidx ?0.1?
14 package require doctools::idx::parse
16 package require doctools::idx::structure
18 package require doctools::msgcat
20 package require doctools::tcl::parse
22 package require fileutil
24 package require logger
26 package require snit
28 package require struct::list
30 package require struct::set
32 package require struct::stack
34 package require struct::tree
36 package require treeql
38 import string configuration
40______________________________________________________________________________
42
44 This package implements the doctools keyword index import plugin for
45 the parsing of docidx markup.
46 This is an internal package of doctools, for use by the higher level
48 management packages handling keyword indices, especially doc‐
49 tools::idx::import, the import manager.
50 Using it from a regular interpreter is possible, however only with con‐
52 tortions, and is not recommended. The proper way to use this function‐
53 ality is through the package doctools::idx::import and the import man‐
54 ager objects it provides.
55
57 The API provided by this package satisfies the specification of the
58 docidx import plugin API version 2.
59 import string configuration
61 This command takes the string and parses it as docidx markup
62 encoding a keyword index, in the context of the specified con‐
63 figuration (a dictionary). The result of the command is the
64 canonical serialization of that keyword index, in the form spec‐
65 ified in section Keyword index serialization format.
66
68 The docidx format for keyword indices, also called the docidx markup
69 language, is too large to be covered in single section. The interested
70 reader should start with the document
71 [1] docidx language introduction
73 and then proceed from there to the formal specifications, i.e. the doc‐
75 uments
76 [1] docidx language syntax and
78 [2] docidx language command reference.
80 to get a thorough understanding of the language.
82
84 Here we specify the format used by the doctools v2 packages to serial‐
85 ize keyword indices as immutable values for transport, comparison, etc.
86 We distinguish between regular and canonical serializations. While a
88 keyword index may have more than one regular serialization only exactly
89 one of them will be canonical.
90 regular serialization
92 [1] An index serialization is a nested Tcl dictionary.
94 [2] This dictionary holds a single key, doctools::idx, and
96 its value. This value holds the contents of the index.
97 [3] The contents of the index are a Tcl dictionary holding
99 the title of the index, a label, and the keywords and
100 references. The relevant keys and their values are
101 title The value is a string containing the title of the
103 index.
104 label The value is a string containing a label for the
106 index.
107 keywords
109 The value is a Tcl dictionary, using the keywords
110 known to the index as keys. The associated values
111 are lists containing the identifiers of the refer‐
112 ences associated with that particular keyword.
113 Any reference identifier used in these lists has
115 to exist as a key in the references dictionary,
116 see the next item for its definition.
117 references
119 The value is a Tcl dictionary, using the identi‐
120 fiers for the references known to the index as
121 keys. The associated values are 2-element lists
122 containing the type and label of the reference, in
123 this order.
124 Any key here has to be associated with at least
126 one keyword, i.e. occur in at least one of the
127 reference lists which are the values in the key‐
128 words dictionary, see previous item for its defi‐
129 nition.
130 [4] The type of a reference can be one of two values,
132 manpage
134 The identifier of the reference is interpreted as
135 symbolic file name, referring to one of the docu‐
136 ments the index was made for.
137 url The identifier of the reference is interpreted as
139 an url, referring to some external location, like
140 a website, etc.
141 canonical serialization
143 The canonical serialization of a keyword index has the format as
144 specified in the previous item, and then additionally satisfies
145 the constraints below, which make it unique among all the possi‐
146 ble serializations of the keyword index.
147 [1] The keys found in all the nested Tcl dictionaries are
149 sorted in ascending dictionary order, as generated by
150 Tcl's builtin command lsort -increasing -dict.
151 [2] The references listed for each keyword of the index, if
153 any, are listed in ascending dictionary order of their
154 labels, as generated by Tcl's builtin command lsort
155 -increasing -dict.
156
158 This document, and the package it describes, will undoubtedly contain
159 bugs and other problems. Please report such in the category doctools
160 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
161 also report any ideas for enhancements you may have for either package
162 and/or documentation.
163 When proposing code changes, please provide unified diffs, i.e the out‐
165 put of diff -u.
166 Note further that attachments are strongly preferred over inlined
168 patches. Attachments can be made by going to the Edit form of the
169 ticket immediately after its creation, and then using the left-most
170 button in the secondary navigation bar.
171
173 deserialization, docidx, doctools, import, index
174
176 Text formatter plugin
177
179 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
180tcllib 0.1 doctools::idx::import::docidx(n)