%%+---------------------------------------------------------------+
%%+---------------------------------------------------------------+
%%+                        POWDER SUITE                           +
%%+---------------------------------------------------------------+
%%+---------------------------------------------------------------+
%%
%%	Software authors:
%%		B. H. Toby, Air Products and Chemicals, Inc.
%%		R. L. Harlow, Du Pont
%%		M. F. Garbauskas, General Electric
%%		R. Goehner
%%		M. A. Holomany, JCPDS-ICDD
%%		apologies to any contributors not mentioned here
%%
%%	Documentation author:
%%		B. H. Toby, 
%%		Air Products & Chemicals, Inc.
%%		7201 Hamilton Blvd.
%%		Allentown, PA 18195
%%		InterNET: tobybh@ttown.apci.com
%%
%%-------------------------------------------------------------------------
%%  Software Copyright 1988, 1989, 1990, 1991 and 1992 Brian H. Toby, 
%%  E. I. du Pont de Nemours and Co. and Air Products and Chemicals, Inc.
%%
%%  Permission is granted for unlimited use, distribution and modification 
%%  of this manual and associated software, provided that modified software 
%%  and software based on this code must also be made freely available.
%%-------------------------------------------------------------------------

\chapter Installation Instructions

%% The following programs have recently been revised for inclusion in 
%% this package:
%%	LOGIC
%%	SEARCH
%%	ENCODE
%%
%% The following programs are still under revision and may or may not 
%% function as desired.
%%	CMPR			
%%	MANIP
%%

This chapter gives instructions for loading the Powder Suite package 
onto a VAX/VMS system. The programs have been tested on systems running 
VMS version 4.7 through 5.4; the package will likely run under all 4.x 
versions but probably will not run on VMS version 3.x or earlier. It 
is recommended that the programs be relinked on your local system 
during installation and after each operating system upgrade. 

If bugs are found in these programs please document them as best 
possible and notify Brian Toby. If you want a rapid 
solution to the bug, you may be best off trying to fix it yourself. 
Bugs, particularly with fixes, will be greatly welcomed by the authors. 
Suggestions for additional features will not be quite so well received.

DCL procedures have been written to simplify installation. 
Most users will be able to load, install and rebuild the 
programs by following the few steps in the following section
and answering the few questions asked during the installation 
procedure.

\subrub
Summary of Installation Instructions
%----------------------------------%

\leftskip 0 in
  (0) Before starting to install the software, decide the following 
      items:
\par\leftskip 0.3 in
\TAB 
    (A)	Where will the software be placed: which device and which
	directory? Replace |dev:[dir...]| in the following steps
	with this information. For example: |USER:[XRD...]|
	to put the files in the XRD ``account'' or |DUA0:[000000...]|
	to create root-level directory |DUA0:[PS...]|.
\TAB 
    (B)	Which version of the PDF-2 (full) JCPDS-ICDD database will be
	used? Your choices are on disk, on CD-ROM or none.
	Where will this file be placed?
\TAB 
    (C)	What graphics devices are available on your system? What
	printers are available? Which printer and plotter
	should be the default device for users to send their
	output? What DCL commands will be needed to process 
	or queue the files?
		
\leftskip 0 in
  (1) Load the PS software/PDF-1 database/graphics library from tape
\par\leftskip 0.3 in
		|$ BACKUP  mua0:/SAV/REW dev:[dir...]/NEW_VERSION|

\leftskip 0 in
  (2) Install the PDF-2 (optional -- see below)
\par\leftskip 0.3 in

\leftskip 0 in
  (3) Use the installation procedure to link the code and create the 
      appropriate |.COM| files.
\par\leftskip 0.3 in
		|$ SET DEF dev:[dir.PS]|\>
		|$ @INSTALL|\>

\leftskip 0 in
  (4) Test the package.
\par\leftskip 0.3 in
		|$ SET DEF dev:[dir.PS]|
\par\leftskip 0.3 in
		|$ @PS| -- (try out HELP, LOGIC and SEARCH, test 
		    out as many options as possible)

\subrub
Required Directories and Files 
%----------------------------%

The package is distributed as two savesets on a single tape. The 
first saveset contains the Powder Suite software, including all 
source files and object files. Also included in the first saveset 
is a partial distribution of the graphics package used in the 
programs (PGPLOT) and the PDF-1 JCPDS-ICDD database files. 

