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



______________________________________________________________________________

NAME
       doctools::toc - Holding tables of contents

SYNOPSIS
       package require doctools::toc  ?2?

       package require Tcl  8.4

       package require doctools::toc::structure

       package require struct::tree

       package require snit

       ::doctools::toc objectName

       objectName method ?arg arg ...?

       objectName destroy

       objectName + reference id label docid desc

       objectName + division id label ?docid?

       objectName remove id

       objectName up id

       objectName next id

       objectName prev id

       objectName child id label ?...?

       objectName element ?...?

       objectName children id

       objectName type id

       objectName full-label id

       objectName elabel id ?newlabel?

       objectName description id ?newdesc?

       objectName document id ?newdocid?

       objectName title

       objectName title text

       objectName label

       objectName label text

       objectName importer

       objectName importer object

       objectName exporter

       objectName exporter object

       objectName deserialize = data ?format?

       objectName deserialize += data ?format?

       objectName serialize ?format?

_________________________________________________________________

DESCRIPTION
       This package provides a class to contain and programmatically
       manipulate tables of contents.

       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]    Importing 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 used to encode tables of contents as values see the
       section ToC serialization format.  This is the only format directly
       known to this class. Conversions from and to any other format are
       handled by export and import manager objects. These may be attached to
       a container, but do not have to be, it is merely a convenience.

