Provided by: tcllib_1.21+dfsg-1_all bug

NAME

       docidx_plugin_apiref - docidx 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?

       idx_initialize

       idx_listvariables

       idx_numpasses

       idx_postprocess text

       idx_setup n

       idx_shutdown

       idx_varset varname text

       fmt_plain_text text

_________________________________________________________________________________________________

DESCRIPTION

       This  document  is  intended for plugin writers, i.e. developers wishing to write an index
       formatting engine for some output format X.

       It specifies the interaction between the doctools::idx package and its plugins,  i.e.  the
       interface any index 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  docidx  language  introduction  and  proceed  from  there  to  the  formal
       specifications, i.e. the docidx language syntax and the docidx language command reference.

OVERVIEW

       The API for an index 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 an  index
       formatting  engine,  is  able  to  query  the frontend. These commands are provided by the
       frontend and linked into the plugin interpreter.

       I.e. an index 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_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::idx.

       dt_format
              Query command. It returns  the  name  of  the  format  associated  with  the  index
              formatting engine.

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

       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:

                  idx_numpasses -> n
                  idx_listvariables -> vars

                  idx_varset var1 value1
                  idx_varset var2 value2
                  ...
                  idx_varset varK valueK
                  idx_initialize
                  idx_setup 1
                  ...
                  idx_setup 2
                  ...
                  ...
                  idx_setup n
                  ...
                  idx_postprocess
                  idx_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 idx_varset.

       In  each  of  the  passes, i.e. after the calls of idx_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 docidx markup
       language, as specified in the docidx language syntax specification.

       A different way of looking at the sequence is:

       •      First some basic parameters are determined.

       •      Then everything starting at the first idx_varset to idx_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 idx_setup
              and going until either the next idx_setup or idx_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:

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

       idx_listvariables
              Initialization/Shutdown and Engine parameters.  Second command is called after  the
              plugin  code  has  been  loaded,  i.e.  immediately after idx_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.

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

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

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

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

       idx_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 idx_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  docidx  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 five markup commands specified in the docidx 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  docidx  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 docidx markup language, as specified in the
       docidx 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,  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 output 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

       docidx_intro, docidx_lang_cmdref, docidx_lang_faq, docidx_lang_intro,  docidx_lang_syntax,
       doctools::idx

KEYWORDS

       formatting engine, index, index formatter, keywords, markup, plugin, semantic markup

CATEGORY

       Documentation tools

COPYRIGHT

       Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>