1doctools::idx::export::docidx(nD)ocumentation toodlosctools::idx::export::docidx(n)
2______________________________________________________________________________
6
8 doctools::idx::export::docidx - docidx export plugin
9
11 package require Tcl 8.4
12 package require doctools::idx::export::docidx ?0.1?
14 export serial configuration
16______________________________________________________________________________
18
20 This package implements the doctools keyword index export plugin for
21 the generation of docidx markup.
22 This is an internal package of doctools, for use by the higher level
24 management packages handling keyword indices, especially doc‐
25 tools::idx::export, the export manager.
26 Using it from a regular interpreter is possible, however only with con‐
28 tortions, and is not recommended. The proper way to use this function‐
29 ality is through the package doctools::idx::export and the export man‐
30 ager objects it provides.
31
33 The API provided by this package satisfies the specification of the
34 docidx export plugin API version 2.
35 export serial configuration
37 This command takes the canonical serialization of a keyword
38 index, as specified in section Keyword index serialization for‐
39 mat, and contained in serial, the configuration, a dictionary,
40 and generates docidx markup encoding the index. The created
41 string is then returned as the result of the command.
42
44 The docidx format for keyword indices, also called the docidx markup
45 language, is too large to be covered in single section. The interested
46 reader should start with the document
47 [1] docidx language introduction
49 and then proceed from there to the formal specifications, i.e. the doc‐
51 uments
52 [1] docidx language syntax and
54 [2] docidx language command reference.
56 to get a thorough understanding of the language.
58
60 The docidx export plugin recognizes the following configuration vari‐
61 ables and changes its behaviour as they specify.
62 string user
64 This standard configuration variable contains the name of the
65 user running the process which invoked the export plugin. The
66 plugin puts this information into the provenance comment at the
67 beginning of the generated document.
68 string file
70 This standard configuration variable contains the name of the
71 file the index came from. This variable may not be set or con‐
72 tain the empty string. The plugin puts this information, if
73 defined, i.e. set and not the empty string, into the provenance
74 comment at the beginning of the generated document.
75 boolean newlines
77 If this flag is set the plugin will break the generated docidx
78 code across lines, with each markup command on a separate line.
79 If this flag is not set (the default), the whole document will
81 be written on a single line, with minimum spacing between all
82 elements.
83 boolean indented
85 If this flag is set the plugin will indent the markup commands
86 according to the structure of indices. To make this work this
87 also implies that newlines is set. This effect is independent of
88 the value for aligned however.
89 If this flag is not set (the default), the output is formatted
91 as per the values of newlines and aligned, and no indenting is
92 done.
93 boolean aligned
95 If this flag is set the generator ensures that the arguments for
96 the manpage and url commands in a keyword section are aligned
97 vertically for a nice table effect. To make this work this also
98 implies that newlines is set. This effect is independent of the
99 value for indented however.
100 If this flag is not set (the default), the output is formatted
102 as per the values of newlines and indented, and no alignment is
103 done.
104 Note that this plugin ignores the standard configuration variables for‐
106 mat, and map, and their values.
107
109 Here we specify the format used by the doctools v2 packages to serial‐
110 ize keyword indices as immutable values for transport, comparison, etc.
111 We distinguish between regular and canonical serializations. While a
113 keyword index may have more than one regular serialization only exactly
114 one of them will be canonical.
115 regular serialization
117 [1] An index serialization is a nested Tcl dictionary.
119 [2] This dictionary holds a single key, doctools::idx, and
121 its value. This value holds the contents of the index.
122 [3] The contents of the index are a Tcl dictionary holding
124 the title of the index, a label, and the keywords and
125 references. The relevant keys and their values are
126 title The value is a string containing the title of the
128 index.
129 label The value is a string containing a label for the
131 index.
132 keywords
134 The value is a Tcl dictionary, using the keywords
135 known to the index as keys. The associated values
136 are lists containing the identifiers of the refer‐
137 ences associated with that particular keyword.
138 Any reference identifier used in these lists has
140 to exist as a key in the references dictionary,
141 see the next item for its definition.
142 references
144 The value is a Tcl dictionary, using the identi‐
145 fiers for the references known to the index as
146 keys. The associated values are 2-element lists
147 containing the type and label of the reference, in
148 this order.
149 Any key here has to be associated with at least
151 one keyword, i.e. occur in at least one of the
152 reference lists which are the values in the key‐
153 words dictionary, see previous item for its defi‐
154 nition.
155 [4] The type of a reference can be one of two values,
157 manpage
159 The identifier of the reference is interpreted as
160 symbolic file name, referring to one of the docu‐
161 ments the index was made for.
162 url The identifier of the reference is interpreted as
164 an url, referring to some external location, like
165 a website, etc.
166 canonical serialization
168 The canonical serialization of a keyword index has the format as
169 specified in the previous item, and then additionally satisfies
170 the constraints below, which make it unique among all the possi‐
171 ble serializations of the keyword index.
172 [1] The keys found in all the nested Tcl dictionaries are
174 sorted in ascending dictionary order, as generated by
175 Tcl's builtin command lsort -increasing -dict.
176 [2] The references listed for each keyword of the index, if
178 any, are listed in ascending dictionary order of their
179 labels, as generated by Tcl's builtin command lsort
180 -increasing -dict.
181
183 This document, and the package it describes, will undoubtedly contain
184 bugs and other problems. Please report such in the category doctools
185 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
186 also report any ideas for enhancements you may have for either package
187 and/or documentation.
188 When proposing code changes, please provide unified diffs, i.e the out‐
190 put of diff -u.
191 Note further that attachments are strongly preferred over inlined
193 patches. Attachments can be made by going to the Edit form of the
194 ticket immediately after its creation, and then using the left-most
195 button in the secondary navigation bar.
196
198 docidx, doctools, export, index, serialization
199
201 Text formatter plugin
202
204 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
205tcllib 0.1 doctools::idx::export::docidx(n)