The second saveset contains source code and documentation for 
the graphics package. This saveset need not be loaded, but may 
be of use to more advanced users. If the PDF-2 files will also 
be used with these programs, a CD-ROM or a set of tapes with the 
PDF-2 database must also be obtained from the JCPDS-ICDD.

The tape obtained from the JCPDS-ICDD may not be distributed to
anyone other than the intended receipient, since duplication and 
distribution of this tape would violate your copyright agreement with 
the JCPDS-ICDD. The Powder Suite software, without the database, 
may be distributed subject to the restrictions given at the copyright 
notice, above.

To run this package, you will need the files described in the 
following sections of this documentation. They consist of: 

\leftskip 0 in
\TAB 
  (1) The Powder Suite Files 

\leftskip 0.6 in
	The only Powder Suite program files that are required to be kept 
	on-line are the |.HLB|, |.EXE| and |.COM| files found in the |[PS.EXE]| 
	directory plus file |PS.COM| in the |[PS]| directory. The
	logical name |PS_EXE| will be needed to define the location of 
	executable files. 
	Other files that are needed to run the programs are:
	the PGPLOT Graphics library, usually located in the |[PS.PGPLOT]| 
	directory; the PDF-1 files, usually located in directory |[PS.PDF1]|;
	if the PDF-2 database is used, the three files in directory 
	|[PS.PDF2]|.

\leftskip 0 in
\TAB
  (2) The Graphics Package

\leftskip 0.6 in
	At a minimum, you will need to have the font table, file
	|GRFONT.DAT| on-line. Logical name |PGPLOT_FONT| will define
	the location of this file. To relink the programs you will 
	also need the non-shareable object library, |GRPCKG.OLB| or
	the shareable image files, |GRPSHR.EXE| and |GRPSHR.OLB|.
	If you use the shareable image version (recommended), you 
	will use logical name |GRPSHR| to define the location of
	the |GRPSHR.EXE| file.

	These files may be located on any on-line disk in any 
	directory where users of the programs will have read access. 
	As distributed, a subset of the PGPLOT files are located 
	in directory |[PS.PGPLOT]|.

\leftskip 0 in
\TAB
  (3) The JCPDS-ICDD Database 

PDF-1:\>
\leftskip 0.6 in
	A copy of the JCPDS-ICDD PDF-1 database is required to run 
	LOGIC and SEARCH. The PDF-1 files must be in the Harlow/Toby 
	modification of the format developed by Goehner and Garbauskas.
	These PDF-1 files optionally may be used in CMPR and MANIP. 
	This database is copyright by the International Centre for 
	Diffraction Data and may be only used with a license.

	The PDF-1 files can be located in any directory on any on-line 
	disk where users of the programs will have read access. Two 
	logical names |PS_JCPDS| and |PS_BITMAP| are used to define 
	the location of these files. As distributed, both sets of 
	files are located in directory |[PS.PDF1]|. 
	The PDF-1 files are build using the ENCODE programs from the 
	PDF-2 database. The ENCODE programs may also be used to 
	include locally defined entries in the database.

\leftskip 0 in
PDF-2:\>
\leftskip 0.6 in
	Program LOGIC can access the PDF-2 database from CD-ROM or
	from a disk file, but the PDF-2 file is not required for 
	program LOGIC. Program SEARCH does not access the PDF-2 
	database. 

\leftskip 0 in
\subrub
Loading The Source Code
%---------------------%

For the command procedures for compiling/linking and installation to 
work properly and for convenience, it is strongly suggested that 
you retain the directory structure used in the backup saveset. 

To restore the PS saveset, use the command:

\TAB {} |$ BACKUP  mua0:/SAV/REW dev:[dir...]/NEW_VERSION|

  where |dev:[dir]| is the directory where the package is to be placed.
  This creates subdirectory |dev:[dir.PS]| and a number of 
  ``sub-subdirectories'', for example |dev:[dir.PS.EXE]|.
  Use of this command will retain the original directory structure.
  If it is desired to move all the files or use a name other than 
  |[dir.PS...]|, the file |dev:[dir]PS.DIR| can be renamed. To create PS
  as a root directory, use |dev:[000000...]|. 

  Note that the name |mua0:| will need to be replaced with the 
  appropriate device name for your system, such as |MSA0:|, 
  |MKA500:|, or |$TAPE1:|
  

