Tcl Library Source Code

Documentation
Login


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

NAME

doctools - doctools - Processing documents

Table Of Contents

SYNOPSIS

package require Tcl 8.2
package require doctools ?1.5.6?

::doctools::new objectName ?option value...?
::doctools::help
::doctools::search path
objectName method ?arg arg ...?
objectName configure
objectName configure option
objectName configure -option value...
objectName cget -option
objectName destroy
objectName format text
objectName map symbolic actual
objectName parameters
objectName search path
objectName setparam name value
objectName warnings

DESCRIPTION

This package provides a class for the creation of objects able to process and convert text written in the doctools markup language into any output format X for which a formatting engine is available.

A reader interested in the markup language itself should start with the doctools language introduction and proceed from there to the formal specifications, i.e. the doctools language syntax and the doctools language command reference.

If on the other hand the reader wishes to write her own formatting engine for some format, i.e. is a plugin writer then reading and understanding the doctools plugin API reference is an absolute necessity, as that document specifies the interaction between this package and its plugins, i.e. the formatting engines, in detail.

PUBLIC API

PACKAGE COMMANDS

OBJECT COMMAND

All commands created by ::doctools::new have the following general form and may be used to invoke various operations on their doctools converter object.

OBJECT METHODS

OBJECT CONFIGURATION

All doctools objects understand the following configuration options:

FORMAT MAPPING

The package and object will perform the following algorithm when trying to map a format name foo to a file containing an implementation of a formatting engine for foo:

  1. If foo is the name of an existing file then 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, then that file is taken as the implementation.

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

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

    This list of paths can be extended through the command ::doctools::search. It contains initially one path, the subdirectory "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.

PREDEFINED ENGINES

The package provides predefined engines for the following formats. Some of the engines support parameters. These will be explained below as well.

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

doctools_intro, doctools_lang_cmdref, doctools_lang_intro, doctools_lang_syntax, doctools_plugin_apiref

KEYWORDS

HTML, TMML, conversion, documentation, manpage, markdown, markup, nroff

CATEGORY

Documentation tools

COPYRIGHT

Copyright © 2003-2019 Andreas Kupries