dtplite(1) | Documentation toolbox | dtplite(1) |
dtplite - Lightweight DocTools Markup Processor
dtplite -o output ?options? format inputfile
dtplite validate inputfile
dtplite -o output ?options? format inputdirectory
dtplite -merge -o output ?options? format inputdirectory
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.
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.
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).
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.
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.
When used multiple times only the last definition is relevant.
When used multiple times only the last definition is relevant.
When used multiple times only the last definition is relevant.
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.
When used multiple times only the last definition is relevant.
Positioning and handling of multiple uses is like for options -prenav and -postnav, see below.
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 relative to the main files (TOC and Keyword index), and will be transformed for all others to still link properly.
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 relative to the main files (TOC and Keyword index), and will be transformed for all others to still link properly.
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:
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].
output/ toc.html index.html files/ path/to/FOO.html
inputdirectory/path/to/FOO
output .toc .idx .tocdoc .idxdoc .xrf toc.html index.html FOO1/ ... FOO2/ toc.html files/ path/to/BAR.html
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.
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 output 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.
docidx introduction, doctoc introduction, doctools introduction
HTML, TMML, conversion, docidx, doctoc, doctools, manpage, markup, nroff
Documentation tools
Copyright (c) 2004-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>
1.0.5 | tcllib |