The IDS documents the design of the package at an internal, detailed
level.  Not only HOW but WHY should often be documented;  when a 
choice between two approaches is made, it is very useful to have the
reasoning explained.  This greatly assist the poor person stuck with
porting the package, or worse, maintaining it.

The IDS parallels the structure of the subsystem:

    - A section on each package (related group of programs)

	- A subsection on each program and library in the package.

	    - A chapter in the section on each file (source and
	      header) used to build the program.

	    - A set of paragraphs on each function within the file.

The program subsection should contain an overview of the program, what
does it do, why and how.  Any interesting packaging decisions should
be discussed.  If there are any restrictions on the program or "weirdness",
please discuss.  List the libararies needed to link the program.

The file chapters may have an overview if there is something
unobvious.  Its is frequently useful to discuss why the modules (functions)
are packaged together.  Cover the compilation dependences, which
header files are needed to compile the file.

For each function, discribe the calling sequence, returns, and errors.  
Use either english or pseudo-code to descibe the "algorithm" implemented
by the function.  Also describe the "global" data items effected by the
function if any, both as input and output.

Major pieces of the package which are not executable code, such as
data interchange formats (protocols), interprocess communication schemes,
etc should be covered at the same level as a source file.

See the postscript file ../doc/ids/IDS_structure.PS for a pictorial view
of the IDS structure.


SPECIAL MACROS for the IDS

The following troff macros have been defined in ids_setup.ms:

.Tc	Used to create a Table of Contents entry

	.Tc "This is an entry"
	
.Fi	Used to create both a Table of Contents and Index index entries
	for a file name.  Typically used in the numbered section header
	introducing the file and its functions:

	.NH 3
	.Fi junk.c
	.LP

.Fn	Used to create an Index entry for a module name and draw a box arround
	its name in the text.  Typically used to identify the module/function
	name under the section of the file which contains the function.

	.NH 3
	.Fi junk.c
	.LP
	This file contains a bunch of junky routines that do nothing.
	.Fn motherhood()
	.Cs
	int motherhood(char *nag)
	.Ce
	.IP Args: 4
	.RS
	.IP nag
	The favorite expression used to nag.
	.RE
	.IP Returns: 4
	.RS
	.IP 1
	Always returns true.
	.RE
	.LP		<--- note, this LP is inportant to reset indent

.Ix	Create index entry only, the argument is NOT printed in the text.

.Cs .Ce	Used to bracket a block of code or other items to be printed
	in a mono-spaced type and with fill turned off (no justification).


