doctoc(n) 1.0 doctools "Documentation tools"
doctoc - Create and manipulate doctoc converter objects
package require Tcl 8.2
package require doctools::toc ?1.0?
This package provides objects which can be used to convert text
written in the doctoc format as specified in doctoc_fmt into
any output format X, assuming that a formatting engine for X is
available and provides the interface specified in doctoc_api.
- ::doctools::toc::new objectName ?option value...?
-
Creates a new doctoc 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::toc::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::toc::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.
All commands created by ::doctools::toc::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.
- 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 doctoc 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::toc::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.
All doctoc 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.
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:
-
If foo is the name of an existing file this file is directly
taken as the implementation.
-
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.
-
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 "toc.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::toc::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 "doctoc.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.
-
The mapping fails.
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.
doctoc_api, doctoc_fmt
HTML, TMML, conversion, documentation, index, manpage, markup, nroff, table of contents, toc
Copyright © 2003 Andreas Kupries <andreas_kupries@users.sourceforge.net>