1doctools::toc::import(n)      Documentation tools     doctools::toc::import(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       doctools::toc::import - Importing keyword indices
9

SYNOPSIS

11       package require doctools::toc::import  ?0.2.1?
12
13       package require Tcl  8.4
14
15       package require struct::map
16
17       package require doctools::toc::structure
18
19       package require snit
20
21       package require pluginmgr
22
23       ::doctools::toc::import objectName
24
25       objectName method ?arg arg ...?
26
27       objectName destroy
28
29       objectName import text text ?format?
30
31       objectName import file path ?format?
32
33       objectName import object text object text ?format?
34
35       objectName import object file object path ?format?
36
37       objectName config names
38
39       objectName config get
40
41       objectName config set name ?value?
42
43       objectName config unset pattern...
44
45       objectName includes
46
47       objectName include add path
48
49       objectName include remove path
50
51       objectName include clear
52
53       IncludeFile currentfile path
54
55       import text configuration
56
57______________________________________________________________________________
58

DESCRIPTION

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
64       This  is  one  of  the three public pillars the management of tables of
65       contents resides on. The other two pillars are
66
67       [1]    Exporting tables of contents, and
68
69       [2]    Holding tables of contents
70
71       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
76       The  plugin  system of our class is based on the package pluginmgr, and
77       configured to look for plugins using
78
79       [1]    the environment variable DOCTOOLS_TOC_IMPORT_PLUGINS,
80
81       [2]    the environment variable DOCTOOLS_TOC_PLUGINS,
82
83       [3]    the environment variable DOCTOOLS_PLUGINS,
84
85       [4]    the path "~/.doctools/toc/import/plugin"
86
87       [5]    the path "~/.doctools/toc/plugin"
88
89       [6]    the path "~/.doctools/plugin"
90
91       [7]    the path "~/.doctools/toc/import/plugins"
92
93       [8]    the path "~/.doctools/toc/plugins"
94
95       [9]    the path "~/.doctools/plugins"
96
97       [10]   the registry entry  "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\IM‐
98              PORT\PLUGINS"
99
100       [11]   the      registry     entry     "HKEY_CURRENT_USER\SOFTWARE\DOC‐
101              TOOLS\TOC\PLUGINS"
102
103       [12]   the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"
104
105       The last three are used only when the package is run on a machine using
106       Windows(tm) operating system.
107
108       The  whole  system  is  delivered  with  two predefined import plugins,
109       namely
110
111       doctoc See doctoc import plugin for details.
112
113       json   See json import plugin for details.
114
115       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

CONCEPTS

121       [1]    A  table of contents consists of a (possibly empty) list of ele‐
122              ments.
123
124       [2]    Each element in the list is identified by its label.
125
126       [3]    Each element is either a reference, or a division.
127
128       [4]    Each reference has an associated document, identified by a  sym‐
129              bolic id, and a textual description.
130
131       [5]    Each  division  may have an associated document, identified by a
132              symbolic id.
133
134       [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
138       A few notes
139
140       [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
144       [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

API

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
159   OBJECT COMMAND
160       All objects created by the  ::doctools::toc::import  command  have  the
161       following general form:
162
163       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
168   OBJECT METHODS
169       objectName destroy
170              This method destroys the object it is invoked for.
171
172       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
180              If no format is specified the method defaults to doctoc.
181
182              The specification of what a canonical serialization  is  can  be
183              found in the section ToC serialization format.
184
185              The  plugin has to conform to the interface specified in section
186              Import plugin API v2 reference.
187
188       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
194       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
203       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
208       objectName config names
209              This  method returns a list containing the names of all configu‐
210              ration variables currently known to the object.
211
212       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
216       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
220              If no value is specified it simply returns  the  current  value,
221              without changing it.
222
223              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
228       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
233       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
240       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
247              The method does nothing if the path is already known.
248
249       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
254              The method does nothing if the path is not known.
255
256       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

IMPORT PLUGIN API V2 REFERENCE

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
266       A plugin for this package has to follow the rules listed below:
267
268       [1]    A plugin is a package.
269
270       [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
276       [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
280       [4]    The plugin can  expect  that  a  command  named  IncludeFile  is
281              present, with the signature
282
283              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
289                     The plugin has to supply the following arguments
290
291                     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
295                     string path
296                            The  path  of the include file as specified in the
297                            include directive being processed.
298
299                     The result of the command will be a 5-element  list  con‐
300                     taining
301
302                     [1]    A  boolean  flag  indicating the success (True) or
303                            failure (False) of the operation.
304
305                     [2]    In case of success the contents  of  the  included
306                            file, and the empty string otherwise.
307
308                     [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
314                     [4]    In  case of success an empty string, and for fail‐
315                            ure a code indicating the reason for it, one of
316
317                            notfound
318                                   The specified file could not be found.
319
320                            notread
321                                   The specified file was found,  but  not  be
322                                   read into memory.
323
324                     [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
328       [5]    A  plugin  has  to provide one command, with the signature shown
329              below.
330
331              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
336                     string text
337                            This argument will contain the text  encoding  the
338                            table  of  contents  per  the format the plugin is
339                            for.
340
341                     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
346                            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
353                            user   This  variable  is  expected to contain the
354                                   name of the user owning the process  invok‐
355                                   ing the plugin.
356
357                            format This  variable  is  expected to contain the
358                                   name of the format whose plugin is invoked.
359
360       [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

TOC SERIALIZATION FORMAT

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
369       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
373       regular serialization
374
375              [1]    The serialization of any table of contents  is  a  nested
376                     Tcl dictionary.
377
378              [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
382              [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
386                     title  The  value is a string containing the title of the
387                            table of contents.
388
389                     label  The value is a string containing a label  for  the
390                            table of contents.
391
392                     items  The  value  is  a Tcl list holding the elements of
393                            the table, in the order they are to be shown.
394
395                            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
401                            The two legal item types  and  their  descriptions
402                            are
403
404                            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
414                                   id     The value is a string containing the
415                                          id  of  the document associated with
416                                          the entry.
417
418                                   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
425                                   desc   The  value  is a string containing a
426                                          longer description for this entry.
427
428                            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
438                                   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
443                                   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
450                                   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
462       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
468              [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

BUGS, IDEAS, FEEDBACK

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
479       When proposing code changes, please provide unified diffs, i.e the out‐
480       put of diff -u.
481
482       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

KEYWORDS

488       conversion, doctoc, documentation, import, json, manpage, markup, pars‐
489       ing, plugin, reference, table, table of contents, url
490

CATEGORY

492       Documentation tools
493
495       Copyright (c) 2009-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
496
497
498
499
500tcllib                               0.2.1            doctools::toc::import(n)
Impressum