doctools(n) 1.0.1 "Documentation tools"

NAME

doctools - Create and manipulate doctools converter object

SYNOPSIS

package require Tcl 8.2
package require doctools ?1.0.1?

::doctools::new objectName ?option value...?
::doctools::help
::doctools::search path
objectName option ?arg arg ...?
objectName configure
objectName configure option
objectName configure option value...
objectName cget option
objectName destroy
objectName format text
objectName search path
objectName warnings

DESCRIPTION

This package provides objects which can be used to convert text written in the doctools format as specified in dtformat(n) into any output format X, assuming that a formatting engine for X is available and provides the interface specified in dtformatter(n).

API

::doctools::new objectName ?option value...?
Creates a new doctools object with an associated global Tcl command whose name is objectName. This command is explained in full detail in the sections OBJECT COMMAND and OBJECT METHODS.

The list of options and values coming after the name of the object is used to set the initial configuration of the object.

::doctools::help
This is a pure convenience command for applications which want to provide their user with a reminder of the available formatting commands and their meanings. It returns a string containing a standard help for this purpose.

::doctools::search path
Whenever the package has to map the name of a format to the file containing the code for its formatting engine it will search the file in a number of directories. Three such directories are declared by the package itself.

However the list is extensible by the user of the package and the command above is the means to do so. When given a path to an existing and readable directory it will prepend that directory to the existing list. This means that the path added last is searched through first.

An error will be thrown if the path either does not excist, is not a directory, or is not readable.

OBJECT COMMAND

All commands created by ::doctools::new have the following general form and may be used to invoke various operations on the object they are associated with.

objectName option ?arg arg ...?
The option and its args determine the exact behavior of the command. See section OBJECT METHODS for more explanations.

OBJECT METHODS

objectName configure
When called without argument this method returns a list of all known options and their current values.

objectName configure option
When called with a single argument this method behaves like cget.

objectName configure option value...
When called with more than one argument the method reconfigures the object using the options and values given to it.

The legal configuration options are described in section OBJECT CONFIGURATION.

objectName cget option
This method expects a legal configuration option as argument and returns the current value of that option for the object the method was invoked for.

The legal configuration options are described in section OBJECT CONFIGURATION.

objectName destroy
Destroys the object it is invoked for.

objectName format text
Takes the text and runs it through the configured formatting engine. The resulting string is returned as the result of this method. An error will be thrown if no -format was configured for the object.

The method assumes that the text is in doctools format as specified in dtformat(n). Errors will be thrown otherwise.

objectName search path
This method extends the per-object list of paths searched for formatting engines. See also ::doctools::search on how to extend the global (per-package) list of paths.

The path entered last is searched through first.

objectName warnings
Returns a list containing all the warnings generated by the engine during the last invocation of method format.

OBJECT CONFIGURATION

All doctools objects understand the following configuration options:

-file file
The argument of this option is stored in the object and can be retrieved by the formatting engine via the command dt_file (see dtformatter(n)). Its default value is the empty string.

It will be interpreted as the name of the file containing the text currently processed by the engine.

-module text
The argument of this option is stored in the object and can be retrieved by the formatting engine via the command dt_module (see dtformatter(n)). Its default value is the empty string.

It will be interpreted as the name of the module the file containing the text currently processed by the engine belongs to.

-format text
The argument of this option specifies the format and thus the engine to use when converting text via format. Its default value is the empty string. No formatting is possible if this option is not set at least once.

The package will immediately try to map the name of the format to a file containing the implementation of the engine for that format. An error will be thrown if this mapping fails and a previously configured format is left untouched.

Section FORMAT MAPPING explains how the package looks for engine implementations.

-deprecated boolean
This option is a flag. If set the object will generate warnings when formatting a text containing the deprecated markup command strong Its default value is FALSE. In other words, no warnings will be generated.

FORMAT MAPPING

When trying to map a format name foo to the file containing the implementation of formatting engine for foo the package will perform the following algorithm:

  1. If foo is the name of an existing file this file is directly taken as the implementation.

  2. If not, the list of per-object search paths is searched. For each directory in the list the package checks if that directory contains a file "fmt.foo". If yes, that file is taken as the implementation.

    This list of paths is initially empty and can be extended through the object method search.

  3. If not, the list of global (package) paths is searched. For each directory in the list the package checks if that directory contains a file "fmt.foo". If yes, that file is taken as the implementation.

    This list of paths contains initially one path and can be extended through the command ::doctools::search.

    The initial (standard) path is the sub directory "mpformats" of the directory the package itself is located in. In other words, if the package implementation "doctools.tcl" is installed in the directory "/usr/local/lib/tcllib/doctools" then it will by default search the directory "/usr/local/lib/tcllib/doctools/mpformats" for format implementations.

  4. The mapping fails.

ENGINES

The package comes with the following predefined formatting engines

html
This engine generates HTML markup, for processing by web browsers and the like.

latex
This engine generates output suitable for the latex text processor coming out of the TeX world.

list
This engine retrieves version, section and title of the manpage from the document. As such it can be used to generate a directory listing for a set of manpages.

nroff
This engine generates nroff output, for processing by nroff, or groff. The result will be standard man pages as they are known in the unix world.

null
This engine generates no outout at all. This can be used if one just wants to validate some input.

tmml
This engine generates TMML markup as specified by Joe English. The Tcl Manpage Markup Language is a derivate of XML.

wiki
This engine generates Wiki markup as understood by Jean Claude Wippler's wikit application.

SEE ALSO

doctools_api, doctools_fmt

KEYWORDS

HTML, TMML, conversion, documentation, index, manpage, markup, nroff, table of contents, toc

COPYRIGHT

Copyright © 2003 Andreas Kupries <andreas_kupries@users.sourceforge.net>