Tcl Library Source Code

Documentation
Login


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

doctools_plugin_apiref - doctools plugin API reference

Table Of Contents

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.

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:

The commands, their names, signatures, and responsibilities are, in detail:

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.

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. 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 © 2007-2010 Andreas Kupries