NAME

       doctoc_intro - doctoc introduction

DESCRIPTION

       doctoc  (short for documentation tables of contents) stands for a set of related, yet different, entities
       which are working  together  for  the  easy  creation  and  transformation  of  tables  of  contents  for
       documentation. These are

       [1]    A  tcl based language for the semantic markup of a table of contents. Markup is represented by Tcl
              commands.

       [2]    A package providing the ability to read and transform texts written in that markup language. It is
              important to note that the actual transformation of the input text is delegated to plugins.

       [3]    An API describing the interface between the package above and a plugin.

       Which  of  the  more  detailed documents are relevant to the reader of this introduction depends on their
       role in the documentation process.

       [1]    A writer of documentation has to understand the markup  language  itself.  A  beginner  to  doctoc
              should  read  the more informally written doctoc language introduction first. Having digested this
              the formal doctoc language syntax specification should become understandable. A writer experienced
              with  doctoc  may only need the doctoc language command reference from time to time to refresh her
              memory.

              While a document is written the dtp application can be used to validate it, and  after  completion
              it  also performs the conversion into the chosen system of visual markup, be it *roff, HTML, plain
              text, wiki, etc. The simpler dtplite application  makes  internal  use  of  doctoc  when  handling
              directories of documentation, automatically generating a proper table of contents for them.

       [2]    A  processor  of  documentation  written in the doctoc markup language has to know which tools are
              available for use.

              The main tool is the aforementioned dtp application provided by Tcllib. The simpler  dtplite  does
              not expose doctoc to the user.  At the bottom level, common to both applications, however sits the
              package doctoools::toc, providing the basic facilities to read and process files  containing  text
              in the doctoc format.

       [3]    At  last,  but  not  least,  plugin  writers  have  to  understand  the  interaction  between  the
              doctools::toc package and its plugins, as described in the doctoc plugin API reference.

RELATED FORMATS

       doctoc does not stand alone, it has two companion formats. These are called docidx and doctools, and they
       are  for  the  markup of keyword indices, and general documentation, respectively.  They are described in
       their own sets of  documents,  starting  at  the  docidx  introduction  and  the  doctools  introduction,
       respectively.

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.

SEE ALSO

       docidx_intro,     doctoc_lang_cmdref,     doctoc_lang_faq,     doctoc_lang_intro,     doctoc_lang_syntax,
       doctoc_plugin_apiref, doctools::toc, doctools_intro

KEYWORDS

       markup, semantic markup, table of contents, toc

CATEGORY

       Documentation tools

COPYRIGHT

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