Likely, it will be most convenient to keep the source and object files 
on-line, since they require only around 5,000 blocks. However, you can 
delete either the source files or the object code (or both) after 
installation. The only files that must be retained are described in the
previous section. Note that command files |DELOBJECT.COM| and 
|DELSOURCE.COM| are provided for deleting the source and object code,
respectively.

\subrub
Plotting Package
%--------------%

After loading the PS files, the full PGPLOT/GRPCKG graphics library 
can optionally be loaded. This is not required, but is recommended 
for users who wish to ``get their hands dirty'' and optimize the 
installation for their own site, or modify the code, or write a 
graphics driver for an unsupported device (often not very difficult!).
The package is quite easy to use and may be valuable to users on
your system for their own programming.

For best performance and the smallest |.EXE| files you should use the 
shareable image version. (See Appendix C in the PGPLOT documentation 
files for more info.) No system privileges are needed to install the 
package as a shareable image. Note that if the shareable image will 
be used, an extra file (|GRPSHR.EXE|) must remain on-line and an extra 
logical name (|GRPSHR|) will be used.
If the shareable image is used, then support for additional graphics 
devices can be added without recompiling the Powder Suite programs. The 
main disadvantage is that the shareable library should be relinked
on each system (or cluster) where it will be used and should probably
be relinked after each operating system upgrade.

A subset of the full PGPLOT distribution is contained in subdirectory 
|[.PS.PGPLOT...]|. If the full package will be loaded, 
for simplicity it is recommended that the files are placed 
in a subdirectory |[.PS.PGPLOT...]|, using restore command

\TAB {}    |$ BACKUP  mua0:/SAV/NOREW dev:[dir.PS...]/NEW_VERSION|

There are many command files in the |[.PGPLOT]| directory for 
partial or complete rebuilds of the package. The most simple to use 
is procedure |PGINSTALL.COM| in the |[PS]| directory, which selects 
supported graphics devices, recompiles and relinks all code. That procedure
calls routines |CHOOSE.COM|, |COMPILE.COM|, |BUILD.COM| and 
|LIST_DRIVERS.COM|. Note that if drivers are added to the PGPLOT 
library, the Powder Suite programs need to be recompiled, unless
the shareable image version of PGPLOT has been used.

This package is copyright and is distributed with permission of the 
author, Tim Pearson of the Caltech Astronomy Department, on the 
provision that any software based on his package be distributed 
without a fee. 

If the shareable image is used, the following logical definitions will 
be needed:

{\parskip 0pt
\par\leftskip 0.3 in
to run:
\par\leftskip 0.6 in
	|$ PGPLOT   := $disk1:[public.pgplot]		! |system dependent\>
	|$ DEFINE PGPLOT_FONT     'PGPLOT'GRFONT.DAT|\>
	|$ DEFINE GRPSHR          'PGPLOT'GRPSHR.EXE|\>
\par\leftskip 0.3 in

to link:
\par\leftskip 0.6 in
	|$ DEFINE LNK$LIBRARY     'PGPLOT'GRPSHR.OLB|\>
\par\leftskip 0 in
\parskip 0pt}

As distributed, the |.EXE| files are linked without using the 
shareable image version of the library, since this is more portable.
The logical assignments are then:

{\parskip 0pt
\par\leftskip 0 in
to run:
\par\leftskip 0.6 in
	|$ PGPLOT   := $disk1:[public.pgplot]		! |system dependent\>
	|$ DEFINE PGPLOT_FONT     'PGPLOT'GRFONT.DAT|\>
\par\leftskip 0 in
to link:
\par\leftskip 0.6 in
	|$ DEFINE LNK$LIBRARY     'PGPLOT'GRPCKG.OLB|\>

\par\leftskip 0 in
\parskip 0pt}
These definitions can be put in the system startup files, login 
startup files. The are usually located in the |PS_LOCALINIT.COM| 
file of the PS package (described later).

\subrub
JCPDS-ICDD Files
%--------------%

The JCPDS-ICDD database consists of the following group of files:

