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

# doctools\_api(3tcl)

Specification of the Interface to Doctools Formatting Engines

```

```

## NAME

doctools\_api - Specification of the Interface to Doctools Formatting Engines

## SYNOPSIS

**fmt\_numpasses**

**fmt\_initialize**

**fmt\_setup** *n*

**fmt\_postprocess** *text*

**fmt\_shutdown**

**fmt\_listvariables**

**fmt\_varset** *varname* *text*

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

**fmt\_comment** *text*

**fmt\_manpage\_begin** *command* *section* *version*

**fmt\_manpage\_end**

**fmt\_moddesc** *desc*

**fmt\_titledesc** *desc*

**fmt\_copyright** *text*

**fmt\_description**

**fmt\_require** *pkg* ?*version*?

**fmt\_section** *name*

**fmt\_subsection** *name*

**fmt\_para**

**fmt\_see\_also** *args*

**fmt\_keywords** *args*

**fmt\_arg** *text*

**fmt\_cmd** *text*

**fmt\_opt** *text*

**fmt\_emph** *text*

**fmt\_strong** *text*

**fmt\_sectref** *text* ?*label*?

**fmt\_syscmd** *text*

**fmt\_method** *text*

**fmt\_namespace** *text*

**fmt\_option** *text*

**fmt\_widget** *text*

**fmt\_fun** *text*

**fmt\_type** *text*

**fmt\_package** *text*

**fmt\_class** *text*

**fmt\_var** *text*

**fmt\_file** *text*

**fmt\_uri** *text* ?*text*?

**fmt\_term** *text*

**fmt\_const** *text*

**fmt\_nl**

**fmt\_example\_begin**

**fmt\_example\_end**

**fmt\_list\_begin** *what*

**fmt\_list\_end**

**fmt\_bullet**

**fmt\_enum**

**fmt\_lst\_item** *text*

**fmt\_call** *args*

**fmt\_arg\_def** *type* *name* ?*mode*?

**fmt\_opt\_def** *name* ?*arg*?

**fmt\_cmd\_def** *command*

**fmt\_tkoption\_def** *name* *dbname* *dbclass*

**fmt\_usage** *args*

**dt\_copyright**

**dt\_file**

**dt\_fileid**

**dt\_fmap** *symfname*

**dt\_format**

**dt\_lnesting**

**dt\_module**

**dt\_source** *file*

**dt\_user**

**ex\_cappend**

**ex\_cget**

**ex\_cis**

**ex\_cname**

**ex\_cpop**

**ex\_cpush**

**ex\_cset**

**ex\_lb**

**ex\_rb**

**c\_inpass**

**c\_begin**

**c\_begun**

**c\_set\_module** *text*

**c\_get\_module**

**c\_set\_title** *text*

**c\_get\_title**

**c\_provenance**

**c\_pass** *pass proc arguments body*

**c\_holdBuffers** *args*

**c\_hold** *buffer entry*

**c\_held** *buffer*

**c\_cnext**

**c\_cinit**

**c\_creset**

**NOP** *args*

**NYI** ?*message*?

**c\_sectionId** *name*

**c\_possibleReference** *text gi*

```

```

## DESCRIPTION

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

## API

### EXPORTED COMMANDS

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

