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?
12
13       package require Tcl  8.4
14
15       package require doctools::config
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\DOC‐
98              TOOLS\TOC\IMPORT\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
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

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

TOC SERIALIZATION FORMAT

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
370       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
374       regular serialization
375
376              [1]    The  serialization  of  any table of contents is a nested
377                     Tcl dictionary.
378
379              [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
383              [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
387                     title  The value is a string containing the title of  the
388                            table of contents.
389
390                     label  The  value  is a string containing a label for the
391                            table of contents.
392
393                     items  The value is a Tcl list holding  the  elements  of
394                            the table, in the order they are to be shown.
395
396                            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
402                            The  two  legal  item types and their descriptions
403                            are
404
405                            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
415                                   id     The value is a string containing the
416                                          id of the document  associated  with
417                                          the entry.
418
419                                   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
426                                   desc   The value is a string  containing  a
427                                          longer description for this entry.
428
429                            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
439                                   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
444                                   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
451                                   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
463       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
469              [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

BUGS, IDEAS, FEEDBACK

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

KEYWORDS

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

CATEGORY

493       Documentation tools
494
496       Copyright (c) 2009-2018 Andreas Kupries <andreas_kupries@users.sourceforge.net>
497
498
499
500
501tcllib                                0.2             doctools::toc::import(n)
Impressum