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



______________________________________________________________________________

NAME
       doctools::toc - doctoc - Processing tables of contents

SYNOPSIS
       package require Tcl  8.2

       package require doctools::toc  ?1.1.3?

       ::doctools::toc::new objectName ?-option value ...?

       ::doctools::toc::help

       ::doctools::toc::search path

       objectName method ?arg arg ...?

       objectName configure

       objectName configure option

       objectName configure -option value...

       objectName cget -option

       objectName destroy

       objectName format text

       objectName map symbolic actual

       objectName parameters

       objectName search path

       objectName setparam name value

       objectName warnings

_________________________________________________________________

DESCRIPTION
       This package provides a class for the creation of objects able to
       process and convert text written in the doctoc markup language into any
       output format X for which a formatting engine is available.

       A reader interested in the markup language itself should start with the
       doctoc language introduction and proceed from there to the formal
       specifications, i.e. the doctoc language syntax and the doctoc language
       command reference.

       If on the other hand the reader wishes to write her own formatting
       engine for some format, i.e. is a plugin writer then reading and
       understanding the doctoc plugin API reference is an absolute necessity,
       as that document specifies the interaction between this package and its
       plugins, i.e. the formatting engines, in detail.

PUBLIC API
   PACKAGE COMMANDS
       ::doctools::toc::new objectName ?-option value ...?
              This command creates a new doctoc 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.

              The options and their values coming after the name of the object
              are used to set the initial configuration of the object.

       ::doctools::toc::help
              This is a convenience command for applications wishing to
              provide their user with a short description of the available
              formatting commands and their meanings. It returns a string
              containing a standard help text.

       ::doctools::toc::search path
              Whenever an object created by this the package has to map the
              name of a format to the file containing the code for its
              formatting engine it will search for the file in a number of
              directories stored in a list. See section FORMAT MAPPING for
              more explanations.

              This list not only contains three default directories which are
              declared by the package itself, but is also extensible user of
              the package.  This command is the means to do so. When given a
              path to an existing and readable directory it will prepend that
              directory to the list of directories to search. This means that
              the path added last is later searched through first.

              An error will be thrown if the path either does not exist, is
              not a directory, or is not readable.

   OBJECT COMMAND
       All commands created by ::doctools::toc::new have the following general
       form and may be used to invoke various operations on their doctoc
       converter object.

       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 configure
              The method returns a list of all known options and their current
              values when called without any arguments.

       objectName configure option
              The method behaves like the method cget when called with a
              single argument and returns the value of the option specified by
              said argument.

       objectName configure -option value...
              The method reconfigures the specified options of the object,
              setting them to the associated values, when called with an even
              number of arguments, at least two.

              The legal options are described in the section OBJECT
              CONFIGURATION.

       objectName cget -option
              This method expects a legal configuration option as argument and
              will return the current value of that option for the object the
              method was invoked for.

              The legal configuration options are described in section OBJECT
              CONFIGURATION.

       objectName destroy
              This method destroys the object it is invoked for.

       objectName format text
              This method runs the text through the configured formatting
              engine and returns the generated string as its result. An error
              will be thrown if no -format was configured for the object.

              The method assumes that the text is in doctoc format as
              specified in the companion document doctoc_fmt. Errors will be
              thrown otherwise.

       objectName map symbolic actual
              This methods add one entry to the per-object mapping from
              symbolic filenames to the actual uris.  The object just stores
              this mapping and makes it available to the configured formatting
              engine through the command dt_fmap.  This command is described
              in more detail in the doctoc plugin API reference which
              specifies the interaction between the objects created by this
              package and toc formatting engines.

       objectName parameters
              This method returns a list containing the names of all engine
              parameters provided by the configured formatting engine. It will
              return an empty list if the object is not yet configured for a
              specific format.

       objectName search path
              This method extends the per-object list of paths searched for
              toc formatting engines. See also the command
              ::doctools::toc::search on how to extend the per-package list of
              paths. Note that the path entered last will be searched first.
              For more details see section FORMAT MAPPING.

       objectName setparam name value
              This method sets the named engine parameter to the specified
              value.  It will throw an error if the object is either not yet
              configured for a specific format, or if the formatting engine
              for the configured format does not provide a parameter with the
              given name.  The list of parameters provided by the configured
              formatting engine can be retrieved through the method
              parameters.

       objectName warnings
              This method returns a list containing all the warnings which
              were generated by the configured formatting engine during the
              last invocation of the method format.

   OBJECT CONFIGURATION
       All doctoc objects understand the following configuration options:

       -file file
              The argument of this option is stored in the object and made
              available to the configured formatting engine through the
              command dt_file.  This command is described in more detail in
              the companion document doctoc_api which specifies the API
              between the object and formatting engines.

              The default value of this option is the empty string.

              The configured formatting engine should interpret the value as
              the name of the file containing the document which is currently
              processed.

       -format text
              The argument of this option specifies the format to generate and
              by implication the formatting engine to use when converting text
              via the method format. Its default value is the empty string.
              The method format cannot be used if this option is not set to a
              valid value at least once.

              The package will immediately try to map the given name to a file
              containing the code for a formatting engine generating that
              format. An error will be thrown if this mapping fails. In that
              case a previously configured format is left untouched.

              The section FORMAT MAPPING explains in detail how the package
              and object will look for engine implementations.

   FORMAT MAPPING
       The package and object will perform the following algorithm when trying
       to map a format name foo to a file containing an implementation of a
       formatting engine for foo:

       [1]    If foo is the name of an existing file then this file is
              directly taken as the implementation.

       [2]    If not, the list of per-object search paths is searched. For
              each directory in the list the package checks if that directory
              contains a file "toc.foo". If yes, then that file is taken as
              the implementation.

              Note that this list of paths is initially empty and can be
              extended through the object method search.

       [3]    If not, the list of package paths is searched.  For each
              directory in the list the package checks if that directory
              contains a file "toc.foo". If yes, then that file is taken as
              the implementation.

              This list of paths can be extended through the command
              ::doctools::toc::search.  It contains initially one path, the
              subdirectory "mpformats" of the directory the package itself is
              located in. In other words, if the package implementation
              "doctoc.tcl" is installed in the directory
              "/usr/local/lib/tcllib/doctools" then it will by default search
              the directory "/usr/local/lib/tcllib/doctools/mpformats" for
              format implementations.

       [4]    The mapping fails.

