


doctools2toc_introductioDno(cnu)mentation tdooocltsools2toc_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 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.  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  speci-
              fication  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  for-
              mats, 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 plug-
              ins.


       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 conver-
              sion 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  documenta-
              tion,  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  lan-
              guage has to know which tools are available for use.




doctools2toc                   2.0                              1





doctools2toc_introductioDno(cnu)mentation tdooocltsools2toc_introduction(n)


              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, program-
              matic manipulation in memory, and  export  to  textual  formats.
              These are

              ddooccttoooooollss::::ttoocc
                     Programmatic  manipulation  of tables of contents in mem-
                     ory.

              ddooccttoooooollss::::ttoocc::::iimmppoorrtt
                     Import of tables of contents from  various  textual  for-
                     mats.  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 \\



doctools2toc                   2.0                              2





doctools2toc_introductioDno(cnu)mentation tdooocltsools2toc_introduction(n)


                               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       _S_F       _T_r_a_c_k_e_r_s       [http://source-
       forge.net/tracker/?group_id=12883].   Please  also report any ideas for
       enhancements you may have for either package and/or documentation.

SSEEEE AALLSSOO
       doctools2doc_introduction, doctools2idx_introduction

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>

















doctools2toc                   2.0                              3


