---
name: "docidx_api"
section: "3tcl"
platform: "linux"
package: "tcllib"
version: "1.8-1"
release: "Debian 4.0 (Etch)"
platforms: ["linux"]
url: "https://new.carta.tech/docidx_api"
---

# docidx\_api(3tcl)

Specification of the Interface to Index Formatting Engines

```

```

## NAME

docidx\_api - Specification of the Interface to Index Formatting Engines

## SYNOPSIS

**idx\_numpasses**

**idx\_initialize**

**idx\_setup** *n*

**idx\_postprocess** *text*

**idx\_shutdown**

**idx\_listvariables**

**idx\_varset** *varname* *text*

**fmt\_plain\_text** *text*

**fmt\_comment** *text*

**fmt\_index\_begin** *text* *title*

**fmt\_index\_end**

**fmt\_key** *text*

**fmt\_manpage** *file* *text*

**fmt\_url** *url* *text*

**dt\_format**

**dt\_fmap** *symfname*

**dt\_source** *file*

**ex\_cappend**

**ex\_cget**

**ex\_cis**

**ex\_cname**

**ex\_cpop**

**ex\_cpush**

**ex\_cset**

**ex\_lb**

**ex\_rb**

```

```

## DESCRIPTION

This document specifies version 1 of the interface an index formatting engine has to comply with to be usable by the package **doctools::idx**. The specification of the *docidx* format all index formatting engines have to process can be found in the companion document *docidx\_fmt*.

## API

### EXPORTED COMMANDS

Each index formatting engine has to provide a number of commands through which objects created by the package **doctools::idx** will upon the functionality of the engine. These commands are described here.

- *Management commands*

  - **idx\_numpasses**

    This command is called by a docidx object immediately after it has loaded the engine. 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\_initialize**

    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. See **idx\_numpasses**. The command has to initialize the general state of the index formatting engine, beyond the initialization done during the load.

  - **idx\_setup** *n*

    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 index formatting engine for this particular pass.

  - **idx\_postprocess** *text*

    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 last-ditch modifications of the generated document. The text returned by this command will be the final result of the conversion.

    An engine for a format which requires no postprocessing can simply return the argument without change.

  - **idx\_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 index formatting engine. 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.

  - **idx\_listvariables**

    This command is called by a docidx object after it has loaded the engine (after **idx\_numpasses**). It has to return a list containing the names of the engine parameters provided by the engine. This list can be empty.

  - **idx\_varset** *varname* *text*

    This command is called whenever the docidx object wishes 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** are considered known.

    The values of all engine parameters have to persist between passes and runs.

- *Formatting commands*

  The commands listed in this section are responsible for the conversion of the input into the wanted output. Their names are the names of the associated markup command, with prefix **fmt\_** added to them. Not all markup commands have associated formatting commands. The two exceptions are **vset** and **include**. These markup commands are processed by the docidx object itself.

  A detailed documentation of the markup commands can be found in the companion document *docidx\_fmt*. It is the formal specification of the *docidx* format.

  *Note*: The formatting commands can expect that they are only called in an order allowed by the format specification.

  - **fmt\_plain\_text** *text*

    This command has no associated markup command. It is called for any plain text encountered by the processor in the input. It has to perform any special processing required for plain text. The text returned as its result is added to the output. If no special processing is required it has to simply return its argument without change.

  - **fmt\_comment** *text*

    This command has to format the *text* as a comment and return the formatted string. It has to return the empty string if the output format has no way of formatting comments.

  - **fmt\_index\_begin** *text* *title*

    This command has to format the label *text* and the associated *title* string as the start of the generated index and return the formatted string.

  - **fmt\_index\_end**

    This command has to generate the end of the generated index and return the formatted string.

  - **fmt\_key** *text*

    This commands has to format the keyword *text* at the beginning of a list of documents and other entities which belong to it and return the formatted string.

  - **fmt\_manpage** *file* *text*

    This command has to format a document reference and return the formatted string. The document referenced by the entry is specified through its symbolic name *file*, whereas the label to use for the link is provided by *text*. Use the command **dt\_fmap** to convert the symbolic name to the actual link. It is described in section **IMPORTED ENVIRONMENT**.

  - **fmt\_url** *url* *text*

    This is the second command to describe an index element. It has to format an url reference and return the formatted string. The label to use is provided by *text*, like for **fmt\_manpage**. The place to link to is however not given through a symbolic name, but the exact uri to use in the output.

### IMPORTED ENVIRONMENT

The implementation of an index formatting engine can make the following assumptions about the environment it is executed in:

- \[1\]

  That 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\]

  That the following commands are provided by the docidx object controlling the engine:

  - Doctools commands

    - **dt\_format**

      This command returns the name of the format currently executing.

    - **dt\_fmap** *symfname*

      This command returns the actual name to use in the output in place of the symbolic filename *symfname*. It will return the unchanged input if no mapping was found for *symfname*.

    - **dt\_source** *file*

      This command allows the index formatting engine to load additional tcl code. 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.

  - Expander commands

    All of the commands below are methods of the expander object (without the prefix **ex\_**) handling the current input. This gives the engine limited access to the state of the expander. Their arguments and results are described in the documentation for the package **expander**.

    - **ex\_cappend**

      - **ex\_cget**

      - **ex\_cis**

      - **ex\_cname**

      - **ex\_cpop**

      - **ex\_cpush**

      - **ex\_cset**

      - **ex\_lb**

      - **ex\_rb**

      - Other commands

    The file "*\_idx\_common.tcl*" contains default implementations of **fmt\_plaint\_text** and all the **idx\_** commands listed in section **EXPORTED COMMANDS**. It resides in the subdirectory "*mpformats*" containing all the predefined formats. This means that all external formats (i.e. not provided by the package **doctools::idx**) cannot use it immediately, but have to have a copy at their location.

## SEE ALSO

docidx, docidx\_fmt

## KEYWORDS

HTML, LaTeX, TMML, generic markup, index, keyword index, keywords, markup, nroff

## COPYRIGHT

```
Copyright (c) 2003-2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
```