|
ActiveTcl User Guide
|
|
|
[ Main table Of Contents | Tcllib Table Of Contents | Tcllib Index ]
dtplite(n) 1.0 "Documentation toolbox"
dtplite - Lightweight DocTools Markup Processor
TABLE OF
CONTENTS
SYNOPSIS
DESCRIPTION
USE CASES
COMMAND LINE
OPTIONS
FORMATS
DIRECTORY STRUCTURES
SEE ALSO
KEYWORDS
COPYRIGHT
The application described by this document, dtplite , is the successor to the
extremely simple mpexpand . Influenced in
its functionality by the dtp doctools processor it
is much more powerful than mpexpand , yet still as
easy to use; definitely easier than dtp with its
myriad of subcommands and options.
dtplite is based
upon the package doctools, like the other two
processors .
dtplite was written
with the following three use cases in mind.
- Validation of a single document, i.e. checking that it was
written in valid doctools format. This mode can also be used to get
a preliminary version of the formatted output for a single
document, for display in a browser, nroff, etc., allowing
proofreading of the formatting.
- Generation of the formatted documentation for a single package,
i.e. all the manpages, plus a table of contents and an index of
keywords.
- An extension of the previous mode of operation, a method for
the easy generation of one documentation tree for several packages.
Especially unified table of contents and keyword index.
Beyond the above we also want to make use of the customization
features provided by the HTML formatter. It is not the only format
the application should be able to generate, but we anticipiate it
to be the most commonly used, and it is one of the few which do
provide customization hooks.
We allow the caller to specify a header string, footer string, a
stylesheet, and data for a bar of navigation links at the top of
the generated document. While all can be set as long as the
formatting engine provides an appropriate engine parameter (See
section OPTIONS) the last two have internal
processing which make them specific to HTML.
- dtplite -o output ?options? format inputfile
- This is the form for use case [1]. The options will be explained later, in section OPTIONS.
- path output (in)
- This argument specifies where to write the generated document.
It can be the path to a file or directory, or -.
The last value causes the application to write the generated
documented to stdout.
If the output does not exist then [file dirname
$output] has to exist and must be a writable directory. The
generated document will be written to a file in that directory, and
the name of that file will be derived from the inputfile, the format, and the value
given to option -ext (if present).
- (path|handle) format (in)
- This argument specifies the formatting engine to use when
processing the input, and thus the format of the generated
document. See section FORMATS for the
possibilities recognized by the application.
- path inputfile (in)
- This argument specifies the path to the file to process. It has
to exist, must be readable, and written in doctools format.
- dtplite -o output ?options? format inputdirectory
- This is the form for use case [2]. It differs from the form for
use case [1] by having the input documents specified through a
directory instead of a file. The other arguments are identical,
except for output, which now has to be the path
to an existing and writable directory.
The input documents are all files in inputdirectory or any of its subdirectories which were
recognized by fileutil::fileType as containing
text in doctools
format.
- dtplite -merge
-o output ?options? format inputdirectory
- This is the form for use case [3]. The only difference to the
form for use case [2] is the additional option
-merge.
Each such call will merge the generated documents coming from
processing the input documents under inputdirectory or any of its subdirectories to the files
under output. In this manner it is possible to
incrementally build the unified documentation for any number of
packages. Note that it is necessary to run through all the packages
twice to get fully correct cross-references (for formats supporting
them).
This section describes all the options available to the user of
the application, with the exception of the options
-o and -merge. These two were
described already, in section COMMAND
LINE.
- -ext string
- If the name of an output file has to be derived from the name
of an input file it will use the name of the format as the extension by default. This option here will
override this however, forcing it to use string
as the file extension. This option is ignored if the name of the
output file is fully specified through option
-o.
When used multiple times only the last definition is relevant.
- -header file
- This option can be used if and only if the selected format provides an engine parameter named "header". It
takes the contents of the specified file and assign them to that
parameter, for whatever use by the engine. The HTML engine will
insert the text just after the tag <body>.
If navigation buttons are present (see option -nav
below), then the HTML generated for them is appended to the header
data originating here before the final assignment to the
parameter.
When used multiple times only the last definition is relevant.
- -footer file
- Like -header, except that: Any navigation
buttons are ignored, the corresponding required engine parameter is
named "footer", and the data is inserted just before the tag
</body>.
When used multiple times only the last definition is relevant.
- -style file
- This option can be used if and only if the selected format provides an engine parameter named "meta". When
specified it will generate a piece of HTML code declaring the file as the stylesheet for the generated document
and assign that to the parameter. The HTML engine will insert this
inot the document, just after the tag
<head>.
When processing an input directory the stylesheet file is copied
into the output directory and the generated HTML will refer to the
copy, to make the result more self-contained. When processing an
input file we have no location to copy the stylesheet to and so
just reference it as specified.
When used multiple times only the last definition is relevant.
- -nav label url
- Use this option to specify a navigation button with label to display and the url to link
to. This option can be used if and only if the selected format provides an engine parameter named "header". The
HTML generated for this is appended to whatever data we got from
option -header before it is inserted into the
generated documents.
When used multiple times all definitions are collected and a
navigation bar is created, with the first definition shown at the
left edge and the last definition to the right.
At first the format argument will be treated
as a path to a tcl file containing the code for the requested
formatting engine. The argument will be treated as the name of one
of the predefined formats listed below if and only if the path does
not exist.
Note a limitation: If treating the format as path to
the tcl script implementing the engine was sucessful, then this
script has to implement not only the engine API for doctools, i.e.
doctools_api ,
but for doctoc_api and docidx_api as well.
Otherwise the generation of a table of contents and of a keyword
index will fail.
List of predefined formats, i.e. as provided by the package
doctools:
- nroff
- The processor generates *roff output, the standard format for
unix manpages.
- html
- The processor generates HTML output, for usage in and display
by web browsers. This engine is currently the only one providing
the various engine parameters required for the additional
customaization of the output.
- tmml
- The processor generates TMML output, the Tcl Manpage Markup
Language, a derivative of XML.
- latex
- The processor generates LaTeX output.
- wiki
- The processor generates Wiki markup as understood by
wikit.
- list
- The processor extracts the information provided by manpage_begin. This format is used internally to extract
the meta data from which both table of contents and keyword index
are derived from.
- null
- The processor does not generate any output.
In this section we describe the directory structures generated
by the application under output when processing
all documents in an inputdirectory. In other
words, this is only relevant to the use cases [2] and [3].
- [2]
- The following directory structure is created when processing a
single set of input documents. The file extension used is for
output in HTML, but that is not relevant to the structure and was
just used to have proper file names.
|
output/
toc.html
index.html
files/
path/to/FOO.html
|
The last line in the example shows the document generated for a
file FOO located at
|
inputdirectory/path/to/FOO
|
- [3]
- When merging many packages into a unified set of documents the
generated directory structure is a bit deeper:
|
output
.toc
.idx
.xrf
toc.html
index.html
FOO1/
...
FOO2/
toc.html
files/
path/to/BAR.html
|
Each of the directories FOO1, ... contains the documents generated
for the package FOO1, ... and follows the structure shown for use
case [2]. The only exception is that there is no per-package
index.
The files ".toc", ".idx", and
".xrf" contain the internal status of the whole
output and will be read and updated by the next invokation. Their
contents will not be documented. Remove these files when all
packages wanted for the output have been processed, i.e. when the
output is complete.
docidx_api , docidx_fmt , doctoc_api , doctoc_fmt , doctools_api , doctools_fmt
HTML , TMML , conversion , doctools , manpage , markup , nroff
Copyright © 2004 Andreas Kupries
<andreas_kupries@users.sourceforge.net>