{\parskip 0pt
\TAB {} |  CHEM.BITMAP;1          1300|
\TAB {} |  DI.LIBRARY;1          15093|
\TAB {} |  DSP00.BITMAP;1         3273|
\TAB {} |  DSP30.BITMAP;1         3273|
\TAB {} |  DSP3S.BITMAP;1         3273|
\TAB {} |  DSP70.BITMAP;1         3273|
\TAB {} |  ELMCOUNT.BITMAP;1       100|
\TAB {} |  JCPDS.INDEX;1          1599|
\TAB {} |  MISC.BITMAP;1           100|
\TAB {} |  NAME.DIRECT;1          7675|
\par\parskip 0pt}

Note that the actual sizes of these files varies with the version
of the database, the use of deleted patterns and the number of local
patterns which are added to the database.

A license from the JCPDS-International Centre for Diffraction Data 
is required for use of these files. Logical names |PS_JCPDS| and 
|PS_BITMAP| must be defined with the location of these files. 
Logical name |PS_BITMAP| points	to the location of the |.BITMAP| 
files, while logical name |PS_JCPDS| points to the remaining files. 

If Powder Suite will run on more than one computer (or cluster), 
the |PS_JCPDS| files may be accessed across a DECNET link and thus
stored on a single VAX, however this will slow database access 
and is not recommended. The programs have never been successfully 
run where the |PS_BITMAP| files are accessed via DECNET.

If the PDF-2 database will be accessed by program LOGIC, 
either on disk or on CD-ROM the following files are also be required:
{\parskip 0pt
\TAB {} |  CODENS40.DAT;1         266|
\TAB {} |  DISP.INIT;1              1|
\TAB {} |  MINERAL40.DAT;1         24|
\TAB {} |  VAXPDF40.BIN;1           7|
\par\parskip 0pt}
Note that in later releases the set number (40) may increase and the 
file sizes may also change. These files are provided by the JCPDS-ICDD
for use with the PDF-2 database.

Logical name |PS_PDF2_INDEX| must be defined with the location of these 
files. While it is possible to access the files across DECNET, again 
this is not recommended. 

If the PDF-2 file will be accessed by LOGIC on disk, logical name 
|PS_PDF2_DISK| should be defined to point to the directory containing 
the file:
{\parskip 0pt
\TAB {} |  JCPDS.DIRECT;1       255613|
\par\parskip 0pt}
Access of this file over DECNET has been tested and while it does result
in somewhat slower access, it is often faster than CD-ROM access and 
may well be worth the savings in disk space.

If the PDF-2 file will be accessed by LOGIC on CD-ROM, the disk should 
be mounted from a system-level account using the following command.
{\parskip 0pt
\TAB {} |  $ mount/for/sys/prot=(s:REWD,o:REWD,w:REWD,g:REWD) DUB0|
\par\parskip 0pt}
If the CD-ROM will be mounted on a device other than |DUB0:|, 
logical name |PS_PDF2_CDROM| should be defined to point to this device. 
The CD-ROM version of the PDF-2 may be shared on a cluster, provided 
that the drive appears to be local to each system on the cluster, but 
the CD-ROM drive cannot be shared via DECNET.

Program LOGIC can be used with either version of the PDF-2, or
without the PDF-2 database. The program checks for definition of
logical names |PS_PDF2_DISK| and |PS_PDF2_CDROM| to see if a PDF-2 
file is available.

\subrub
Compiling and Linking the Powder Suite
%-------------------------------------%

The executable files on the distribution saveset may not run 
properly on your system if you have an earlier version of VMS
than the one used for the distribution copy of the programs,
so it is recommended to relink during installation. This will be 
done by the |INSTALL.COM| command procedure as a default option. 
Other routines will be useful to people wishing customize or 
expand the programs or documentation.

  Supplied command files in directory |[.PS]|:

\TAB {} |INSTALL.COM| 
\par\leftskip 0.6 in
		A fairly user-friendly routine for installing and 
		linking the PS package. Checks for required files
		and relinks. Calls |SELPDF2.COM|, |WRINIT.COM|,
		|PGINSTALL.COM| and |CLEANUP.COM| and other files.

