doctools2toc_introduction(n)  Documentation tools doctools2toc_introduction(n)



______________________________________________________________________________

NNAAMMEE
       doctools2toc_introduction - DocTools - Tables of Contents

DDEESSCCRRIIPPTTIIOONN
       _d_o_c_t_o_c (short for _d_o_c_u_m_e_n_t_a_t_i_o_n _t_a_b_l_e_s _o_f _c_o_n_t_e_n_t_s) stands for a set of
       related, yet different, entities which are working together for the
       easy creation and transformation of tables and 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.  Beginners
              should start with the _d_o_c_t_o_c _l_a_n_g_u_a_g_e _i_n_t_r_o_d_u_c_t_i_o_n.  The formal
              specification is split over two documents, one dealing with the
              _d_o_c_t_o_c _l_a_n_g_u_a_g_e _s_y_n_t_a_x, the other a _d_o_c_t_o_c _l_a_n_g_u_a_g_e _c_o_m_m_a_n_d
              _r_e_f_e_r_e_n_c_e.

       [2]    A set of packages for the programmatic manipulation of tables of
              contents in memory, and their conversion between various
              formats, reading and writing. The aforementioned markup language
              is one of the formats which can be both read from and written
              to.

       [3]    The system for the conversion of tables of contents is based on
              a plugin mechanism, for this we have two APIs describing the
              interface between the packages above and the import/export
              plugins.

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

       [1]    A _w_r_i_t_e_r of documentation has to understand the markup language
              itself. A beginner to doctoc should read the more informally
              written _d_o_c_t_o_c _l_a_n_g_u_a_g_e _i_n_t_r_o_d_u_c_t_i_o_n first. Having digested this
              the formal _d_o_c_t_o_c _l_a_n_g_u_a_g_e _s_y_n_t_a_x specification should become
              understandable. A writer experienced with doctoc may only need
              the _d_o_c_t_o_c _l_a_n_g_u_a_g_e _c_o_m_m_a_n_d _r_e_f_e_r_e_n_c_e from time to time to
              refresh her memory.

              While a document is written the ddttpp 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 ddttpplliittee application
              makes internal use of doctoc when handling directories of
              documentation, automatically generating a proper table of
              contents for them.

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

              The main tool is the aforementioned ddttpp application provided by
              Tcllib. The simpler ddttpplliittee does not expose doctoc to the user.
              At the bottom level, common to both applications, however we
              find the three packages providing the basic facilities to handle
              tables of contents, i.e. import from textual formats,
              programmatic manipulation in memory, and export to textual
              formats. These are

              ddooccttoooooollss::::ttoocc
                     Programmatic manipulation of tables of contents in
                     memory.

              ddooccttoooooollss::::ttoocc::::iimmppoorrtt
                     Import of tables of contents from various textual
                     formats. The set of supported formats is extensible
                     through plugin packages.

              ddooccttoooooollss::::ttoocc::::eexxppoorrtt
                     Export of tables of contents to various textual formats.
                     The set of supported formats is extensible through plugin
                     packages.

              See also section PPaacckkaaggee OOvveerrvviieeww for an overview of the
              dependencies between these and other, supporting packages.

       [3]    At last, but not least, _p_l_u_g_i_n _w_r_i_t_e_r_s have to understand the
              interaction between the import and export packages and their
              plugins.  These APIs are described in the documentation for the
              two relevant packages, i.e.

              o      ddooccttoooooollss::::ttoocc::::iimmppoorrtt

              o      ddooccttoooooollss::::ttoocc::::eexxppoorrtt

RREELLAATTEEDD FFOORRMMAATTSS
       The doctoc format does not stand alone, it has two companion formats.
       These are called _d_o_c_i_d_x and _d_o_c_t_o_o_l_s, and they are intended for the
       markup of _k_e_y_w_o_r_d _i_n_d_i_c_e_s, and of general documentation, respectively.
       They are described in their own sets of documents, starting at the
       _D_o_c_T_o_o_l_s _- _K_e_y_w_o_r_d _I_n_d_i_c_e_s and the _D_o_c_T_o_o_l_s _- _G_e_n_e_r_a_l, respectively.

PPAACCKKAAGGEE OOVVEERRVVIIEEWW
                                                  ~~~~~~~~~~~ doctools::toc ~~~~~~~~~~~
                                                 ~~                   |               ~~
                              doctools::toc::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::toc::import
                                      |                               |                       |
                      +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
                      |               |                         |     |    |                  |               |                       |               |
              doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
                                      |                         |     |    |                  |
                              doctools::toc::export::<*>        |     |    |          doctools::toc::import::<*>
                                      doctoc                    |     |    |                  doctoc, json
                                      json                      |     |    |                  |           \\
                                      html                      |     |    |          doctools::toc::parse \\
                                      nroff                     |     |    |                  |             \\
                                      wiki                      |     |    |  +---------------+              json
                                      text                      |     |    |  |               |
                                                              doctools::toc::structure        |
                                                                                              |
                                                                                      +-------+---------------+
                                                                                      |                       |
                        doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat
                              |                                                                               |
                        doctools::text  doctools::nroff::man_macros                                           =
                                                                                                              |
                                                                                                      doctools::msgcat::toc::<*>
                                                                                                              c, en, de, fr
                                                                                                              (fr == en for now)
                      ~~      Interoperable objects, without actual package dependencies
                      --      Package dependency, higher requires lower package
                      =       Dynamic dependency through plugin system
                      <*>     Multiple packages following the given form of naming.



BBUUGGSS,, IIDDEEAASS,, FFEEEEDDBBAACCKK
       This document, and the package it describes, will undoubtedly contain
       bugs and other problems.  Please report such in the category _d_o_c_t_o_o_l_s
       of the _T_c_l_l_i_b _T_r_a_c_k_e_r_s [http://core.tcl.tk/tcllib/reportlist].  Please
       also report any ideas for enhancements you may have for either package
       and/or documentation.

SSEEEE AALLSSOO
       doctoc_intro, doctools, doctools2doc_introduction,
       doctools2idx_introduction, doctools_lang_cmdref, doctools_lang_faq,
       doctools_lang_intro, doctools_lang_syntax, doctools_plugin_apiref

KKEEYYWWOORRDDSS
       contents, conversion, formatting, markup, parsing, plugin, semantic
       markup, table of contents

CCAATTEEGGOORRYY
       Documentation tools

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




tcllib                                2.0         doctools2toc_introduction(n)
