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, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category
doctools of the
Tcllib Trackers [
http://core.tcl.tk/tcllib/reportlist]. Please also
report any ideas for enhancements you may have for either package and/or
documentation.
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>