


doctools::toc::import(nDocumentation tooldoctools::toc::import(n)


______________________________________________________________________________

NAME
       doctools::toc::import - Importing keyword indices

SYNOPSIS
       package require doctools::toc::import  ?0.1?

       package require Tcl  8.4

       package require doctools::config

       package require doctools::toc::structure

       package require snit

       package require pluginmgr

       ::doctools::toc::import objectName

       objectName method ?arg arg ...?

       objectName destroy

       objectName import text text ?format?

       objectName import file path ?format?

       objectName import object text object text ?format?

       objectName import object file object path ?format?

       objectName config names

       objectName config get

       objectName config set name ?value?

       objectName config unset pattern...

       objectName includes

       objectName include add path

       objectName include remove path

       objectName include clear

       IncludeFile currentfile path

       import text configuration

_________________________________________________________________




doctools2toc                   0.1                              1





doctools::toc::import(nDocumentation tooldoctools::toc::import(n)


DESCRIPTION
       This  package  provides a class to manage the plugins for the import of
       tables of contents from other formats, i.e. their conversion from,  for
       example doctoc, json, etc.

       This  is  one  of  the three public pillars the management of tables of
       contents resides on. The other two pillars are

       [1]    Exporting tables of contents, and

       [2]    Holding tables of contents


       For information about the Concepts of tables  of  contents,  and  their
       parts,  see  the  same-named  section.   For information about the data
       structure which is the major output of the manager objects provided  by
       this package see the section ToC serialization format.

       The  plugin  system of our class is based on the package pluginmgr, and
       configured to look for plugins using

       [1]    the environment variable DOCTOOLS_TOC_IMPORT_PLUGINS,

       [2]    the environment variable DOCTOOLS_TOC_PLUGINS,

       [3]    the environment variable DOCTOOLS_PLUGINS,

       [4]    the path "~/.doctools/toc/import/plugin"

       [5]    the path "~/.doctools/toc/plugin"

       [6]    the path "~/.doctools/plugin"

       [7]    the path "~/.doctools/toc/import/plugins"

       [8]    the path "~/.doctools/toc/plugins"

       [9]    the path "~/.doctools/plugins"

       [10]   the     registry     entry      "HKEY_CURRENT_USER\SOFTWARE\DOC-
              TOOLS\TOC\IMPORT\PLUGINS"

       [11]   the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\PLU-
              GINS"

       [12]   the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"

       The last three are used only when the package is run on a machine using
       Windows(tm) operating system.

       The whole system is  delivered  with  two  predefined  import  plugins,
       namely

       doctoc See doctoc import plugin for details.



doctools2toc                   0.1                              2





doctools::toc::import(nDocumentation tooldoctools::toc::import(n)


       json   See json import plugin for details.


       Readers  wishing to write their own import plugin for some format, i.e.
       plugin writers reading and understanding  the  section  containing  the
       Import  plugin  API v2 reference is an absolute necessity, as it speci-
       fies the interaction between this package and its plugins in detail.

CONCEPTS
       [1]    A table of contents consists of a (possibly empty) list of  ele-
              ments.

       [2]    Each element in the list is identified by its label.

       [3]    Each element is either a reference, or a division.

       [4]    Each  reference has an associated document, identified by a sym-
              bolic id, and a textual description.

       [5]    Each division may have an associated document, identified  by  a
              symbolic id.

       [6]    Each  division  consists  consists of a (possibly empty) list of
              elements, with each element following the rules as specified  in
              item 2 and above.

       A few notes

       [1]    The  above  rules span up a tree of elements, with references as
              the leaf nodes, and divisions as the inner nodes, and each  ele-
              ment representing an entry in the whole table of contents.

       [2]    The  identifying labels of any element E are unique within their
              division (or toc), and the full label of any element  E  is  the
              list of labels for all nodes on the unique path from the root of
              the tree to E, including E.


API
   PACKAGE COMMANDS
       ::doctools::toc::import objectName
              This command creates a new import manager object with an associ-
              ated  Tcl  command whose name is objectName. This object command
              is explained in full detail in the sections Object  command  and
              Object  methods.  The  object  command will be created under the
              current namespace if the objectName is not fully qualified,  and
              in the specified namespace otherwise.


   OBJECT COMMAND
       All  objects  created  by  the ::doctools::toc::import command have the
       following general form:





doctools2toc                   0.1                              3





doctools::toc::import(nDocumentation tooldoctools::toc::import(n)


       objectName method ?arg arg ...?
              The method method and its arg'uments determine the exact  behav-
              ior of the command.  See section Object methods for the detailed
              specifications.


   OBJECT METHODS
       objectName destroy
              This method destroys the object it is invoked for.

       objectName import text text ?format?
              This method takes the text and converts it  from  the  specified
              format  to  the  canonical  serialization of a table of contents
              using the import plugin for the format. An error is thrown if no
              plugin  could be found for the format.  The serialization gener-
              ated by the conversion process is returned as the result of this
              method.

              If no format is specified the method defaults to doctoc.

              The  specification  of  what a canonical serialization is can be
              found in the section ToC serialization format.

              The plugin has to conform to the interface specified in  section
              Import plugin API v2 reference.

       objectName import file path ?format?
              This  method  is  a  convenient  wrapper  around the import text
              method described by the previous item.  It reads the contents of
              the  specified  file  into  memory, feeds the result into import
              text and returns the resulting serialization as its own  result.

       objectName import object text object text ?format?
              This  method  is  a  convenient  wrapper  around the import text
              method described by the previous item.  It expects  that  object
              is  an  object command supporting a deserialize method expecting
              the canonical serialization of a table of contents.  It  imports
              the  text using import text and then feeds the resulting serial-
              ization into the object via deserialize.   This  method  returns
              the empty string as it result.

       objectName import object file object path ?format?
              This  method  behaves  like  import  object text, except that it
              reads the text to convert from the  specified  file  instead  of
              being given it as argument.

       objectName config names
              This  method returns a list containing the names of all configu-
              ration variables currently known to the object.

       objectName config get
              This method returns a dictionary containing the names and values
              of all configuration variables currently known to the object.




doctools2toc                   0.1                              4





doctools::toc::import(nDocumentation tooldoctools::toc::import(n)


       objectName config set name ?value?
              This  method  sets the configuration variable name to the speci-
              fied value and returns the new value of the variable.

              If no value is specified it simply returns  the  current  value,
              without changing it.

              Note  that  while  the user can set the predefined configuration
              variables user and format doing so will have  no  effect,  these
              values will be internally overriden when invoking an import plu-
              gin.

       objectName config unset pattern...
              This method unsets  all  configuration  variables  matching  the
              specified  glob  patterns.  If  no  pattern is specified it will
              unset all currently defined configuration variables.

       objectName includes
              This method returns a list containing  the  currently  specified
              paths  to use to search for include files when processing input.
              The order of paths in the list corresponds to the order in which
              they  are  used, from first to last, and also corresponds to the
              order in which they were added to the object.

       objectName include add path
              This methods adds the specified path to the list of paths to use
              to  search  for include files when processing input. The path is
              added to the end of the list, causing it to  be  searched  after
              all  previously  added  paths.  The result of the command is the
              empty string.

              The method does nothing if the path is already known.

       objectName include remove path
              This methods removes the specified path from the list  of  paths
              to  use  to  search for include files when processing input. The
              result of the command is the empty string.

              The method does nothing if the path is not known.

       objectName include clear
              This method clears the list  of  paths  to  use  to  search  for
              include  files  when processing input. The result of the command
              is the empty string.


IMPORT PLUGIN API V2 REFERENCE
       Plugins are what this package uses to manage the support for any  input
       format beyond the ToC serialization format. Here we specify the API the
       objects created by this package use to interact with their plugins.

       A plugin for this package has to follow the rules listed below:

       [1]    A plugin is a package.



doctools2toc                   0.1                              5





doctools::toc::import(nDocumentation tooldoctools::toc::import(n)


       [2]    The   name   of   a   plugin   package   has   the   form   doc-
              tools::toc::import::FOO, where FOO is the name of the format the
              plugin will generate output for. This name is also the  argument
              to  provide  to  the  various  import  methods of import manager
              objects to get a string encoding a table  of  contents  in  that
              format.

       [3]    The    plugin    can    expect    that    the    package    doc-
              tools::toc::export::plugin is present, as indicator that it  was
              invoked from a genuine plugin manager.

       [4]    The  plugin  can expect that a command named IncludeFile is pre-
              sent, with the signature

              IncludeFile currentfile path
                     This command has to be invoked by the plugin when it  has
                     to  process  an included file, if the format has the con-
                     cept of such. An example of such a format would  be  doc-
                     toc.

                     The plugin has to supply the following arguments

                     string currentfile
                             The  path of the file it is currently processing.
                             This may be the empty string if no such is known.

                     string path
                             The  path of the include file as specified in the
                             include directive being processed.
              The result of the command will be a 5-element list containing

                      [1]    A boolean flag indicating the success  (True)  or
                             failure (False) of the operation.

                      [2]    In  case  of success the contents of the included
                             file, and the empty string otherwise.

                      [3]    The resolved, i.e. absolute path of the  included
                             file,  if  possible,  or the unchanged path argu-
                             ment. This is for display in an error message, or
                             as  the  currentfile  argument of another call to
                             IncludeFile should this file contain more  files.

                      [4]    In case of success an empty string, and for fail-
                             ure a code indicating the reason for it, one of

                             notfound
                                    The specified file could not be found.

                             notread
                                    The specified file was found, but  not  be
                                    read into memory.

                      [5]    An  empty string in case of success of a notfound



doctools2toc                   0.1                              6





doctools::toc::import(nDocumentation tooldoctools::toc::import(n)


                             failure, and an additional error message describ-
                             ing  the  reason  for  a  notread  error  in more
                             detail.

       [5]    A plugin has to provide one command, with  the  signature  shown
              below.

              import text configuration
                     Whenever  an import manager of doctools::toc has to parse
                     input for a table of contents it will  invoke  this  com-
                     mand.

                     string text
                             This  argument will contain the text encoding the
                             table of contents per the format  the  plugin  is
                             for.

                     dictionary configuration
                             This argument will contain the current configura-
                             tion to apply to the  parsing,  as  a  dictionary
                             mapping from variable names to values.

                             The following configuration variables have a pre-
                             defined  meaning  all  plugins  have   to   obey,
                             although  they  can  ignore  this  information at
                             their discretion. Any other  other  configuration
                             variables   recognized   by   a  plugin  will  be
                             described in the manpage for that plugin.

                             user   This variable is expected to  contain  the
                                    name of the user owning the process invok-
                                    ing the plugin.

                             format This variable is expected to  contain  the
                                    name   of   the  format  whose  plugin  is
                                    invoked.

       [6]    A single usage cycle of a plugin consists of the invokations  of
              the command import. This call has to leave the plugin in a state
              where another usage cycle can be run without problems.


TOC SERIALIZATION FORMAT
       Here we specify the format used by the doctools v2 packages to  serial-
       ize  tables  of contents as immutable values for transport, comparison,
       etc.

       We distinguish between regular and canonical serializations.   While  a
       table  of  contents  may  have more than one regular serialization only
       exactly one of them will be canonical.


       regular serialization




doctools2toc                   0.1                              7





doctools::toc::import(nDocumentation tooldoctools::toc::import(n)


              [1]    The serialization of any table of contents  is  a  nested
                     Tcl dictionary.

              [2]    This  dictionary  holds  a single key, doctools::toc, and
                     its value. This value holds the contents of the table  of
                     contents.

              [3]    The  contents  of the table of contents are a Tcl dictio-
                     nary holding the title of the table of contents, a label,
                     and its elements. The relevant keys and their values are

                      title  The value is a string containing the title of the
                             table of contents.

                      label  The value is a string containing a label for  the
                             table of contents.

                      items  The  value  is a Tcl list holding the elements of
                             the table, in the order they are to be shown.

                             Each element is a Tcl list holding  the  type  of
                             the  item, and its description, in this order. An
                             alternative description would be that it is a Tcl
                             dictionary  holding  a single key, the item type,
                             mapped to the item description.

                             The two legal item types and  their  descriptions
                             are

                             reference
                                    This  item describes a single entry in the
                                    table of contents,  referencing  a  single
                                    document.   To this end its value is a Tcl
                                    dictionary containing an id for the refer-
                                    enced document, a label, and a longer tex-
                                    tual description which can  be  associated
                                    with  the  entry.   The  relevant keys and
                                    their values are

                                    id     The value is  a  string  containing
                                           the  id  of the document associated
                                           with the entry.

                                    label  The value is a string containing  a
                                           label  for  this entry. This string
                                           also identifies the entry,  and  no
                                           two  entries  (references and divi-
                                           sions) in the containing  list  are
                                           allowed to have the same label.

                                    desc   The  value is a string containing a
                                           longer description for this  entry.





doctools2toc                   0.1                              8





doctools::toc::import(nDocumentation tooldoctools::toc::import(n)


                             division
                                    This  item describes a group of entries in
                                    the table of contents, inducing a  hierar-
                                    chy  of entries.  To this end its value is
                                    a Tcl dictionary containing  a  label  for
                                    the  group,  an  optional id to a document
                                    for the  whole  group,  and  the  list  of
                                    entries  in  the group.  The relevant keys
                                    and their values are

                                    id     The value is  a  string  containing
                                           the  id  of the document associated
                                           with the whole group. This  key  is
                                           optional.

                                    label  The  value is a string containing a
                                           label for the  group.  This  string
                                           also  identifies  the entry, and no
                                           two entries (references  and  divi-
                                           sions)  in  the containing list are
                                           allowed to have the same label.

                                    items  The value is a Tcl list holding the
                                           elements of the group, in the order
                                           they are to be  shown.   This  list
                                           has the same structure as the value
                                           for  the  keyword  items  used   to
                                           describe  the  whole  table of con-
                                           tents, see above. This  closes  the
                                           recusrive  definition of the struc-
                                           ture, with  divisions  holding  the
                                           same  type of elements as the whole
                                           table of contents, including  other
                                           divisions.

       canonical serialization
              The  canonical serialization of a table of contents has the for-
              mat as specified in the previous  item,  and  then  additionally
              satisfies  the constraints below, which make it unique among all
              the possible serializations of this table of contents.

              [1]    The keys found in all the  nested  Tcl  dictionaries  are
                     sorted  in  ascending  dictionary  order, as generated by
                     Tcl's builtin command lsort -increasing -dict.


BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will  undoubtedly  contain
       bugs  and  other problems.  Please report such in the category doctools
       of       the       Tcllib       SF       Trackers       [http://source-
       forge.net/tracker/?group_id=12883].   Please  also report any ideas for
       enhancements you may have for either package and/or documentation.





doctools2toc                   0.1                              9





doctools::toc::import(nDocumentation tooldoctools::toc::import(n)


KEYWORDS
       conversion, doctoc, documentation, import, json, manpage, markup, pars-
       ing, plugin, reference, table, table of contents, url

CATEGORY
       Documentation tools

COPYRIGHT
       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
















































doctools2toc                   0.1                             10


