Provided by: tcllib_1.21+dfsg-1_all bug

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 referred 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 referred 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 referred 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  Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be made by going to the Edit form of the ticket immediately after its creation,  and  then
       using the left-most button in the secondary navigation bar.

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>