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

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.

       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 language itself should
       start with the  doctoc  language  introduction  and  proceed  from  there  to  the  formal
       specifications, i.e. the doctoc language 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 interpreter.

       I.e. a toc 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::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 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 toc 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:

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

       •      First some basic parameters are determined.

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

       •      Embedded  within  each run we have one or more passes, each starting 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  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.

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

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

       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  internal  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 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  doctoc  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 doctoc 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  doctoc  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 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,  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

       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>