doctools_api(n) 1.0 doctools "Documentation tools"

NAME

doctools_api - Interface specification for formatter code

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

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

INTERFACE

Each formatting engine has to provide

Implementations of all the formatting commands as specified in doctools_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.
and additionally implementations for

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

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

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

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

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

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

fmt_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 fmt_listvariables are considered known.

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

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.
The surrounding system provides the engine with the following commands:

Doctools commands

dt_file
Returns the full name of the file currently processed by the engine.

dt_fileid
Returns the name of the file currently processed by the engine, without path, nor extension

dt_format
Returns the name of format loaded into the engine

dt_lnesting
Returns the number lists currently open

dt_module
Returns the name of the module the file currently processed belongs to.

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

_common.tcl commands
Any engine loading (dt_source) the file "_common.tcl" has default implementations of the fmt_ commands explicitly listed in this document, and can additionally use

c_inpass
Returns the id of the pass currently executing

c_begin
Use this to mark that processing of the text after manpage_begin has begun.

c_begun
Checks the flag set by c_begin.

c_set_module text
Remember text as module information.

c_get_module
Retrieve module information stored by c_set_module.

c_set_title text
Remember text as title.

c_get_title
Retrieve title stored by c_set_title.

c_provenance
Returns a string describing how the input was processed.

c_pass pass proc arguments body
Define a procedure which is valid when pass pass of the engine is executed.

c_holdBuffers args
Define one or more buffers for holding data between passes.

c_hold buffer entry
Add an entry to the specified buffer. The buffer has to be defined by an earlier invocation of the command c_holdBuffers.

c_held buffer
Retrieves the contents of the specified buffer. The buffer is empty afterwards. All entries in the buffer are joined by newlines.

c_cnext
Increment the counter and return its current value.

c_cinit
Push the current counter on the stack and reinitialize the counter to zero.

c_creset
Reinitialize the counter with the value on the counter stack and remove that value from the stack.

NOP args
Do nothing command. Can be used in conjunction with c_pass to visibly declare in which passes a formatting command has nothing to do.

NYI ?message?
Throws the error "message Not yet implemented".

c_sectionId name
Remembers the name of the section for later cross-referencing

c_possibleReference text gi
Checks if a section is available for text. This command is currently tuned for use by engines like HTML and TMML.

KEYWORDS

HTML, LaTeX, TMML, generic markup, manpage, markup, nroff

doctools_api(n) 1.0 doctools "Documentation tools"

NAME

DESCRIPTION

INTERFACE

SEE ALSO

KEYWORDS

COPYRIGHT