- *Management commands*

  - **fmt\_numpasses**

    This command is called by a doctools 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.

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

  - **fmt\_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 doctools formatting engine for this particular pass.

  - **fmt\_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.

  - **fmt\_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 doctools 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.

  - **fmt\_listvariables**

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

  - **fmt\_varset** *varname* *text*

    This command is called whenever the doctools 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 **fmt\_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 doctools object itself.

  A detailed documentation of the markup commands can be found in the companion document *doctools\_fmt*. It is the formal specification of the *doctools* 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\_manpage\_begin** *command* *section* *version*

    This command has to format the *command* name, the *section* the manpage resides in, and the *version* of the module as the start of the generated manpage and return the formatted string.

  - **fmt\_manpage\_end**

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

  - **fmt\_moddesc** *desc*

    This command remembers its argument *desc* as a short description of the module the manpage resides in. It may or may not return a formatted string.

  - **fmt\_titledesc** *desc*

    This command remembers its argument *desc* as the title of the manpage. It may or may not return a formatted string. If this command was omitted the argument of **moddesc** has to be be used for the title as well.

  - **fmt\_copyright** *text*

    This command remembers its argument *text* as declaration of a copyright assignment for the manpage. When invoked more than once the assignments have to be accumulated. It may or may not return a formatted string.

    Assignments provided by this command have priority over information supplied by an doctools processing application.

  - **fmt\_description**

    This command separates the header part of the manpage from the main body. It may or may not return a formatted string.

  - **fmt\_require** *pkg* ?*version*?

    This command remembers its arguments as name and version of a package which is required by an application or other library to use the described package. It may or may not return a formatted string.

  - **fmt\_section** *name*

    This command partitions the body of the manpage into named sections. Note that the command **description** at the beginning of the manpage body implicitly started a section named "DESCRIPTION". A section command has to close the last **para**graph coming before it and also open the first paragraph of the new section. It may or may not return a formatted string.

  - **fmt\_subsection** *name*

    This command partitions the body of a *section* into named sub-sections. A subsection command has to close the last **para**graph coming before it and also opens the first paragraph of the new section.  It may or may not return a formatted string.

  - **fmt\_para**

    This command partitions the text in a section or sub-section into paragraphs. Each invokation has to close the paragraph coming before it and open a new paragraph for the text coming after.  It may or may not return a formatted string.

  - **fmt\_see\_also** *args*

    This command defines direct cross-references to other documents. Each argument is a label identifying the referenced document. If this command is used multiple times all the arguments have to accumulate. It may or may not return a formatted string.

  - **fmt\_keywords** *args*

    This command defines the keywords applying to this document. Each argument is a single keyword. If this command is used multiple times all the arguments have to accumulate.  It may or may not return a formatted string.

  - **fmt\_arg** *text*

    This command declares that the argument *text* is the name of a command argument.  It has to return a formatted string.

  - **fmt\_cmd** *text*

    This command declares that the argument *text* is the name of a command.  It has to return a formatted string.

  - **fmt\_opt** *text*

    This command declares that the argument *text* is something optional. It has to return a formatted string.

  - **fmt\_emph** *text*

    This command emphasizes the *text*.  It has to return a formatted string.

  - **fmt\_strong** *text*

    This command emphasizes the *text*. Same as **emph**. Usage of this command is discouraged. The command is deprecated and present only for backward compatibility.  It has to return a formatted string.

  - **fmt\_sectref** *text* ?*label*?

    This command declares that the argument *text* is the name of a section somewhere else in the document, and the current location should refer to it.  It has to return a formatted string. If a *label* is specified then it has to be used in the returned text. Otherwise the section title *text* is used.

  - **fmt\_syscmd** *text*

    This command declares that the argument *text* is the name of a system command.  It has to return a formatted string.

  - **fmt\_method** *text*

    This command declares that the argument *text* is the name of an object method.  It has to return a formatted string.

  - **fmt\_namespace** *text*

    This command declares that the argument *text* is the name of a namespace.  It has to return a formatted string.

  - **fmt\_option** *text*

    This command declares that the argument *text* is the name of an option.  It has to return a formatted string.

  - **fmt\_widget** *text*

    This command declares that the argument *text* is the name of a widget.  It has to return a formatted string.

  - **fmt\_fun** *text*

    This command declares that the argument *text* is the name of a function.  It has to return a formatted string.

  - **fmt\_type** *text*

    This command declares that the argument *text* is the name of a data type.  It has to return a formatted string.

  - **fmt\_package** *text*

    This command declares that the argument *text* is the name of a package.  It has to return a formatted string.

  - **fmt\_class** *text*

    This command declares that the argument *text* is the name of a class.  It has to return a formatted string.

  - **fmt\_var** *text*

    This command declares that the argument *text* is the name of a variable.  It has to return a formatted string.

  - **fmt\_file** *text*

    This command declares that the argument *text* is a file.  It has to return a formatted string.

  - **fmt\_uri** *text* ?*text*?

    This command declares that the argument *text* is an uri. The second argument, if it is present, is the human-readable description of the uri. In other words, the label for the link. Without a labeling text the uri is used as its own label.  It has to return a formatted string.

  - **fmt\_term** *text*

    This command declares that the argument *text* contains some unspecific terminology.  It has to return a formatted string.

  - **fmt\_const** *text*

    This command declares that the argument *text* is a constant value.  It has to return a formatted string.

  - **fmt\_nl**

    This command signals vertical space to separate blocks of text.  It may or may not return a formatted string.

  - **fmt\_example\_begin**

    This command begins an example block. Subsequent text belongs to the example. Line breaks, spaces, and tabs have to be preserved literally. It may or may not return a formatted string.

  - **fmt\_example\_end**

    This command closes the example block.  It may or may not return a formatted string.

  - **fmt\_list\_begin** *what*

    This command starts new list. The value of the argument *what* determines what type of list is opened. This also defines what command has to be used to start an item in the new list. The allowed types (and their associated item commands) are explained in the format specification, i.e. *doctools\_fmt*.  It may or may not return a formatted string.

  - **fmt\_list\_end**

    This command ends the list opened by the last **list\_begin**.  It may or may not return a formatted string.

  - **fmt\_bullet**

    This command starts a new list item in a bulletted list. The previous item has to be closed automatically.  It may or may not return a formatted string.

  - **fmt\_enum**

    This command starts a new list item in an enumerated list. The previous item has to be closed automatically.  It may or may not return a formatted string.

  - **fmt\_lst\_item** *text*

    This command starts a new list item in a definition list. The argument is the term to be defined. The previous item has to be closed automatically.  It may or may not return a formatted string.

  - **fmt\_call** *args*

    This command starts a new list item in a definition list, but the term defined by it is a command and its arguments. The previous item is automatically closed. The first argument is the name of the described command, and everything after that are descriptions of the command arguments.  It may or may not return a formatted string.

  - **fmt\_arg\_def** *type* *name* ?*mode*?

    This command starts a new list item in an argument list. The previous item has to be closed automatically. Specifies the data-*type* of the described argument, its *name* and its i/o-*mode*. The latter is optional.  It may or may not return a formatted string.

  - **fmt\_opt\_def** *name* ?*arg*?

    This command starts a new list item in an option list. The previous item has to be closed automatically. Specifies the *name* of the option and its arguments (*arg*). The latter is a list, and can be left out.  It may or may not return a formatted string.

  - **fmt\_cmd\_def** *command*

    This command starts a new list item in a command list.  The previous item has to be closed automatically. Specifies the name of the *command*.  It may or may not return a formatted string.

  - **fmt\_tkoption\_def** *name* *dbname* *dbclass*

    This command starts a new list item in a widget option list. The previous item has to be closed automatically. Specifies the *name* of the option, i.e. the name used in scripts, the name used by the option database (*dbname*), and the class (type) of the option (*dbclass*).  It may or may not return a formatted string.

  - **fmt\_usage** *args*

    This command is like **call**, except that a formatting engine must not generate output at the location of the command. In other words, this command is *silent*. The data it defines may appear in a different section of the output, for example a table of contents, or synopsis, depending on the formatting engine and its output format. It may or may not return a formatted string.

