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.

+

-toc path

+

This option specifies a doctoc file to use for the table 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 relative +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 relative +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 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.

+