|
ActiveTcl User Guide
|
|
|
[ Main table Of Contents | Tcllib Table Of Contents | Tcllib Index ]
doctoc_api(n) 1.0 "Documentation tools"
doctoc_api - Interface specification for toc formatting code
This manpage specifies the interface between formatting engines
for data in the doctoc
format as specified in doctoc_fmt , and
doctools::toc, the package for the generic
handling of such data, as described in doctoc .
Each formatting engine has to implement the conversion of input
in doctoc format to one
particular output format as chosen by the author of the formatting
engine.
Each formatting engine has to provide
- Implementations of all the formatting commands as specified in
doctoc_fmt , using
the defined names, but prefixed with the string
fmt_. The sole exceptions to this are the
formatting commands vset and include. These two commands are processed by the generic
layer and will never be seen by the formatting engine.
- and additionally implementations for
- toc_numpasses
- This command is called immediately after the formatter is
loaded and has to return the number of passes required by this
formatter to process a manpage. This information has to be an
integer number greater or equal to one.
- toc_initialize
- This command is called at the beginning of every conversion run
and is responsible for initializing the general state of the
formatting engine.
- toc_setup n
- This command is called at the beginning of each pass over the
input and is given the id of the current pass as its first
argument. It is responsible for setting up the internal state of
the formatting for this particular pass.
- toc_postprocess text
- This command is called immediately after the last pass, with
the expansion result of that pass as argument, and can do any
last-ditch modifications of the generated result. Its result will
be the final result of the conversion.
Most formats will use identity here.
- toc_shutdown
- This command is called at the end of every conversion run and
is responsible for cleaning up of all the state in the formatting
engine.
- fmt_plain_text text
- This command is called for any plain text encountered by the
processor in the input and can do any special processing required
for plain text. Its result is the string written into the
expansion.
Most formats will use identity here.
- toc_listvariables
- The command is called after loading a formatting engine to
determine which parameters are supported by that engine. The return
value is a list containing the names of these parameters.
- toc_varset varname text
- The command is called by the generic layer to set the value of
an engine specific parameter. The parameter to change is specified
by varname, and the value to set is given in text.
The command will throw an error if an unknown varname is used. Only the names returned by toc_listvariables are considered known.
The tcl code of a formatting engine implementing all of the
above can make the following assumptions about its environment
- It has full access to its own safe interpreter. In other words,
the engine cannot damage the other parts of the processor, nor can
it damage the filesystem.
- The surrounding system provides the engine with the following
commands:
- Doctools commands
-
- dt_format
- Returns the name of format loaded into the engine
- dt_fmap fname
- Returns the actual name to use in the output in place of the
symbolic filename fname.
- dt_source file
- This command allows the engine to load additional tcl code. The
file being loaded has to be in the same directory as the file the
format engine was loaded from. Any path specified for file is ignored.
- Expander commands
- All of the commands below are methods of the expander object
(without the prefix ex_) handling the input. Their
arguments and results are described in
expander(n).
- ex_cappend
- ex_cget
- ex_cis
- ex_cname
- ex_cpop
- ex_cpush
- ex_cset
- ex_lb
- ex_rb
- _toc_common.tcl commands
- Any engine loading (dt_source) the file
"_toc_common.tcl" has default implementations of
the toc_ commands explicitly listed in this
document and of fmt_plaint_text.
doctoc , doctoc_fmt
HTML , LaTeX , TMML , generic markup , markup , nroff , table of contents , toc
Copyright © 2003 Andreas Kupries
<andreas_kupries@users.sourceforge.net>