@setfilename tim.info
@settitle The TIM Documentation Language
@ifclear largerdoc
@titlepage
@title The TIM Documentation Language
@author Bill Janssen @code{<janssen@@parc.xerox.com>}
@sp
@today{}
@sp
Copyright @copyright{} 1993 Xerox Corporation@*
All Rights Reserved.
@end titlepage
@end ifclear

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

@section TIM

@language{TIM} is essentially a superset of the @system{GNU} @language{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
@language{texinfo} system first.  Documentation on @language{texinfo} is supplied
with the @system{ILU} distribution; you should be able to find it in the files
@file{ilu/doc/texinfo2.ps}.

@language{TIM} removes the need to begin every file with @code{\input texinfo},
and to end every file with @code{@@bye}.  These lines are added automatically by
@language{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.

@language{TIM} redefines the following @language{texinfo} markup commands:

@itemize @bullet
@item
@kwd{@@var} is now used to indicate a regular programming language variable.  The term @kwd{@@metavar}
is used to mark meta-variables.
@end itemize

@language{TIM} also extends @language{texinfo} by adding the following markup:

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

@section TIM Tools
@system{ILU} provides a program called @program{tim} to turn @language{TIM} files
into either @language{PostScript} or @system{GNU} @language{Info} files.  It is
invoked either as
@transcript
% @userinput{tim -t @metavar{INPUTFILE}.tim >@metavar{OUTPUTFILE}.ps}
@end transcript
@noindent
to produce @language{PostScript} code from a .tim file, or as
@transcript
% @userinput{tim -i @metavar{INPUTFILE}.tim >@metavar{OUTPUTFILE}.info}
@end transcript
@noindent
to produce @system{GNU} @language{Info} code, or as
@transcript
% @userinput{tim -w @metavar{INPUTFILE}.tim >@metavar{OUTPUTFILE}.html}
@end transcript
@noindent
to produce @system{World Wide Web} @language{HTML}, or as
@transcript
% @userinput{tim -x @metavar{INPUTFILE}.tim >@metavar{OUTPUTFILE}.texinfo}
@end transcript
@noindent
to produce @system{GNU} @language{texinfo} code.

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

