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

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:

       •      First some basic parameters are determined.

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

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

       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>