1doctools::toc::export(n) Documentation tools doctools::toc::export(n)
2______________________________________________________________________________
6
8 doctools::toc::export - Exporting tables of contents
9
11 package require doctools::toc::export ?0.2?
12 package require Tcl 8.4
14 package require doctools::config
16 package require doctools::toc::structure
18 package require snit
20 package require pluginmgr
22 ::doctools::toc::export objectName
24 objectName method ?arg arg ...?
26 objectName destroy
28 objectName export serial serial ?format?
30 objectName export object object ?format?
32 objectName config names
34 objectName config get
36 objectName config set name ?value?
38 objectName config unset pattern...
40 export serial configuration
42______________________________________________________________________________
44
46 This package provides a class to manage the plugins for the export of
47 tables of contents to other formats, i.e. their conversion to, for
48 example doctoc, HTML, etc.
49 This is one of the three public pillars the management of tables of
51 contents resides on. The other two pillars are
52 [1] Importing tables of contents, and
54 [2] Holding tables of contents
56 For information about the Concepts of tables of contents, and their
58 parts, see the same-named section. For information about the data
59 structure which is the major input to the manager objects provided by
60 this package see the section ToC serialization format.
61 The plugin system of our class is based on the package pluginmgr, and
63 configured to look for plugins using
64 [1] the environment variable DOCTOOLS_TOC_EXPORT_PLUGINS,
66 [2] the environment variable DOCTOOLS_TOC_PLUGINS,
68 [3] the environment variable DOCTOOLS_PLUGINS,
70 [4] the path "~/.doctools/toc/export/plugin"
72 [5] the path "~/.doctools/toc/plugin"
74 [6] the path "~/.doctools/plugin"
76 [7] the path "~/.doctools/toc/export/plugins"
78 [8] the path "~/.doctools/toc/plugins"
80 [9] the path "~/.doctools/plugins"
82 [10] the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOC‐
84 TOOLS\TOC\EXPORT\PLUGINS"
85 [11] the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOC‐
87 TOOLS\TOC\PLUGINS"
88 [12] the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"
90 The last three are used only when the package is run on a machine using
92 Windows(tm) operating system.
93 The whole system is delivered with six predefined export plugins,
95 namely
96 doctoc See doctoc export plugin for details.
98 html See html export plugin for details.
100 json See json export plugin for details.
102 nroff See nroff export plugin for details.
104 text See text export plugin for details.
106 wiki See wiki export plugin for details.
108 Readers wishing to write their own export plugin for some format, i.e.
110 plugin writers reading and understanding the section containing the
111 Export plugin API v2 reference is an absolute necessity, as it speci‐
112 fies the interaction between this package and its plugins in detail.
113
115 [1] A table of contents consists of a (possibly empty) list of ele‐
116 ments.
117 [2] Each element in the list is identified by its label.
119 [3] Each element is either a reference, or a division.
121 [4] Each reference has an associated document, identified by a sym‐
123 bolic id, and a textual description.
124 [5] Each division may have an associated document, identified by a
126 symbolic id.
127 [6] Each division consists consists of a (possibly empty) list of
129 elements, with each element following the rules as specified in
130 item 2 and above.
131 A few notes
133 [1] The above rules span up a tree of elements, with references as
135 the leaf nodes, and divisions as the inner nodes, and each ele‐
136 ment representing an entry in the whole table of contents.
137 [2] The identifying labels of any element E are unique within their
139 division (or toc), and the full label of any element E is the
140 list of labels for all nodes on the unique path from the root of
141 the tree to E, including E.
142
144 PACKAGE COMMANDS
145 ::doctools::toc::export objectName
146 This command creates a new export manager object with an associ‐
147 ated Tcl command whose name is objectName. This object command
148 is explained in full detail in the sections Object command and
149 Object methods. The object command will be created under the
150 current namespace if the objectName is not fully qualified, and
151 in the specified namespace otherwise.
152 OBJECT COMMAND
154 All objects created by the ::doctools::toc::export command have the
155 following general form:
156 objectName method ?arg arg ...?
158 The method method and its arg'uments determine the exact behav‐
159 ior of the command. See section Object methods for the detailed
160 specifications.
161 OBJECT METHODS
163 objectName destroy
164 This method destroys the object it is invoked for.
165 objectName export serial serial ?format?
167 This method takes the canonical serialization of a table of con‐
168 tents stored in serial and converts it to the specified format,
169 using the export plugin for the format. An error is thrown if no
170 plugin could be found for the format. The string generated by
171 the conversion process is returned as the result of this method.
172 If no format is specified the method defaults to doctoc.
174 The specification of what a canonical serialization is can be
176 found in the section ToC serialization format.
177 The plugin has to conform to the interface specified in section
179 Export plugin API v2 reference.
180 objectName export object object ?format?
182 This method is a convenient wrapper around the export serial
183 method described by the previous item. It expects that object
184 is an object command supporting a serialize method returning the
185 canonical serialization of a table of contents. It invokes that
186 method, feeds the result into export serial and returns the
187 resulting string as its own result.
188 objectName config names
190 This method returns a list containing the names of all configu‐
191 ration variables currently known to the object.
192 objectName config get
194 This method returns a dictionary containing the names and values
195 of all configuration variables currently known to the object.
196 objectName config set name ?value?
198 This method sets the configuration variable name to the speci‐
199 fied value and returns the new value of the variable.
200 If no value is specified it simply returns the current value,
202 without changing it.
203 Note that while the user can set the predefined configuration
205 variables user and format doing so will have no effect, these
206 values will be internally overridden when invoking an import
207 plugin.
208 objectName config unset pattern...
210 This method unsets all configuration variables matching the
211 specified glob patterns. If no pattern is specified it will
212 unset all currently defined configuration variables.
213
215 Plugins are what this package uses to manage the support for any output
216 format beyond the ToC serialization format. Here we specify the API the
217 objects created by this package use to interact with their plugins.
218 A plugin for this package has to follow the rules listed below:
220 [1] A plugin is a package.
222 [2] The name of a plugin package has the form doc‐
224 tools::toc::export::FOO, where FOO is the name of the format the
225 plugin will generate output for. This name is also the argument
226 to provide to the various export methods of export manager
227 objects to get a string encoding a table of contents in that
228 format.
229 [3] The plugin can expect that the package doc‐
231 tools::toc::export::plugin is present, as indicator that it was
232 invoked from a genuine plugin manager.
233 [4] A plugin has to provide one command, with the signature shown
235 below.
236 export serial configuration
238 Whenever an export manager of doctools::toc has to gener‐
239 ate output for a table of contents it will invoke this
240 command.
241 string serial
243 This argument will contain the canonical serial‐
244 ization of the table of contents for which to gen‐
245 erate the output. The specification of what a
246 canonical serialization is can be found in the
247 section ToC serialization format.
248 dictionary configuration
250 This argument will contain the current configura‐
251 tion to apply to the generation, as a dictionary
252 mapping from variable names to values.
253 The following configuration variables have a pre‐
255 defined meaning all plugins have to obey, although
256 they can ignore this information at their discre‐
257 tion. Any other other configuration variables rec‐
258 ognized by a plugin will be described in the man‐
259 page for that plugin.
260 user This variable is expected to contain the
262 name of the user owning the process invok‐
263 ing the plugin.
264 format This variable is expected to contain the
266 name of the format whose plugin is invoked.
267 file This variable, if defined by the user of
269 the table object is expected to contain the
270 name of the input file for which the plugin
271 is generating its output for.
272 map This variable, if defined by the user of
274 the table object is expected to contain a
275 dictionary mapping from symbolic document
276 ids used in the table entries to actual
277 paths (or urls). A plugin has to be able to
278 handle the possibility that a document id
279 is without entry in this mapping.
280 [5] A single usage cycle of a plugin consists of the invokations of
282 the command export. This call has to leave the plugin in a state
283 where another usage cycle can be run without problems.
284
286 Here we specify the format used by the doctools v2 packages to serial‐
287 ize tables of contents as immutable values for transport, comparison,
288 etc.
289 We distinguish between regular and canonical serializations. While a
291 table of contents may have more than one regular serialization only
292 exactly one of them will be canonical.
293 regular serialization
295 [1] The serialization of any table of contents is a nested
297 Tcl dictionary.
298 [2] This dictionary holds a single key, doctools::toc, and
300 its value. This value holds the contents of the table of
301 contents.
302 [3] The contents of the table of contents are a Tcl dictio‐
304 nary holding the title of the table of contents, a label,
305 and its elements. The relevant keys and their values are
306 title The value is a string containing the title of the
308 table of contents.
309 label The value is a string containing a label for the
311 table of contents.
312 items The value is a Tcl list holding the elements of
314 the table, in the order they are to be shown.
315 Each element is a Tcl list holding the type of the
317 item, and its description, in this order. An
318 alternative description would be that it is a Tcl
319 dictionary holding a single key, the item type,
320 mapped to the item description.
321 The two legal item types and their descriptions
323 are
324 reference
326 This item describes a single entry in the
327 table of contents, referencing a single
328 document. To this end its value is a Tcl
329 dictionary containing an id for the refer‐
330 enced document, a label, and a longer tex‐
331 tual description which can be associated
332 with the entry. The relevant keys and
333 their values are
334 id The value is a string containing the
336 id of the document associated with
337 the entry.
338 label The value is a string containing a
340 label for this entry. This string
341 also identifies the entry, and no
342 two entries (references and divi‐
343 sions) in the containing list are
344 allowed to have the same label.
345 desc The value is a string containing a
347 longer description for this entry.
348 division
350 This item describes a group of entries in
351 the table of contents, inducing a hierarchy
352 of entries. To this end its value is a Tcl
353 dictionary containing a label for the
354 group, an optional id to a document for the
355 whole group, and the list of entries in the
356 group. The relevant keys and their values
357 are
358 id The value is a string containing the
360 id of the document associated with
361 the whole group. This key is
362 optional.
363 label The value is a string containing a
365 label for the group. This string
366 also identifies the entry, and no
367 two entries (references and divi‐
368 sions) in the containing list are
369 allowed to have the same label.
370 items The value is a Tcl list holding the
372 elements of the group, in the order
373 they are to be shown. This list has
374 the same structure as the value for
375 the keyword items used to describe
376 the whole table of contents, see
377 above. This closes the recusrive
378 definition of the structure, with
379 divisions holding the same type of
380 elements as the whole table of con‐
381 tents, including other divisions.
382 canonical serialization
384 The canonical serialization of a table of contents has the for‐
385 mat as specified in the previous item, and then additionally
386 satisfies the constraints below, which make it unique among all
387 the possible serializations of this table of contents.
388 [1] The keys found in all the nested Tcl dictionaries are
390 sorted in ascending dictionary order, as generated by
391 Tcl's builtin command lsort -increasing -dict.
392
394 This document, and the package it describes, will undoubtedly contain
395 bugs and other problems. Please report such in the category doctools
396 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
397 also report any ideas for enhancements you may have for either package
398 and/or documentation.
399 When proposing code changes, please provide unified diffs, i.e the out‐
401 put of diff -u.
402 Note further that attachments are strongly preferred over inlined
404 patches. Attachments can be made by going to the Edit form of the
405 ticket immediately after its creation, and then using the left-most
406 button in the secondary navigation bar.
407
409 HTML, conversion, doctoc, documentation, export, formatting, genera‐
410 tion, json, manpage, markup, nroff, plugin, reference, table, table of
411 contents, tcler's wiki, text, url, wiki
412
414 Documentation tools
415
417 Copyright (c) 2009-2018 Andreas Kupries <andreas_kupries@users.sourceforge.net>
418tcllib 0.2 doctools::toc::export(n)