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:

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 [ -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, 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:

TIM also extends texinfo by adding the following markup:

Go to the previous, next section.