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

NAME

       doctools::toc - doctoc - Processing tables of contents

SYNOPSIS

       package require Tcl  8.2

       package require doctools::toc  ?1.2?

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

       markdown
              This engine generates Markdown markup.

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

SEE ALSO

       doctoc_intro,       doctoc_lang_cmdref,       doctoc_lang_intro,       doctoc_lang_syntax,
       doctoc_plugin_apiref

KEYWORDS

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

CATEGORY

       Documentation tools

COPYRIGHT

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