### IMPORTED ENVIRONMENT

The implementation of a doctools 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 doctools object controlling the engine:

  - Doctools commands

    - **dt\_copyright**

      This command returns a string containing the copyright information the doctools object was configured with (option **-copyright**).

    - **dt\_file**

      This command returns the full name of the file currently processed by the engine.

    - **dt\_fileid**

      This command returns the name of the file currently processed by the engine, without path, nor extension.

    - **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\_format**

      This command returns the name of the format currently executing.

    - **dt\_lnesting**

      This command returns the number of lists currently open.

    - **dt\_module**

      This command returns the name of the module the file currently processed belongs to.

    - **dt\_source** *file*

      This command allows the doctools 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.

    - **dt\_user**

      This command returns the name of the current user as known to the tcl interpreter the doctools object controlling the engine resides in.

  - 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 "*\_common.tcl*" contains default implementations of **fmt\_plaint\_text** and all the **fmt\_** 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**) cannot use it immediately, but have to have a copy at their location. Additional commands provided by this file are:

    - **c\_inpass**

      This command returns the id of the pass currently executing.

    - **c\_begin**

      This command signals that processing of the text after **manpage\_begin** has begun.

    - **c\_begun**

      This command checks the flag set by **c\_begin**.

    - **c\_set\_module** *text*

      This command remembers *text* as module information.

    - **c\_get\_module**

      This command retrieves the module information stored by **c\_set\_module**.

    - **c\_set\_title** *text*

      This command remembers *text* as title.

    - **c\_get\_title**

      This command retrieves the title stored by **c\_set\_title**.

    - **c\_provenance**

      This command returns a string describing how the input was processed.

    - **c\_pass** *pass proc arguments body*

      This command defines a procedure which is valid when pass *pass* of the engine is executed.

    - **c\_holdBuffers** *args*

      This command defines one or more buffers for holding data between passes.

    - **c\_hold** *buffer entry*

      This command adds an entry to the specified buffer. The buffer has to be defined by an earlier invocation of the command **c\_holdBuffers**.

    - **c\_held** *buffer*

      This command retrieves the contents of the specified buffer. The buffer is empty afterwards. All entries in the buffer are joined by newlines.

    - **c\_cnext**

      This command increments the counter and return its current value.

    - **c\_cinit**

      This command pushes the current counter on the stack and reinitialize the counter to zero.

    - **c\_creset**

      This command reinitializes the counter with the value on the counter stack and removes that value from the stack.

    - **NOP** *args*

      This command does nothing. It can be used in conjunction with **c\_pass** to visibly declare in which passes a formatting command has nothing to do.

    - **NYI** ?*message*?

      This command throws the error "*message* **Not yet implemented**".

    - **c\_sectionId** *name*

      This command remembers the name of the section for later cross-referencing.

    - **c\_possibleReference** *text gi*

      This command checks if a section is available for *text*. This command is currently tuned for use by engines like HTML and TMML.

## SEE ALSO

doctools, doctools\_fmt

## KEYWORDS

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

## COPYRIGHT

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