Initial commit

1 files changed, 1004 insertions, 0 deletions

diff --git a/doc/unixiraf.ms b/doc/unixiraf.ms
new file mode 100644
index 00000000..1f8ea7bd
--- /dev/null
+++ b/doc/unixiraf.ms
@@ -0,0 +1,1004 @@
+.RP
+.TL
+UNIX/IRAF Installation and Maintenance Guide
+.AU
+Doug Tody
+.br
+Steve Rooke
+.AI
+.K2 "" "" "*"
+.br
+August 1987
+
+.AB
+The procedure for installing IRAF on a UNIX host is described.
+Procedures are given both for the initial system installation,
+and for updating an existing installation with a new version of IRAF.
+The interfaces for site specific devices such as video terminals,
+graphics terminals, printers, plotters, image displays, and so on are
+discussed, and the steps to be taken to interface a new device are
+described.
+.AE
+
+.pn 1
+.bp
+.ce
+.ps +2
+\fBContents\fR
+.ps -2
+.sp 3
+.sp
+1.\h'|0.4i'\fBIntroduction\fP\l'|5.6i.'\0\01
+.sp
+2.\h'|0.4i'\fBInstalling the System\fP\l'|5.6i.'\0\02
+.br
+\h'|0.4i'2.1.\h'|0.9i'Initial System Installation\l'|5.6i.'\0\02
+.br
+\h'|0.9i'2.1.1.\h'|1.5i'Create the `iraf' account\l'|5.6i.'\0\02
+.br
+\h'|0.9i'2.1.2.\h'|1.5i'Read the distribution tape\l'|5.6i.'\0\03
+.br
+\h'|0.9i'2.1.3.\h'|1.5i'Run the INSTALL script\l'|5.6i.'\0\03
+.br
+\h'|0.9i'2.1.4.\h'|1.5i'Relink the system if necessary\l'|5.6i.'\0\04
+.br
+\h'|0.4i'2.2.\h'|0.9i'Updating an Existing IRAF Installation\l'|5.6i.'\0\04
+.br
+\h'|0.9i'2.2.1.\h'|1.5i'Save Locally Modified Files\l'|5.6i.'\0\05
+.br
+\h'|0.9i'2.2.2.\h'|1.5i'Read the Distribution Tape or Tapes\l'|5.6i.'\0\05
+.br
+\h'|0.9i'2.2.3.\h'|1.5i'Restore Site-Dependent Files\l'|5.6i.'\0\05
+.br
+\h'|0.9i'2.2.4.\h'|1.5i'Run the INSTALL Script\l'|5.6i.'\0\06
+.br
+\h'|0.4i'2.3.\h'|0.9i'Configuring the IRAF Device Tables\l'|5.6i.'\0\07
+.br
+\h'|0.9i'2.3.1.\h'|1.5i'$hlib/zzsetenv.def\l'|5.6i.'\0\07
+.br
+\h'|0.9i'2.3.2.\h'|1.5i'$iraf/dev/devices\l'|5.6i.'\0\07
+.br
+\h'|0.9i'2.3.3.\h'|1.5i'$iraf/dev/termcap\l'|5.6i.'\0\07
+.br
+\h'|0.9i'2.3.4.\h'|1.5i'$iraf/dev/graphcap\l'|5.6i.'\0\07
+.br
+\h'|0.9i'2.3.5.\h'|1.5i'Network Tables\l'|5.6i.'\0\08
+.sp
+3.\h'|0.4i'\fBTesting the System\fP\l'|5.6i.'\0\08
+.sp
+4.\h'|0.4i'\fBReconfiguring the System\fP\l'|5.6i.'\0\09
+.br
+\h'|0.4i'4.1.\h'|0.9i'Bootstrapping the System\l'|5.6i.'\0\09
+.br
+\h'|0.4i'4.2.\h'|0.9i'Relinking the System\l'|5.6i.'\0\09
+.br
+\h'|0.9i'4.2.1.\h'|1.5i'Relinking individual packages\l'|5.6i.'\0\010
+.br
+\h'|0.4i'4.3.\h'|0.9i'Autogeneration of the System (SYSGEN)\l'|5.6i.'\0\010
+.br
+\h'|0.4i'4.4.\h'|0.9i'New Ports\l'|5.6i.'\0\011
+.sp
+5.\h'|0.4i'\fBTuning Considerations\fP\l'|5.6i.'\0\012
+.br
+\h'|0.4i'5.1.\h'|0.9i'Precompiling TERMCAP and GRAPHCAP Entries\l'|5.6i.'\0\012
+.br
+\h'|0.4i'5.2.\h'|0.9i'Stripping the System to Reduce Disk Consumption\l'|5.6i.'\0\012
+.sp
+6.\h'|0.4i'\fBInterfacing New Graphics Devices\fP\l'|5.6i.'\0\013
+.br
+\h'|0.4i'6.1.\h'|0.9i'Graphics Terminals\l'|5.6i.'\0\013
+.br
+\h'|0.4i'6.2.\h'|0.9i'Graphics Plotters\l'|5.6i.'\0\013
+.br
+\h'|0.4i'6.3.\h'|0.9i'Image Displays\l'|5.6i.'\0\014
+.sp
+7.\h'|0.4i'\fBThe IRAF Directory Structure\fP\l'|5.6i.'\0\014
+
+.nr PN 0
+.bp
+.NH
+Introduction
+.PP
+The procedure for installing IRAF on a UNIX host is complicated by the great
+variety of computers which run UNIX, by the many small differences in the
+operating system software on these machines, and by the differences in the
+hardware configurations of the various machines.  Fortunately, however,
+most sites installing UNIX/IRAF will be installing IRAF on a system which
+is already directly supported by NOAO, in which case the installation should
+be straightforward.
+.PP
+This system installation and maintenance guide describes those operations and
+procedures which are the same regardless of the peculiarities of each vendor's
+UNIX implementation.  To install or update IRAF on a specific machine you
+will need both this manual and the installation notes for your particular
+host system.  For example, to install IRAF on a Sun workstation you will
+follow the instructions given in this manual, plus those given in the
+\fISun/IRAF Installation Notes\fR.
+.PP
+The distribution tape is a snapshot of one of our local (NOAO/Tucson) UNIX/IRAF
+systems.  The device and system configuration tables come configured for our
+system, and will have to be modified as part of the installation process.
+These modifications are discussed in detail in this document.
+To simplify the installation process as well as future upgrades, we have tried
+to isolate the site dependent files to the minimum number of directories, i.e.,
+\fLdev\fR, \fLhlib\fR (a subdirectory of \fL$iraf/unix\fR), and \fLlocal\fR and its
+subdirectories.  The remainder of the system should not require any
+modifications.
+.sp
+.TS
+center;
+cb s s
+l l l.
+IRAF HOTLINE
+.sp
+telephone	\fL(602) 323-4160\fP
+internet	iraf@noao.arizona.edu
+BITnet	iraf@noao.arizona.edu
+	    (via Wisconsin gateway until 1 Dec 87)
+SPAN/HEPnet (DECnet)	draco::iraf or 5356::iraf
+UUCP/Usenet	seismo!noao!iraf, ihnp4!noao!iraf,
+	    uunet!noao.arizona.edu!iraf (after 1 Sept 87)
+.TE
+.PP
+An installation typically takes about an hour, somewhat longer if relinking is
+necessary.  Interfacing new graphics terminals, plotters, or image displays
+can take considerably longer, of course, and we will only touch upon such
+matters in the installation guide.  Feel free to contact the IRAF hotline for
+assistance if any problems should arise during the installation, or for help
+in interfacing new devices.
+
+.NH
+Installing the System
+.PP
+The procedures to be followed to install the system depend upon whether you
+are installing IRAF for the first time, or merely updating an existing IRAF
+installation.  If you updating an existing installation to the latest IRAF
+release you have less work to do, as you will have already modified the
+site-dependent files as part of the previous installation.
+Proceed to \(sc2.2 if that is the case.
+
+.NH 2
+Initial System Installation
+.PP
+This section documents the procedure for installing a binary distribution
+tape prepared on a compatible (VAX, Sun, or Microvax) system at NOAO.
+The procedure outlined in this section is also used to install a source
+distribution, the difference being that when one is done it is still
+necessary to do a sysgen to compile and link the system.
+If you have already installed IRAF and are merely installing a new release
+of the system, proceed to \(sc2.2 instead of following the procedure
+outlined here.
+.LP
+The basic system installation procedure is as follows:
+.RS
+.IP \(bu
+create the `iraf' account
+.IP \(bu
+read the distribution tape or tapes (UNIX \fItar\fR format)
+.IP \(bu
+run the \fLinstall\fR script
+.IP \(bu
+configure the device tables
+.RE
+.PP
+This should suffice for the basic installation of a full binary distribution.
+If executables were not included with the distribution (a "you relink" type
+distribution) then relinking will also be necessary, but this is easy.
+In some cases it may be desirable to delete all binaries and recompile the
+entire system, e.g., to reconfigure the system for different floating point
+hardware.  Once the basic system is up and running it will still be necessary
+to provide interfaces for the terminals, printers, plotters, and so on in
+use at your site, in order to have a fully functional system.
+
+.NH 3
+Create the `iraf' account
+.PP
+The first step is to set up an account for user `iraf'.
+IRAF is a big system and we do not recommend trying to install it as a
+subdirectory of someone's personal account.  IRAF system maintenance
+should be performed by the IRAF system manager while logged into the `iraf'
+account, to ensure that the environment is properly configured to run the
+system management tools.  Ordinary users should not have write permissions
+on the IRAF directories to avoid accidental deletion of critical files.
+.PP
+The pathname to the root directory does not matter, but it is wise to keep
+it short to speed up pathname resolution and to minimize the possibility
+of filename truncation.  A typical IRAF root directory is "\fL/usr/iraf\fR"
+or "\fL/u/iraf\fR".  The account should be set up to use \fL/bin/csh\fR as the
+standard shell.  The disk partition containing IRAF should have about 60 Mb
+of space available for the system; if necessary, the system can be stripped
+later to save space, but the full 60 Mb is required during system installation.
+.PP
+In what follows, we refer to the IRAF root directory as "\fL$iraf\fR", as if it
+were a cshell \fIsetenv\fR environment variable.  Note that during the
+initial stages of the installation this variable may not yet be defined,
+hence you should be prepared to manually substitute the actual pathname
+when entering the commands shown.
+.PP
+Contrary to common practice,
+the login directory for `iraf' is not \fL$iraf\fR as one would expect,
+but \fL$iraf/local\fR.  This is done so that all local files may be kept
+in one place, apart from the standard system.  This simplifies system
+updates and makes it easier to keep track of locally added or modified files.
+When creating the iraf account be sure to set up the root directory in this
+way, else when you later login as `iraf' you will not access the
+standard \fL.login\fR etc. files in the \fL$iraf/local\fR directory.
+
+.NH 3
+Read the distribution tape
+.PP
+The system is distributed on one or more UNIX \fItar\fR format tapes or
+cassettes.  Login as IRAF, go to the IRAF root directory, and enter the
+\fLtar\fR command shown for each tape in the distribution kit.
+The order in which the tapes are read is not important.
+Note that the \fL$iraf/local\fR directory, \fL.login\fR file,
+etc., will not be created
+until the tape is read, so the login will not be completely successful,
+but this is harmless.  Note also that the environment variable \fIiraf\fR
+has probably not yet been defined, so you must substitute the actual
+pathname to the iraf root directory when entering the commands shown below.
+.DS
+\fL% cd $iraf
+% tar -xpf /dev/\fIdevice\fR
+.DE
+The full system contains something like 7000 files in over 250 directories;
+printing the filenames (e.g., with \fLtar -tv\fR) as the tape is read is not
+recommended, as this can slow things down considerably.
+It typically takes a half hour or so to restore the tape or tapes to disk.
+.NH 3
+Run the INSTALL script
+.PP
+Once the system has been restored onto disk, most of the remaining work
+required for the basic installation is done by the semi-automated \fIinstall\fR
+script supplied with the system.  The install script edits various IRAF system
+configuration files to reflect the pathname to IRAF on the local system,
+and installs a few links in standard UNIX directories to define the UNIX
+level tasks necessary for the user to start up IRAF.
+.PP
+The install script may be run in "do-nothing" mode by specifying the -n
+option on the command line, as in the example below.  This is recommended
+the first time the script is run so that you can see what questions will be
+asked and what the script will do, without actually doing anything.
+.DS
+\fL% cd $iraf/unix/hlib
+% install -n\fR
+.DE
+The script will make educated guesses regarding the pathname to the iraf
+root directory, the pathname to the UNIX directory where locally added
+commands are normally put, and the pathname to the public scratch directory
+(\fLimdir\fR) where bulk image data is to be stored,
+and then ask for you to enter
+the pathnames to these directories, prompting with the values it has guessed.
+If the prompted value is acceptable hit return to accept it, otherwise
+you should enter a new value.
+.PP
+As mentioned earlier, typical values for the IRAF root directory are
+\fL/usr/iraf\fR or \fL/u/iraf\fR.
+If the actual directory is more obscure the script
+will fail to find it and you must enter the actual path.  Locally added UNIX
+level tasks are most commonly put in a directory like \fL/usr/local/bin\fR,
+but any directory in the normal user's search path will do, even \fL/usr/bin\fR
+if you have not defined a \fLlocal/bin\fR directory on your system.
+.PP
+Most likely the script will not find any good place for \fLimdir\fR,
+and will prompt
+with \fL/tmp\fR for lack of anything better.  This will work during the initial
+system testing, but is not recommended as a permanent solution as your image
+files will be deleted every time the system is rebooted.  On the other hand,
+we do not recommend storing bulk image data directly in the user directories
+as the disk management policies for large but short-lived data files tend to
+be different than those for small but long-lived user files.  The best solution
+is to set aside a large area (on our system it is \fL/tmp2\fR,
+\fL/tmp3\fR, etc.) which
+is not backed up daily or weekly, and in which files which have not been
+modified for two weeks or so are automatically deleted.  Another advantage of
+a separate area for large data files on BSD derived systems is that when you
+make the files system you can specify a larger than normal file system block
+size to increase the i/o bandwidth to disk.
+.LP
+Once you are happy with the installation procedure, become super user and
+run the install script for real, without leaving the \fLhlib\fR directory:
+.DS
+\fL% su
+% install\fR
+.DE
+You should now log out entirely and log back in as `iraf'.
+Type "\fLecho $iraf\fR"
+to verify that the system knows what the root directory is.  If you have
+installed a full binary distribution on a compatible machine you should be
+able to run IRAF by entering the commands \fBmkiraf\fR to configure the IRAF
+environment for user `iraf' (while still in the \fL$iraf/local\fR login
+directory) and \fBcl\fR to start up the IRAF Command Language (CL).
+If the CL does not run you must relink or recompile and relink the system,
+as described in the next section.
+
+.NH 3
+Relink the system if necessary
+.PP
+Relinking the IRAF system is necessary if the distribution was shipped
+without the executables in the \fLbin\fR directory (e.g. a `you-relink'
+system).  In order to relink, the system must first have been
+\fIbootstrapped\fR; see \(sc4.1 if in doubt or if it is necessary
+to perform a bootstrap.  `You-relink' and of course `load-and-go'
+distributions are already bootstrapped; source only distributions are not.
+.PP
+Relinking is covered in greater detail in \(sc4.2.  Briefly, to relink the
+entire system while spooling the output, run \fLmkpkg\fR from the IRAF root
+directory:
+.DS
+\fL% cd $iraf
+% mkpkg >& spool &\fR
+.DE
+See \(sc4.3 for information on inspecting a spoolfile for errors.
+A relink-only sysgen might take a half hour or so depending on the
+hardware configuration and system loading.
+.PP
+If IRAF is being installed on a host machine which is binary incompatible
+with the distributed system (e.g., because the local host uses floating point
+hardware not available at NOAO) then it may be necessary to strip the binaries
+and recompile the system from scratch.  Recompiling the full system can easily
+take an entire day (of computer time, not person time).
+
+.NH 2
+Updating an Existing IRAF Installation
+.PP
+Skip to \(sc2.3 if you are installing IRAF for the first time.  This section
+is for sites upgrading to a new version of IRAF.
+.PP
+Updating a UNIX/IRAF installation is similar to the initial installation
+procedure.  The main difference is that local modifications made to the
+site dependent files should be saved and then merged back into the generic
+system from the distribution tape.  The typical update process consists of
+the following steps:
+.RS
+.IP \(bu
+Save any locally modified files.
+.IP \(bu
+Delete the old system.
+.IP \(bu
+Read the distribution tape.
+.IP \(bu
+Restore site-dependent files.
+.IP \(bu
+Run the \fLinstall\fR script.
+.IP \(bu
+Relink the system if necessary.
+.RE
+.NH 3
+Save Locally Modified Files
+.PP
+Login as IRAF.  Ordinarily the only directories containing files you may wish
+to save are \fLdev\fR, \fLhlib\fR (\fL$iraf/unix/hlib\fR), and \fLlocal\fR.
+The safest and easiest way to do this is to save the entire contents of
+those directories.  For example:
+.DS
+\fL% cd $iraf
+% mkdir O
+% mv dev local unix/hlib O\fR
+.DE
+Many variations on this are of course possible.  The basic idea is to move
+the old directories to a nonstandard place so that they are not deleted or
+overwritten when we install the new system.
+.NH 3
+Read the Distribution Tape or Tapes
+.PP
+Having temporarily preserved all directories containing the locally modified
+files, it is now time to delete the old system and read in the new one.  If
+you are the cautious type you may wish first to preserve the entire
+existing IRAF system on an archive tape (e.g. if something were to have
+happened to the distribution tape en route).  The old system may be deleted
+as follows (assuming IRAF owns all the files in \fL$iraf/*\fR):
+.DS
+\fL% cd $iraf
+% rm -rf [a-z]*\fR
+.DE
+This will preserve the old site local files in subdirectory "O".
+Now read the distribution tape or tapes:
+.DS
+\fL% tar -xpf /dev/\fIdevice\fR
+.DE
+.LP
+Repeat this for each tape in the distribution set.  The order in which the
+tapes are restored is not important.
+.NH 3
+Restore Site-Dependent Files
+.PP
+You can either merge the contents of locally modified files saved from
+the previous installation into their counterparts in the new system, or edit
+the new ones from scratch.  Whichever is easier depends on how much editing
+you had to do in the first place, which probably depends upon the complexity
+of your local computer network and the number of peripheral devices.
+Any of the site configuration files might have been modified in the new
+release of IRAF, so in general one cannot simply replace such a file with
+the one that was saved.
+.PP
+Merging means inspecting the two files (newly distributed vs. its
+saved counterpart) for differences, and deciding how to update the new
+file with local device names, directory pathnames, etc.
+The UNIX "\fLdiff\fR" utility may be useful for this,
+depending on how much a file has changed, and how extensively it
+was modified locally.  One thing that is a big help is to keep track of
+all local changes made to the standard system in a local "notes" file;
+when the next system update occurs or when the installation is repeated on
+another cpu at the local site, one can then go down the list and make all
+the same changes to the newly installed system.
+.KS
+.TS
+center;
+ci ci ci
+l l l.
+directory	files	[and possibly]
+.sp
+\fLdev\fR	devices, graphcap, termcap	[, hosts, hostlogin, uhosts]
+\fLhlib\fR	zzsetenv.def	[, mkpkg.inc, mkpkg.sf]
+\fLlocal\fR	(any local additions)	[, all . (hidden) files]
+.TE
+.KE
+.PP
+The files which should be edited, via a diff/merge operation on the saved
+files or otherwise, are summarized in the table above.
+It is likely that only some of these files will have been modified at a
+given site; the ones in brackets are used at IRAF networking sites, for
+nonstandard compilation, and possibly window-system startup files for
+workstations.  In principle the entire contents of the \fLlocal\fR
+directories are site-dependent and may be preserved in toto during an
+update, but this is not true for all versions of IRAF, and sometimes
+we add things to these directories which user sites may be useful to user
+sites as well.
+.PP
+The \fLinstall\fR script, new in IRAF V2.5, takes care of the editing
+that previously was done manually on such files as \fLhlib$mkiraf.csh\fR
+and \fLhlib$libc/iraf.h\fR, so it is not necessary to diff/merge these files.
+.NH 3
+Run the INSTALL Script
+.PP
+Use of the \fLinstall\fR script is described in detail in \(sc2.1.3, and is
+summarized only briefly here.  To preview its effects (still logged in as
+`iraf'):
+.DS
+\fL% cd $iraf/unix/hlib
+% install -n\fR
+.DE
+If you are satisfied, login as superuser and execute it for real, still
+in the \fLhlib\fR directory:
+.DS
+\fL% su
+% install\fR
+.DE
+Then log out entirely and back in as `iraf'.  Verify that the system
+knows where the root directory is, using "\fLecho $iraf\fR".  At this
+point you can test the system as described in the last paragraph of
+\(sc2.1.3.  If everything works, the installation is complete, and the
+remainder of this manual will serve for system maintenance or when
+device configurations change.  If the CL does not run, you must relink
+or recompile and relink the system as described in \(sc2.1.4.
+
+.NH 2
+Configuring the IRAF Device Tables
+.PP
+The following files should now be edited to define the default terminal,
+printer, editor, and so on for your system.  Any part of this can be left
+until later if desired.
+.NH 3
+$hlib/zzsetenv.def
+.PP
+This file contains the name of the default editor, the default names of all
+the standard devices, and a number of other definitions which are not site
+dependent and which can therefore be ignored.  To be accessible by the IRAF
+system, each local device named must also have an entry in the \fLtermcap\fR
+file (terminals and printers) or \fLgraphcap\fR file (graphics terminals and
+image displays) in \fLdev\fR.  There must also be an \fIeditor\fL.ed\fR
+file in \fLdev\fR
+for the named editor; EDT, EMACS, and VI are currently supported.
+Edit the string to the right of the equals sign for the following entries.
+Sample values are shown.
+.DS
+\fLset editor	= "vi"
+set printer	= "imagen"
+set stdgraph	= "vt640"
+set stdimage	= "iism70l"
+set stdplot	= "versatec"
+set terminal	= "vt640"\fR
+.DE
+For example, you may wish to change the default editor to "\fLemacs\fR",
+the default printer to "\fLversatec\fR", the default image display to
+"\fLiism75\fR", and the default terminal to "\fLvt100\fR".  Note that the set of
+devices for which interfaces are already available is steadily growing
+but always finite.  The issues of interfacing new graphics and image
+display devices are discussed further in \(sc6.
+.NH 3
+$iraf/dev/devices
+.PP
+This file contains a list of the allocatable devices (primarily tape drives)
+for the local system.  It should be obvious how to change it by reading the
+comments in the file and studying the current values, which are for our system.
+.NH 3
+$iraf/dev/termcap
+.PP
+There must be entries in this file for all local terminal and printer
+devices you wish to access from IRAF (there is no \fLprintcap\fR file in IRAF).
+The entry for a printer contains one special (nonstandard termcap) entry,
+called DD.  This consists of three fields: node!device, the template for the
+temporary spoolfile, and the UNIX command to be used to dispose of the file to
+the printer.  On Berkeley UNIX it is rarely necessary to make use of the node
+name capability, since the UNIX \fLlpr\fR already provides this capability.
+.PP
+If you have a new terminal which has no entry in the termcap file provided,
+you probably already have an entry in the UNIX termcap file.  Simply copy it
+into the IRAF file; both systems use the same termcap database format.
+However, if this is also a graphics terminal with a device entry in
+\fLdev$graphcap\fR, you should add a `\fL:gd\fR' capability to the termcap
+entry.  If the graphcap entry has a different name from the termcap entry,
+make it `\fL:gd=\fIgname\fR'.
+.NH 3
+$iraf/dev/graphcap
+.PP
+There must be entries in this file for all graphics terminals, batch plotters,
+and image displays accessed by IRAF programs.  Weird graphics terminals will
+need a new entry.  The IRAF file \fLsys$gio/doc/gio.hlp\fR contains docs for
+graphcap.  A printed copy of this document is available upon request, however
+once IRAF is up you may find it easier to generate your own copy using
+\fLhelp\fR, as follows:
+.DS
+\fLcl> cd sys$gio/doc
+cl> help gio.hlp fi+ | lprint\fR
+.DE
+The manual page for the \fBshowcap\fR task should also be printed since this
+utility is useful for generating new graphcap entries.  More focused
+documentation will be available eventually.  Help is available for those who
+need it via the IRAF Hotline.  We ask that new graphcap entries be sent
+back to us so that we may include them in the master graphcap file for other
+sites to use.
+.NH 3
+Network Tables
+.PP
+The \fLdev\fR directory also contains a number of files (\fLhosts\fR,
+\fLhostlogin\fR, and \fLuhosts\fR)
+used by the IRAF network software.  We depend upon the networking capabilities
+of IRAF heavily at NOAO to access image displays, printers, files, etc. resident
+upon remote nodes (the IRAF network interface is also capable of spawning
+subprocess and background jobs on remote nodes, and works even when the nodes
+run different host operating systems, e.g., both UNIX and VMS).
+.PP
+We expect that most sites will not need this capability initially, hence
+documentation of the networking software will be left for later.  For sites
+that want to try it out, all that is necessary to enable networking is to
+edit the three networking files in the \fLdev\fR directory, and install IRAF on
+the other nodes.  It does not matter what native operating system runs on the
+remote nodes, so long as it runs IRAF as well.  The source for the network
+interface is in the \fLsys$ki\fR directory, and a discussion of the conceptual
+design of the interface is given in the \fLREADME\fR file in that directory.
+
+.NH
+Testing the System
+.PP
+Once the system has been installed or updated and the principal device tables
+configured, it is time to perform a few simple tests to make sure the system
+is working properly.  At this point it would probably be wise to read the
+CL User's Guide, if you have not already done so.  Once the IRAF environment
+is configured with \fLmkiraf\fR (discussed earlier) one need only enter the
+"cl" command to start up the CL.
+.DS
+\fL% cl\fR
+.DE
+After a bit IRAF should print the message of the day and the root IRAF menu,
+and issue the \fLcl> \fR prompt.
+Once in the CL, you will probably have magtape and printer access, are likely
+to have graphics terminal access, and very possibly will not have either
+image display access or graphics plotter access.  If the graphics terminal
+capability is ready, the next step is to run the IRAF test procedure to
+verify that all is working well, as well as try out a few of the many tasks
+in the system.  If the graphics terminal is not up yet, there is probably
+no point in running the test procedure.  To run the test procedure,
+familiarize yourself with the documentation in Volume 1A of the
+\fIIRAF User Handbook\fR and follow the instructions therein.
+
+.NH
+Reconfiguring the System
+.NH 2
+Bootstrapping the System
+.PP
+All current normal IRAF distributions come with the system already bootstrapped.
+A bootstrap should not be necessary unless one is doing something unusual,
+e.g., attempting a new port.
+.PP
+A bootstrap is like a full system sysgen, except that it is the host
+system interface (kernel and bootstrap utilities) which are compiled and
+linked, rather than IRAF itself.  The system must be bootstrapped before
+a sysgen is possible, since the bootstrap utilities are required to do a
+sysgen.  The two operations are distinct because only the bootstrap is
+machine dependent; everything else works the same on all IRAF systems.
+.PP
+The bootstrap operation is necessary when installing the system from a
+source only distribution tape.  We assume that the files in the host system
+interface have already been configured for the host system.  If this is
+not the case, then we are doing a port, which is a lot more ambitious than
+a simple bootstrap.
+.PP
+To bootstrap UNIX/IRAF, go to the \fLunix\fR directory and interpret the shell
+script \fLmkpkg.csh\fR.  This takes about 45 minutes, so the output should be
+spooled in a file.  Note that (for no good reason) the files have a \fL.csh\fR
+extension even though we have chosen to use the Bourne shell to execute
+the commands therein.
+.DS
+\fL% cd $iraf/unix
+% sh -x mkpkg.csh >& spool &\fR
+.DE
+A bootstrap recompiles everything whether it needs to or not, so it is
+usually not necessary to delete the binaries before doing a full bootstrap.
+
+.NH 2
+Relinking the System
+.PP
+Relinking the system is necessary if the system was shipped without
+the executables in the \fLbin\fR directory.  In order to relink the system must
+first have been bootstrapped.  When the system is shipped without
+executables (to save space) it will already have been bootstrapped.
+If it is necessary to bootstrap the system, e.g., given a source only
+distribution, go read \(sc4.1 before trying to relink the system.
+.PP
+The system is relinked by the bootstrap utility program \fBmkpkg\fR.
+The \fLmkpkg\fR program is driven by the \fLmkpkg\fR files found in all IRAF
+source directories.  Running \fLmkpkg\fR in a directory causes the
+contents of that directory, normally an applications package or library,
+to be updated, along with the contents of all subdirectories referenced
+by the root \fLmkpkg\fR file.
+.PP
+Running \fLmkpkg\fR in the root IRAF directory causes the entire system to
+be updated.  If the system libraries are all up to date, the effect is to
+relink the system.  If the system has been modified and some library modules
+have to be recompiled and inserted into the system libraries, then the
+operation is a partial sysgen.  If there are no libraries or object libraries
+then we have a full sysgen, which is the topic of the next section.
+The \fLmkpkg\fR utility is documented in detail in Volume 1B of the
+IRAF User Handbook, in the manual pages for the \fLsoftools\fR package.
+.LP
+To relink all of IRAF, go to the root and run \fLmkpkg\fR, i.e.,
+.DS
+\fL% cd $iraf
+% mkpkg\fR
+.DE
+The program will inspect all source modules and verify that the system
+libraries are up to date, then relink the system executables, followed by
+all the applications executables, installing the executable files in the
+\fLbin\fR directory.
+.NH 3
+Relinking individual packages
+.PP
+It is just as easy to relink the individual IRAF packages, e.g., after
+a bug has been fixed, or if an update of a package is received by electronic
+mail.  This would normally be done from within IRAF since the next step
+is to test the new package.  We will use the \fLcl> \fR prompt in the
+examples, but since \fLmkpkg\fR is a bootstrap utility (IRAF foreign task),
+usage is the same both in IRAF and in UNIX.
+.LP
+To relink a package and install the new executable in \fLbin\fR:
+.DS
+\fLcl> mkpkg update\fR
+.DE
+To relink a package, leaving the executable in the package directory for
+testing or debugging prior to installation:
+.DS
+\fLcl> mkpkg\fR
+.DE
+To install an already linked executable after testing:
+.DS
+\fLcl> mkpkg install\fR
+.DE
+To update only the package library without relinking (this assumes that the
+name of the library is \fLlibpkg.a\fR):
+.DS
+\fLcl> mkpkg libpkg.a\fR
+.DE
+The "update", "install", and "libpkg.a" identifiers are entry points in the
+\fLmkpkg\fR file, which may be read to see what is going on.
+.PP
+As an actual example of a package relink, suppose we wanted to increase the
+size of the stack area in the CL to 8000 elements, e.g., because the CL was
+running out of space at runtime.  We would go to the CL directory, edit
+the file \fLconfig.h\fR, change the value of \fLSTACKSIZ\fR to \fL8000\fR,
+and then run \fLmkpkg\fR:
+.DS
+\fLcl> cd cl
+cl> ed config.h
+cl> mkpkg update\fR
+.DE
+Since \fLconfig.h\fR is included by nearly all the CL source files, the entire
+package would be recompiled unnecessarily, but it is safer that way.
+
+.NH 2
+Autogeneration of the System (SYSGEN)
+.PP
+A full system sysgen is necessary when installing a source only version
+of the system.  The system must first have been bootstrapped; see \(sc4.1
+if this has not yet been done.  A full sysgen may also be necessary if
+a binary distribution has been received but it is later discovered that it is
+necessary or desirable to recompile the system.  In this case the existing
+libraries and objects \fImust be deleted\fR before the sysgen, else the sysgen
+will be nothing more than a relink.  The \fBrmbin\fR utility is used to
+descend a directory tree, deleting all binary files therein.  Note that
+the ONLY case in which it is necessary to use \fLrmbin\fR is when we wish
+to force the entire system to be recompiled.  The \fLrmbin\fR task is yet
+another bootstrap utility, and is documented in the manual pages for the
+\fLsoftools\fR package.
+.DS
+\fL% cd $iraf
+% rmbin -vi bin lib pkg sys\fR
+.DE
+This will delete all binaries in the portable part of the system, excluding
+the \fLhost\fR or \fL$iraf/unix\fR directories (if you run \fLrmbin\fR on the
+\fL$iraf/unix\fR directories, you will have to bootstrap the system as well).
+.PP
+Before starting the full system sysgen it may be desirable to review the
+switches in the file \fLmkpkg.inc\fR in the \fLhlib\fR directory.
+This is the global include file for the \fLmkpkg\fR utility,
+and contains various switches controlling \fLmkpkg\fR, e.g., which packages
+will be compiled, and the default compiler and linker flags.
+.PP
+Since a full sysgen takes a long time and generates a lot of output which
+later has to be reviewed, they are always run in batch with the output
+redirected, e.g.:
+.DS
+\fL% cd $iraf
+% mkpkg >& spool &\fR
+.DE
+To watch what is going on after this command has been submitted and while
+it is running, try
+.DS
+\fL% tail -f spool\fR
+.DE
+Sysgens are restartable, so if the sysgen aborts for any reason, simply
+fix the problem and start it up again.
+.PP
+A full sysgen generates a lot of output, too much to be safely reviewed for
+errors by simply paging the spool file.  Enter the following command to review
+the output (this assumes that the output has been saved in a file named
+\fLspool\fR).
+.DS
+\fL% mkpkg summary\fR
+.DE
+It is normal for a number of compiler messages warning about assigning
+character data to an integer variable to appear in the spooled output.
+These are harmless on most (but not all) machines, and are due to questionable
+coding practices in the old NCAR graphics utilities and some of the math
+library routines, all of which are coded in Fortran (SPP code never causes
+such problems!).
+.PP
+The discussion up to now has centered on the full system sysgen.
+Partial sysgens are actually much more common.  For example, if an important
+bug is fixed in the VOS or in the IRAF kernel, a (partial) sysgen should be
+conducted to recompile the affected modules and relink the system.
+An example of this occurs when the \fLtermcap\fR or \fLgraphcap\fR entries
+for important local devices are cached by running the \fBttycompile\fR
+task (another \fLsoftools\fR utility).  A sysgen is required after regenerating
+the cache tables, since these must be compiled and linked into the affected
+programs to have any effect.
+
+.NH 2
+New Ports
+.PP
+We recommend that you contact the IRAF group for assistance if you are
+contemplating porting IRAF to a new host machine.
+To port IRAF to a new version of UNIX requires some modifications to the
+files in the host interface directories (\fL$iraf/unix/\fR...),
+followed by a full
+sysgen and lots of testing.  Typically most of the code in the host interface
+can be used without change, with only minor changes to the remaining code,
+since the different versions of UNIX are quite similar (as compared to,
+for example, a port to a completely different operating system like VMS or
+AOS/VS).
+.PP
+Note that even when the target system is a "fully compatible" 4.X BSD UNIX
+system, some changes are likely to be necessary since all of these systems
+are slightly different.  For example, the SUN and ISI implementations of
+BSD UNIX employ different assemblers, and the Fortran compilers on the
+two systems have diverged considerably.  A port to Bell System V or one of
+the UNIX look alikes would certainly require some changes to the IRAF kernel,
+particularly in the exception handling, process control, and network interface
+facilities.
+.PP
+The changes required are likely to be minor for someone sufficiently familiar
+with both IRAF and UNIX, but should not be underestimated.  Every new port
+produces its share of compile time errors (due to differences in the Fortran
+compilers) and finds a few new bugs, sometimes in the IRAF software but more
+often in the host Fortran compiler, now that IRAF has been ported to so many
+systems.  A thorough understanding of both IRAF and the host system is required
+to rapidly isolate such bugs.
+
+.NH
+Tuning Considerations
+.PP
+There are two things that are commonly done to tune UNIX/IRAF for a
+particular host system:
+.RS
+.IP \(bu
+Precompile selected \fLtermcap\fR and \fLgraphcap\fR entries
+.IP \(bu
+Strip the system to reduce disk consumption
+.RE
+.LP
+The most important optimization is precompilation of the termcap and graphcap
+entries of the devices most commonly used at the local site, particular when
+running IRAF on a slow machine.  Stripping the system is inadvisable if the
+system is to be used for software development, but is normally desirable when
+installing a production version of IRAF on a small system with limited disk
+space, e.g., a workstation.
+
+.NH 2
+Precompiling TERMCAP and GRAPHCAP Entries
+.PP
+Precompilation of a termcap or graphcap entry is a technique used to
+speed runtime access of the entry for that device.  If the entry is not
+precompiled the termcap or graphcap file must be physically opened and
+scanned at runtime to read the desired entry.  This causes a noticeable
+delay of as much as a second when clearing the terminal screen or plotting
+a graph, hence it is usually worthwhile to cache the entries for commonly
+used video and graphics terminals.  It is not worthwhile for printers,
+plotters, and image displays.
+.PP
+The system comes with selected termcap and graphcap entries already
+precompiled.  To see which devices are precompiled, page the cache data
+files, \fLdev$cachet.dat\fR (for termcap) and \fLdev$cacheg.dat\fR
+(for graphcap).
+To cache a different set of entries one must regenerate these files with the
+\fBmkttydata\fR task in the \fLsoftools\fR package, and then do a full
+sysgen with the \fLmkpkg\fR utility.  Detailed instructions are given in
+the manual page for \fLmkttydata\fR.
+.PP
+Note that if you wish to precompile and relink the system to cache selected
+termcap or graphcap device entries and plan to strip the system as well to
+save disk space, \fIyou must cache the termcap and graphcap entries before
+stripping the system\fR, because once the system is stripped you cannot
+relink.
+
+.NH 2
+Stripping the System to Reduce Disk Consumption
+.PP
+If the system is to be installed on multiple cpus, or if a production
+version is to be installed on a workstation, it may be necessary or desirable
+to strip the system of all non-runtime files to save disk space.
+This equates to deleting all the sources and all the reference manuals and
+other documentation, excluding the online manual pages.  A special utility
+called \fBrmfiles\fR (in the \fLsoftools\fR package, of course) is provided
+for this purpose.  It is not necessary to run \fLrmfiles\fR directly to strip
+the system.  The preferred technique is to enter the commands given below.
+The example is for the cshell for consistency with the rest of this document,
+but this could be done from within the CL as well.
+.DS
+\fL% cd $iraf
+% mkpkg strip\fR
+.DE
+This will preserve all runtime files, permitting use of the standard system
+as well as user software development.  The size of the system is reduced
+from about 50 Mb (megabytes) to around 26 Mb.  One can optionally enter the
+command \fLmkpkg stripall\fR to delete the system libraries as well, but this
+saves only another couple of Mb and a full sysgen or a tape reload will be
+required to regain the capability to link user programs with the IRAF
+libraries (including IMFORT), or relink the IRAF executables.
+.PP
+Note:  if the \fLvms\fR directory is present at the \fL$iraf\fR root,
+it may be removed entirely.  On a full system it takes up over 3Mb, and
+may be present on some distribution tapes for UNIX/IRAF cut on our master
+development system.
+
+.NH
+Interfacing New Graphics Devices
+.PP
+There are three types of graphics devices that concern us here.
+These are the graphics terminals, graphics plotters, and image displays.
+
+.NH 2
+Graphics Terminals
+.PP
+The IRAF system as distributed is capable of talking to just about any
+conventional graphics terminal and most workstations' terminal emulators,
+using the \fLstdgraph\fR
+graphics kernel supplied with the system.  All one need do to interface to a
+new graphics terminal is add a new graphcap entry for the device.  This can
+take anywhere from a few hours to a few days, depending on one's level of
+expertise, and the perversity of the device in question.  Be sure to check
+the contents of the \fLdev$graphcap\fR file to see if the terminal is already
+supported, before trying to write a new entry.  Assistance in interfacing new
+graphics terminals is available via the IRAF Hotline.
+
+.NH 2
+Graphics Plotters
+.PP
+The current IRAF system comes with several graphics kernels used to drive
+graphics plotters.  The standard plotter interface is via the SGI graphics
+kernel, which has largely replaced the older \fLNCAR\fR kernel used in earlier
+versions of IRAF (in those earlier versions the \fLNCAR\fR kernel was called
+the \fLstdplot\fR kernel).  Further information on the SGI plotter interface
+is given in the paper \fIThe IRAF Simple Graphics Interface\fR, a copy of which
+is included with the installation kit.
+.PP
+SGI device interfaces for most
+plotter devices already exist, and adding support for new devices is
+straightforward.  Sources for the SGI device translators supplied with the
+distributed system are maintained in the directory \fL$iraf/unix/gdev/sgidev\fR.
+NOAO serves as a clearinghouse for new SGI plotter device interfaces;
+contact us if you do not find support for a local plotter device in the
+distributed system, and if you plan to implement a new device interface let
+us know so that we may help other sites with the same device.
+.PP
+The older \fLNCAR\fR kernel is used to generate NCAR metacode and can be
+interfaced to an NCAR metacode translator at the host system level to get
+plots on devices supported by host-level NCAR metacode translators.
+The host level NCAR metacode translators are not included in the standard
+IRAF distribution, but public domain versions of the NCAR implementation for
+UNIX systems are widely available.  A site which already has the
+NCAR software may wish to go this route, but the SGI interface will provide
+a more efficient and simpler solution in most cases.
+.PP
+The remaining possibility with the current system is the \fLcalcomp\fR kernel.
+Many sites will have a Calcomp or Versaplot libary (or Calcomp compatible
+library) already available locally.  To make use of such a library to get
+plotter output on any devices supported by the interface, one may copy
+the library to the \fLhlib\fR directory and relink the Calcomp graphics
+kernel.
+.PP
+A graphcap entry for each new device will also be required.  Information on
+preparing graphcap entries for graphics devices is given in the GIO design
+document, and many actual working examples will be found in the graphcap
+file.  The best approach is usually to copy one of these and modify it.
+
+.NH 2
+Image Displays
+.PP
+The current IRAF system does not yet have a well defined and well isolated
+device independent image display interface.  Work on such an interface is
+currently underway; contact the IRAF group at NOAO for further information
+on the status of the new display interfaces.  Further information on the
+image display interfaces currently available may be found in the
+\fIIRAF Newsletter\fR.
+.PP
+If there is no IRAF interface for your device, the best approach at present is
+to use the IMFORT interface and whatever non-IRAF display software you
+currently have to construct a host level Fortran or C display program
+(a number of people have also managed to construct an interface by hacking
+the IRAF display software in \fLpkg$images/tv/display\fR).
+The IMFORT library provides host system Fortran or C programs with access
+to IRAF images on disk.  Documentation on the IMFORT interface is available in
+\fIA User's Guide to Fortran Programming in IRAF -- The IMFORT Interface\fR,
+Doug Tody, September 1986, a copy of which is included in the IRAF User
+Handbook, Volume 1A.
+
+.NH
+The IRAF Directory Structure
+.PP
+The current full UNIX/IRAF directory structure is documented graphically in
+the appendix.  The main branches of the tree are the following; beneath the
+directories shown are some 250 subdirectories, the largest directory trees
+being \fLsys\fR, \fLpkg\fR, and \fLnoao\fR.  The entire contents of all
+directories other than \fLunix\fR, \fLlocal\fR, and a few configuration files
+in \fLdev\fR are fully portable, and are identical in all installations
+of IRAF sharing the same version number.
+.DS
+\fLbin        \fR- installed executables
+\fLdev        \fR- device tables (\fLtermcap\fR, \fLgraphcap\fR, etc.)
+\fLdoc        \fR- assorted IRAF manuals
+\fLlib        \fR- the system library; object libraries, global files
+\fLlocal      \fR- iraf login directory; locally added software
+\fLmath       \fR- sources for the mathematical libraries
+\fLnoao       \fR- packages for NOAO data reduction
+\fLpkg        \fR- the IRAF applications packages
+\fLsys        \fR- the virtual operating system (VOS)
+\fLunix       \fR- the UNIX host system interface (HSI = kernel + bootstrap utilities)
+.DE
+.LP
+The contents of the \fLunix\fR directory (host system interface) are
+as follows:
+.DS
+\fLas         \fR- assembler sources for UNIX/IRAF
+\fLboot       \fR- bootstrap utilities (mkpkg, rtar, wtar, etc.)
+\fLgdev       \fR- graphics device interfaces (SGI device translators)
+\fLhlib       \fR- host dependent runtime files
+\fLmc68000    \fR- Motorola 68xxx assembler sources
+\fLmkpkg.sh   \fR- executed to bootstrap the UNIX/IRAF HSI
+\fLos         \fR- OS interface routines (UNIX/IRAF kernel)
+\fLrmbin.sh   \fR- executed to delete binary files in subdirectories
+.DE
+.PP
+If you will be working with the system much at the system level, it will be
+well worthwhile to spend some time exploring these directories and gaining
+familiarity with the system.