


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


______________________________________________________________________________

NAME
       doctools::toc::export::doctoc - doctoc export plugin

SYNOPSIS
       package require Tcl  8.4

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

       export serial configuration

_________________________________________________________________

DESCRIPTION
       This  package  implements  the doctools table of contents export plugin
       for the generation 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::export, the export 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::export and the export  man-
       ager objects it provides.

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

       export serial configuration
              This command takes the canonical serialization  of  a  table  of
              contents,  as specified in section ToC serialization format, and
              contained in serial, the configuration, a dictionary, and gener-
              ates  doctoc  markup  encoding the table.  The created string is
              then returned as the result of the command.


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



doctools2toc                   0.1                              1





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


CONFIGURATION
       The  doctoc  export plugin recognizes the following configuration vari-
       ables and changes its behaviour as they specify.

       string user
              This standard configuration variable contains the  name  of  the
              user  running  the process which invoked the export plugin.  The
              plugin puts this information into the provenance comment at  the
              beginning of the generated document.

       string file
              This  standard  configuration  variable contains the name of the
              file the table of contents came from. This variable may  not  be
              set  or contain the empty string.  The plugin puts this informa-
              tion, if defined, i.e. set and not the empty  string,  into  the
              provenance comment at the beginning of the generated document.

       boolean newlines
              If  this  flag is set the plugin will break the generated doctoc
              code across lines, with each markup command on a separate  line.

              If  this  flag is not set (the default), the whole document will
              be written on a single line, with minimum  spacing  between  all
              elements.

       boolean indented
              If  this  flag is set the plugin will indent the markup commands
              according to the structure of tables of contents. To  make  this
              work  this  also  implies  that  newlines is set. This effect is
              independent of the value for aligned however.

              If this flag is not set (the default), the output  is  formatted
              as per the value of newlines, and no indenting is done.

       boolean aligned
              If this flag is set the generator ensures that the arguments for
              the item commands in a division are  aligned  vertically  for  a
              nice table effect. To make this work this also implies that new-
              lines is set. This  effect  is  independent  of  the  value  for
              indented however.

              If  this  flag is not set (the default), the output is formatted
              as per the values of newlines and indented, and no alignment  is
              done.

       Note that this plugin ignores the standard configuration variables for-
       mat, and map, and their values.

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



doctools2toc                   0.1                              2





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


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



doctools2toc                   0.1                              3





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


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



doctools2toc                   0.1                              4





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


       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
       doctoc, doctools, export, serialization, table of contents, toc

CATEGORY
       Text formatter plugin

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













































doctools2toc                   0.1                              5


