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:

    idx_numpasses -> n
    idx_listvariables -> vars
    idx_varset var1 value1
    idx_varset var2 value2
    ...
    idx_varset varK valueK
    idx_initialize
    idx_setup 1
    ...
    idx_setup 2
    ...
    ...
    idx_setup n
    ...
    idx_postprocess
    idx_shutdown
    ...

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

In each of the passes, i.e. after the calls of idx_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 docidx markup language, as specified in the docidx language syntax specification.

A different way of looking at the sequence is:

• First some basic parameters are determined.
• Then everything starting at the first idx_varset to idx_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 idx_setup and going until either the next idx_setup or idx_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:

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

idx_listvariables

Initialization/Shutdown and Engine parameters. Second command is called after the plugin code has been loaded, i.e. immediately after idx_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.

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

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

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

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

idx_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 idx_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 docidx 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 five markup commands specified in the docidx 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 docidx 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 docidx markup language, as specified in the docidx 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.