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.1?
12 package require Tcl 8.4
14 package require struct::map
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\DOCTOOLS\TOC\IM‐
98 PORT\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 Im‐
117 port plugin API v2 reference is an absolute necessity, as it specifies
118 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 us‐
175 ing 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 be‐
206 ing 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 un‐
231 set 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 in‐
258 clude files when processing input. The result of the command is
259 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 doctools::toc::im‐
271 port::FOO, where FOO is the name of the format the plugin will
272 generate output for. This name is also the argument to provide
273 to the various import methods of import manager objects to get a
274 string encoding a table of contents in that format.
275 [3] The plugin can expect that the package doctools::toc::ex‐
277 port::plugin is present, as indicator that it was invoked from a
278 genuine plugin manager.
279 [4] The plugin can expect that a command named IncludeFile is
281 present, with the signature
282 IncludeFile currentfile path
284 This command has to be invoked by the plugin when it has
285 to process an included file, if the format has the con‐
286 cept of such. An example of such a format would be doc‐
287 toc.
288 The plugin has to supply the following arguments
290 string currentfile
292 The path of the file it is currently processing.
293 This may be the empty string if no such is known.
294 string path
296 The path of the include file as specified in the
297 include directive being processed.
298 The result of the command will be a 5-element list con‐
300 taining
301 [1] A boolean flag indicating the success (True) or
303 failure (False) of the operation.
304 [2] In case of success the contents of the included
306 file, and the empty string otherwise.
307 [3] The resolved, i.e. absolute path of the included
309 file, if possible, or the unchanged path argument.
310 This is for display in an error message, or as the
311 currentfile argument of another call to Include‐
312 File should this file contain more files.
313 [4] In case of success an empty string, and for fail‐
315 ure a code indicating the reason for it, one of
316 notfound
318 The specified file could not be found.
319 notread
321 The specified file was found, but not be
322 read into memory.
323 [5] An empty string in case of success of a notfound
325 failure, and an additional error message describ‐
326 ing the reason for a notread error in more detail.
327 [5] A plugin has to provide one command, with the signature shown
329 below.
330 import text configuration
332 Whenever an import manager of doctools::toc has to parse
333 input for a table of contents it will invoke this com‐
334 mand.
335 string text
337 This argument will contain the text encoding the
338 table of contents per the format the plugin is
339 for.
340 dictionary configuration
342 This argument will contain the current configura‐
343 tion to apply to the parsing, as a dictionary map‐
344 ping from variable names to values.
345 The following configuration variables have a pre‐
347 defined meaning all plugins have to obey, although
348 they can ignore this information at their discre‐
349 tion. Any other other configuration variables rec‐
350 ognized by a plugin will be described in the man‐
351 page for that plugin.
352 user This variable is expected to contain the
354 name of the user owning the process invok‐
355 ing the plugin.
356 format This variable is expected to contain the
358 name of the format whose plugin is invoked.
359 [6] A single usage cycle of a plugin consists of the invokations of
361 the command import. This call has to leave the plugin in a state
362 where another usage cycle can be run without problems.
363
365 Here we specify the format used by the doctools v2 packages to serial‐
366 ize tables of contents as immutable values for transport, comparison,
367 etc.
368 We distinguish between regular and canonical serializations. While a
370 table of contents may have more than one regular serialization only ex‐
371 actly one of them will be canonical.
372 regular serialization
374 [1] The serialization of any table of contents is a nested
376 Tcl dictionary.
377 [2] This dictionary holds a single key, doctools::toc, and
379 its value. This value holds the contents of the table of
380 contents.
381 [3] The contents of the table of contents are a Tcl dictio‐
383 nary holding the title of the table of contents, a label,
384 and its elements. The relevant keys and their values are
385 title The value is a string containing the title of the
387 table of contents.
388 label The value is a string containing a label for the
390 table of contents.
391 items The value is a Tcl list holding the elements of
393 the table, in the order they are to be shown.
394 Each element is a Tcl list holding the type of the
396 item, and its description, in this order. An al‐
397 ternative description would be that it is a Tcl
398 dictionary holding a single key, the item type,
399 mapped to the item description.
400 The two legal item types and their descriptions
402 are
403 reference
405 This item describes a single entry in the
406 table of contents, referencing a single
407 document. To this end its value is a Tcl
408 dictionary containing an id for the refer‐
409 enced document, a label, and a longer tex‐
410 tual description which can be associated
411 with the entry. The relevant keys and
412 their values are
413 id The value is a string containing the
415 id of the document associated with
416 the entry.
417 label The value is a string containing a
419 label for this entry. This string
420 also identifies the entry, and no
421 two entries (references and divi‐
422 sions) in the containing list are
423 allowed to have the same label.
424 desc The value is a string containing a
426 longer description for this entry.
427 division
429 This item describes a group of entries in
430 the table of contents, inducing a hierarchy
431 of entries. To this end its value is a Tcl
432 dictionary containing a label for the
433 group, an optional id to a document for the
434 whole group, and the list of entries in the
435 group. The relevant keys and their values
436 are
437 id The value is a string containing the
439 id of the document associated with
440 the whole group. This key is op‐
441 tional.
442 label The value is a string containing a
444 label for the group. This string
445 also identifies the entry, and no
446 two entries (references and divi‐
447 sions) in the containing list are
448 allowed to have the same label.
449 items The value is a Tcl list holding the
451 elements of the group, in the order
452 they are to be shown. This list has
453 the same structure as the value for
454 the keyword items used to describe
455 the whole table of contents, see
456 above. This closes the recusrive
457 definition of the structure, with
458 divisions holding the same type of
459 elements as the whole table of con‐
460 tents, including other divisions.
461 canonical serialization
463 The canonical serialization of a table of contents has the for‐
464 mat as specified in the previous item, and then additionally
465 satisfies the constraints below, which make it unique among all
466 the possible serializations of this table of contents.
467 [1] The keys found in all the nested Tcl dictionaries are
469 sorted in ascending dictionary order, as generated by
470 Tcl's builtin command lsort -increasing -dict.
471
473 This document, and the package it describes, will undoubtedly contain
474 bugs and other problems. Please report such in the category doctools
475 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
476 also report any ideas for enhancements you may have for either package
477 and/or documentation.
478 When proposing code changes, please provide unified diffs, i.e the out‐
480 put of diff -u.
481 Note further that attachments are strongly preferred over inlined
483 patches. Attachments can be made by going to the Edit form of the
484 ticket immediately after its creation, and then using the left-most
485 button in the secondary navigation bar.
486
488 conversion, doctoc, documentation, import, json, manpage, markup, pars‐
489 ing, plugin, reference, table, table of contents, url
490
492 Documentation tools
493
495 Copyright (c) 2009-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
496tcllib 0.2.1 doctools::toc::import(n)