1doctools_intro(n) Documentation tools doctools_intro(n)
2______________________________________________________________________________
6
8 doctools_intro - doctools introduction
9
11 doctools (short for documentation tools) stands for a set of related,
12 yet different, entities which are working together for the easy cre‐
13 ation and transformation of documentation. These are
14 [1] A tcl based language for the semantic markup of text. Markup is
16 represented by Tcl commands interspersed with the actual text.
17 [2] A package providing the ability to read and transform texts
19 written in that markup language. It is important to note that
20 the actual transformation of the input text is delegated to
21 plugins.
22 [3] An API describing the interface between the package above and a
24 plugin.
25 Which of the more detailed documents are relevant to the reader of this
27 introduction depends on their role in the documentation process.
28 [1] A writer of documentation has to understand the markup language
30 itself. A beginner to doctools should read the more informally
31 written doctools language introduction first. Having digested
32 this the formal doctools language syntax specification should
33 become understandable. A writer experienced with doctools may
34 only need the doctools language command reference from time to
35 time to refresh her memory.
36 While a document is written the dtplite application can be used
38 to validate it, and after completion it also performs the con‐
39 version into the chosen system of visual markup, be it *roff,
40 HTML, plain text, wiki, etc.
41 [2] A processor of documentation written in the doctools markup lan‐
43 guage has to know which tools are available for use.
44 The main tool is the aforementioned dtplite application provided
46 by Tcllib. A more powerful one (in terms of options and ability
47 to configure it) is the dtp application, provided by Tclapps.
48 At the bottom level, common to both applications, however sits
49 the package doctools, providing the basic facilities to read and
50 process files containing text in the doctools format.
51 [3] At last, but not least, plugin writers have to understand the
53 interaction between the doctools package and its plugins, as
54 described in the doctools plugin API reference.
55
57 doctools does not stand alone, it has two companion formats. These are
58 called docidx and doctoc, and they are for the markup of keyword
59 indices, and tables of contents, respectively. They are described in
60 their own sets of documents, starting at the docidx introduction and
61 the doctoc introduction, respectively.
62
64 This document, and the package it describes, will undoubtedly contain
65 bugs and other problems. Please report such in the category doctools
66 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
67 also report any ideas for enhancements you may have for either package
68 and/or documentation.
69 When proposing code changes, please provide unified diffs, i.e the out‐
71 put of diff -u.
72 Note further that attachments are strongly preferred over inlined
74 patches. Attachments can be made by going to the Edit form of the
75 ticket immediately after its creation, and then using the left-most
76 button in the secondary navigation bar.
77
79 docidx_intro, doctoc_intro, doctools, doctools_lang_cmdref, doc‐
80 tools_lang_faq, doctools_lang_intro, doctools_lang_syntax, doc‐
81 tools_plugin_apiref
82
84 markup, semantic markup
85
87 Documentation tools
88
90 Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
91tcllib 1.0 doctools_intro(n)