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 in‐
32 terface 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 re‐
44 fresh 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 in‐
50 ternal use of doctoc when handling directories of documentation,
51 automatically generating a proper table of contents for them.
52 [2] A processor of documentation written in the doctoc markup lan‐
54 guage has to know which tools are available for use.
55 The main tool is the aforementioned dtp application provided by
57 Tcllib. The simpler dtplite does not expose doctoc to the user.
58 At the bottom level, common to both applications, however we
59 find the three packages providing the basic facilities to handle
60 tables of contents, i.e. import from textual formats, program‐
61 matic manipulation in memory, and export to textual formats.
62 These are
63 doctoools::toc
65 Programmatic manipulation of tables of contents in mem‐
66 ory.
67 doctoools::toc::import
69 Import of tables of contents from various textual for‐
70 mats. The set of supported formats is extensible through
71 plugin packages.
72 doctoools::toc::export
74 Export of tables of contents to various textual formats.
75 The set of supported formats is extensible through plugin
76 packages.
77 See also section Package Overview for an overview of the depen‐
79 dencies between these and other, supporting packages.
80 [3] At last, but not least, plugin writers have to understand the
82 interaction between the import and export packages and their
83 plugins. These APIs are described in the documentation for the
84 two relevant packages, i.e.
85 • doctoools::toc::import
87 • doctoools::toc::export
89
91 The doctoc format does not stand alone, it has two companion formats.
92 These are called docidx and doctools, and they are intended for the
93 markup of keyword indices, and of general documentation, respectively.
94 They are described in their own sets of documents, starting at the Doc‐
95 Tools - Keyword Indices and the DocTools - General, respectively.
96
98 ~~~~~~~~~~~ doctools::toc ~~~~~~~~~~~
99 ~~ | ~~
100 doctools::toc::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::toc::import
101 | | |
102 +---------------+-------------------------+ | +------------------+---------------+-----------------------+---------------+
103 | | | | | | | | |
104 struct:map = | | | = doctools::include struct::map fileutil::paths
105 | | | | |
106 doctools::toc::export::<*> | | | doctools::toc::import::<*>
107 doctoc | | | doctoc, json
108 json | | | | \
109 html | | | doctools::toc::parse \
110 nroff | | | | \
111 wiki | | | +---------------+ json
112 text | | | | |
113 doctools::toc::structure |
114 |
115 +-------+---------------+
116 | |
117 doctools::html doctools::html::cssdefaults doctools::tcl::parse doctools::msgcat
118 | |
119 doctools::text doctools::nroff::man_macros =
120 |
121 doctools::msgcat::toc::<*>
122 c, en, de, fr
123 (fr == en for now)
124 ~~ Interoperable objects, without actual package dependencies
125 -- Package dependency, higher requires lower package
126 = Dynamic dependency through plugin system
127 <*> Multiple packages following the given form of naming.
128
132 This document, and the package it describes, will undoubtedly contain
133 bugs and other problems. Please report such in the category doctools
134 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
135 also report any ideas for enhancements you may have for either package
136 and/or documentation.
137 When proposing code changes, please provide unified diffs, i.e the out‐
139 put of diff -u.
140 Note further that attachments are strongly preferred over inlined
142 patches. Attachments can be made by going to the Edit form of the
143 ticket immediately after its creation, and then using the left-most
144 button in the secondary navigation bar.
145
147 doctoc_intro, doctools, doctools2doc_introduction, doctools2idx_intro‐
148 duction, doctools_lang_cmdref, doctools_lang_faq, doctools_lang_intro,
149 doctools_lang_syntax, doctools_plugin_apiref
150
152 contents, conversion, formatting, markup, parsing, plugin, semantic
153 markup, table of contents
154
156 Documentation tools
157
159 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
160tcllib 2.0 doctools2toc_introduction(n)