\leftskip 0 in
\TAB {} |HELP.COM| 
\par\leftskip 0.6 in
		Creates the main help files (|PS.HLB|) from the |.TEX| 
		documentation files. If file |LOCAL.HELP| is found in 
		the current directory this file is included in the
		help library. Also creates ASCII (|.DOC|) versions of 
		the \TeX\ documentation.

\leftskip 0 in
\TAB {} |CLEANUP.COM| 
\par\leftskip 0.6 in
		Deletes unneeded files.

\leftskip 0 in
\TAB {} |SELPDF2.COM| 
\par\leftskip 0.6 in
		Selects the version of the PDF-2 database to be used.

\leftskip 0 in
\TAB {} |WRINIT.COM|
\par\leftskip 0.6 in
		Writes the |PS_INIT.COM| file with logical definitions
		used to initialize the package.

\leftskip 0 in
\TAB {} |WRLINIT.COM|
\par\leftskip 0.6 in
		Can be used to write a |PS_LOCALINIT.COM| file with 
		logical definitions to initialize the package.

\leftskip 0 in
\TAB {} |DELOBJECT.COM|
\par\leftskip 0.6 in
		Deletes all object code files (|.OBJ|) and object code
		libraries (|.OLB|). This will save around 2,000 blocks
		at the expense of some computer time, if it is ever
		necessary to relink the package. Note that it will not
		be possible to rebuild these files if your system 
		does not have a FORTRAN compiler.
		
\leftskip 0 in
\TAB {} |DELSOURCE.COM|
\par\leftskip 0.6 in
		Deletes all FORTRAN and \TeX\ source and object code,
		and most command files. This will save around 4,000 
		blocks. However, it is not recommended to perform
		this action unless disk space is very tight as you
		may wish to rebuild some of the code at some future
		time. 

\leftskip 0 in
\TAB {} |MASTER.COM| 
\par\leftskip 0.6 in
		Used to recompile and link all programs and rebuild their
		help files. Calls |HELP.COM|.

\leftskip 0 in
\TAB {} |RELINK.COM| 
\par\leftskip 0.6 in
		Used to relink all programs using the existing object 
		libraries.

\leftskip 0 in
\TAB {} |PGINSTALL.COM|
\par\leftskip 0.6 in
		Facilitates the configuration, compiling and build
		libraries for PGPLOT.

\leftskip 0 in
\TAB {} |PGLNKLIB.COM|
\par\leftskip 0.6 in
		Specifies the location of the PGPLOT graphics library. 
		Created by |PGINSTALL.COM|; called as needed by the Link
		command files. Should never need to be called directly 
		or edited.

\leftskip 0 in
\TAB {} |GSASLNKLIB.COM|
\par\leftskip 0.6 in
		Specifies the location of the GSAS object library. 
		If GSAS is actively used and upgraded, it is best to
		modify this file to reference the file |GSASLIB.OLB|
		supplied by Los Alamos on their distribution tape.

\leftskip 0 in
\TAB {} |MAKEGSASLIB.COM|
\par\leftskip 0.6 in
		Used to update the subset of the GSAS object library
		used by PS. Before using the file, it must first be
		edited to specifies the location of the GSAS object 
		library. This need only be used when GSAS is upgraded.
		It is better to modify |GSASLNKLIB.COM| so that the 
		the file |GSASLIB.OLB| supplied by Los Alamos is used
		for linking.

\leftskip 0 in
\subrub
Installation of Command Procedures
%--------------------------------%

Two DCL command procedures are used to run the package:

|         XRD:[PS.EXE]PS_INIT.COM| and |XRD:[PS]PS.COM|.

   The first time the PS command procedure (|PS.COM|) is used, and any time
   the command procedure is used with the INIT option, the DCL procedure
   executes the system-wide definitions found in the |[PS.EXE]PS_INIT.COM|
   file. In addition, users may supply override these definitions with
   their own |PS_LOCALINIT.COM| file. The PS command procedure looks for a 
   file named |PS_LOCALINIT.COM| in:
\TAB
	(1) the current default directory
\TAB
	(2) the current login directory (as defined by |SYS$LOGIN|)

If neither of these files are found, and a |PS_EXE:LOCAL.COM| file is
found, this file is executed. This file may be used to provide a menu
of setup options. See the Customization chapter for more information.
%%(File CUSTOMIZE.DOC)

