doctoc_api(n) 1.0 doctools "Documentation tools"

NAME

doctoc_api - Interface specification for toc formatting code

DESCRIPTION

This manpage specifies the interface between formatting engines for data in the doctoc format as specified in doctoc_fmt, and doctools::toc, the package for the generic handling of such data, as described in doctoc.

Each formatting engine has to implement the conversion of input in doctoc format to one particular output format as chosen by the author of the formatting engine.

INTERFACE

Each formatting engine has to provide

1. Implementations of all the formatting commands as specified in doctoc_fmt, using the defined names, but prefixed with the string fmt_. The sole exceptions to this are the formatting commands vset and include. These two commands are processed by the generic layer and will never be seen by the formatting engine.
   
   
2. and additionally implementations for
   
   

   toc_numpasses

   This command is called immediately after the formatter is loaded and has to return the number of passes required by this formatter to process a manpage. This information has to be an integer number greater or equal to one.
   
   

   toc_initialize

   This command is called at the beginning of every conversion run and is responsible for initializing the general state of the formatting engine.
   
   

   toc_setup n

   This command is called at the beginning of each pass over the input and is given the id of the current pass as its first argument. It is responsible for setting up the internal state of the formatting for this particular pass.
   
   

   toc_postprocess text

   This command is called immediately after the last pass, with the expansion result of that pass as argument, and can do any last-ditch modifications of the generated result. Its result will be the final result of the conversion.
   
   Most formats will use identity here.
   
   

   toc_shutdown

   This command is called at the end of every conversion run and is responsible for cleaning up of all the state in the formatting engine.
   
   

   fmt_plain_text text

   This command is called for any plain text encountered by the processor in the input and can do any special processing required for plain text. Its result is the string written into the expansion.
   
   Most formats will use identity here.
   
   

   toc_listvariables

   The command is called after loading a formatting engine to determine which parameters are supported by that engine. The return value is a list containing the names of these parameters.
   
   

   toc_varset varname text

   The command is called by the generic layer to set the value of an engine specific parameter. The parameter to change is specified by varname, and the value to set is given in text.
   
   The command will throw an error if an unknown varname is used. Only the names returned by toc_listvariables are considered known.

The tcl code of a formatting engine implementing all of the above can make the following assumptions about its environment

1. It has full access to its own safe interpreter. In other words, the engine cannot damage the other parts of the processor, nor can it damage the filesystem.
   
   
2. The surrounding system provides the engine with the following commands:
   
   

   Doctools commands

   dt_format

   Returns the name of format loaded into the engine
   
   

   dt_fmap fname

   Returns the actual name to use in the output in place of the symbolic filename fname.
   
   

   dt_source file

   This command allows the engine to load additional tcl code. The file being loaded has to be in the same directory as the file the format engine was loaded from. Any path specified for file is ignored.

   Expander commands

   All of the commands below are methods of the expander object (without the prefix ex_) handling the input. Their arguments and results are described in expander(n).
   
   

   ex_cappend

   ex_cget

   ex_cis

   ex_cname

   ex_cpop

   ex_cpush

   ex_cset

   ex_lb

   ex_rb

   _toc_common.tcl commands

   Any engine loading (dt_source) the file "_toc_common.tcl" has default implementations of the toc_ commands explicitly listed in this document and of fmt_plaint_text.

SEE ALSO

doctoc, doctoc_fmt

KEYWORDS

HTML, LaTeX, TMML, generic markup, markup, nroff, table of contents, toc

COPYRIGHT

Copyright © 2003 Andreas Kupries <andreas_kupries@users.sourceforge.net>