Tcl Library Source Code

Documentation
Login


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

dtplite - Lightweight DocTools Markup Processor

Table Of Contents

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

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.

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 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:

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].

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. 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.

SEE ALSO

docidx introduction, doctoc introduction, doctools introduction

KEYWORDS

HTML, TMML, conversion, docidx, doctoc, doctools, manpage, markup, nroff

CATEGORY

Documentation tools

COPYRIGHT

Copyright © 2004-2013 Andreas Kupries