|
|
Эта страница руководства для версии 10.9 Mac OS XЕсли Вы выполняете различную версию Mac OS X, просматриваете документацию локально:
Читать страницы руководстваСтраницы руководства предназначаются как справочник для людей, уже понимающих технологию.
|
doctools_plugin_apiref(n) Documentation tools doctools_plugin_apiref(n)
____________________________________________________________________________________________________________
NAME
doctools_plugin_apiref - doctools plugin API reference
SYNOPSIS
dt_copyright
dt_file
dt_mainfile
dt_fileid
dt_fmap symfname
dt_format
dt_imgdata key extensions
dt_imgdst key extensions
dt_imgsrc key extensions
dt_lnesting
dt_module
dt_read file
dt_source file
dt_user
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?
fmt_initialize
fmt_listvariables
fmt_numpasses
fmt_postprocess text
fmt_setup n
fmt_shutdown
fmt_varset varname text
fmt_plain_text text
____________________________________________________________________________________________________________
DESCRIPTION
This document is intended for plugin writers, i.e. developers wishing to write a doctools formatting
engine for some output format X.
It specifies the interaction between the doctools package and its plugins, i.e. the interface any
doctools 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 language itself should start with the
doctools language introduction and proceed from there to the formal specifications, i.e. the doctools
language syntax and the doctools language command reference.
OVERVIEW
The API for a doctools 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 sec-tion section
tion 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 doctools format-ting formatting
ting engine, is able to query the frontend. These commands are provided by the frontend and linked
into the plugin interpreter.
I.e. a doctools formatting engine can assume that all of the following commands 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 processor, 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 spe-cific specific
cific parts of the frontend, whereas the commands with prefix ex_ provide access to the state of the
textutil::expander object which does the main parsing of the input within the frontend. These com-mands commands
mands should not be except under very special circumstances.
dt_copyright
Query command. It returns a string containing the copyright information the doctools processor
was configured with. The relevant option is -copyright).
dt_file
Query command. It returns the full path of the file containing the input currently processed
by the engine. This may be an included file.
dt_mainfile
Query command. It returns the full path of the toplevel file containing the input currently
processed by the engine.
dt_fileid
Query command. It returns the name of the file containing the input currently processed by the
engine, without path, nor extension.
dt_fmap symfname
Query command. It returns the actual pathname to use in the output in place of the symbolic
filename symfname. It will return the unchanged input if no mapping was established for symf-name. symfname.
name.
The required mappings are established with the method map of a frontend, as explained in sec-tion section
tion OBJECT METHODS of the documentation for the package doctools.
dt_format
Query command. It returns the name of the format associated with the doctools formatting
engine.
dt_imgdata key extensions
Query command. Access to the image map. Looks for an image recorded under the key and having
on the specified extension. If a matching image is found its data is returned as the result of
the command. Otherwise an empty string is returned.
dt_imgdst key extensions
Query command. Access to the image map. Looks for an image recorded under the key and having
on the specified extension. If a matching image is found its destination path in the output is
returned as the result of the command. Otherwise an empty string is returned.
dt_imgsrc key extensions
Query command. Access to the image map. Looks for an image recorded under the key and having
on the specified extension. If a matching image is found its origin path is returned as the
result of the command. Otherwise an empty string is returned.
dt_lnesting
Query command. It returns the number of lists currently open.
dt_module
Query command. It returns the name of the module the input currently processed belongs to.
dt_read file
Controlled filesystem access. Returns contents of file for whatever 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 directory causes an error.
dt_source file
Controlled filesystem access. This command allows the doctools formatting engine to load addi-tional additional
tional Tcl code it may need. 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.
dt_user
Query command. It returns the name of the current user as known to the tcl interpreter the
frontend controlling the formatting engine resides in.
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 context 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 spe-cific specific
cific sequence while processing input. They fall into two categories, management and formatting.
Their expected names, signatures, and responsibilities are specified in the following two subsec-tions. subsections.
tions.
MANAGEMENT COMMANDS
The management commands a plugin has to provide are used by the frontend 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 established the commands will be
called in the following sequence:
fmt_numpasses -> n
fmt_listvariables -> vars
fmt_varset var1 value1
fmt_varset var2 value2
...
fmt_varset varK valueK
fmt_initialize
fmt_setup 1
...
fmt_setup 2
...
...
fmt_setup n
...
fmt_postprocess
fmt_shutdown
...
I.e. first the number of passes and the set of available engine parameters 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 fmt_varset.
In each of the passes, i.e. after the calls of fmt_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 determined by the grammar of the doctools markup language, as specified in the doctools language
syntax specification.
A different way of looking at the sequence is:
• First some basic parameters are determined.
• Then everything starting at the first fmt_varset to fmt_shutdown forms a run, the formatting
of a single input. Each run can be followed by more.
• Embedded within each run we have one or more passes, each starting with fmt_setup and going
until either the next fmt_setup or fmt_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 detail:
fmt_initialize
Initialization/Shutdown. 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. 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.
fmt_listvariables
Initialization/Shutdown and Engine parameters. Second command is called after the plugin code
has been loaded, i.e. immediately after fmt_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.
fmt_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.
fmt_postprocess text
Initialization/Shutdown. 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 modifications of the generated document. 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.
fmt_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 internal state of the plugin for
this particular pass. No return value is expected, and any returned value is ignored.
fmt_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 expected, and any returned value is ignored.
fmt_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
fmt_listvariables have to be considered 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 doctools markup language, except 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 format-ting formatting
ting of plain text has to be provided, something which has no markup in the input at all.
This means, that each of the 49 markup commands specified in the doctools 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 semantics specified in the com-mand command
mand 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 doctools language command reference for their signature and descrip-tion. description.
tion. 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 doctools markup language, as specified in the doctools language syn-tax syntax
tax specification.
fmt_plain_text text
No associated markup command.
Called by the frontend for any plain text encountered in the input. 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, will undoubtedly contain bugs and other problems. Please report such in the category
doctools of the Tcllib SF Trackers [http://sourceforge.net/tracker/?group_id=12883]. Please also
report any ideas for enhancements you may have.
SEE ALSO
doctools, doctools_intro, doctools_lang_cmdref, doctools_lang_faq, doctools_lang_intro, doc-tools_lang_syntax doctools_lang_syntax
tools_lang_syntax
KEYWORDS
document, formatter, formatting engine, manpage, markup, semantic markup
CATEGORY
Documentation tools
COPYRIGHT
Copyright (c) 2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>
doctools 1.1 doctools_plugin_apiref(n)
|
Сообщение о проблемах
Способ сообщить о проблеме с этой страницей руководства зависит от типа проблемы:
- Ошибки содержания
- Ошибки отчета в содержании этой документации со ссылками на отзыв ниже.
- Отчеты об ошибках
- Сообщите об ошибках в функциональности описанного инструмента или API через Генератор отчетов Ошибки.
- Форматирование проблем
- Отчет, форматирующий ошибки в интерактивной версии этих страниц со ссылками на отзыв ниже.