


doctoc_plugin_apiref(n)Documentation toolsdoctoc_plugin_apiref(n)


______________________________________________________________________________

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.




doctools                       1.0                              1





doctoc_plugin_apiref(n)Documentation toolsdoctoc_plugin_apiref(n)


       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.




doctools                       1.0                              2





doctoc_plugin_apiref(n)Documentation toolsdoctoc_plugin_apiref(n)


              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



doctools                       1.0                              3





doctoc_plugin_apiref(n)Documentation toolsdoctoc_plugin_apiref(n)


              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 fron-
       tend 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.



doctools                       1.0                              4





doctoc_plugin_apiref(n)Documentation toolsdoctoc_plugin_apiref(n)


       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
       determined  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
       detail:

       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.




doctools                       1.0                              5





doctoc_plugin_apiref(n)Documentation toolsdoctoc_plugin_apiref(n)


       toc_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 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
              expected, 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,
       except  lb,  rb,  vset, include, and comment. These exceptions are pro-
       cessed 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.



doctools                       1.0                              6





doctoc_plugin_apiref(n)Documentation toolsdoctoc_plugin_apiref(n)


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










doctools                       1.0                              7


