 |
ActiveTcl User Guide
|
 |
|
[ Main table Of Contents | Tcllib Table Of Contents | Tcllib Index ]
doctools_api(n) 1.0 "Documentation tools"
doctools_api - Interface specification for formatter code
This manpage specifies the interface between formatting engines
for data in the doctools format as specified in
doctools_fmt , and
doctools, the package for the generic handling of
such data, as described in doctools .
Each formatting engine has to implement the conversion of input
in doctools 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
doctools_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
- fmt_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.
- fmt_initialize
- This command is called at the beginning of every conversion run
and is responsible for initializing the general state of the
formatting engine.
- fmt_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.
- fmt_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.
- fmt_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.
- fmt_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.
- fmt_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 fmt_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_file
- Returns the full name of the file currently processed by the
engine.
- dt_fileid
- Returns the name of the file currently processed by the engine,
without path, nor extension
- dt_format
- Returns the name of format loaded into the engine
- dt_lnesting
- Returns the number lists currently open
- dt_module
- Returns the name of the module the file currently processed
belongs to.
- 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
- _common.tcl commands
- Any engine loading (dt_source) the file
"_common.tcl" has default implementations of the
fmt_ commands explicitly listed in this document,
and can additionally use
- c_inpass
- Returns the id of the pass currently executing
- c_begin
- Use this to mark that processing of the text after manpage_begin has begun.
- c_begun
- Checks the flag set by c_begin.
- c_set_module text
- Remember text as module information.
- c_get_module
- Retrieve module information stored by c_set_module.
- c_set_title text
- Remember text as title.
- c_get_title
- Retrieve title stored by c_set_title.
- c_provenance
- Returns a string describing how the input was processed.
- c_pass pass proc arguments
body
- Define a procedure which is valid when pass pass of the engine is executed.
- c_holdBuffers args
- Define one or more buffers for holding data between passes.
- c_hold buffer entry
- Add an entry to the specified buffer. The buffer has to be
defined by an earlier invocation of the command c_holdBuffers.
- c_held buffer
- Retrieves the contents of the specified buffer. The buffer is
empty afterwards. All entries in the buffer are joined by
newlines.
- c_cnext
- Increment the counter and return its current value.
- c_cinit
- Push the current counter on the stack and reinitialize the
counter to zero.
- c_creset
- Reinitialize the counter with the value on the counter stack
and remove that value from the stack.
- NOP args
- Do nothing command. Can be used in conjunction with c_pass to visibly declare in which passes a formatting
command has nothing to do.
- NYI ?message?
- Throws the error "message Not yet
implemented".
- c_sectionId name
- Remembers the name of the section for later
cross-referencing
- c_possibleReference text
gi
- Checks if a section is available for text.
This command is currently tuned for use by engines like HTML and
TMML.
doctools , doctools_fmt
HTML , LaTeX , TMML , generic markup , manpage , markup , nroff
Copyright © 2002 Andreas Kupries
<andreas_kupries@users.sourceforge.net>
Copyright © 2003 Andreas Kupries
<andreas_kupries@users.sourceforge.net>