doctoc_intro - doctoc introduction

       This  document,  and  the package it describes, will undoubtedly contain bugs and other problems.  Please
       report such in the category  doctools  of  the  TcllibTrackers  [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 unifieddiffs, 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.

       Documentation tools

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

tcllib                                                 1.0                                    doctoc_intro(3tcl)

doctoc  (short for documentationtablesofcontents) 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 doctoclanguageintroduction first. Having  digested  this
              the formal doctoclanguagesyntax specification should become understandable. A writer experienced
              with  doctoc  may only need the doctoclanguagecommandreference 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,  pluginwriters  have  to  understand  the  interaction  between  the
              doctools::toc package and its plugins, as described in the doctocpluginAPIreference.

       markup, semantic markup, table of contents, toc

       doctoc_intro - doctoc introduction

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

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