1doctools::idx::export::html(n)Documentation toolsdoctools::idx::export::html(n)
2______________________________________________________________________________
6
8 doctools::idx::export::html - HTML export plugin
9
11 package require Tcl 8.4
12 package require doctools::idx::export::html ?0.2?
14 package require doctools::text
16 package require doctools::html
18 package require doctools::html::cssdefaults
20 export serial configuration
22______________________________________________________________________________
24
26 This package implements the doctools keyword index export plugin for
27 the generation of HTML markup.
28 This is an internal package of doctools, for use by the higher level
30 management packages handling keyword indices, especially doc‐
31 tools::idx::export, the export manager.
32 Using it from a regular interpreter is possible, however only with con‐
34 tortions, and is not recommended. The proper way to use this function‐
35 ality is through the package doctools::idx::export and the export man‐
36 ager objects it provides.
37
39 The API provided by this package satisfies the specification of the
40 docidx export plugin API version 2.
41 export serial configuration
43 This command takes the canonical serialization of a keyword
44 index, as specified in section Keyword index serialization for‐
45 mat, and contained in serial, the configuration, a dictionary,
46 and generates HTML markup encoding the index. The created
47 string is then returned as the result of the command.
48
50 The html export plugin recognizes the following configuration variables
51 and changes its behaviour as they specify.
52 string user
54 This standard configuration variable contains the name of the
55 user running the process which invoked the export plugin. The
56 plugin puts this information into the provenance comment at the
57 beginning of the generated document.
58 string file
60 This standard configuration variable contains the name of the
61 file the index came from. This variable may not be set or con‐
62 tain the empty string. The plugin puts this information, if
63 defined, i.e. set and not the empty string, into the provenance
64 comment at the beginning of the generated document.
65 dictionary map
67 This standard configuration variable contains a dictionary map‐
68 ping from the symbolic files names in manpage references to the
69 actual filenames and/or urls to be used in the output.
70 Url references and symbolic file names without a mapping are
72 used unchanged.
73 boolean newlines
75 If this flag is set the plugin will break the generated html
76 code across lines, with each markup command on a separate line.
77 If this flag is not set (the default), the whole document will
79 be written on a single line, with minimum spacing between all
80 elements.
81 boolean indented
83 If this flag is set the plugin will indent the markup commands
84 according to the structure of indices. To make this work this
85 also implies that newlines is set.
86 If this flag is not set (the default), the output is formatted
88 as per the value of newlines, and no indenting is done.
89 string meta
91 This variable is meant to hold a fragment of HTML (default:
92 empty). The fragment it contains will be inserted into the gen‐
93 erated output in the <head> section of the document, just after
94 the <title> tag.
95 string header
97 This variable is meant to hold a fragment of HTML (default:
98 empty). The fragment it contains will be inserted into the gen‐
99 erated output just after the <h1> title tag in the body of the
100 document, in the class.header <div>'ision.
101 string footer
103 This variable is meant to hold a fragment of HTML (default:
104 empty). The fragment it contains will be inserted into the gen‐
105 erated output just before the </body> tag, in the class.footer
106 <div>'ision.
107 dictionary kwid
109 The value of this variable (default: empty) maps keywords to the
110 identifiers to use as their anchor names. Each keyword FOO not
111 found in the dictionary uses KW-FOO as anchor, i.e. itself pre‐
112 fixed with the string KW-.
113 string sepline
115 The value of this variable is the string to use for the separa‐
116 tor comments inserted into the output when the outpout is broken
117 across lines and/or indented. The default string consists of 60
118 dashes.
119 integer kwidth
121 This variable holds the size of the keyword column in the main
122 table generated by the plugin, in percent of the total width of
123 the table. This is an integer number in the range of 1 to 99.
124 Choosing a value outside of that range causes the generator to
125 switch back to the defauly setting, 35 percent.
126 string dot
128 This variable contains a HTML fragment inserted between the
129 entries of the navigation bar, and the references associated
130 with each keyword. The default is the HTML entity · i.e.
131 the bullet character, also known as the "Greek middle dot", i.e.
132 the unicode character 00B7.
133 string class.main
135 This variable contains the class name for the main <div>'ivision
136 of the generated document. The default is doctools.
137 string class.header
139 This variable contains the class name for the header <div>'ision
140 of the generated document. The default is idx-header. This
141 division contains the document title, the user specified header,
142 if any, a visible separator line, and the navigation bar for
143 quick access to each keyword section.
144 string class.title
146 This variable contains the class name for the <h1> tag enclosing
147 the document title. The default is idx-title.
148 string class.navsep
150 This variable contains the class name for the <hr> separators in
151 the header and footer sections of the generated document. The
152 default is idx-navsep.
153 string class.navbar
155 This variable contains the class name for the navigation
156 <div>'ision enclosing the navigation bar of the generated docu‐
157 ment. The default is idx-kwnav.
158 string class.contents
160 This variable contains the class name for the <table> holding
161 the keywords and their references in the generated document. The
162 default is idx-contents.
163 string class.leader
165 This variable contains the class name for the anchor names the
166 plugin inserts into the keyword table when switching from one
167 section to the next (Each section holds all keywords with a par‐
168 ticular first character). The default is idx-leader.
169 string class.row0
171 This variable contains the class name used to label the even
172 rows (<tr>) of the keyword table. The default is idx-even.
173 string class.row1
175 This variable contains the class name used to label the odd rows
176 (<tr>) of the keyword table. The default is idx-odd.
177 string class.keyword
179 This variable contains the class name used to label the keyword
180 cells/column (<td>) in the keyword table of the document. The
181 default is idx-keyword.
182 string class.refs
184 This variable contains the class name used to label the refer‐
185 ence cells/column (<td>) in the keyword table of the document.
186 The default is idx-refs.
187 string class.footer
189 This variable contains the class name for the footer <div>'ision
190 of the generated document. The default is idx-footer. This divi‐
191 sion contains a browser-visible separator line and the user
192 specified footer, if any.
193 Note that this plugin ignores the standard configuration variable for‐
195 mat, and its value.
196
198 Here we specify the format used by the doctools v2 packages to serial‐
199 ize keyword indices as immutable values for transport, comparison, etc.
200 We distinguish between regular and canonical serializations. While a
202 keyword index may have more than one regular serialization only exactly
203 one of them will be canonical.
204 regular serialization
206 [1] An index serialization is a nested Tcl dictionary.
208 [2] This dictionary holds a single key, doctools::idx, and
210 its value. This value holds the contents of the index.
211 [3] The contents of the index are a Tcl dictionary holding
213 the title of the index, a label, and the keywords and
214 references. The relevant keys and their values are
215 title The value is a string containing the title of the
217 index.
218 label The value is a string containing a label for the
220 index.
221 keywords
223 The value is a Tcl dictionary, using the keywords
224 known to the index as keys. The associated values
225 are lists containing the identifiers of the refer‐
226 ences associated with that particular keyword.
227 Any reference identifier used in these lists has
229 to exist as a key in the references dictionary,
230 see the next item for its definition.
231 references
233 The value is a Tcl dictionary, using the identi‐
234 fiers for the references known to the index as
235 keys. The associated values are 2-element lists
236 containing the type and label of the reference, in
237 this order.
238 Any key here has to be associated with at least
240 one keyword, i.e. occur in at least one of the
241 reference lists which are the values in the key‐
242 words dictionary, see previous item for its defi‐
243 nition.
244 [4] The type of a reference can be one of two values,
246 manpage
248 The identifier of the reference is interpreted as
249 symbolic file name, referring to one of the docu‐
250 ments the index was made for.
251 url The identifier of the reference is interpreted as
253 an url, referring to some external location, like
254 a website, etc.
255 canonical serialization
257 The canonical serialization of a keyword index has the format as
258 specified in the previous item, and then additionally satisfies
259 the constraints below, which make it unique among all the possi‐
260 ble serializations of the keyword index.
261 [1] The keys found in all the nested Tcl dictionaries are
263 sorted in ascending dictionary order, as generated by
264 Tcl's builtin command lsort -increasing -dict.
265 [2] The references listed for each keyword of the index, if
267 any, are listed in ascending dictionary order of their
268 labels, as generated by Tcl's builtin command lsort
269 -increasing -dict.
270
272 This document, and the package it describes, will undoubtedly contain
273 bugs and other problems. Please report such in the category doctools
274 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
275 also report any ideas for enhancements you may have for either package
276 and/or documentation.
277 When proposing code changes, please provide unified diffs, i.e the out‐
279 put of diff -u.
280 Note further that attachments are strongly preferred over inlined
282 patches. Attachments can be made by going to the Edit form of the
283 ticket immediately after its creation, and then using the left-most
284 button in the secondary navigation bar.
285
287 HTML, doctools, export, index, serialization
288
290 Text formatter plugin
291
293 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
294tcllib 0.2 doctools::idx::export::html(n)