When |INSTALL.COM| is used, it creates the |PS_INIT.COM| file and 
updates the definition of logical name |PS_EXE| in file |PS.COM|. 
If for some reason |INSTALL.COM| is not used, this definition must 
be updated. In addition the definitions of the following logical 
names must be properly defined in file |PS_INIT.COM|.

\TAB {}
  |PS_EXE| is the location of the |.EXE|, the |.HLB| files, and the |.COM|
	files (file |PS.COM| can be located anywhere convenient).

\TAB {}
  |PS_JCPDS| and |PS_BITMAP| are the locations of the PDF-1 
  JCPDS-ICDD database files.
  |PS_PDF2_CDROM| or |PS_PDF2_DISK| and |PS_PDF2_INDEX| are the 
  locations of PDF-2 JCPDS-ICDD database files.

\TAB {}
  |PGPLOT_FONT| and possibly |GRPCKG| are needed for the PGPLOT graphics 
  package.

\TAB {}
  |PS_TMP| is a device/directory for scratch files.

\TAB {}
  |PS_HDEV| and |PS_HFILE| determine the default graphics hardcopy 
	device type (as defined in PGPLOT) and the default plot file name.
	A command to process the file can also be defined as |PS_HCOM|

\TAB {}
  |PS_PFILE| and |PS_PCOM| define a file to be used for a hard copy printer
	and an optional command to process/queue the print file after 
	it has been written. The are used the same manner as |PS_HFILE| and 
	|PS_HCOM|

\subrub
Upgrading the Database
%--------------------%

A new release of the database is generated each year by the ICDD. To replace
the old version of the database with the new version requires replacing
The PDF-2 database with the newer release and loading or rebuilding the 
PDF-1 files from the new PDF-2 files. 

If the PDF-2 is obtained from the ICDD on CD-ROM, loading the PDF-2 database
simply means placing the new CD-ROM into the CD drive. Loading the PDF-2
database to disk is a more difficult task, requiring that the file be copied
from tape or CD-ROM to disk. Program COPYCD in the |[.ENCODE]| is provided 
to copy the PDF-2 database from CD-ROM to disk, optionally removing deleted 
patterns. Program CDCOPY may be used to copy any file from the CD-ROM and
program CDDIR is used to list the contents of the database. To load the files
from magnetic tape, the BACKUP command is normally used. Instructions are
usually supplied with the tape.

The four files in directory |[.PS.PDF2]|: |DISP.INIT|, |CODENSxx.DAT|, 
|MINERALxx.DAT| and |VAXPDFxx.BIN| are created by the ICDD with each
release of the database, where |xx| is the most recent set number in the
release. It is suggested that you update these files with upgrade of the 
database, but this is not required. Note: all four files must 
be replaced at the same time.

Future releases of the PDF-2 on CDROM may possibly include the 
Powder Suite PDF-1 files. If so, instructions will be distributed 
with the CD-ROM on how to copy these files from the disk.

The PDF-1 files may be built from the PDF-2 database using the ENCODE 
programs or may be obtained from the ICDD. If the PDF-2 database will not
be used, the database must be obtained in PDF-1 format rather than 
PDF-2 format.

\subrub
Upgrading the Software
%--------------------%

To upgrade the software from previous versions of Powder Suite, 
you may load the new files into the same directories as the same 
previous version. If so, be sure to use the |/NEW_VERSION| option
for the |BACKUP| command. If the same directories are used, the old 
version of the program may not be accessed once the upgrade is started.

If space allows, it is also possible to load the Powder Suite 
files in a second location, build the programs (and possibly the PDF-1
database), test the new package and then delete the old version. If the
package will be moved (most easily by renaming the |PS.DIR| file), it
will be necessary to rerun the |INSTALL.COM| procedure after moving 
the files, but to save time, do not recompile or relink the programs.

The version of Powder Suite released with Set 41 of the database will 
not function with older versions of the PDF-1 files. If this version 
of the software will be used with a previous version of the database,
it is necessary to rebuild the PDF-1 database files from the PDF-2
database using the ENCODE programs.

\vfill\eject\chapter Programmer's Information

%-------------------------------------------------------------------%
%******************  Information for Programmers *******************%
%-------------------------------------------------------------------%