PREDEFINED ENGINES
       The package provides predefined formatting engines for the following
       formats. Some of the formatting engines support engine parameters.
       These will be explicitly highlighted.

       html   This engine generates HTML markup, for processing by web
              browsers and the like. This engine supports three parameters:

              footer The value for this parameter has to be valid
                     selfcontained HTML markup for the body section of a HTML
                     document. The default value is the empty string. The
                     value is inserted into the generated output just before
                     the </body> tag, closing the body of the generated HTML.

                     This can be used to insert boilerplate footer markup into
                     the generated document.

              header The value for this parameter has to be valid
                     selfcontained HTML markup for the body section of a HTML
                     document. The default value is the empty string. The
                     value is inserted into the generated output just after
                     the <body> tag, starting the body of the generated HTML.

                     This can be used to insert boilerplate header markup into
                     the generated document.

              meta   The value for this parameter has to be valid
                     selfcontained HTML markup for the header section of a
                     HTML document. The default value is the empty string. The
                     value is inserted into the generated output just after
                     the <head> tag, starting the header section of the
                     generated HTML.

                     This can be used to insert boilerplate meta data markup
                     into the generated document, like references to a
                     stylesheet, standard meta keywords, etc.


       latex  This engine generates output suitable for the latex text
              processor coming out of the TeX world.

       list   This engine retrieves version, section and title of the manpage
              from the document. As such it can be used to generate a
              directory listing for a set of manpages.

       nroff  This engine generates nroff output, for processing by nroff, or
              groff. The result will be standard man pages as they are known
              in the unix world.

       null   This engine generates no outout at all. This can be used if one
              just wants to validate some input.

       tmml   This engine generates TMML markup as specified by Joe English.
              The Tcl Manpage Markup Language is a derivate of XML.

       wiki   This engine generates Wiki markup as understood by Jean Claude
              Wippler's wikit application.

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.

SEE ALSO
       doctoc_intro, doctoc_lang_cmdref, doctoc_lang_intro,
       doctoc_lang_syntax, doctoc_plugin_apiref

KEYWORDS
       HTML, TMML, conversion, doctoc, documentation, latex, manpage, markup,
       nroff, table of contents, toc, wiki

CATEGORY
       Documentation tools

COPYRIGHT
       Copyright (c) 2003-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>




doctools                             1.1.3                    doctools::toc(n)
