


docidx_intro(n)        Documentation tools        docidx_intro(n)


______________________________________________________________________________

NAME
       docidx_intro - docidx introduction

DESCRIPTION
       docidx (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 keyword-based indices for documen-
       tation. These are

       [1]    A tcl based language for the semantic markup of a keyword index.
              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  docidx should read the more informally
              written docidx language introduction first. Having digested this
              the  formal  docidx  language syntax specification should become
              understandable. A writer experienced with docidx may  only  need
              the  docidx  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 docidx when handling directories  of  documenta-
              tion,  automatically generating a proper keyword index for them.

       [2]    A processor of documentation written in the docidx  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 docidx to the  user.
              At  the  bottom level, common to both applications, however sits
              the package doctoools::idx, providing the  basic  facilities  to
              read and process files containing text in the docidx format.

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



doctools                       1.0                              1





docidx_intro(n)        Documentation tools        docidx_intro(n)


RELATED FORMATS
       docidx  does  not  stand alone, it has two companion formats. These are
       called doctoc and doctools, and they are for the markup  of  tables  of
       contents,  and general documentation, respectively.  They are described
       in their own sets of documents, starting at the doctoc 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_lang_cmdref,         docidx_lang_faq,         docidx_lang_intro,
       docidx_lang_syntax,  docidx_plugin_apiref, doctoc_intro, doctools::idx,
       doctools_intro

KEYWORDS
       index, keyword index, markup, semantic markup

CATEGORY
       Documentation tools

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































doctools                       1.0                              2


