dtplite(3tcl) Documentation toolbox dtplite(3tcl)
______________________________________________________________________________
NAME
dtplite - Lightweight DocTools Markup Processor
SYNOPSIS
package require dtplite ?1.3.1?
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 proces-
sors.
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 writ-
ten in valid doctools format. This mode can also be used to get
a preliminary version of the formatted output for a single docu-
ment, for display in a browser, nroff, etc., allowing proofread-
ing 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 applica-
tion 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 en-
gine 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 doc-
ument. It can be the path to a file or directory, or -.
The last value causes the application to write the gener-
ated documented to stdout.
If the output does not exist then [file dirname $output]
has to exist and must be a writable directory. The gen-
erated document will be written to a file in that direc-
tory, 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 gener-
ated 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 doc-
tools 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 ap-
plication, 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 iden-
tified as manpages to process which match the exclude pattern
are ignored. The option can be provided multiple times, each us-
age 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 exten-
sion 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 pro-
vides 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 ap-
pended to the header data originating here before the final as-
signment 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 pro-
vides 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 pa-
rameter. 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 process-
ing 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.
-toc path|text
This option specifies a doctoc file (or text) to use for the ta-
ble of contents instead of generating our own.
When used multiple times only the last definition is relevant.
-pre+toc label path|text
-post+toc label path|text
This option specifies additional doctoc files (or texts) to use
in the navigation bar.
Positioning and handling of multiple uses is like for options
-prenav and -postnav, see below.
-nav label url
-prenav 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.
The url can be relative. In that case it is assumed to be rela-
tive to the main files (TOC and Keyword index), and will be
transformed for all others to still link properly.
-postnav 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 last definition shown at the
right edge and the first definition to the left.
The url can be relative. In that case it is assumed to be rela-
tive to the main files (TOC and Keyword index), and will be
transformed for all others to still link properly.
FORMATS
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 be-
low if and only if the path does not exist.
Note a limitation: If treating the format as path to the tcl script im-
plementing the engine was sucessful, then this script has to implement
not only the engine API for doctools, i.e. doctools_api, but for doc-
toc_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 cus-
tomaization of the output.
tmml The processor generates TMML output, the Tcl Manpage Markup Lan-
guage, 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_be-
gin. 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 inputdi-
rectory. 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 gener-
ated 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 in-
vokation. Their contents will not be documented. Remove these
files when all packages wanted for the output have been pro-
cessed, i.e. when the output is complete.
The files ".tocdoc", and ".idxdoc", are intermediate files in
doctoc and docidx markup, respectively, containing the main ta-
ble of contents and keyword index for the set of documents be-
fore 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 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.
When proposing code changes, please provide unified diffs, i.e the out-
put of diff -u.
Note further that attachments are strongly preferred over inlined
patches. Attachments can be made by going to the Edit form of the
ticket immediately after its creation, and then using the left-most
button in the secondary navigation bar.
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-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>
tcllib 1.3.1 dtplite(3tcl)