
                  GUIDELINES FOR ON-LINE DOCUMENTATION


OVERVIEW

On-line documentation is reference by a  -H  line on a form.  There are two
options in using this, depending on the amount of information to be displayed.


SINGLE FILE

	If there is just a small amount (easily accessed on a single help pane),
	then the  -H  line should reference a single file.

DIRECTORY

	If there is too much information, then break it up into several files.  
	Generally there should be an  "Overview"  which gives a general 
	description of the topic of interest.  "Overview" will be the first 
	file that is displayed.  Create all the help files in a single 
	directory, giving them short appropriate names (the file name will 
	appear as the title on the help buttons themselves).  Then create a 
	subdirectory  /help  which will be the target reference given on the  
	-H  line of the form.


SPECIFIC GUIDELINES FOR CREATING ON-LINE DOCUMENTATION 

See the file  Template.doc  as an example:

1.  Filenames should end with the  .doc  extension.

2.  First line must be:

	.TH xxx yy

    where  xxx  identifies the application (Cantata, Xprism2, etc.)
    and  yy  indicates the specific location where this HELP will
    be referenced (Workspace, Files, etc.).

3.  Second and third lines should be:

	.SH
	ZZZZ

    where  ZZZZ  is the title for this particular HELP file (OVERVIEW,
    USAGE, etc.), preferably all CAPS.

4.  Fourth line should probably be:

	.LP

    followed by the appropriate description.  Start with a single
    sentence that summarizes what will follow.  This way the user will
    know if they want to read further.

    Use headings and white space liberally to improve readability.
    The user should be able to scan the information to find what they
    are looking for.  If it gets too long, break it up into different files.

5.  Do not include authors, copyright, etc.  Remember, this file will be 
    include, as is, in the printed manual (except for the top 3 lines).

6.  The formatdoc routine pipes the "file.doc" through nroff, etc. to produce
    the "file" which is referenced on the the -H line of the form.

    The arguments for formatdoc are:

        -i <filename>  (optional for types alldoc and allhelp) 

        -type doc      (formats a single  .doc  file)
	-type alldoc   (formats all the .doc files in a directory)
	-type help     (formats a single file, placing the result in the
		        subdirectory  /help  which must already exist)
	-type allhelp  (formats all the files in a directory, placing the
		        results in the  /help  subdirectory)

CANTATA MANUAL PAGES

cantata manual pages are derived from man/man1 files and are formated
by using the command vuphelppage(1).
