NAME¶
doctools_intro - doctools introduction
DESCRIPTION¶
doctools (short for
documentation tools) stands for a set of
related, yet different, entities which are working together for the easy
creation and transformation of documentation. These are
- [1]
- A tcl based language for the semantic markup of text.
Markup is represented by Tcl commands interspersed with the actual
text.
- [2]
- A package providing the ability to read and transform texts
written in that markup language. It is important to note that the actual
transformation of the input text is delegated to plugins.
- [3]
- An API describing the interface between the package above
and a plugin.
Which of the more detailed documents are relevant to the reader of this
introduction depends on their role in the documentation process.
- [1]
- A writer of documentation has to understand the
markup language itself. A beginner to doctools should read the more
informally written doctools language introduction first. Having
digested this the formal doctools language syntax specification
should become understandable. A writer experienced with doctools may only
need the doctools language command reference from time to time to
refresh her memory.
While a document is written the dtplite application can be used to
validate it, and after completion it also performs the conversion into the
chosen system of visual markup, be it *roff, HTML, plain text, wiki,
etc.
- [2]
- A processor of documentation written in the
doctools markup language has to know which tools are available for
use.
The main tool is the aforementioned dtplite application provided by
Tcllib. A more powerful one (in terms of options and ability to configure
it) is the dtp application, provided by Tclapps. At the bottom
level, common to both applications, however sits the package
doctools, providing the basic facilities to read and process files
containing text in the doctools format.
- [3]
- At last, but not least, plugin writers have to
understand the interaction between the doctools package and its
plugins, as described in the doctools plugin API reference.
doctools does not stand alone, it has two companion formats. These are called
docidx and
doctoc, and they are for the markup of
keyword
indices, and
tables of contents, respectively. They are described
in their own sets of documents, starting at the
docidx introduction and
the
doctoc introduction, respectively.
BUGS, IDEAS, FEEDBACK¶
This document, will undoubtedly contain bugs and other problems. Please report
such in the category
doctools of the
Tcllib SF Trackers
[
http://sourceforge.net/tracker/?group_id=12883]. Please also report any ideas
for enhancements you may have.
SEE ALSO¶
docidx_intro, doctoc_intro, doctools, doctools_lang_cmdref, doctools_lang_faq,
doctools_lang_intro, doctools_lang_syntax, doctools_plugin_apiref
KEYWORDS¶
markup, semantic markup
CATEGORY¶
Documentation tools
COPYRIGHT¶
Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>