


doctoc_intro(n)        Documentation tools        doctoc_intro(n)


______________________________________________________________________________

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 documenta-
       tion. These are

       [1]    A tcl based language for the semantic markup of a table of  con-
              tents. 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 plu-
              gins.

       [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 conver-
              sion 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  documenta-
              tion,  automatically  generating  a proper table of contents for
              them.

       [2]    A processor of documentation written in the doctoc  markup  lan-
              guage 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,



doctools                       1.0                              1





doctoc_intro(n)        Documentation tools        doctoc_intro(n)


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

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>





























doctools                       1.0                              2


