


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


______________________________________________________________________________

NAME
       doctools::toc::export - Exporting tables of contents

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

       package require Tcl  8.4

       package require doctools::config

       package require doctools::toc::structure

       package require snit

       package require pluginmgr

       ::doctools::toc::export objectName

       objectName method ?arg arg ...?

       objectName destroy

       objectName export serial serial ?format?

       objectName export object object ?format?

       objectName config names

       objectName config get

       objectName config set name ?value?

       objectName config unset pattern...

       export serial configuration

_________________________________________________________________

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

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

       [1]    Importing tables of contents, and

       [2]    Holding tables of contents


       For information about the Concepts of tables  of  contents,  and  their



doctools2toc                   0.1                              1





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


       parts,  see  the  same-named  section.   For information about the data
       structure which is the major input to 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_EXPORT_PLUGINS,

       [2]    the environment variable DOCTOOLS_TOC_PLUGINS,

       [3]    the environment variable DOCTOOLS_PLUGINS,

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

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

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

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

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

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

       [10]   the     registry     entry      "HKEY_CURRENT_USER\SOFTWARE\DOC-
              TOOLS\TOC\EXPORT\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  six  predefined  export  plugins,
       namely

       doctoc See doctoc export plugin for details.

       html   See html export plugin for details.

       json   See json export plugin for details.

       nroff  See nroff export plugin for details.

       text   See text export plugin for details.

       wiki   See wiki export plugin for details.


       Readers  wishing to write their own export plugin for some format, i.e.
       plugin writers reading and understanding  the  section  containing  the



doctools2toc                   0.1                              2





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


       Export  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::export objectName
              This command creates a new export 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::export command have the
       following general form:

       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.





doctools2toc                   0.1                              3





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


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

       objectName export serial serial ?format?
              This method takes the canonical serialization of a table of con-
              tents  stored in serial and converts it to the specified format,
              using the export plugin for the format. An error is thrown if no
              plugin  could  be found for the format.  The string generated 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
              Export plugin API v2 reference.

       objectName export object object ?format?
              This  method  is  a  convenient wrapper around the export serial
              method described by the previous item.  It expects  that  object
              is an object command supporting a serialize method returning the
              canonical serialization of a table of contents. It invokes  that
              method,  feeds  the  result  into  export serial and returns the
              resulting string as its own result.

       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.

       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.






doctools2toc                   0.1                              4





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


EXPORT PLUGIN API V2 REFERENCE
       Plugins are what this package uses to manage the support for any output
       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.

       [2]    The   name   of   a   plugin   package   has   the   form   doc-
              tools::toc::export::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  export  methods  of  export  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]    A plugin has to provide one command, with  the  signature  shown
              below.

              export serial configuration
                     Whenever an export manager of doctools::toc has to gener-
                     ate output for a table of contents it  will  invoke  this
                     command.

                     string serial
                             This  argument will contain the canonical serial-
                             ization of the table of  contents  for  which  to
                             generate the output.  The specification of what a
                             canonical serialization is can be  found  in  the
                             section ToC serialization format.

                     dictionary configuration
                             This argument will contain the current configura-
                             tion to apply to the generation, 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.



doctools2toc                   0.1                              5





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


                             file   This variable, if defined by the  user  of
                                    the  table  object  is expected to contain
                                    the name of the input file for  which  the
                                    plugin is generating its output for.

                             map    This  variable,  if defined by the user of
                                    the table object is expected to contain  a
                                    dictionary  mapping from symbolic document
                                    ids used in the table  entries  to  actual
                                    paths  (or  urls). A plugin has to be able
                                    to handle the possibility that a  document
                                    id is without entry in this mapping.

       [5]    A  single usage cycle of a plugin consists of the invokations of
              the command export. 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

              [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,



doctools2toc                   0.1                              6





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


                             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.

                             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



doctools2toc                   0.1                              7





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


                                           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.

KEYWORDS
       HTML,  conversion,  doctoc,  documentation, export, formatting, genera-
       tion, json, manpage, markup, nroff, plugin, reference, table, table  of
       contents, tcler's wiki, text, url, wiki

CATEGORY
       Documentation tools

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



















doctools2toc                   0.1                              8


