Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

docidx_plugin_apiref(n)                      Documentation tools                     docidx_plugin_apiref(n)



____________________________________________________________________________________________________________

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  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 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 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_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::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  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.

       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:

           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 syn-tax syntax
       tax 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 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 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 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 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, 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
       docidx_intro,   docidx_lang_cmdref,   docidx_lang_faq,  docidx_lang_intro,  docidx_lang_syntax,  doc-tools::idx doctools::idx
       tools::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>




doctools                                             1.0                             docidx_plugin_apiref(n)