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

@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.