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

TIM is essentially a superset of the GNU texinfo language, version 2. It adds several features to allow more precise discrimination of semantics when documenting software systems. 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 ``ilu/doc/texinfo2.ps'`.

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 redefines the following texinfo markup commands:

- `@var` is now 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}`.
- `@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 Modula-3 module 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.

## TIM Tools

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

    % tim -t INPUTFILE.tim >OUTPUTFILE.ps

to produce PostScript code from a .tim file, or as

    % tim -i INPUTFILE.tim >OUTPUTFILE.info

to produce GNU Info code, or as

    % tim -w INPUTFILE.tim >OUTPUTFILE.html

to produce World Wide Web HTML, or as

    % tim -x INPUTFILE.tim >OUTPUTFILE.texinfo

to produce GNU texinfo code.

`tim` is a script written in the perl script language, so you will need to have `perl` installed to use it. See the ILU installation instructions for a location from which `perl` can be FTP'ed.

Go to the previous, next section.