1doctools2toc_introduction(n) Documentation tools doctools2toc_introduction(n)
2______________________________________________________________________________
6
8 doctools2toc_introduction - DocTools - Tables of Contents
9
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 These are
17 [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 [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 [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 Which of the more detailed documents are relevant to the reader of this
36 introduction depends on their role in the documentation process.
37 [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 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 [2] A processor of documentation written in the doctoc markup lan‐
55 guage has to know which tools are available for use.
56 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 doctoools::toc
66 Programmatic manipulation of tables of contents in mem‐
67 ory.
68 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 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 See also section Package Overview for an overview of the depen‐
80 dencies between these and other, supporting packages.
81 [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 · doctoools::toc::import
88 · 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
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
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 When proposing code changes, please provide unified diffs, i.e the out‐
140 put of diff -u.
141 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
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
153 contents, conversion, formatting, markup, parsing, plugin, semantic
154 markup, table of contents
155
157 Documentation tools
158
160 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
161tcllib 2.0 doctools2toc_introduction(n)