1doctools::toc::export::html(n)Documentation toolsdoctools::toc::export::html(n)
2______________________________________________________________________________
6
8 doctools::toc::export::html - HTML export plugin
9
11 package require Tcl 8.4
12 package require doctools::toc::export::html ?0.1?
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 table of contents export plugin
27 for the generation of HTML markup.
28 This is an internal package of doctools, for use by the higher level
30 management packages handling tables of contents, especially doc‐
31 tools::toc::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::toc::export and the export man‐
36 ager objects it provides.
37
39 The API provided by this package satisfies the specification of the
40 doctoc export plugin API version 2.
41 export serial configuration
43 This command takes the canonical serialization of a table of
44 contents, as specified in section ToC serialization format, and
45 contained in serial, the configuration, a dictionary, and gener‐
46 ates HTML markup encoding the table. The created string is then
47 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 table of contents came from. This variable may not be
62 set or contain the empty string. The plugin puts this informa‐
63 tion, if defined, i.e. set and not the empty string, into the
64 provenance 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) document ids in reference entries to
69 the actual filenames and/or urls to be used in the output.
70 Document ids without a mapping are used unchanged.
72 boolean newlines
74 If this flag is set the plugin will break the generated html
75 code across lines, with each markup command on a separate line.
76 If this flag is not set (the default), the whole document will
78 be written on a single line, with minimum spacing between all
79 elements.
80 boolean indented
82 If this flag is set the plugin will indent the markup commands
83 according to the structure of indices. To make this work this
84 also implies that newlines is set.
85 If this flag is not set (the default), the output is formatted
87 as per the value of newlines, and no indenting is done.
88 string meta
90 This variable is meant to hold a fragment of HTML (default:
91 empty). The fragment it contains will be inserted into the gen‐
92 erated output in the <head> section of the document, just after
93 the <title> tag.
94 string header
96 This variable is meant to hold a fragment of HTML (default:
97 empty). The fragment it contains will be inserted into the gen‐
98 erated output just after the <h1> title tag in the body of the
99 document, in the class.header <div>'ision.
100 string footer
102 This variable is meant to hold a fragment of HTML (default:
103 empty). The fragment it contains will be inserted into the gen‐
104 erated output just before the </body> tag, in the class.footer
105 <div>'ision.
106 dictionary rid
108 The value of this variable (default: empty) maps references to
109 the identifiers to use as their anchor names. Each reference FOO
110 not found in the dictionary uses REF-FOO as anchor, i.e. itself
111 prefixed with the string REF-.
112 string sepline
114 The value of this variable is the string to use for the separa‐
115 tor comments inserted into the output when the outpout is broken
116 across lines and/or indented. The default string consists of 60
117 dashes.
118 string class.main
120 This variable contains the class name for the main <div>'ivision
121 of the generated document. The default is doctools.
122 string class.header
124 This variable contains the class name for the header <div>'ision
125 of the generated document. The default is toc-header. This
126 division contains the document title, the user specified header,
127 if any, and a visible separator line.
128 string class.title
130 This variable contains the class name for the <h1> tag enclosing
131 the document title. The default is toc-title.
132 string class.navsep
134 This variable contains the class name for the <hr> separators in
135 the header and footer sections of the generated document. The
136 default is toc-navsep.
137 string class.contents
139 This variable contains the class name for the XXXXX holding the
140 keywords and their references in the generated document. The
141 default is toc-contents.
142 string class.ref
144 This variable contains the class name for the table elements
145 which are references to other documents. The default is toc-ref.
146 string class.div
148 This variable contains the class name for the table elements
149 which are divisions. The default is toc-div.
150 string class.footer
152 This variable contains the class name for the footer <div>'ision
153 of the generated document. The default is toc-footer. This divi‐
154 sion contains a browser-visible separator line and the user
155 specified footer, if any.
156 Note that this plugin ignores the standard configuration variable for‐
158 mat, and its value.
159
161 Here we specify the format used by the doctools v2 packages to serial‐
162 ize tables of contents as immutable values for transport, comparison,
163 etc.
164 We distinguish between regular and canonical serializations. While a
166 table of contents may have more than one regular serialization only
167 exactly one of them will be canonical.
168 regular serialization
170 [1] The serialization of any table of contents is a nested
172 Tcl dictionary.
173 [2] This dictionary holds a single key, doctools::toc, and
175 its value. This value holds the contents of the table of
176 contents.
177 [3] The contents of the table of contents are a Tcl dictio‐
179 nary holding the title of the table of contents, a label,
180 and its elements. The relevant keys and their values are
181 title The value is a string containing the title of the
183 table of contents.
184 label The value is a string containing a label for the
186 table of contents.
187 items The value is a Tcl list holding the elements of
189 the table, in the order they are to be shown.
190 Each element is a Tcl list holding the type of the
192 item, and its description, in this order. An
193 alternative description would be that it is a Tcl
194 dictionary holding a single key, the item type,
195 mapped to the item description.
196 The two legal item types and their descriptions
198 are
199 reference
201 This item describes a single entry in the
202 table of contents, referencing a single
203 document. To this end its value is a Tcl
204 dictionary containing an id for the refer‐
205 enced document, a label, and a longer tex‐
206 tual description which can be associated
207 with the entry. The relevant keys and
208 their values are
209 id The value is a string containing the
211 id of the document associated with
212 the entry.
213 label The value is a string containing a
215 label for this entry. This string
216 also identifies the entry, and no
217 two entries (references and divi‐
218 sions) in the containing list are
219 allowed to have the same label.
220 desc The value is a string containing a
222 longer description for this entry.
223 division
225 This item describes a group of entries in
226 the table of contents, inducing a hierarchy
227 of entries. To this end its value is a Tcl
228 dictionary containing a label for the
229 group, an optional id to a document for the
230 whole group, and the list of entries in the
231 group. The relevant keys and their values
232 are
233 id The value is a string containing the
235 id of the document associated with
236 the whole group. This key is
237 optional.
238 label The value is a string containing a
240 label for the group. This string
241 also identifies the entry, and no
242 two entries (references and divi‐
243 sions) in the containing list are
244 allowed to have the same label.
245 items The value is a Tcl list holding the
247 elements of the group, in the order
248 they are to be shown. This list has
249 the same structure as the value for
250 the keyword items used to describe
251 the whole table of contents, see
252 above. This closes the recusrive
253 definition of the structure, with
254 divisions holding the same type of
255 elements as the whole table of con‐
256 tents, including other divisions.
257 canonical serialization
259 The canonical serialization of a table of contents has the for‐
260 mat as specified in the previous item, and then additionally
261 satisfies the constraints below, which make it unique among all
262 the possible serializations of this table of contents.
263 [1] The keys found in all the nested Tcl dictionaries are
265 sorted in ascending dictionary order, as generated by
266 Tcl's builtin command lsort -increasing -dict.
267
269 This document, and the package it describes, will undoubtedly contain
270 bugs and other problems. Please report such in the category doctools
271 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
272 also report any ideas for enhancements you may have for either package
273 and/or documentation.
274 When proposing code changes, please provide unified diffs, i.e the out‐
276 put of diff -u.
277 Note further that attachments are strongly preferred over inlined
279 patches. Attachments can be made by going to the Edit form of the
280 ticket immediately after its creation, and then using the left-most
281 button in the secondary navigation bar.
282
284 HTML, doctools, export, serialization, table of contents, toc
285
287 Text formatter plugin
288
290 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
291tcllib 0.1 doctools::toc::export::html(n)