CONCEPTS
       [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.

API
   PACKAGE COMMANDS
       ::doctools::toc objectName
              This command creates a new container 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.

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

       objectName method ?arg arg ...?
              The method method and its arg'uments determine the exact
              behavior 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 + reference id label docid desc
              This method adds a new reference element to the table of
              contents, under the element specified via its handle id. This
              parent element has to be a division element, or the root. An
              error is thrown otherwise.  The new element will be externally
              identified by its label, which has to be be unique within the
              parent element. An error is thrown otherwise.

              As a reference element it will refer to a document identified by
              the symbolic docid. This reference must not be the empty string,
              an error is thrown otherwise.  Beyond the label the element also
              has a longer descriptive string, supplied via desc.

              The result of the method is the handle (id) of the new element.

       objectName + division id label ?docid?
              This method adds a new division element to the table of
              contents, under the element specified via its handle id. This
              parent element has to be a division element, or the root. An
              error is thrown otherwise.  The new element will be externally
              identified by its label, which has to be be unique within the
              parent element. An error is thrown otherwise.

              As a division element it is can refer to a document, identified
              by the symbolic docid, but may choose not to.

              The result of the method is the handle (id) of the new element.

       objectName remove id
              This method removes the element identified by the handle id from
              the table of contents.  If the element is a division all of its
              children, if any, are removed as well. The root element/division
              of the table of contents cannot be removed however, only its
              children.

              The result of the method is the empty string.

       objectName up id
              This method returns the handle of the parent for the element
              identified by its handle id, or the empty string if id refered
              to the root element.

       objectName next id
              This method returns the handle of the right sibling for the
              element identified by its handle id, or the handle of the parent
              if the element has no right sibling, or the empty string if id
              refered to the root element.

       objectName prev id
              This method returns the handle of the left sibling for the
              element identified by its handle id, or the handle of the parent
              if the element has no left sibling, or the empty string if id
              refered to the root element.

       objectName child id label ?...?
              This method returns the handle of a child of the element
              identified by its handle id. The child itself is identified by a
              series of labels.

       objectName element ?...?
              This method returns the handle of the element identified by a
              series of labels, starting from the root of the table of
              contents. The series of labels is allowed to be empty, in which
              case the handle of the root element is returned.

       objectName children id
              This method returns a list containing the handles of all
              children of the element identified by the handle id, from first
              to last, in that order.

       objectName type id
              This method returns the type of the element, either reference,
              or division.

       objectName full-label id
              This method is the complement of the method element, converting
              the handle id of an element into a list of labels full
              identifying the element within the whole table of contents.

       objectName elabel id ?newlabel?
              This method queries and/or changes the label of the element
              identified by the handle id. If the argument newlabel is present
              then the label is changed to that value. Regardless of this, the
              result of the method is the current value of the label.

              If the label is changed the new label has to be unique within
              the containing division, or an error is thrown.

              Further, of the id refers to the root element of the table of
              contents, then using this method is equivalent to using the
              method label, i.e. it is accessing the global label for the
              whole table.

       objectName description id ?newdesc?
              This method queries and/or changes the description of the
              element identified by the handle id. If the argument newdesc is
              present then the description is changed to that value.
              Regardless of this, the result of the method is the current
              value of the description.

              The element this method operates on has to be a reference
              element, or an error will be thrown.

       objectName document id ?newdocid?
              This method queries and/or changes the document reference of the
              element identified by the handle id.  If the argument newdocid
              is present then the description is changed to that value.
              Regardless of this, the result of the method is the current
              value of the document reference.

              Setting the reference to the empty string means unsetting it,
              and is allowed only for division elements. Conversely, if the
              result is the empty string then the element has no document
              reference, and this can happen only for division elements.

       objectName title
              Returns the currently defined title of the table of contents.

       objectName title text
              Sets the title of the table of contents to text, and returns it
              as the result of the command.

       objectName label
              Returns the currently defined label of the table of contents.

       objectName label text
              Sets the label of the table of contents to text, and returns it
              as the result of the command.

       objectName importer
              Returns the import manager object currently attached to the
              container, if any.

       objectName importer object
              Attaches the object as import manager to the container, and
              returns it as the result of the command.  Note that the object
              is not put into ownership of the container. I.e., destruction of
              the container will not destroy the object.

              It is expected that object provides a method named import text
              which takes a text and a format name, and returns the canonical
              serialization of the table of contents contained in the text,
              assuming the given format.

       objectName exporter
              Returns the export manager object currently attached to the
              container, if any.

       objectName exporter object
              Attaches the object as export manager to the container, and
              returns it as the result of the command.  Note that the object
              is not put into ownership of the container. I.e., destruction of
              the container will not destroy the object.

              It is expected that object provides a method named export object
              which takes the container and a format name, and returns a text
              encoding table of contents stored in the container, in the given
              format. It is further expected that the object will use the
              container's method serialize to obtain the serialization of the
              table of contents from which to generate the text.

       objectName deserialize = data ?format?
              This method replaces the contents of the table object with the
              table contained in the data. If no format was specified it is
              assumed to be the regular serialization of a table of contents.

              Otherwise the object will use the attached import manager to
              convert the data from the specified format to a serialization it
              can handle.  In that case an error will be thrown if the
              container has no import manager attached to it.

              The result of the method is the empty string.

       objectName deserialize += data ?format?
              This method behaves like deserialize = in its essentials, except
              that it merges the table of contents in the data to its contents
              instead of replacing it.  The method will throw an error if
              merging is not possible, i.e. would produce an invalid table.
              The existing content is left unchanged in that case.

              The result of the method is the empty string.

       objectName serialize ?format?
              This method returns the table of contents contained in the
              object. If no format is not specified the returned result is the
              canonical serialization of its contents.

              Otherwise the object will use the attached export manager to
              convert the data to the specified format.  In that case an error
              will be thrown if the container has no export manager attached
              to it.

TOC SERIALIZATION FORMAT
       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.

       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
                     dictionary 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
                                   referenced document, a label, and a longer
                                   textual 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
                                          divisions) 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 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

                                   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
                                          divisions) 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 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.

       canonical serialization
              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.

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

KEYWORDS
       HTML, TMML, conversion, doctoc markup, documentation, formatting,
       generation, json, latex, markup, nroff, parsing, plugin, reference,
       table, table of contents, tcler's wiki, text, wiki

CATEGORY
       Documentation tools

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




doctools2toc                           2                      doctools::toc(n)
