Go to the previous, next section.

# The TIM Documentation Language

This document describes the TIM documentation language that the documentation for ILU is written in. It is not necessary to be familiar with TIM to use ILU; you will only need to know TIM if you wish to use it to write or modify documentation.

TIM is essentially a superset of the GNU texinfo language, version 2. It adds several features such as support for pictures and URLs, but its most important extension is to provide domain-specific markup commands to allow adding arbitrary meta-information to Texinfo documents. You should be familiar with the basic Texinfo system first. Documentation on Texinfo is supplied with the ILU distribution; you should be able to find it in the files ``ILUSRC/doc/texinfo2.ps'`.

## Introduction

Both TIM and Texinfo input files contain text `marked up' with document markup commands. These commands are similar to LaTeX commands, except that they start with an at-sign character rather than a backslash. They contain meta-information about the area of the text to which they apply. For example:

      A kernel server @dfn{export}s its objects by making them available
      to other modules.  It may do so via one or more @dfn{port}s, which are
      abstractly a tuple of (@metavar{rpc protocol}, @metavar{transport type},
      @metavar{transport address}).  For example, a typical port might
      provide access to a kernel server's objects via @code{(@protocol{Sun RPC},
      @transport{TCP/IP}, UNIX port 2076)}.  Another port on the
      same kernel server might provide access to the objects via
      @code{(@protocol{Xerox Courier}, @transport{XNS SPP}, XNS port 1394)}.

When formatted, this paragraph would look like

> A kernel server exports its objects by making them available to other modules. It may do so via one or more ports, which are abstractly a tuple of (rpc protocol, transport type, transport address). For example, a typical port might provide access to a kernel server's objects via `(`Sun RPC`, `TCP/IP`, UNIX port 2076)`. Another port on the same kernel server might provide access to the objects via `(`Xerox Courier`, `XNS SPP`, XNS port 1394)`.

There are two kinds of markup commands: without arguments or with arguments. The commands without arguments always span some portion of the document, so we call them span commands. They may be nested, but may not overlap. There are two forms of span commands, style commands and format commands. The style commands mark some section of the text, typically a short sequence of text, with a single attribute, which may be either a semantic tag like `important`, or a formatting style like `italic`. The format commands apply a similar tag to a block of the input; they begin with a single line containing `@attribute`, and end with a single line containing `@end attribute`. Style commands may be nested in a block command, but block commands should not be nested in style commands.

Markup commands with arguments always take a single line. The line begins with `@attribute`, followed by whitespace, followed by the arguments, separated by whitespace. If there is whitespace in an argument, the argument is surrounded with braces, as in
`@deffun {struct foo} Bar ( arg )`

## Extensions to GNU Texinfo

TIM removes the need to begin every file with `\input texinfo`, and to end every file with `@bye`. These lines are added automatically by TIM as needed. This allows a file to define both a stand-alone document, and to be included as a section in some larger document.

### TIM Domain-Independent Format

TIM domain-independent format (DIF) is basically Texinfo with four new built-in commands. They are:

- `@url`, a style command, is used to mark World Wide Web URL forms that appear in the text.
- `@picture`, a command with arguments, is used to include an Encapsulated Postscript picture into the document. It takes two arguments, the name of the file, and a caption for the picture. The caption may be omitted.
- `@ttitalic`, a style command, is used to indicate that this span should be rendered in an italic typewriter font, if available.
- `@timmacro`, a command with arguments, allows the user to define domain-specific markup commands. The two arguments are the macro name, and the macro's replacement in vanilla DIF.

### Defining Domain-Specific Markup Commands With @timmacro

[ TBD ]

## TIM Tools

ILU provides a program called `tim` to turn TIM files into either PostScript, text, or GNU Info files. It is invoked as

`tim output-format [ -s flag ] [ -m macros ] [ -o output-file ] [ input-file.tim ]`

where output-format must be either -p for Postscript output, -i for GNU Info output, -d for TIM DIF output, -t for plain text output, and -x for vanilla GNU Texinfo output.

In addition, the switch -v can be specified to cause the `tim` script to output information about progress, the switch -m macro-file-name may be specified to have `tim` pre-load a file of `@timmacro` macros, the switch -s may be specified to set various TexInfo conditional flags, and the switch -o output-file-name may used to specify the output file. If no input file is specified, `tim` reads from the standard input. If no output file is specified, `tim` writes to the standard output.

`tim` is a script written in the Python script language, so you will need to have `Python` installed to use it. See the ILU installation instructions for a location from which `Python` can be FTP'ed. The script uses the GNU programs `texindex` and `makeinfo`, along with `TeX` and `dvips`, so it is necessary to have all four of those programs installed to use `tim`.

Another program called `timdif2html` can be used to turn TIM DIF files into World Wide Web HTML. See the end of the `timdif2html` script for instructions on how to use it. It in turn uses the script `eps2gif`, which requires having `ghostscript` built with a GIF driver. Both `timdif2html` and `eps2gif` are Perl scripts, so the Perl interpreter `perl` must be installed to use them.

## Markup Commands used with ILU

The file ``ILUSRC/doc/ilu-macros.tim'` defines the following TIM markup commands that are used with the ILU documentation:

