


doctools::toc::import::Documentatdoctools::toc::import::doctoc(n)


______________________________________________________________________________

NAME
       doctools::toc::import::doctoc - doctoc import plugin

SYNOPSIS
       package require Tcl  8.4

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

       package require doctools::toc::parse

       package require doctools::toc::structure

       package require doctools::msgcat

       package require doctools::tcl::parse

       package require fileutil

       package require logger

       package require snit

       package require struct::list

       package require struct::set

       package require struct::stack

       package require struct::tree

       package require treeql

       import string configuration

_________________________________________________________________

DESCRIPTION
       This  package  implements  the doctools table of contents import plugin
       for the parsing of doctoc markup.

       This is an internal package of doctools, for use by  the  higher  level
       management  packages  handling  tables  of  contents,  especially  doc-
       tools::toc::import, the import manager.

       Using it from a regular interpreter is possible, however only with con-
       tortions, and is not recommended.  The proper way to use this function-
       ality is through the package doctools::toc::import and the import  man-
       ager objects it provides.

API
       The  API  provided  by  this package satisfies the specification of the
       doctoc import plugin API version 2.



doctools2toc                   0.1                              1





doctools::toc::import::Documentatdoctools::toc::import::doctoc(n)


       import string configuration
              This command takes the string and parses  it  as  doctoc  markup
              encoding  a  table  of contents, in the context of the specified
              configuration (a dictionary). The result of the command  is  the
              canonical  serialization  of that table of contents, in the form
              specified in section ToC serialization format.


[DOCTOC] NOTATION OF TABLES OF CONTENTS
       The doctoc format for tables of contents, also called the doctoc markup
       language, is too large to be covered in single section.  The interested
       reader should start with the document

       [1]    doctoc language introduction

       and then proceed from there to the formal specifications, i.e. the doc-
       uments

       [1]    doctoc language syntax and

       [2]    doctoc language command reference.

       to get a thorough understanding of the language.

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



doctools2toc                   0.1                              2





doctools::toc::import::Documentatdoctools::toc::import::doctoc(n)


                             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.

                             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



doctools2toc                   0.1                              3





doctools::toc::import::Documentatdoctools::toc::import::doctoc(n)


                                           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 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
       deserialization, doctoc, doctools, import, table of contents, toc

CATEGORY
       Text formatter plugin

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















doctools2toc                   0.1                              4


