doctools_plugin_apiref(n) Documentation tools doctools_plugin_apiref(n) 







doctools_plugin_apiref - doctools plugin API reference








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












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.








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.








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.



  
  
Query command. It returns a string containing the copyright information
      the doctools processor was configured with. The relevant option is
      -copyright).

  

  
Query command. It returns the full path of the file containing the input
      currently processed by the engine. This may be an included file.

  

  
Query command. It returns the full path of the toplevel file containing
      the input currently processed by the engine.

  

  
Query command. It returns the name of the file containing the input
      currently processed by the engine, without path, nor extension.

  

  
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.

  

  

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

  

  
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.

  

  
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.

  

  
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.

  

  
Query command. It returns the number of lists currently open.

  

  
Query command. It returns the name of the module the input currently
      processed belongs to.

  

  
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.

  

  
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.

  

  
Query command. It returns the name of the current user as known to the tcl
      interpreter the frontend controlling the formatting engine resides
    in.

  

  
Appends a string to the output in the current context. This command should
      rarely be used by macros or application code.

  

  
Retrieves the value of variable varname, defined in the current
      context.

  

  
Determines whether or not the name of the current context is
    cname.

  

  
Returns the name of the current context.

  

  
Pops a context from the context stack, returning all accumulated output in
      that context. The context must be named cname, or an error
    results.

  

  
Pushes a context named cname onto the context stack. The context
      must be popped by cpop before expansion ends or an error
    results.

  

  
Sets variable varname to value in the current context.

  

  
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.

  

  
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.










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.






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:



  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  

  
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.

  

  
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.

  

  
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.

  










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.



  

  
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.

  












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.








doctools, doctools_intro, doctools_lang_cmdref, doctools_lang_faq,
    doctools_lang_intro, doctools_lang_syntax








document, formatter, formatting engine, manpage, markup, semantic
    markup








Documentation tools








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








  

    1.1
    doctools