NAME¶
dtplite - Lightweight DocTools Markup Processor
SYNOPSIS¶
dtplite -o output ?options?
format inputfile
dtplite validate inputfile
dtplite -o output ?options?
format
inputdirectory
dtplite -merge -o output ?options?
format
inputdirectory
DESCRIPTION¶
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.
USE CASES¶
dtplite was written with the following three use cases in mind.
- [1]
- 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.
- [2]
- Generation of the formatted documentation for a single
package, i.e. all the manpages, plus a table of contents and an index of
keywords.
- [3]
- An extension of the previous mode of operation, a method
for the easy generation of one documentation tree for several packages,
and especially of a 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.
COMMAND LINE¶
- 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 validate inputfile
- This is a simpler form for use case [1]. The
"validate" format generates no output at all, only syntax checks
are performed. As such the specification of an output file or other
options is not necessary and left out.
- 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).
OPTIONS¶
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.
- -exclude string
- This option specifies an exclude (glob) pattern. Any files
identified as manpages to process which match the exclude pattern are
ignored. The option can be provided multiple times, each usage adding an
additional pattern to the list of exclusions.
- -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. This is
equivalent to validate.
DIRECTORY STRUCTURES¶
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
.tocdoc
.idxdoc
.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.
The files " .tocdoc", and ".idxdoc", are
intermediate files in doctoc and docidx markup, respectively, containing
the main table of contents and keyword index for the set of documents
before their conversion to the chosen output format. They are left in
place, i.e. not deleted, to serve as demonstrations of doctoc and docidx
markup.
BUGS, IDEAS, FEEDBACK¶
This document, and the application it describes, 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 for either
application and/or documentation.
SEE ALSO¶
docidx introduction, doctoc introduction, doctools introduction
KEYWORDS¶
HTML, TMML, conversion, docidx, doctoc, doctools, manpage, markup, nroff
CATEGORY¶
Documentation tools
COPYRIGHT¶
Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>