# $Id: README,v 1.2 2004/01/17 04:03:55 wes Exp $
# $Revision: 1.2 $
# $Log: README,v $
# Revision 1.2  2004/01/17 04:03:55  wes
# Updates for 1.5.1.
#
# Revision 1.1.1.1  2003/01/28 02:15:23  wes
# Manual rebuild of rm150 repository.
#
# Revision 1.3  2000/04/22 02:03:16  wes
# More OpenRM 1.2.1 updates.
#
# Revision 1.2  2000/04/20 16:12:52  wes
# Updated to reflect new features of doc-building.
#
# Revision 1.1.1.1  2000/02/28 21:29:40  wes
# OpenRM 1.2 Checkin
#

Documentation Readme 

OpenRM provides the means to generate "man page" style HTML documentation
directly from the source code. This facility relies upon the presence
of "appropriate documentation" inside the source code, and the
scripts in this directory ($RM/doc).

By "appropriate documentation", we mean text that is surrounded by
recognizable tags inside the source file. There is a file in this
directory called "docTemplate.c" that should be used as a starting point.
That file contains text which we've doctored here as if to
document the sqrt() routine:

/*
 * ----------------------------------------------------
 * @Name sqrt
 @pstart
 double sqrt(double x)
 @pend

 @astart
 double x - a double precision floating point value (input)
 @aend

 @dstart
 The  sqrt()  function returns the non-negative square root
 of x.  It fails and sets errno to EDOM, if x is  negative.
 @dend
 * ----------------------------------------------------
 */

@Name - contains the routine name by itself.
@pstart/@pend - these tags surround the function prototype, and
	each of these tags should be on it's own line.
@astart/@aend - these tags surround a detailed description of the
	function arguments.
@dstart/@dend - surround whatever you want to write about the function.


Generating the documentation
----------------------------

1. From the $RM directory, type:
	% make docs

   There is also a "cleandocs" make target - that target will remove
   all the files from the $RM/doc/HTML directory.

   [ In OpenRM 1.2.0, the doc building process involved running a
   c-shell script manually. The shell script may now be invoked by the
   make target (above), or you can still run the script directly
   if desired

   1. cd to $RM/doc
   2. Make the docs:
	% cd $RM/doc
	% ./makeDocs.csh            // no args

   --- ]

Notes about how documentation is built:
	
a. Looks at all the .c source files in each of ../rm, ../rmv, ../rmi, and
   ../rmaux, then runs the source2html.pl script on each C source
   file creating a .html file in $RM/doc. The source2html.pl
   script looks for the tags (above) and creates HTML documentation.

b. Creates an index.html file inside $RM/doc that has hyperlinks to
   all the routines processed during step 3.a. The routines are
   sorted in ascending alphabetical order and formatted (lightly)
   to improve readability.

// April 2000 changes, thanks to jdb.

The new functionality is similar to before, except that the individual
libraries (rmaux, rm, rmv currently) each have their own index page,
referenced from the master `overview page'.  Public datatypes have
been added, and a bunch more documentation although some of that is a
bit terse.  Code tags for possible future developer documentation have
been inserted into the code (`PRIVATE' in comments, crude but
temporary).  The documentation is presented datatypes first and then
functions, indexed alphabetically (although the actual HTML files are
in file order).  The banner was hacked to make the docs a bit snazzier.

Viewing and Cleaning the Documentation
--------------------------------------

Point, click, and reference:
	% cd $RM
	% netscape ./doc/HTML/index.html

You can also clean up the documentation:
	% cd $RM
	% ./make cleandocs


--EOF--