- `@var` is used to indicate a regular programming language variable. The term `@metavar` is used to mark meta-variables.

TIM also extends texinfo by adding the following markup:

- `@C` is used to mark artifacts of the C language, e.g., `@C{#define}`.
- `@C++` is used to mark artifacts of the C++ language, e.g., `@C++{#define}`.
- `@class` is used to mark names of object classes.
- `@command` is used to mark user input, such as a user-typed shell command, when it occurs in the normal flow of text. The term `@userinput` is used when the user input occurs within a `@transcript` section.
- `@codeexample` is used to mark code that is excerpted in the style of a texinfo `example`. The term `@codeexample` should appear on a line by itself, before the text of the code, and the terms `@end codeexample` should appear on a line by itself, at the end of the text of the code.
- `@cl` is used to mark artifacts of the Common Lisp language, e.g., `@cl{defmacro}`.
- `@constant` can be used to mark constant names and values that appear in the text.
- `@exception` is used to mark names of exceptions.
- `@fn` is used to mark function names that occur in the text.
- `@interface` is used to mark interface names.
- `@isl` is used to mark artifacts of the ILU ISL language, e.g. `@isl{SIBLING}`.
- `@java` is used to mark artifacts of the Java language, e.g. `@java{class Foo;}`.
- `@kwd` is used to mark keywords that occur in the text.
- `@language` is used to mark names of computer or human languages.
- `@m3` is used to mark artifacts of the Modula-3 language, e.g. `@m3{INTERFACE Foo;}`.
- `@macro` is used to mark names of macros that occur in the text.
- `@message` is used to mark in-line text that is a message a program may write to its output.
- `@metavar` is used to mark meta-variables.
- `@method` is used to mark method names.
- `@module` is used to denote module names for those languages which support them, such as Common Lisp package names, or Java package names.
- `@parm` is used to mark parameter names.
- `@picture` is used to include a file containing encapsulated Postscript of a diagram or picture. It should appear on a line, followed by the name of the file containing the picture, followed by a newline. We find the InterViews tool `idraw` works well in creating diagrams in the form of encapsulated Postscript.
- `@program` is used to mark program names that occur in the text.
- `@protocol` is used to mark names of ILU RPC protocols.
- `@symbol` is used to mark names of symbols in Makefiles or object files.
- `@system` is used to mark system names that occur in the text.
- `@switch` is used to mark command-line switches or options to programs.
- `@transcript` is used to mark an example that is a dialog between a user and a program. The term `@transcript` should appear on a line by itself, before the text of the dialog, and the terms `@end transcript` should appear on a line by itself, at the end of the dialog. The term `@userinput` may be used within a transcript.
- `@transport` is used to mark the names of ILU data transport systems.
- `@type` is used to mark the names of programming language types.
- `@url` is used to mark World Wide Web urls.
- `@userinput` is used to mark text typed by the user in a transcript section.

Go to the previous, next section.