doctoc_plugin_apiref(3tcl) Documentation tools doctoc_plugin_apiref(3tcl)
______________________________________________________________________________
NAME
doctoc_plugin_apiref - doctoc plugin API reference
SYNOPSIS
dt_fmap symfname
dt_format
dt_read file
dt_source file
ex_cappend text
ex_cget varname
ex_cis cname
ex_cname
ex_cpop cname
ex_cpush cname
ex_cset varname value
ex_lb ?newbracket?
ex_rb ?newbracket?
toc_initialize
toc_listvariables
toc_numpasses
toc_postprocess text
toc_setup n
toc_shutdown
toc_varset varname text
fmt_plain_text text
______________________________________________________________________________
DESCRIPTION
This document is intended for plugin writers, i.e. developers wishing
to write a toc formatting engine for some output format X.
It specifies the interaction between the doctools::toc package and its
plugins, i.e. the interface any toc formatting engine has to comply
with.
This document deals with version 1 of the interface.
A reader who is on the other hand more interested in the markup lan-
guage itself should start with the doctoc language introduction and
proceed from there to the formal specifications, i.e. the doctoc lan-
guage syntax and the doctoc language command reference.
OVERVIEW
The API for a toc formatting engine consists of two major sections.
On the one side we have a set of commands through which the plugin is
able to query the frontend. These commands are provided by the frontend
and linked into the plugin interpreter. Please see section FRONTEND
COMMANDS for their detailed specification.
And on the other side the plugin has to provide its own set of commands
which will then be called by the frontend in a specific sequence while
processing input. They, again, fall into two categories, management and
formatting. Please see section PLUGIN COMMANDS and its subsections for
their detailed specification.
FRONTEND COMMANDS
This section specifies the set of commands through which a plugin, also
known as a toc formatting engine, is able to query the frontend. These
commands are provided by the frontend and linked into the plugin inter-
preter.
I.e. a toc formatting engine can assume that all of the following com-
mands are present when any of its own commands (as specified in section
PLUGIN COMMANDS) are executed.
Beyond that it can also assume that it has full access to its own safe
interpreter and thus is not able to damage the other parts of the pro-
cessor, nor can it damage the filesystem. It is however able to either
kill or hang the whole process, by exiting, or running an infinite
loop.
Coming back to the imported commands, all the commands with prefix dt_
provide limited access to specific parts of the frontend, whereas the
commands with prefix ex_ provide access to the state of the textu-
til::expander object which does the main parsing of the input within
the frontend. These commands should not be except under very special
circumstances.
dt_fmap symfname
Query command. It returns the actual pathname to use in the out-
put in place of the symbolic filename symfname. It will return
the unchanged input if no mapping was established for symfname.
The required mappings are established with the method map of a
frontend, as explained in section OBJECT METHODS of the documen-
tation for the package doctools::toc.
dt_format
Query command. It returns the name of the format associated with
the toc formatting engine.
dt_read file
Controlled filesystem access. Returns contents of file for what-
ever use desired by the plugin. 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 direc-
tory causes an error.
dt_source file
Controlled filesystem access. This command allows the toc for-
matting engine to load additional Tcl code it may need. Only
files which are either in the same directory as the file con-
taining the engine, or below it, can be loaded. Trying to load a
file outside of this directory causes an error.
ex_cappend text
Appends a string to the output in the current context. This
command should rarely be used by macros or application code.
ex_cget varname
Retrieves the value of variable varname, defined in the current
context.
ex_cis cname
Determines whether or not the name of the current context is
cname.
ex_cname
Returns the name of the current context.
ex_cpop cname
Pops a context from the context stack, returning all accumulated
output in that context. The context must be named cname, or an
error results.
ex_cpush cname
Pushes a context named cname onto the context stack. The con-
text must be popped by cpop before expansion ends or an error
results.
ex_cset varname value
Sets variable varname to value in the current context.
ex_lb ?newbracket?
Returns the current value of the left macro expansion bracket;
this is for use as or within a macro, when the bracket needs to
be included in the output text. If newbracket is specified, it
becomes the new bracket, and is returned.
ex_rb ?newbracket?
Returns the current value of the right macro expansion bracket;
this is for use as or within a macro, when the bracket needs to
be included in the output text. If newbracket is specified, it
becomes the new bracket, and is returned.
PLUGIN COMMANDS
The plugin has to provide its own set of commands which will then be
called by the frontend in a specific sequence while processing input.
They fall into two categories, management and formatting. Their ex-
pected names, signatures, and responsibilities are specified in the
following two subsections.
MANAGEMENT COMMANDS
The management commands a plugin has to provide are used by the front-
end to
[1] initialize and shutdown the plugin
[2] determine the number of passes it has to make over the input
[3] initialize and shutdown each pass
[4] query and initialize engine parameters
After the plugin has been loaded and the frontend commands are estab-
lished the commands will be called in the following sequence:
toc_numpasses -> n
toc_listvariables -> vars
toc_varset var1 value1
toc_varset var2 value2
...
toc_varset varK valueK
toc_initialize
toc_setup 1
...
toc_setup 2
...
...
toc_setup n
...
toc_postprocess
toc_shutdown
...
I.e. first the number of passes and the set of available engine parame-
ters is established, followed by calls setting the parameters. That
second part is optional.
After that the plugin is initialized, the specified number of passes
executed, the final result run through a global post processing step
and at last the plugin is shutdown again. This can be followed by more
conversions, restarting the sequence at toc_varset.
In each of the passes, i.e. after the calls of toc_setup the frontend
will process the input and call the formatting commands as markup is
encountered. This means that the sequence of formatting commands is de-
termined by the grammar of the doctoc markup language, as specified in
the doctoc language syntax specification.
A different way of looking at the sequence is:
o First some basic parameters are determined.
o Then everything starting at the first toc_varset to toc_shutdown
forms a run, the formatting of a single input. Each run can be
followed by more.
o Embedded within each run we have one or more passes, each start-
ing with toc_setup and going until either the next toc_setup or
toc_postprocess is reached.
If more than one pass is required to perform the formatting only
the output of the last pass is relevant. The output of all the
previous, preparatory passes is ignored.
The commands, their names, signatures, and responsibilities are, in de-
tail:
toc_initialize
Initialization/Shutdown. This command is called at the begin-
ning 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. It has to initialize the general state of the plugin,
beyond the initialization done during the load. No return value
is expected, and any returned value is ignored.
toc_listvariables
Initialization/Shutdown and Engine parameters. Second command
is called after the plugin code has been loaded, i.e. immedi-
ately after toc_numpasses. It has to return a list containing
the names of the parameters the frontend can set to configure
the engine. This list can be empty.
toc_numpasses
Initialization/Shutdown and Pass management. First command
called after the plugin code has been loaded. 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_postprocess text
Initialization/Shutdown. This command is called immediately af-
ter 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 modifications of the generated doc-
ument. If no post-processing is required for a specific format
the command has to just return the argument.
Expected to return a value, the final result of formatting the
input.
toc_setup n
Initialization/Shutdown and Pass management. 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 inter-
nal state of the plugin for this particular pass. No return
value is expected, and any returned value is ignored.
toc_shutdown
Initialization/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 plugin.
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. No return value is ex-
pected, and any returned value is ignored.
toc_varset varname text
Engine parameters. This command is called by the frontend 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 have to be consid-
ered as known.
The values of all engine parameters have to persist between
passes and runs.
FORMATTING COMMANDS
The formatting commands have to implement the formatting for the output
format, for all the markup commands of the doctoc markup language, ex-
cept lb, rb, vset, include, and comment. These exceptions are processed
by the frontend and are never seen by the plugin. In return a command
for the formatting of plain text has to be provided, something which
has no markup in the input at all.
This means, that each of the five markup commands specified in the doc-
toc language command reference and outside of the set of exceptions
listed above has an equivalent formatting command which takes the same
arguments as the markup command and whose name is the name of markup
command with the prefix fmt_ added to it.
All commands are expected to format their input in some way per the se-
mantics specified in the command reference and to return whatever part
of this that they deem necessary as their result, which will be added
to the output.
To avoid essentially duplicating the command reference we do not list
any of the command here and simply refer the reader to the doctoc lan-
guage command reference for their signature and description. The sole
exception is the plain text formatter, which has no equivalent markup
command.
The calling sequence of formatting commands is not as rigid as for the
management commands, but determined by the grammar of the doctoc markup
language, as specified in the doctoc language syntax specification.
fmt_plain_text text
No associated markup command.
Called by the frontend for any plain text encountered in the in-
put. It has to perform any and all special processing required
for plain text.
The formatted text is expected as the result of the command, and
added to the output. If no special processing is required it has
to simply return its argument without change.
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 [http://core.tcl.tk/tcllib/reportlist]. 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 out-
put 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
doctoc_intro, doctoc_lang_cmdref, doctoc_lang_faq, doctoc_lang_intro,
doctoc_lang_syntax, doctools::toc
KEYWORDS
formatting engine, markup, plugin, semantic markup, table of contents,
toc, toc formatter
CATEGORY
Documentation tools
COPYRIGHT
Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
tcllib 1.0 doctoc_plugin_apiref(3tcl)