\subrub
Source Code
%---------%

The LOGIC, SEARCH and ENCODE programs consist of a large number of 
subroutines which are found in the appropriate directories. The 
subroutines in the |[.RET3]| routines are also used in LOGIC and ENCODE
for access to PDF-2 database. All programs use other subroutines found 
in the |[.SHARED]| directory. 

Routine |BUILD.COM| in each directory is used to compile and link 
the programs. This file in turn calls other files used to build and
interprete the command definition language (|.CLD|) file, compile
the program(s), build an object file library and finally link the 
program(s).

\subrub
Documentation/Help File Format
%----------------------------%

There are five on-line help libraries, |PS.HLB|, |LOGIC.HLB|, 
|SEARCH.HLB|, |CMPR.HLB|, and |MANIP.HLB|. These files may be
accessed with the command:

\TAB {}	|HELP/LIBR=PS_EXE:PS	|(etc.)

or by typing |@PS HELP| (or |PS HELP|). Help is also available from 
inside the CMPR, LOGIC, SEARCH and MANIP programs by typing HELP,
optionally followed by a command name. 

The online help files (|.HLP|) are encoded, along with the command definition
language (|.CLD|) files into \TeX\ documentation files (|.TEX|). These files 
have a simple, fixed format which allows a single file to be used for three 
different purposes. The |.TEX| files can be processed by the \TeX\ typesetting
language (see The \TeX book, D. Knuth, Addison Wesley) with no preprocessing.
However, since two simple editing procedures are used to convert the files
to |.CLD| and |.HLP| format, the number of \TeX\ commands should be 
restricted to those listed in the following paragraphs.

Documentation format: (angle brackets, |<| and |>|, delimit items that must
be specified.

{\parskip 0pt
|      %CLD%Module <program>_SUBCOMMANDS|\>
|      %CLD%|\>
|      \Program <program>|\>
|      %HLP%1 HELP|\>
|      %HLP%                Information on commands within <program>|\>
| |
|      %CLD% <... definition of 1st command ...>|\>
|      %CLD%|\>
|      \Command <name of 1st command>\par|\>
|      <... description of command goes here ...>|\>
|      \Parameter|\>
|      \parm|\>
|      parameter <name>\par|\>
|      <... a description of the parameter(s) goes here ...>|\>
|      \Qualifiers|\>
|      \qual|\>
|      <qualifier number 1>\<|\>
|      <qualifier number 2>\<|\>
|      <last qualifier>\par|\>
|      <... a description of the qualifier(s) goes here ...>|\>
|      \Examples|\>
|      \exam|\>
|      <line with an example>\par|\>
|      <... a description of the example goes here ...>|\>
|      	.|\>
|      	.|\>
|      	.|\>
\parskip 0pt}

Lines beginning with |%CLD%| will be copied to the |.CLD| file and the |%CLD%|
prefix will be removed. This prefix should appear at the beginning of each line.
(Lines with this prefix will be ignored by \TeX). 

The |.HLP| file is copy of the |.TEX| file except for the following changes:
The |%HLP%| prefix will be removed from lines so that will be used in 
the |.HLP| file, but will be ignored by \TeX. Lines beginning with
|\!| will be used in the \TeX\ file, but will be removed from the |.HLP| file.

The |\Qualifier|, |\Parameter|, |\Example| lines are translated
to the appropriate headers for Help library format, but they must start
in the first column. The |\Program| line is translated to a comment line.

Lines containing |\qual|, |\exam|, |\parm| and |%CLD%| are removed from the 
|.HLP| file.

The following \TeX\ codes are translated: (|``|) becomes (|"|); (|''|) becomes 
(|"|) and (|\#|) becomes (|#|). The following codes are removed: 
|\<|, |\par|, |{|, and |}|

The following definitions are used for \TeX\ special symbols and 
are translated to the string in parenthesis:
\TAB {} 
		|\Kalpha1|	(|K alpha 1|),
\TAB {} 
		|\Kalpha2|	(|K alpha 2|)
\TAB {} 
		|\twotheta|	(|two-theta|)
\TAB {} 
		|\muVAX| 	(|microVAX-II|)
\TAB {} 
		|\||TAB|	(two spaces)  

