|
ActiveTcl User Guide
|
|
|
[ Main table Of Contents | Tcllib Table Of Contents | Tcllib Index ]
doctoc_api(n) 1.0 "Documentation tools"
doctoc_api - Specification of the Interface to ToC Formatting
Engines
TABLE OF
CONTENTS
SYNOPSIS
DESCRIPTION
API
EXPORTED COMMANDS
IMPORTED ENVIRONMENT
SEE ALSO
KEYWORDS
COPYRIGHT
This document specifies version 1 of the interface an toc
formatting engine has to comply with to be usable by the package
doctools::toc. The specification of the doctoc format all toc
formatting engines have to process can be found in the companion
document doctoc_fmt .
Each toc formatting engine has to provide a number of commands
through which objects created by the package
doctools::toc will upon the functionality of the
engine. These commands are described here.
- Management commands
-
- toc_numpasses
- This command is called by a doctoc object immediately after it
has loaded the engine. No other command of the engine will be
called before it. It has to return the number of passes this engine
requires to fully process the input document. This value has to be
an integer number greater or equal to one.
- toc_initialize
- This command is called at the beginning of every conversion
run, as the first command of that run. Note that a run is not a
pass, but may consist of multiple passes. See toc_numpasses. The command has to initialize the general
state of the toc formatting engine, beyond the initialization done
during the load.
- toc_setup n
- This command is called at the beginning of each pass over the
input in a run. Its argument is the number of the pass which has
begun. Passes are counted from 1 upward. The
command has to set up the internal state of the toc formatting
engine for this particular pass.
- toc_postprocess text
- This command is called immediately after the last pass in a
run. Its argument is the result of the conversion generated by that
pass. It is provided to allow the engine to perform any global
last-ditch modifications of the generated document. The text
returned by this command will be the final result of the
conversion.
An engine for a format which requires no postprocessing can simply
return the argument without change.
- toc_shutdown
- This command is called at the end of every conversion run. It
is the last command called in a run. It has to clean up of all the
run-specific state in the toc formatting engine. After the call the
engine has to be in a state which allows the initiation of another
run without fear that information from the last run is leaked into
this new run.
- toc_listvariables
- This command is called by a doctoc object after it has loaded
the engine (after toc_numpasses). It has to
return a list containing the names of the engine parameters
provided by the engine. This list can be empty.
- toc_varset varname text
- This command is called whenever the doctoc object wishes to set
an engine parameter to a particular value. The parameter to change
is specified by varname, the value to set in text.
The command has to throw an error if an unknown varname is used. Only the names returned by toc_listvariables are considered known.
The values of all engine parameters have to persist between passes
and runs.
- Formatting commands
- The commands listed in this section are responsible for the
conversion of the input into the wanted output. Their names are the
names of the associated markup command, with prefix
fmt_ added to them. Not all markup commands have
associated formatting commands. The two exceptions are vset and include. These markup
commands are processed by the doctoc object itself.
A detailed documentation of the markup commands can be found in
the companion document doctoc_fmt . It is the formal
specification of the doctoc format.
Note: The formatting commands can expect that they are
only called in an order allowed by the format specification.
- fmt_plain_text text
- This command has no associated markup command. It is called for
any plain text encountered by the processor in the input. It has to
perform any special processing required for plain text. The text
returned as its result is added to the output. If no special
processing is required it has to simply return its argument without
change.
- fmt_comment text
- This command has to format the text as a
comment and return the formatted string. It has to return the empty
string if the output format has no way of formatting comments.
- fmt_toc_begin text title
- This command has to format the label text
and the associated title string as the start of
the generated table of contents and return the formatted
string.
- fmt_toc_end
- This command has to generate the end of the generated table of
contents and return the formatted string.
- fmt_division_start text ?symfile?
- This command has to open the beginning of a new section in the
generated table of contents and return the formatted string. This
opening may refer to another file, if supported by the format, and
specified through symfile. An possible
application of this would be to refer to a smaller table of
contents just for the section. The text argument
is the title of the new section.
- fmt_division_end
- This command has to close a section in the generated table of
contents and return the formatted string.
- fmt_item file text desc
- This command has to format an individual toc element and return
the formatted string. The document referenced by the element is
specified through its symbolic name file,
whereas the label to use for the link is provided by text. Use the command dt_fmap to
convert the symbolic name to the actual link. It is described in
section IMPORTED ENVIRONMENT.
The last argument, desc, provides a short
descriptive text for the referenced document.
The implementation of an toc formatting engine can make the
following assumptions about the environment it is executed in:
- That 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.
- That the following commands are provided by the doctoc object
controlling the engine:
- Doctools commands
-
- dt_format
- This command returns the name of the format currently
executing.
- dt_fmap symfname
- This command returns the actual name to use in the output in
place of the symbolic filename symfname. It will
return the unchanged input if no mapping was found for symfname.
- dt_source file
- This command allows the toc formatting engine to load
additional tcl code. Only files which are either in the same
directory as the file containing the engine, or below it, can be
loaded. Trying to load a file outside of this directory causes an
error.
- Expander commands
- All of the commands below are methods of the expander object
(without the prefix ex_) handling the current
input. This gives the engine limited access to the state of the
expander. Their arguments and results are described in the
documentation for the package expander.
- ex_cappend
- ex_cget
- ex_cis
- ex_cname
- ex_cpop
- ex_cpush
- ex_cset
- ex_lb
- ex_rb
- Other commands
- The file "_toc_common.tcl" contains default
implementations of fmt_plaint_text and all the
toc_ commands listed in section EXPORTED COMMANDS. It resides in the
subdirectory "mpformats" containing all the
predefined formats. This means that all external formats (i.e. not
provided by the package doctools::toc) cannot use
it immediately, but have to have a copy at their location.
doctoc , doctoc_fmt
HTML , LaTeX , TMML , generic markup , markup , nroff , table of contents , toc
Copyright © 2003-2004 Andreas Kupries
<andreas_kupries@users.sourceforge.net>