
The KHOROS_HOME/manual directory is organized by Volume of the Khoros
manual.  There is a directory corresponding to each Volume of the Khoros
manual, vol1, vol2, and vol3.  In each of these directories are 
subdirectories corresponding to each Chapter of the manual (ex. in vol1
are the Chapters chpt1, cantata, xprism2, etc.).  In each Volume
directory are files that contain the Volume cover page, title page, 
and contents.  Each of these files are referenced by the "Volx_hdr.man"
file.  This file contains the .so lines that pull in the other files.

There are two script programs for processing and printing the Khoros
manual.  These programs are "bldmanual", a low level script that is
called by the interactive script for printing the manual, "prnmanual".
To print the manual, one should invoke "prnmanual", which will prompt
the user for all the necessary information to print the manual.


Khoros script programs for the manual:

  bldmanual - pulls information from the doc directories (online help)
              and inserts it into the *.ms files.  Also expands the
              KHOROS_HOME paths to the full path for .so lines, and
              adds a .so line at the top of the file pointing to the
              tmac.manual.

  prnmanual - a script to automate the process of processing the various
              files through "bldmanual" and "eroff" for creating a 
              postscript file for a selected chapter.


File naming conventions for the manual directories:

  *.sec -  These files contain the actual documentation for a particular 
           section of the manual.  These files will be run through "tbl", 
           before being included in an *.ms file.
           IMPORTANT:  DO NOT DELETE FILES THAT END IN *.sec !!!

  *.man -  These are files that contain .so lines pointing to the sections
           that make up a particular chapter.  Associated with this file
           are the section files ending in *.sec which contain the actual
           documentation for that section.  The paths for the .so lines 
           have KHOROS_HOME in them, and will be expanded when processed
           by "bldmanual" or "prnmanual".  There should NOT be a .so line at
           the top of the file pointing to "tmac.manual".  A *.man file may also
           contain paths pointing to documentation from the doc directories.
           Prnmanual calls "bldmanual", and uses this information to pull in 
           documentation from the appropriate doc directory.  After running 
           the *.man file through "prnmanual" there will be a *.ms file 
           which is ready for generation of a postscript file by "eroff".
           This is all automated by the "prnmanual" script.
           IMPORTANT:  DO NOT DELETE FILES THAT END IN *.man !!!

  *.ms  -  These are files that have already been processed by "bldmanual"
           or "prnmanual" and are ready to be run through "eroff".
           These files have a .so line at the top, and all paths are expanded.
           The existence of these files depends upon whether "prnmanual"
           has been run.

  *.tbl -  These are intermediate files containing the documentation for a 
           particular section of the manual, after being run through "tbl".  


What the "prnmanual" script does -

In order to gain an understanding of how the "prnmanual" script works,
the following three cases are outlined.  Note that this information is
provided only as a guide to how the "prnmanual" script processes the
various files in the manual directories.  It is not necessary to 
execute each step, since running "prnmanual" will take care of processing
each file in the correct order.  The steps required for proceeding
from one type of file to the next are given for each case.

  Case 1 - A manual directory that contains a *.man file.  All that is
           required is to run "bldmanual" on the *.man file, which will
           produce a *.ms file.  The *.ms file can then be run through
           "eroff" to produce a postscript *.ps file.

           *.man ----> "bldmanual" ----> *.ms ----> "eroff" ----> *.ps


  Case 2 - A manual directory that contains a *.ms file.  The only step
           required here is to process the *.ms file with "eroff".  The
           *.ms file should contain all of the expanded paths and the
           .so line at the top pointing to tmac.manual.  This case will
           only occur if "bldmanual" or "prnmanual" was previously run.

           *.ms ----> "eroff" ----> *.ps


  Case 3 - A manual directory that contains one or more *.sec files and
           a *.man file.  The *.sec files must be processed with "tbl"
           resulting in *.tbl files.  The *.man file must then be run
           through "bldmanual" to expand all paths from KHOROS_HOME to
           the full path.  This will result in a *.ms file which will
           contain .so lines pointing to the corresponding *.tbl files
           that contain the chapter information.  The *.ms file can then
           be processed with "eroff" to produce a *.ps file.

           *.sec ----> "tbl" ----> *.tbl --|
                                           |
           *.sec ----> "tbl" ----> *.tbl --|
                                           \/
           *.man ----> "bldmanual" ------> *.ms ----> "eroff" ----> *.ps


Again, running "prnmanual" will process each file in the correct order,
and produce a postscript file for printing.   Prnmanual uses a database 
file "Chapters.list" to process a selected chapter from the Khoros manual.  
The file "Chapters.list" contains the paths to each document file for
the Khoros manual.
