doctools::toc::export(n) Documentation tools doctools::toc::export(n) 







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








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












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 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\DOCTOOLS\TOC\EXPORT\PLUGINS"

  
[11]

  
the registry entry
      "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\PLUGINS"

  
[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



  

  
See doctoc export plugin for details.

  

  
See html export plugin for details.

  

  
See json export plugin for details.

  

  
See nroff export plugin for details.

  

  
See text export plugin for details.

  

  
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 Export plugin API v2 reference is an absolute necessity, as it
    specifies the interaction between this package and its plugins in
  detail.









  
[1]

  
A table of contents consists of a (possibly empty) list of
      elements.

  
[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 symbolic 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 element 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.















  
::doctools::toc::export objectName

  
This command creates a new export manager object with an associated 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.










All objects created by the ::doctools::toc::export command
    have the following general form:



  

  
The method method and its arg'uments determine the exact
      behavior of the command. See section Object methods for the
      detailed specifications.











  

  
This method destroys the object it is invoked for.

  

  
This method takes the canonical serialization of a table of contents
      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.

  

  

  
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.

  

  
This method returns a list containing the names of all configuration
      variables currently known to the object.

  

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

  

  
This method sets the configuration variable name to the specified
      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
        plugin.

  

  

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












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
      doctools::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
      doctools::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.







  

  
Whenever an export manager of doctools::toc has to generate output
      for a table of contents it will invoke this command.







  

  
This argument will contain the canonical serialization 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.

  

  
This argument will contain the current configuration to apply to the
      generation, as a dictionary mapping from variable names to values.
    
The following configuration variables have a predefined
        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.

  







  

  
This variable is expected to contain the name of the user owning the
      process invoking the plugin.

  

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

  

  
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.

  

  
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.










Here we specify the format used by the doctools v2 packages to
    serialize 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.



  

  







  
[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 dictionary holding the
      title of the table of contents, a label, and its elements. The relevant
      keys and their values are







  

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

  

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

  

  
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

  







  

  
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 referenced document, a label, and a longer textual description
      which can be associated with the entry. The relevant keys and their values
      are







  

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

  

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

  

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







  

  
This item describes a group of entries in the table of contents, inducing
      a hierarchy 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







  

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

  

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

  

  
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 contents, see
      above. This closes the recusrive definition of the structure, with
      divisions holding the same type of elements as the whole table of
      contents, including other divisions.













  

  
The canonical serialization of a table of contents has the format 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.












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://sourceforge.net/tracker/?group_id=12883]. Please also report any
    ideas for enhancements you may have for either package and/or
  documentation.








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








Documentation tools








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








  

    0.1
    doctools2toc