1doctools2idx_introduction(n) Documentation tools doctools2idx_introduction(n)
2______________________________________________________________________________
6
8 doctools2idx_introduction - DocTools - Keyword indices
9
11 docidx (short for documentation indices) stands for a set of related,
12 yet different, entities which are working together for the easy cre‐
13 ation and transformation of keyword indices for documentation.
14 These are
16 [1] A tcl based language for the semantic markup of a keyword index.
18 Markup is represented by Tcl commands. Beginners should start
19 with the docidx language introduction. The formal specification
20 is split over two documents, one dealing with the docidx lan‐
21 guage syntax, the other a docidx language command reference.
22 [2] A set of packages for the programmatic manipulation of keyword
24 indices in memory, and their conversion between various formats,
25 reading and writing. The aforementioned markup language is one
26 of the formats which can be both read from and written to.
27 [3] The system for the conversion of indices is based on a plugin
29 mechanism, for this we have two APIs describing the interface
30 between the packages above and the import/export plugins.
31 Which of the more detailed documents are relevant to the reader of this
33 introduction depends on their role in the documentation process.
34 [1] A writer of documentation has to understand the markup language
36 itself. A beginner to docidx should read the more informally
37 written docidx language introduction first. Having digested this
38 the formal docidx language syntax specification should become
39 understandable. A writer experienced with docidx may only need
40 the docidx language command reference from time to time to re‐
41 fresh her memory.
42 While a document is written the dtp application can be used to
44 validate it, and after completion it also performs the conver‐
45 sion into the chosen system of visual markup, be it *roff, HTML,
46 plain text, wiki, etc. The simpler dtplite application makes in‐
47 ternal use of docidx when handling directories of documentation,
48 automatically generating a proper keyword index for them.
49 [2] A processor of documentation written in the docidx markup lan‐
51 guage has to know which tools are available for use.
52 The main tool is the aforementioned dtp application provided by
54 Tcllib. The simpler dtplite does not expose docidx to the user.
55 At the bottom level, common to both applications, however we
56 find the three packages providing the basic facilities to handle
57 keyword indices, i.e. import from textual formats, programmatic
58 manipulation in memory, and export to textual formats. These are
59 doctools::idx
61 Programmatic manipulation of keyword indices in memory.
62 doctools::idx::import
64 Import of keyword indices from various textual formats.
65 The set of supported formats is extensible through plugin
66 packages.
67 doctools::idx::export
69 Export of keyword indices to various textual formats. The
70 set of supported formats is extensible through plugin
71 packages.
72 See also section Package Overview for an overview of the depen‐
74 dencies between these and other, supporting packages.
75 [3] At last, but not least, plugin writers have to understand the
77 interaction between the import and export packages and their
78 plugins. These APIs are described in the documentation for the
79 two relevant packages, i.e.
80 • doctools::idx::import
82 • doctools::idx::export
84
86 The docidx format does not stand alone, it has two companion formats.
87 These are called doctoc and doctools, and they are intended for the
88 markup of tables of contents, and of general documentation, respec‐
89 tively. They are described in their own sets of documents, starting at
90 the DocTools - Tables Of Contents and the DocTools - General, respec‐
91 tively.
92
94 ~~~~~~~~~~~ doctools::idx ~~~~~~~~~~~
95 ~~ | ~~
96 doctools::idx::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::idx::import
97 | | |
98 +---------------+-------------------------+ | +------------------+---------------+-----------------------+---------------+
99 | | | | | | | | |
100 struct::map = | | | = doctools::include struct::map fileutil::paths
101 | | | | |
102 doctools::idx::export::<*> | | | doctools::idx::import::<*>
103 docidx | | | docidx, json
104 json | | | | \
105 html | | | doctools::idx::parse \
106 nroff | | | | \
107 wiki | | | +---------------+ json
108 text | | | | |
109 doctools::idx::structure |
110 |
111 +-------+---------------+
112 | |
113 doctools::html doctools::html::cssdefaults doctools::tcl::parse doctools::msgcat
114 | |
115 doctools::text doctools::nroff::man_macros =
116 |
117 doctools::msgcat::idx::<*>
118 c, en, de, fr
119 (fr == en for now)
120 ~~ Interoperable objects, without actual package dependencies
121 -- Package dependency, higher requires lower package
122 = Dynamic dependency through plugin system
123 <*> Multiple packages following the given form of naming.
124
128 This document, and the package it describes, will undoubtedly contain
129 bugs and other problems. Please report such in the category doctools
130 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
131 also report any ideas for enhancements you may have for either package
132 and/or documentation.
133 When proposing code changes, please provide unified diffs, i.e the out‐
135 put of diff -u.
136 Note further that attachments are strongly preferred over inlined
138 patches. Attachments can be made by going to the Edit form of the
139 ticket immediately after its creation, and then using the left-most
140 button in the secondary navigation bar.
141
143 docidx_intro, doctoc_intro, doctools, doctools2doc_introduction, doc‐
144 tools2toc_introduction, doctools_lang_cmdref, doctools_lang_faq, doc‐
145 tools_lang_intro, doctools_lang_syntax, doctools_plugin_apiref
146
148 conversion, formatting, index, keyword index, markup, parsing, plugin,
149 semantic markup
150
152 Documentation tools
153
155 Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
156tcllib 2.0 doctools2idx_introduction(n)