docidx_intro - docidx 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                                    docidx_intro(3tcl)

docidx  (short for documentationtablesofcontents) stands for a set of related, yet different, entities
       which are working together for  the  easy  creation  and  transformation  of  keyword-based  indices  for
       documentation. 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 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 docidx
              should read the more informally written docidxlanguageintroduction first. Having  digested  this
              the formal docidxlanguagesyntax specification should become understandable. A writer experienced
              with  docidx  may only need the docidxlanguagecommandreference 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  docidx  when  handling
              directories of documentation, automatically generating a proper keyword index for them.

       [2]    A  processor  of  documentation  written in the docidx 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 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,  pluginwriters  have  to  understand  the  interaction  between  the
              doctools::idx package and its plugins, as described in the docidxpluginAPIreference.

       index, keyword index, markup, semantic markup

       docidx_intro - docidx introduction

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

       docidx_lang_cmdref,   docidx_lang_faq,   docidx_lang_intro,   docidx_lang_syntax,   docidx_plugin_apiref,
       doctoc_intro, doctools::idx, doctools_intro