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 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 doctools formatting 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 specific 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 commands 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
              symfname.

              The required mappings are established with the method map of a
              frontend, as explained in section 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 additional 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 specific sequence while processing input.
       They fall into two categories, management and formatting. Their
       expected 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
       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:

       o      First some basic parameters are determined.

       o      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.

       o      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 formatting 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 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 doctools
       language 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 doctools
       markup language, as specified in the doctools language syntax
       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, doctools_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)
