1doctools2toc_introduction(n)  Documentation tools doctools2toc_introduction(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       doctools2toc_introduction - DocTools - Tables of Contents
9

DESCRIPTION

11       doctoc (short for documentation tables of contents) stands for a set of
12       related, yet different, entities which are  working  together  for  the
13       easy  creation and transformation of tables and contents for documenta‐
14       tion.
15
16       These are
17
18       [1]    A tcl based language for the semantic markup of a table of  con‐
19              tents.  Markup is represented by Tcl commands.  Beginners should
20              start with the doctoc language introduction.  The formal  speci‐
21              fication  is split over two documents, one dealing with the doc‐
22              toc language syntax, the other a doctoc language command  refer‐
23              ence.
24
25       [2]    A set of packages for the programmatic manipulation of tables of
26              contents in memory, and their conversion  between  various  for‐
27              mats, reading and writing. The aforementioned markup language is
28              one of the formats which can be both read from and written to.
29
30       [3]    The system for the conversion of tables of contents is based  on
31              a  plugin  mechanism,  for  this we have two APIs describing the
32              interface between the packages above and the import/export plug‐
33              ins.
34
35       Which of the more detailed documents are relevant to the reader of this
36       introduction depends on their role in the documentation process.
37
38       [1]    A writer of documentation has to understand the markup  language
39              itself.  A  beginner  to  doctoc should read the more informally
40              written doctoc language introduction first. Having digested this
41              the  formal  doctoc  language syntax specification should become
42              understandable. A writer experienced with doctoc may  only  need
43              the  doctoc  language  command  reference  from  time to time to
44              refresh her memory.
45
46              While a document is written the dtp application can be  used  to
47              validate  it,  and after completion it also performs the conver‐
48              sion into the chosen system of visual markup, be it *roff, HTML,
49              plain  text,  wiki,  etc.  The simpler dtplite application makes
50              internal use of doctoc when handling directories  of  documenta‐
51              tion,  automatically  generating  a proper table of contents for
52              them.
53
54       [2]    A processor of documentation written in the doctoc  markup  lan‐
55              guage has to know which tools are available for use.
56
57              The  main tool is the aforementioned dtp application provided by
58              Tcllib. The simpler dtplite does not expose doctoc to the  user.
59              At  the  bottom  level,  common to both applications, however we
60              find the three packages providing the basic facilities to handle
61              tables  of  contents, i.e. import from textual formats, program‐
62              matic manipulation in memory, and  export  to  textual  formats.
63              These are
64
65              doctoools::toc
66                     Programmatic  manipulation  of tables of contents in mem‐
67                     ory.
68
69              doctoools::toc::import
70                     Import of tables of contents from  various  textual  for‐
71                     mats.  The set of supported formats is extensible through
72                     plugin packages.
73
74              doctoools::toc::export
75                     Export of tables of contents to various textual  formats.
76                     The set of supported formats is extensible through plugin
77                     packages.
78
79              See also section Package Overview for an overview of the  depen‐
80              dencies between these and other, supporting packages.
81
82       [3]    At  last,  but  not least, plugin writers have to understand the
83              interaction between the import and  export  packages  and  their
84              plugins.   These APIs are described in the documentation for the
85              two relevant packages, i.e.
86
87              ·      doctoools::toc::import
88
89              ·      doctoools::toc::export
90
92       The doctoc format does not stand alone, it has two  companion  formats.
93       These  are  called  docidx  and doctools, and they are intended for the
94       markup of keyword indices, and of general documentation,  respectively.
95       They are described in their own sets of documents, starting at the Doc‐
96       Tools - Keyword Indices and the DocTools - General, respectively.
97

PACKAGE OVERVIEW

99                                                  ~~~~~~~~~~~ doctools::toc ~~~~~~~~~~~
100                                                 ~~                   |               ~~
101                              doctools::toc::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::toc::import
102                                      |                               |                       |
103                      +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
104                      |               |                         |     |    |                  |               |                       |               |
105              doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
106                                      |                         |     |    |                  |
107                              doctools::toc::export::<*>        |     |    |          doctools::toc::import::<*>
108                                      doctoc                    |     |    |                  doctoc, json
109                                      json                      |     |    |                  |           \\
110                                      html                      |     |    |          doctools::toc::parse \\
111                                      nroff                     |     |    |                  |             \\
112                                      wiki                      |     |    |  +---------------+              json
113                                      text                      |     |    |  |               |
114                                                              doctools::toc::structure        |
115                                                                                              |
116                                                                                      +-------+---------------+
117                                                                                      |                       |
118                        doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat
119                              |                                                                               |
120                        doctools::text  doctools::nroff::man_macros                                           =
121                                                                                                              |
122                                                                                                      doctools::msgcat::toc::<*>
123                                                                                                              c, en, de, fr
124                                                                                                              (fr == en for now)
125                      ~~      Interoperable objects, without actual package dependencies
126                      --      Package dependency, higher requires lower package
127                      =       Dynamic dependency through plugin system
128                      <*>     Multiple packages following the given form of naming.
129
130
131

BUGS, IDEAS, FEEDBACK

133       This document, and the package it describes, will  undoubtedly  contain
134       bugs  and  other problems.  Please report such in the category doctools
135       of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].   Please
136       also  report any ideas for enhancements you may have for either package
137       and/or documentation.
138
139       When proposing code changes, please provide unified diffs, i.e the out‐
140       put of diff -u.
141
142       Note  further  that  attachments  are  strongly  preferred over inlined
143       patches. Attachments can be made by going  to  the  Edit  form  of  the
144       ticket  immediately  after  its  creation, and then using the left-most
145       button in the secondary navigation bar.
146

SEE ALSO

148       doctoc_intro, doctools, doctools2doc_introduction,  doctools2idx_intro‐
149       duction,  doctools_lang_cmdref, doctools_lang_faq, doctools_lang_intro,
150       doctools_lang_syntax, doctools_plugin_apiref
151

KEYWORDS

153       contents, conversion, formatting,  markup,  parsing,  plugin,  semantic
154       markup, table of contents
155

CATEGORY

157       Documentation tools
158
160       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
161
162
163
164
165tcllib                                2.0         doctools2toc_introduction(n)
Impressum