1doctools::toc::import(n) Documentation tools doctools::toc::import(n)
2______________________________________________________________________________
6
8 doctools::toc::import - Importing keyword indices
9
11 package require doctools::toc::import ?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::import objectName
24 objectName method ?arg arg ...?
26 objectName destroy
28 objectName import text text ?format?
30 objectName import file path ?format?
32 objectName import object text object text ?format?
34 objectName import object file object path ?format?
36 objectName config names
38 objectName config get
40 objectName config set name ?value?
42 objectName config unset pattern...
44 objectName includes
46 objectName include add path
48 objectName include remove path
50 objectName include clear
52 IncludeFile currentfile path
54 import text configuration
56______________________________________________________________________________
58
60 This package provides a class to manage the plugins for the import of
61 tables of contents from other formats, i.e. their conversion from, for
62 example doctoc, json, etc.
63 This is one of the three public pillars the management of tables of
65 contents resides on. The other two pillars are
66 [1] Exporting tables of contents, and
68 [2] Holding tables of contents
70 For information about the Concepts of tables of contents, and their
72 parts, see the same-named section. For information about the data
73 structure which is the major output of the manager objects provided by
74 this package see the section ToC serialization format.
75 The plugin system of our class is based on the package pluginmgr, and
77 configured to look for plugins using
78 [1] the environment variable DOCTOOLS_TOC_IMPORT_PLUGINS,
80 [2] the environment variable DOCTOOLS_TOC_PLUGINS,
82 [3] the environment variable DOCTOOLS_PLUGINS,
84 [4] the path "~/.doctools/toc/import/plugin"
86 [5] the path "~/.doctools/toc/plugin"
88 [6] the path "~/.doctools/plugin"
90 [7] the path "~/.doctools/toc/import/plugins"
92 [8] the path "~/.doctools/toc/plugins"
94 [9] the path "~/.doctools/plugins"
96 [10] the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOC‐
98 TOOLS\TOC\IMPORT\PLUGINS"
99 [11] the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOC‐
101 TOOLS\TOC\PLUGINS"
102 [12] the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"
104 The last three are used only when the package is run on a machine using
106 Windows(tm) operating system.
107 The whole system is delivered with two predefined import plugins,
109 namely
110 doctoc See doctoc import plugin for details.
112 json See json import plugin for details.
114 Readers wishing to write their own import plugin for some format, i.e.
116 plugin writers reading and understanding the section containing the
117 Import plugin API v2 reference is an absolute necessity, as it speci‐
118 fies the interaction between this package and its plugins in detail.
119
121 [1] A table of contents consists of a (possibly empty) list of ele‐
122 ments.
123 [2] Each element in the list is identified by its label.
125 [3] Each element is either a reference, or a division.
127 [4] Each reference has an associated document, identified by a sym‐
129 bolic id, and a textual description.
130 [5] Each division may have an associated document, identified by a
132 symbolic id.
133 [6] Each division consists consists of a (possibly empty) list of
135 elements, with each element following the rules as specified in
136 item 2 and above.
137 A few notes
139 [1] The above rules span up a tree of elements, with references as
141 the leaf nodes, and divisions as the inner nodes, and each ele‐
142 ment representing an entry in the whole table of contents.
143 [2] The identifying labels of any element E are unique within their
145 division (or toc), and the full label of any element E is the
146 list of labels for all nodes on the unique path from the root of
147 the tree to E, including E.
148
150 PACKAGE COMMANDS
151 ::doctools::toc::import objectName
152 This command creates a new import manager object with an associ‐
153 ated Tcl command whose name is objectName. This object command
154 is explained in full detail in the sections Object command and
155 Object methods. The object command will be created under the
156 current namespace if the objectName is not fully qualified, and
157 in the specified namespace otherwise.
158 OBJECT COMMAND
160 All objects created by the ::doctools::toc::import command have the
161 following general form:
162 objectName method ?arg arg ...?
164 The method method and its arg'uments determine the exact behav‐
165 ior of the command. See section Object methods for the detailed
166 specifications.
167 OBJECT METHODS
169 objectName destroy
170 This method destroys the object it is invoked for.
171 objectName import text text ?format?
173 This method takes the text and converts it from the specified
174 format to the canonical serialization of a table of contents
175 using the import plugin for the format. An error is thrown if no
176 plugin could be found for the format. The serialization gener‐
177 ated by the conversion process is returned as the result of this
178 method.
179 If no format is specified the method defaults to doctoc.
181 The specification of what a canonical serialization is can be
183 found in the section ToC serialization format.
184 The plugin has to conform to the interface specified in section
186 Import plugin API v2 reference.
187 objectName import file path ?format?
189 This method is a convenient wrapper around the import text
190 method described by the previous item. It reads the contents of
191 the specified file into memory, feeds the result into import
192 text and returns the resulting serialization as its own result.
193 objectName import object text object text ?format?
195 This method is a convenient wrapper around the import text
196 method described by the previous item. It expects that object
197 is an object command supporting a deserialize method expecting
198 the canonical serialization of a table of contents. It imports
199 the text using import text and then feeds the resulting serial‐
200 ization into the object via deserialize. This method returns
201 the empty string as it result.
202 objectName import object file object path ?format?
204 This method behaves like import object text, except that it
205 reads the text to convert from the specified file instead of
206 being given it as argument.
207 objectName config names
209 This method returns a list containing the names of all configu‐
210 ration variables currently known to the object.
211 objectName config get
213 This method returns a dictionary containing the names and values
214 of all configuration variables currently known to the object.
215 objectName config set name ?value?
217 This method sets the configuration variable name to the speci‐
218 fied value and returns the new value of the variable.
219 If no value is specified it simply returns the current value,
221 without changing it.
222 Note that while the user can set the predefined configuration
224 variables user and format doing so will have no effect, these
225 values will be internally overridden when invoking an import
226 plugin.
227 objectName config unset pattern...
229 This method unsets all configuration variables matching the
230 specified glob patterns. If no pattern is specified it will
231 unset all currently defined configuration variables.
232 objectName includes
234 This method returns a list containing the currently specified
235 paths to use to search for include files when processing input.
236 The order of paths in the list corresponds to the order in which
237 they are used, from first to last, and also corresponds to the
238 order in which they were added to the object.
239 objectName include add path
241 This methods adds the specified path to the list of paths to use
242 to search for include files when processing input. The path is
243 added to the end of the list, causing it to be searched after
244 all previously added paths. The result of the command is the
245 empty string.
246 The method does nothing if the path is already known.
248 objectName include remove path
250 This methods removes the specified path from the list of paths
251 to use to search for include files when processing input. The
252 result of the command is the empty string.
253 The method does nothing if the path is not known.
255 objectName include clear
257 This method clears the list of paths to use to search for
258 include files when processing input. The result of the command
259 is the empty string.
260
262 Plugins are what this package uses to manage the support for any input
263 format beyond the ToC serialization format. Here we specify the API the
264 objects created by this package use to interact with their plugins.
265 A plugin for this package has to follow the rules listed below:
267 [1] A plugin is a package.
269 [2] The name of a plugin package has the form doc‐
271 tools::toc::import::FOO, where FOO is the name of the format the
272 plugin will generate output for. This name is also the argument
273 to provide to the various import methods of import manager
274 objects to get a string encoding a table of contents in that
275 format.
276 [3] The plugin can expect that the package doc‐
278 tools::toc::export::plugin is present, as indicator that it was
279 invoked from a genuine plugin manager.
280 [4] The plugin can expect that a command named IncludeFile is
282 present, with the signature
283 IncludeFile currentfile path
285 This command has to be invoked by the plugin when it has
286 to process an included file, if the format has the con‐
287 cept of such. An example of such a format would be doc‐
288 toc.
289 The plugin has to supply the following arguments
291 string currentfile
293 The path of the file it is currently processing.
294 This may be the empty string if no such is known.
295 string path
297 The path of the include file as specified in the
298 include directive being processed.
299 The result of the command will be a 5-element list con‐
301 taining
302 [1] A boolean flag indicating the success (True) or
304 failure (False) of the operation.
305 [2] In case of success the contents of the included
307 file, and the empty string otherwise.
308 [3] The resolved, i.e. absolute path of the included
310 file, if possible, or the unchanged path argument.
311 This is for display in an error message, or as the
312 currentfile argument of another call to Include‐
313 File should this file contain more files.
314 [4] In case of success an empty string, and for fail‐
316 ure a code indicating the reason for it, one of
317 notfound
319 The specified file could not be found.
320 notread
322 The specified file was found, but not be
323 read into memory.
324 [5] An empty string in case of success of a notfound
326 failure, and an additional error message describ‐
327 ing the reason for a notread error in more detail.
328 [5] A plugin has to provide one command, with the signature shown
330 below.
331 import text configuration
333 Whenever an import manager of doctools::toc has to parse
334 input for a table of contents it will invoke this com‐
335 mand.
336 string text
338 This argument will contain the text encoding the
339 table of contents per the format the plugin is
340 for.
341 dictionary configuration
343 This argument will contain the current configura‐
344 tion to apply to the parsing, as a dictionary map‐
345 ping from variable names to values.
346 The following configuration variables have a pre‐
348 defined meaning all plugins have to obey, although
349 they can ignore this information at their discre‐
350 tion. Any other other configuration variables rec‐
351 ognized by a plugin will be described in the man‐
352 page for that plugin.
353 user This variable is expected to contain the
355 name of the user owning the process invok‐
356 ing the plugin.
357 format This variable is expected to contain the
359 name of the format whose plugin is invoked.
360 [6] A single usage cycle of a plugin consists of the invokations of
362 the command import. This call has to leave the plugin in a state
363 where another usage cycle can be run without problems.
364
366 Here we specify the format used by the doctools v2 packages to serial‐
367 ize tables of contents as immutable values for transport, comparison,
368 etc.
369 We distinguish between regular and canonical serializations. While a
371 table of contents may have more than one regular serialization only
372 exactly one of them will be canonical.
373 regular serialization
375 [1] The serialization of any table of contents is a nested
377 Tcl dictionary.
378 [2] This dictionary holds a single key, doctools::toc, and
380 its value. This value holds the contents of the table of
381 contents.
382 [3] The contents of the table of contents are a Tcl dictio‐
384 nary holding the title of the table of contents, a label,
385 and its elements. The relevant keys and their values are
386 title The value is a string containing the title of the
388 table of contents.
389 label The value is a string containing a label for the
391 table of contents.
392 items The value is a Tcl list holding the elements of
394 the table, in the order they are to be shown.
395 Each element is a Tcl list holding the type of the
397 item, and its description, in this order. An
398 alternative description would be that it is a Tcl
399 dictionary holding a single key, the item type,
400 mapped to the item description.
401 The two legal item types and their descriptions
403 are
404 reference
406 This item describes a single entry in the
407 table of contents, referencing a single
408 document. To this end its value is a Tcl
409 dictionary containing an id for the refer‐
410 enced document, a label, and a longer tex‐
411 tual description which can be associated
412 with the entry. The relevant keys and
413 their values are
414 id The value is a string containing the
416 id of the document associated with
417 the entry.
418 label The value is a string containing a
420 label for this entry. This string
421 also identifies the entry, and no
422 two entries (references and divi‐
423 sions) in the containing list are
424 allowed to have the same label.
425 desc The value is a string containing a
427 longer description for this entry.
428 division
430 This item describes a group of entries in
431 the table of contents, inducing a hierarchy
432 of entries. To this end its value is a Tcl
433 dictionary containing a label for the
434 group, an optional id to a document for the
435 whole group, and the list of entries in the
436 group. The relevant keys and their values
437 are
438 id The value is a string containing the
440 id of the document associated with
441 the whole group. This key is
442 optional.
443 label The value is a string containing a
445 label for the group. This string
446 also identifies the entry, and no
447 two entries (references and divi‐
448 sions) in the containing list are
449 allowed to have the same label.
450 items The value is a Tcl list holding the
452 elements of the group, in the order
453 they are to be shown. This list has
454 the same structure as the value for
455 the keyword items used to describe
456 the whole table of contents, see
457 above. This closes the recusrive
458 definition of the structure, with
459 divisions holding the same type of
460 elements as the whole table of con‐
461 tents, including other divisions.
462 canonical serialization
464 The canonical serialization of a table of contents has the for‐
465 mat as specified in the previous item, and then additionally
466 satisfies the constraints below, which make it unique among all
467 the possible serializations of this table of contents.
468 [1] The keys found in all the nested Tcl dictionaries are
470 sorted in ascending dictionary order, as generated by
471 Tcl's builtin command lsort -increasing -dict.
472
474 This document, and the package it describes, will undoubtedly contain
475 bugs and other problems. Please report such in the category doctools
476 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
477 also report any ideas for enhancements you may have for either package
478 and/or documentation.
479 When proposing code changes, please provide unified diffs, i.e the out‐
481 put of diff -u.
482 Note further that attachments are strongly preferred over inlined
484 patches. Attachments can be made by going to the Edit form of the
485 ticket immediately after its creation, and then using the left-most
486 button in the secondary navigation bar.
487
489 conversion, doctoc, documentation, import, json, manpage, markup, pars‐
490 ing, plugin, reference, table, table of contents, url
491
493 Documentation tools
494
496 Copyright (c) 2009-2018 Andreas Kupries <andreas_kupries@users.sourceforge.net>
497tcllib 0.2 doctools::toc::import(n)