Initial commit

11 files changed, 4263 insertions, 0 deletions

diff --git a/noao/obsutil/src/doc/bitcount.hlp b/noao/obsutil/src/doc/bitcount.hlp
new file mode 100644
index 00000000..22744f83
--- /dev/null
+++ b/noao/obsutil/src/doc/bitcount.hlp
@@ -0,0 +1,80 @@
+.help bitcount Mar93 noao.obsutil
+.ih
+NAME
+bitcount - accumulate the bit statistics for a list of images
+.ih
+USAGE
+bitcount images
+.ih
+PARAMETERS
+.ls images
+A list of image names whose bit statistics will be counted.  The
+statistics can either be reported for each individual image (the
+default) or as a grand total over all the images.
+.le
+.ls grandtotal = no
+If \fIgrandtotal\fR = yes, accumulate a grand total over all the
+images.  If \fIgrandtotal\fR = no (the default), report the statistics
+individually for each image in turn.
+.le
+.ls leftzeroes = yes
+If \fIleftzeroes\fR = yes, leftmost zeroes are counted into the
+statistics (the default).  If \fIleftzeroes\fR = no, leftmost zeroes
+(those past the most significant digit for each individual pixel)
+are omitted from the statistics.
+.le
+.ls verbose = yes
+If \fIverbose\fR = no, only the raw bit counts will be reported.
+.le
+.ih
+DESCRIPTION
+\fIBitcount\fR will report the absolute and relative proportions
+of zeroes and ones populating each bit plane of a list of images.
+This is useful for diagnosing problems with a CCD's A/D converter,
+especially when an input image is supplied that contains a linear
+ramp in exposure across the range of the A/D.
+
+The statistics for the list of images can be accumulated either
+individually for each image, or as a grand total over all of the
+images depending on the value of the \fIgrandtotal\fR parameter.
+A single linear exposure ramp can be mimiced by a grand total
+over a list of progressively more exposed images.  Care should
+be taken to arrange that the exposures sample all parts of the
+A/D's range.
+
+The \fIleftzeroes\fR parameter is used to correct a problem seen
+with the ctio.bitstat task.  Bitstat under-reports zeroes for the
+more significant bits since only pixels with values greater than
+the bit being currently counted participate in that count.  The
+severity and precise nature of this problem depends on the exposure
+level of a particular test image.  \fILeftzeroes\fR may be set to
+"no" if there is some reason to restore this behavior.
+
+The \fIverbose\fR parameter may be set to "no" in order to pass
+the raw bit counts on to some other task.
+.ih
+EXAMPLES
+To report the bit statistics for a test exposure ramp:
+
+.nf
+    nl> bitcount testramp
+.fi
+
+To accumulate a grand total over a list of images:
+
+.nf
+    nl> bitcount a001*.imh grandtotal+
+.fi
+.ih
+BUGS
+A warning will be issued when accumulating a grand total over a list
+of images whose datatypes vary.  In this case, the totals for each bit
+will be correct - to the extent that some images may not populate some
+bits - but the datatype of the final image in the list will control the
+range of bitplanes included in the output report.  The interpretation
+of the most significant bit as a sign bit will also depend on the
+datatype of this final image.
+.ih
+SEE ALSO
+imstatistics, ctio.bitstat
+.endhelp
diff --git a/noao/obsutil/src/doc/ccdtime.hlp b/noao/obsutil/src/doc/ccdtime.hlp
new file mode 100644
index 00000000..0dee4ed1
--- /dev/null
+++ b/noao/obsutil/src/doc/ccdtime.hlp
@@ -0,0 +1,364 @@
+.help ccdtime Nov01 noao.obsutil
+.ih
+NAME
+ccdtime -- compute time, magnitude, and signal-to-noise for CCDs
+.ih
+USAGE
+ccdtime
+.ih
+PARAMETERS
+.ls time = INDEF
+Time in seconds for output of magnitude at the specified signal-to-noise and
+signal-to-noise at the specified magnitude.  This time applies to all
+filters.  If specified as INDEF then no output at fixed exposure time will
+be produced.  If the value is not greater than zero or less than 100000
+an error is reported.
+.le
+.ls magnitude = 20.
+Magnitude for output of time at the specified signal-to-noise and
+signal-to-noise at the specified time.  This magnitude applies to all
+filters. If specified as INDEF then no output at fixed magnitude will
+be produced.  If the absolute value of the magnitude is greater than 40
+an error will be reported.
+.le
+.ls snr = 20.
+Signal-to-noise ratio for output of time at the specified magnitude and
+magnitude at the specified time.  This signal-to-noise ratio applies to all
+filters. If specified as INDEF then no output at fixed signal-to-noise
+ratio will be produced.  If the value is not greater than zero or less than
+100000 an error is reported.
+.le
+
+.ls database = "ccdtime$kpno.dat"
+Database file for telescope, filter, and detector information.  The format
+of this file is described elsewhere.  This file is typically a standard
+file from the logical directory "ccdtime$" or a personal copy in a
+user's directory.
+.le
+.ls telescope = "?"
+Telescope entry from the database.  If "?" a list of telescopes in the
+database is produced.  The name must match the entry name in the database
+but ignoring case.  If the same telescope has multiple focal ratios then
+there must be multiple entries in the database.
+.le
+.ls detector = ""
+Detector entry from the database.  If "?" a list of detectors in the
+database is produced.  The name must match the entry name in the database
+but ignoring case.
+.le
+.ls sum = 1
+CCD on-chip summing or binning factor.
+.le
+.ls seeing = 1.5
+Expected seeing (FWHM) in arc seconds.  The number of pixels used for computing
+the total star counts and the signal-to-noise is given by 1.4 times the square
+of the seeing converted to pixels and rounded up.
+.le
+.ls airmass = 1.2
+Airmass for observation.
+.le
+.ls phase = 0.
+Moon phase in days (0-28) for the estimation of sky brightness.  A
+phase of zero is new moon or dark sky conditions and a phase of 14
+is full moon.
+.le
+
+.ls f1 = "U", f2 = "B", f3 = "V", f4 = "R", f5 = "I"
+Filters for which to compute the CCD information.  If given as "?"
+a list of filters in the database is produced.  If the name (ignoring
+case) is not found then it is ignored.  A null name, that is "", is used
+to eliminate listing of a filter.  If more than five filters is desired
+each of the parameters may be a comma delimited list of desired filters.
+Note that whitespace is preserved so "U, V" will expand to "U" and " V"
+and so will not match "V" in the database.  Use "U,V" instead.
+.le
+.ih
+DESCRIPTION
+A telescope, CCD detector, and list of filters is selected from a database
+to define the expected photon/electron count rates.  These rates along with
+a specified seeing and airmass are used to estimate the signal-to-noise
+ratio (SNR) for a stellar observation in each filter.  The output provides
+three results per filter; the exposure time to achieve a desired SNR for a
+given magnitude, the magnitude to achieve a desired SNR in a given time, and
+the SNR at a specified magnitude and exposure time.  With each of these,
+the number of star photons (or CCD electrons) in an area 1.4 times the
+square of the seeing, the number of sky photons per pixel, and the RMS noise
+contributions from photon noise in the star, the sky, and the detector
+noise from dark current and read out noise are given.  Note that least two
+of the time, magnitude, and signal-to-noise ratio must be specified but if
+one is INDEF then output with that quantity fixed will be skipped or, in
+other words, only the output where the quantity is computed is produced.
+
+The calibration information needed to define the count rates are
+taken from a database file.  This file may be standard ones given in
+the logical directory "ccdtime$" or the user may create their own.
+The database contains entries organized by telescope name (which may
+include a focal ratio if there are multiple ones), detector name,
+and filter name.  One of the standard files may be used as a template.
+
+The file is actually in free format with whitespace and comments ignored.
+However, following the template formatting makes it easy to see the logical
+structure.  All lines, except the "end" line which separates the different
+catagories of entries, consist of a keyword an equal sign, and a value
+separated by whitespace.  An entry begins with one of the keywords
+"telescope", "detector", or "filter" and ends with the beginning of
+a new entry or the "end" separator.
+
+A keyword is one of the words shown in the example below.  These keywords
+can also be indexed by the name of a telescope, filter, and/or detector
+entry.  This allows having different transmissions in different filters
+due to correctors, different scales for different detectors which may
+have fore-optics, etc.
+
+Specifically a keyword in the telescope section may have arguments
+from the filter or detector entries, a keyword in the filter section may
+have arguments from the telescope and detector entries, and a keyword
+in the detector section may have arguments from the telescope and filter
+entries.  The formats are keyword, keyword(arg), and keyword(arg,arg).
+The arg fields must match an entry name exactly (without the quotes)
+and there can be no whitespace between the keyword and (, between (
+and the argument, between the arguments and the comma, and between the
+last argument and the closing ).  The software will first look for
+keywords with both arguments in either order, then for keywords with
+one argument, and then for keywords with no arguments.
+
+Below is an example of each type of entry:
+
+.nf
+    telescope = "0.9m"
+	    aperture = 0.91
+	    scale = 30.2
+	    transmission = 1.0
+	    transmission(U) = 0.8
+	    transmission(U,T1KA) = 0.7
+
+    filter = "U"
+	    mag = 20
+	    star = 18.0
+	    extinction = 0.2
+	    sky0 = 22.0
+	    sky1 = -0.2666
+	    sky2 = -.00760
+
+    detector = "T1KA"
+	    rdnoise = 3.5
+	    dark = 0.001
+	    pixsize = 24
+	    U = 0.36
+	    B = 0.61
+	    V = 0.71
+	    R = 0.78
+	    I = 0.60
+.fi
+
+In the example, a transmission of 0.7 will be used if the filter is U
+and the detector is T1KA, a value of 0.8 if the filter is U and the
+detector is not T1KA, and a value of 1 for all other cases.
+
+The telescope entry contains the aperture diameter in meters, the
+scale in arcsec/mm, and a transmission factor.  The transmission factor is
+mostly a fudge factor but may be useful if a telescope has various
+configurations with additional mirrors and optics.
+
+The filter entry contains a fiducial magnitude and the total photon count
+rate for a star of that magnitude.  The units are photons per second
+per square meter of aperture.  An effective extinction in magnitudes/airmass is
+given here.  The sky is defined by a quadratic
+function of lunar phase in days:
+
+.nf
+	if (phase < 14)
+	    sky = sky0 + sky1 * phase + sky2 * phase**2
+	else
+	    sky = sky0 + sky1 * (14 - phase) + sky2 * (14 - phase)**2
+.fi
+
+One may set the higher order terms to zero if the moon contribution
+is to be ignored.  The units are magnitudes per square arc second.
+
+The detector entry contains the read out noise in electrons, the
+dark current rate in electrons per second, the pixel size in
+microns, and the detective quantum efficiency (DQE); the fraction of
+detected photons converted to electrons.  Note that the actual
+values used are the DQE times the rates given by the filter entries.
+Thus, one may set the DQE values to 1 and adjust the filter values
+or set the star count rates to 1 in the filter and set the actual
+count rates in the DQE values.
+
+The computed quantities are formally given as follows.  The
+star count rates for the specified telescope/detector/filter are:
+
+.nf
+	r(star) = star * aperture**2 * transmission *
+	    10**(0.4*(1-airmass)*extinction) * dqe
+.fi
+
+where the "star", "aperture", "transmission", "extinction", are those
+in the database and the "dqe" is the appropriate filter value.  The sky
+rate per pixel is:
+
+.nf
+	r(sky) = r(star) * 10 ** (0.4 * (mag - sky)) * pixel**2
+	pixel = pixsize * scale * sum
+.fi
+
+where mag is the fiducial magnitude, sky is the value computed using
+the quadratic formula for the specified moon phase and the database
+coefficients, the "pixel" size is computed using the CCD pixel size and
+the telescope scale from the database, and sum is the
+specified CCD binning factor.
+
+The number of pixels per star is computed from the seeing as:
+
+.nf
+	npix = 1.4 * (seeing / pixel) ** 2
+.fi
+
+where the number is rounded up to the next integer and a minimum of 9
+pixels is enforced.  This number is a compromise between a large aperture
+for high SNR stars and a smaller aperture for fainter stars.
+
+The number of star photons/electrons per star of magnitude m,
+the number of sky photons per pixel, and the number of dark current
+electrons, all in exposure time t, are given by:
+
+.nf
+	nstar = r(star) * 10 ** (0.4 * (mag - m)) * t
+	nsky = r(sky) * t
+	ndark = dark * t
+.fi
+
+where dark is taken from the detector database entry.
+
+Finally the noise contributions, total noise, and signal-to-noise are
+given by:
+
+.nf
+	noise star = nstar ** 1/2
+	noise sky = (npix * nsky) ** 1/2
+	noise ccd = (npix * (ndark + rdnoise**2)) ** 1/2
+	noise total = (nstar+npix*(nsky+ndark+rdnoise**2)) ** 1/2
+	SNR = nstar / noise total
+.fi
+.ih
+EXAMPLES
+1.  To get a list of the telescopes, filters, and detectors in a database:
+
+.nf
+    cl> ccdtime telescope=? detector=? f1=?
+    Entries for telescope in database ccdtime$kpno.dat:
+	    0.9m
+	    ...
+	    4m
+    Entries for detector in database ccdtime$kpno.dat:
+	    T1KA
+	    T2KA
+	    T2KB
+	    TI2
+	    TI3
+	    T5HA
+	    S2KA
+    Entries for filter in database ccdtime$kpno.dat:
+	    U
+	    B
+	    V
+	    R
+	    I
+.fi
+
+2.  The following is for the default magnitude and SNR and with
+a 1 second exposure time specified.  The output has some
+whitespace removed to fit on this page.
+
+.nf
+    cl> ccdtime time=1
+    Telescope: 0.9m
+    Detector: t1ka
+    Database: ccdtime$kpno.dat Telescope: 0.9m    Detector: t1ka
+      Sum: 1 Arcsec/pixel: 0.72  Pixels/star: 6.0
+      Seeing: 1.5  Airmass: 1.20  Phase: 0.0
+
+
+     Filter  Time   Mag   SNR   Star Sky/pix Noise contributions
+					      Star    Sky    CCD
+
+	  U  70.2  20.0  10.0  196.6    8.8  14.02   8.90  10.53
+	  B  13.0  20.0  10.0  208.8   13.0  14.45  10.82  10.51
+	  V  13.2  20.0  10.0  250.7   29.8  15.83  16.37  10.51
+	  R  17.3  20.0  10.0  365.8   95.9  19.13  29.38  10.51
+	  I 126.4  20.0  10.0 1259.2 1609.8  35.49 120.37  10.55
+
+	  U   1.0  15.6  10.0  166.6    0.1  12.91   1.06  10.50
+	  B   1.0  17.4  10.0  170.0    1.0  13.04   3.00  10.50
+	  V   1.0  17.6  10.0  174.6    2.3  13.21   4.50  10.50
+	  R   1.0  17.6  10.0  186.0    5.5  13.64   7.06  10.50
+	  I   1.0  16.7  10.0  207.9   12.7  14.42  10.71  10.50
+
+	  U   1.0  20.0   0.3    2.8    0.1   1.67   1.06  10.50
+	  B   1.0  20.0   1.4   16.0    1.0   4.00   3.00  10.50
+	  V   1.0  20.0   1.6   19.0    2.3   4.36   4.50  10.50
+	  R   1.0  20.0   1.6   21.1    5.5   4.59   7.06  10.50
+	  I   1.0  20.0   0.7   10.0   12.7   3.16  10.71  10.50
+
+.fi
+
+Note that the default of 1 second in the last section
+gives the count rates per second for star and sky.
+
+3.  Sometimes one may want to vary one parameter easily on the command
+line or query.  This can be done by changing the parameter to query
+mode.  In the following example we want to change the magnitude.
+
+.nf
+    cl> ccdtime.magnitude.p_mode=query
+    cl> ccdtime.telescope="0.9m"
+    cl> ccdtime.detector="t1ka"
+    cl> ccdtime.f1=""; ccdtime.f5=""
+    cl> ccdtime
+    Magnitude (20.):
+    Database: ccdtime$kpno.dat   Telescope: 0.9m     Detector: t1ka
+      Sum: 1 Arcsec/pixel: 0.72  Pixels/star: 6.0
+      Seeing: 1.5  Airmass: 1.20  Phase: 0.0
+
+     Filter  Time   Mag   SNR  Star Sky/pix  Noise contributions
+					       Star   Sky    CCD
+
+	  B  13.0  20.0  10.0 208.8    13.0  14.45  10.82  10.51
+	  V  13.2  20.0  10.0 250.7    29.8  15.83  16.37  10.51
+	  R  17.3  20.0  10.0 365.8    95.9  19.13  29.38  10.51
+
+    cl> ccdtime 21
+    ...
+    cl> ccdtime 22
+    ...
+.fi
+.ih
+REVISIONS
+.ls CCDTIME V2.13
+The f1 to f5 parameters were modified to allow lists of filters so
+that more than five filters can be output without changing the parameter
+interface.
+.le
+.ls CCDTIME V2.12
+Task added to OBSUTIL package.
+.le
+.ls CCDTIME V2.11.4
+A error will be reported if the requested time or SNR is not greater
+than zero and less than 100000., or if the absolute value
+of the magnitude is greater than 40.
+.le
+.ls CCDTIME V2.11.2
+The incorrect usage of a 1 mag/airmass extinction was fixed by adding an
+expected "extinction" entry in the filter entries.  Note that old files
+will still give the same result by using an extinction of 1 if the keyword
+is not found.
+
+The database keywords can not be indexed by telescope, filter, and/or
+detector.
+
+The number of pixels per aperture now has a minimum of 9 pixels.
+.le
+.ih
+SEE ALSO
+sptime
+.endhelp
diff --git a/noao/obsutil/src/doc/cgiparse.hlp b/noao/obsutil/src/doc/cgiparse.hlp
new file mode 100644
index 00000000..f054ca4e
--- /dev/null
+++ b/noao/obsutil/src/doc/cgiparse.hlp
@@ -0,0 +1,166 @@
+.help cgiparse Mar03 noao.obsutil
+.ih
+NAME
+cgiparse -- parse STRING_QUERY environment var. into parameters
+.ih
+SYNOPSIS
+CGIPARSE parses the STRING_QUERY environment varabile and sets parameters.
+The string format is a list of task.param=value pairs which includes the
+standard QUERY string special characters '&', '+', and '%'.  This is
+intended to parse a query from a CGI script.
+.ih
+USAGE
+cgiparse
+.ih
+PARAMETERS
+There are no parameters.  The input is the value of the QUERY_STRING
+environment variable.
+.ih
+DESCRIPTION
+CGIPARSE parses the STRING_QUERY environment varabile and sets parameters.
+The string format is a list of task.param=value pairs which includes the
+standard QUERY string special characters '&', '+', and '%'.  This is
+intended to parse a query from a CGI script.
+
+The only input is the STRING_QUERY variable.  If it is undefined the
+task simply does nothing.  The string will normally use the standard
+parameters for this type of string.  The data fields are task.param=value
+strings.  As each is parsed the values will be set for the task.  This
+assumes the tasks are defined.  Theere is no error checking for
+undefined tasks or parameters.
+.ih
+EXAMPLES
+1.  A CGI script calls a CL script with the STRING_QUERY string set.
+The string has "imheader.longheader=yes".  CGIPARSE is called and
+when it completes the parameter value is set.
+
+.nf
+    cl> lpar imhead
+    cl> lpar imheader
+           images =                 image names
+          (imlist = "*.imh,*.fits,*.pl,*.qp,*.hhh") default image ...
+      (longheader = no)             print header in multi-line format
+      (userfields = yes)            print the user fields ...
+            (mode = "ql")           
+    cl> cgiparse
+    cl> lpar imheader
+           images =                 image names
+          (imlist = "*.imh,*.fits,*.pl,*.qp,*.hhh") default image ...
+      (longheader = yes)            print header in multi-line format
+      (userfields = yes)            print the user fields ...
+            (mode = "ql")           
+.fi
+
+Note that when running this in a "#!cl" script where the "login.cl" is
+not used that you must be careful to have all tasks referenced by the
+query string defined.
+
+2.  Below is a "#!cl" type script that uses CGIPARSE.  It is used for
+a spectral exposure time calculator based on OBSUTIL.SPTIME though many
+aspects are fairly generic for this type of application.
+
+.nf
+#!/iraf/iraf/bin.freebsd/cl.e -f
+
+file	urldir
+
+# The following must be set for different hosts.
+# The home directory and the urldir are the same but in different syntax.
+# The home directory must have a world writable tmp subdirectory.
+
+set arch = ".freebsd"
+set (home = osfn ("/www/htdocs/noao/staff/brooke/gsmt/"))
+urldir = "/noao/staff/brooke/gsmt/"
+
+# The uparm is a unique temporary directory.
+s1 = mktemp ("uparm") // "/"
+set (uparm = "home$/tmp/" // s1)
+mkdir uparm$
+cd uparm
+printf ("!/bin/chmod a+rw %s\n", osfn("uparm$")) | cl
+
+# The URL directory is the same as uparm.
+urldir = urldir // "tmp/" // s1
+
+# A private graphcap is required to give an path for sgidispatch.
+set graphcap = home$graphcap
+
+# Load packages.
+dataio
+proto
+noao
+onedspec
+spectime
+gsmt
+
+# Parse the CGI string and set parameters.
+cgiparse
+
+# Create the output.
+
+# Start HTML.
+printf ("Content-Type: text/html\n\n")
+printf ("<html><head><title>Test</title></head>\n")
+printf ("<body>\n")
+if (cl.line == "...")
+    printf ("<center><h2>SPECTIME</h2></center>\n", cl.line)
+else
+    printf ("<center><h2>%s</h2></center>\n", cl.line)
+printf ("<pre>\n")
+
+# Execute task(s).
+#show QUERY_STRING
+
+setup interactive=no mode=h
+printf ("</pre>\n")
+printf ("<A Href='http://www.noao.edu/noao/staff/brooke/gsmt/gsmt.php?stage=1'>Back to form</A>")
+printf ("<pre>\n")
+
+sptime output="counts,snr" graphics="g-gif" interactive=no mode=h
+
+printf ("</pre>\n")
+printf ("<A Href='http://www.noao.edu/noao/staff/brooke/gsmt/gsmt.php?stage=1'>Back to form</A>\n")
+
+printf ("<pre>\n")
+
+# Add any gifs created.  We have to wait for them to be created.
+
+gflush
+
+i = 0; j = 1
+while (i != j) {
+    sleep 2
+    j = i
+    files *.gif | count STDIN | scan (i)
+}
+
+
+if (i > 0) {
+    printf ("<br><p><em>Note: DN and S/N are per-pixel</em><br>\n")
+	
+    files *.gif > gifs
+    list = "gifs"
+    while (fscan (list, s1) != EOF) {
+	if (access (s1))
+		printf ("<img src=\"%s%s\">\n", urldir, s1)
+    }
+    list = ""
+    ## delete ("uparm$gifs", verify-)
+}
+
+printf ("</pre>\n")
+
+# Finish HTML.
+
+printf ("<A Href='http://www.noao.edu/noao/staff/brooke/gsmt/gsmt.php?stage=1'>Back to form</A>")
+
+printf ("</body></html>\n")
+
+# Clean up.
+## delete ("*[^g][^i][^f]", verify-)
+
+logout
+.fi
+.ih
+SEE ALSO
+.endhelp
diff --git a/noao/obsutil/src/doc/findgain.hlp b/noao/obsutil/src/doc/findgain.hlp
new file mode 100644
index 00000000..91bf7eaf
--- /dev/null
+++ b/noao/obsutil/src/doc/findgain.hlp
@@ -0,0 +1,168 @@
+.help findgain Nov01 noao.obsutil
+.ih
+NAME
+findgain -- calculate the gain and readout noise of a CCD
+.ih
+SYNOPSIS
+FINDGAIN uses Janesick's method for determining the gain and read noise
+in a CCD from a pair of dome flat exposures and a pair of zero frame
+exposures (zero length dark exposures).
+.ih
+USAGE
+findgain flat1 flat2 zero1 zero2
+.ih
+PARAMETERS
+.ls flat1, flat2
+First and second dome flats.
+.le
+.ls zero1, zero2
+First and second zero frames (zero length dark exposures).
+.le
+.ls section = ""
+The selected image section for the statistics.  This should be chosen
+to exclude bad columns or rows, cosmic rays and other blemishes, and
+the overscan region.  The flat field iillumination should be constant
+over this section.
+.le
+.ls center = "mean"
+The statistical measure of central tendency that is used to estimate
+the data level of each image.  This can have the values:  \fBmean\fR,
+\fBmidpt\fR, or \fBmode\fR.  These are calculated using the same
+algorithm as the IMSTATISTICS task.
+.le
+.ls nclip = 3
+Number of sigma clipping iterations.  If the value is zero then no clipping
+is performed.
+.le
+.ls lsigma = 4, usigma = 4
+Lower and upper sigma clipping factors used with the mean value and
+standard deviation to eliminate cosmic rays.
+Since \fBfindgain\fR is sensitive to the statistics of the data the
+clipping factors should be symmetric (the same both above and below the
+mean) and should not bias the standard deviation.  Thus the values should
+not be made smaller than around 4 sigma otherwise the gain and readnoise
+estimates will be affected.
+.le
+.ls binwidth = 0.1
+The bin width of the histogram (in sigma) that is used to estimate the
+\fBmidpt\fR or \fBmode\fR of the data section in each image.
+The default case of center=\fBmean\fR does not use this parameter.
+.le
+.ls verbose = yes
+Verbose output?
+.le
+.ih
+DESCRIPTION
+FINDGAIN uses Janesick's method for determining the gain and read noise
+in a CCD from a pair of dome flat exposures and a pair of zero frame
+exposures (zero length dark exposures).
+The task requires that the flats and zeros be unprocessed and uncoadded so
+that the noise characteristics of the data are preserved.  Note, however,
+that the frames may be bias subtracted if the average of many zero frames
+is used, and that the overscan region may be removed prior to using this
+task.
+
+Bad pixels should be eliminated to avoid affecting the statistics.
+This can be done with sigma clipping and/or an image section.
+The sigma clipping should not significantly affect the assumed gaussian
+distribution while eliminating outlyers due to cosmic rays and
+unmasked bad pixels.  This means that clipping factors should be
+symmetric and should have values four or more sigma from the mean.
+.ih
+ALGORITHM
+The formulae used by the task are:
+
+.nf
+    flatdif = flat1 - flat2
+
+    zerodif = zero1 - zero2
+
+       gain = ((mean(flat1) + mean(flat2)) - (mean(zero1) + mean(zero2))) /
+	      ((sigma(flatdif))**2 - (sigma(zerodif))**2 )
+
+   readnoise = gain * sigma(zerodif) / sqrt(2)
+.fi
+
+where the gain is given in electrons per ADU and the readnoise in
+electrons.  Pairs of each type of comparison frame are used to reduce
+the effects of gain variations from pixel to pixel.  The derivation
+follows from the definition of the gain (N(e) = gain * N(ADU)) and from
+simple error propagation.  Also note that the measured variance
+(sigma**2) is related to the exposure level and read-noise variance
+(sigma(readout)**2) as follows:
+
+.nf
+     variance(e) = N(e) + variance(readout)
+.fi
+
+Where N(e) is the number of electrons (above the zero level) in a
+given duration exposure.
+
+In our implementation, the \fBmean\fR used in the formula for the gain
+may actually be any of the \fBmean\fR, \fBmidpt\fR (an estimate of the
+median), or \fBmode\fR as determined by the \fBcenter\fR parameter.
+For the \fBmidpt\fR or \fBmode\fR choices only, the value of the
+\fBbinwidth\fR parameter determines the bin width (in sigma) of the
+histogram that is used in the calculation.  \fBFindgain\fR uses the
+\fBimstatistics\fR task to compute the statistics.
+.ih
+EXAMPLES
+To calculate the gain and readnoise within a 100x100 section:
+
+.nf
+    ms> findgain flat1 flat2 zero1 zero2 section="[271:370,361:460]"
+.fi
+
+To calculate the gain and readnoise using the mode to estimate the data
+level for each image section:
+
+.nf
+    ms> findgain.section="[271:370,361:460]"
+    ms> findgain flat1 flat2 zero1 zero2 center=mode
+.fi
+
+The effects of cosmic rays can be seen in the following example using
+artificial noise created with the \fBartdata.mknoise\fR package.  The
+images have a gain of 5 and a readnoise of 10 with 100 cosmic rays added
+over the 512x512 images.  The zero level images have means of zero and the
+flat field images have means of 1000.  The first execution uses the default
+clipping and the second turns off the clipping.
+
+.nf
+    cl> findgain flat1 flat2 zero1 zero2
+    FINDGAIN:
+      center = mean, binwidth = 0.1
+      nclip = 3, lclip = 4., uclip = 4.
+
+      Flats      = flat1 &  flat2
+      Zeros      = zero1 &  zero2
+      Gain       =  5.01 electrons per ADU
+      Read noise = 10.00 electrons
+    cl> findgain flat1 flat2 zero1 zero2 nclip=0
+    FINDGAIN:
+      center = mean, binwidth = 0.1
+      nclip = 0, lclip = 4., uclip = 4.
+
+      Flats      = flat1  &  flat2
+      Zeros      = zero1  &  zero2
+      Gain       =  2.86 electrons per ADU
+      Read noise = 189.5 electrons
+.fi
+
+.ih
+BUGS
+The image headers are not checked to see if the frames have been
+processed.
+
+There is no provision for finding the "best" values and their errors
+from several flats and zeros.
+.ih
+REVISIONS
+.ls FINDGAIN - V2.12
+New task derived from MSCFINDGAIN.  This makes use of the new clipping
+feature in IMSTATISTICS.
+.le
+.ih
+SEE ALSO
+imstatistics
+.endhelp
diff --git a/noao/obsutil/src/doc/kpnofocus.hlp b/noao/obsutil/src/doc/kpnofocus.hlp
new file mode 100644
index 00000000..176a8fe7
--- /dev/null
+++ b/noao/obsutil/src/doc/kpnofocus.hlp
@@ -0,0 +1,214 @@
+.help kpnofocus Mar96 noao.obsutil
+.ih
+NAME
+kpnofocus -- Determine the best focus from KPNO focus images
+.ih
+USAGE
+kpnofocus images
+.ih
+PARAMETERS
+.ls images
+List of focus images.
+.le
+.ls frame = 1
+The image display is checked to see if the image is already in one of
+the display frames.  If it is not the \fBdisplay\fR task is called to
+display the image in the frame specified by the \fBframe\fR parameter.  All
+other display parameters are taken from the current settings of the task.
+This option requires that the image display be active.
+.le
+
+.ls level = 0.5
+The parameter used to quantify an object image size is the radius from the
+image center enclosing the fraction of the total flux given by this
+parameter.  If the value is greater than 1 it is treated as a percentage.
+.le
+.ls size = "FWHM" (Radius|FWHM|GFWHM|MFWHM)
+There are four ways the PSF size may be shown in graphs and given in
+the output.  These are:
+
+.nf
+    Radius - the radius enclosing the specified fraction of the flux
+    FWHM   - a direct FWHM from the measured radial profile
+    GFWHM  - the FWHM of the best fit Gaussian profile
+    MFWHM  - the FWHM of the best fit Moffat profile
+.fi
+
+The labels in the graphs and output will be the value of this parameter
+to distinguish the different types of size measurements.
+.le
+.ls beta = INDEF
+For the Moffat profile fit (size = MFWHM) the exponent parameter may
+be fixed at a specified value or left free to be determined from the
+fit.  The exponent parameter is determined by the fit if \fIbeta\fR
+task parameter is INDEF.
+.le
+.ls scale = 1.
+Pixel scale in user units per pixel.  Usually the value is 1 to measure
+sizes in pixels or the image pixel scale in arc seconds per pixel.
+.le
+.ls radius = 5., iterations = 2
+Measurement radius in pixels and number of iterations on the radius.  The
+enclosed flux profile is measured out to this radius.  This radius may be
+adjusted if the \fIiteration\fR parameter is greater than 1.  In that case
+after each iteration a new radius is computed from the previous FWHM
+estimate to be the radius the equivalent gaussian enclosing 99.5% of the
+light.  The purpose of this is so that if the initial PSF size of the image
+need not be known.  However, the radius should then be larger than true
+image size since the iterations best converge to smaller values.
+.le
+.ls sbuffer = 5., swidth = 5.
+Sky buffer and sky width in pixels.  The buffer is added to the specified
+measurement \fIradius\fR to define the inner radius for a circular sky
+aperture.  The sky width is the width of the circular sky aperture.
+.le
+.ls saturation=INDEF, ignore_sat=no
+Data values (prior to sky subtraction) to be considered saturated within
+measurement radius.  A value of INDEF treats all pixels as unsaturated.  If
+a measurement has saturated pixels there are two actions.  If
+\fIignore_sat\fR=no then a warning is given but the measurement is saved
+for use.  The object will also be indicated as saturated in the output
+log.  If \fIignore_sat\fR=yes then a warning is given and the object is
+discarded as if it was not measured.  In a focus sequence only the
+saturated objects are discarded and not the whole sequence.
+.le
+.ls logfile = "logfile"
+File in which to record the final results.  If no log file is desired a
+null string may be specified.
+.le
+.ih
+CURSOR COMMANDS
+When selecting objects with the image cursor the following commands are
+available.
+
+.nf
+?  Page cursor command summary
+g  Measure object and graph the results.
+m  Measure object.
+q  Quit object marking and go to next image.
+   At the end of all images go to analysis of all measurements.
+
+:show  Show current results.
+.fi
+
+When in the interactive graphics the following cursor commands are available.
+All plots may not be available depending on the number of focus values and
+the number of stars.
+
+.nf
+?  Page cursor command summary
+a  Spatial plot at a single focus
+b  Spatial plot of best focus values
+d  Delete star nearest to cursor
+e  Enclosed flux for stars at one focus and one star at all focus
+f  Size and ellipticity vs focus for all data
+i  Information about point nearest the cursor
+m  Size and ellipticity vs relative magnitude at one focus
+n  Normalize enclosed flux at x cursor position
+o  Offset enclosed flux to by adjusting background
+p  Radial profiles for stars at one focus and one star at all focus
+q  Quit
+r  Redraw
+s  Toggle magnitude symbols in spatial plots
+t  Size and ellipticity vs radius from field center at one focus
+u  Undelete all deleted points
+x  Delete nearest point, star, or focus (selected by query)
+z  Zoom to a single measurement
+<space> Step through different focus or stars in current plot type
+
+
+:beta <val>     Beta parameter for Moffat fits
+:level <val>	Level at which the size parameter is evaluated
+:overplot <y|n> Overplot the profiles from the narrowest profile?
+:radius <val>   Change profile radius
+:show <file>	Page all information for the current set of objects
+:size <type>	Size type (Radius|FWHM)
+:scale <val>	Pixel scale for size values
+:xcenter <val>	X field center for radius from field center plots
+:ycenter <val>	Y field center for radius from field center plots
+
+The profile radius may not exceed the initial value set by the task
+parameter.
+.fi
+.ih
+DESCRIPTION
+This task is a script based on the task \fBstarfocus\fR.  The details
+of the algorithms and display modes are given in the help for that
+task.  The purpose of \fBkpnofocus\fR is to provide a simpler task
+with fewer parameters because the format of the multiple exposure
+images is given by header keywords.
+
+As a summary of the algorithm, the center of each star image is
+found using centroids, a background is determined from the mode
+of a sky annulus, and the enclosed flux profile is measured.  The
+PSF width is then the radius enclose a specified fraction of the
+flux.  Alternatively a direct FWHM from the radial intensity profile,
+a FWHM for a Moffat profile fit to the enclosed flux profile, or
+a FWHM for a Gaussian profile fit to the enclosed flux profile may be
+used.
+
+If a saturation value is specified then all pixels within the specified
+measurement radius are checked for saturation.  If any saturated pixels are
+found a warning is given and \fIignore_sat\fR parameter may be used ot
+ignore the measurement.  If not ignored the object will still be indicated
+as saturated in the output log.  In a focus sequence only the saturated
+objects are discarded and not the whole sequence.
+
+To use this task consists of specifying a focus image name.  Multiple
+images could be analyzed together but this is uncommon.  The task
+will then display the image, using the current parameters of the
+\fBdisplay\fR task, if the image is not already in the display.
+The user then marks the first exposure (the top one) by pointing
+the image cursor and typing 'm'.  This may be done for more than
+one star if desired.  After all stars to be used are marked type
+'q' to go to the graphical analysis.
+
+A plot showing the variation of the PSF width and ellipticity with
+focus is shown along with a magnitude weighted, parabolic
+interpolated estimate for the best focus.  One may delete bad points
+with the cursor 'd' key.  To exit and record the results to
+a logfile use the 'q' key.  There are many graphical display
+options for more sophisticated analysis such as variations with
+position.  The best thing to do is to try the various keystroke
+commands given in the CURSOR section.  For details about
+the various plots see the \fBstarfocus\fR help.
+
+The other task parameters allow setting the enclosed flux level,
+the object and sky apertures, and the type and scale of the
+reported PSF size.  The log filename may also be specified.
+.ih
+EXAMPLES
+1.  A multiple exposure frame is taken with 7 exposures of a bright
+star, each exposure shifted by 30 pixels using the version of the
+ICE software which records the focus information in the keywords
+FOCSTART, FOCSTEP, FOCNEXPO, and FOCSHIFT.
+
+.nf
+cl> kpnofocus focus1
+<The image is displayed and the image cursor activated>
+<The bright star is marked with 'm'>
+<Marking is finished with 'q'>
+<A graph of FWHM vs focus is shown>
+<Exit with 'q'>
+NOAO/IRAF IRAFV2.10.3 valdes@puppis Fri 15:48:01 12-Nov-93
+
+   Image  Column    Line     Mag   Focus    FWHM   Ellip      PA SAT
+ 36inch1  536.63  804.03    0.07   4660.  13.878    0.06     -11
+	  535.94  753.28   -0.12   4680.   8.569    0.09      89
+	  535.38  703.96   -0.08   4700.   5.164    0.11     -88
+	  537.12  655.36   -0.02   4720.   3.050    0.08     -77
+	  534.20  604.59    0.00   4740.   4.336    0.11      74
+	  534.41  554.99   -0.00   4760.   9.769    0.09     -35
+	  534.83  456.08    0.16   4780.  12.569    0.13     -10
+
+  Best focus of 4722.44 with FWHM (at 50% level) of 3.02
+.fi
+
+The estimated best focus is between the 4th and 5th focus setting
+at a value of 4722.4 and the best focus FWHM is 3.02 pixels.
+.ih
+SEE ALSO
+.nf
+imexamine, implot, pprofile, pradprof, psfmeasure, radlist,
+radplt, radprof, ranges, specfocus, splot, starfocus
+.endhelp
diff --git a/noao/obsutil/src/doc/pairmass.hlp b/noao/obsutil/src/doc/pairmass.hlp
new file mode 100644
index 00000000..d271b42b
--- /dev/null
+++ b/noao/obsutil/src/doc/pairmass.hlp
@@ -0,0 +1,132 @@
+.help pairmass Nov01 noao.obsutil
+.ih
+NAME
+pairmass -- plot the airmass for a given object
+.ih
+USAGE
+pairmass
+.ih
+PARAMETERS
+.ls ra
+The right ascension of the object in hours.
+.le
+.ls dec
+The declination of the object in degrees.
+.le
+.ls epoch=INDEF
+The epoch of the coordinates in years.
+.le
+.ls year
+The year of the observation.
+.le
+.ls month
+The month of the observation (a number from 1 to 12).
+.le
+.ls day
+The day of the month of the observation.
+.le
+.ls observatory = "observatory"
+The observatory identifier in the observatory database.  See the
+help for \fBobservatory\fR task for more information.
+.le
+.ls timesys = "Standard" (Universal|Standard|Siderial)
+Time system for the plot or output list.  The choices are
+"Universal" for universal time, "Standard" for standard time (where
+the time zone is determined from the observatory database), and "Siderial"
+for the siderial time.
+.le
+
+.ls resolution=4
+The number of UT points per hour for which to calculate the airmass.
+.le
+.ls listout=no
+List, rather than plot, the airmass versus time?  Only airmasses
+below that given by the \fIwy2\fR parameters are listed.
+.le
+.ih
+PLOT PARAMETERS
+.ls wx1=-7., wx2=7., wy1=0., wy2=5.
+The range of window (user) coordinates to be included in the plot.
+If the range of values in x or y = 0, the plot is automatically
+scaled from the minimum to maximum data values along that axis.
+The times are available from -24 hours to 48 hours so one can use
+negative numbers to plot hours from midnight or in actual hours.
+.le
+.ls pointmode = no
+Plot individual points instead of a continuous line?
+.le
+.ls marker="box"
+If \fBpointmode\fR = yes, the marker drawn at each point is set with this
+parameter.  The acceptable choices are "point", "box", "plus", "cross",
+"circle", "hebar", "vebar", "hline", "vline", and "diamond".
+.le
+.ls szmarker = 0.005
+The size of the marker drawn when \fBpointmode\fR = yes.  A value of 0
+(zero) indicates that the task should read the size from the input list.
+.le
+.ls logx = no, logy = no
+Draw the x or y axis in log units, versus linear?
+.le
+.ls xlabel="default"
+Label for the X-axis.  The value "default" uses the specified time system.
+.le
+.ls ylabel="Airmass"
+Labels for the Y-axis.
+.le
+.ls title="default"
+Title for plot.  If not changed from "default", a title string consisting
+of the date, observatory, and  object position is used.
+.le
+.ls vx1=0., vx2=0., vy1=0., vy2=0.
+NDC coordinates (0-1) of the plotting device viewport.  If not set
+by the user, a suitable viewport which allows sufficient room for all
+labels is used.
+.le
+.ls majrx=5, minrx=5, majry=5, minry=5
+The number of major and minor divisions along the x or y axis.
+.le
+.ls round = no
+Round axes up to nice values?
+.le
+.ls fill = yes
+Fill the plotting viewport regardless of the device aspect ratio?
+.le
+.bp
+.ls append = no
+Append to an existing plot?
+.le
+.ls device="stdgraph"
+Output device.
+.le
+.ih
+DESCRIPTION
+The airmass is plotted over a specified set of hours for a given
+observatory.  The observatory is specified by an identifier as given
+in the observatory database.  See the help for "observatory" for more
+information about the database and identifiers.
+
+The results can be shown in universal, standard, or siderial time.
+The standard time simply adds the time zone from the observatory
+database tothe universal time and so there is no explicit facility
+for daylight savings time.  The times are computed in the range
+-24 hours to +48 hours.  By setting the \fIwx1\fR and \fIwx2\fR
+parameters one can plot either in hours relative to 0 in the specified
+time system or as positive hours.  This simple task does not support
+axis labeling which wraps around.
+
+The list output prints date, observatory, object coordinates, and
+the time system.  This is followed by the time sorted between 0 and 24
+and the airmasses.  The list only includes airmasses below the
+value specified by \fIwy2\fR.
+.ih
+EXAMPLES
+To plot the airmass for M82 from Kitt Peak for Groundhog's Day in 1992:
+
+.nf
+    pairmass ra=9:51:42 dec=69:56 epoch=1950 year=1992 month=2 day=2
+.fi
+
+.ih
+SEE ALSO
+observatory, airmass, setairmass, graph
+.endhelp
diff --git a/noao/obsutil/src/doc/psfmeasure.hlp b/noao/obsutil/src/doc/psfmeasure.hlp
new file mode 100644
index 00000000..479268b1
--- /dev/null
+++ b/noao/obsutil/src/doc/psfmeasure.hlp
@@ -0,0 +1,633 @@
+.help psfmeasure Nov01 noao.obsutil
+.ih
+NAME
+psfmeasure -- Measure PSF widths in stellar images
+.ih
+USAGE
+psfmeasure images
+.ih
+PARAMETERS
+.ls images
+List of images.
+.le
+.ls coords = "mark1" (center|mark1|markall)
+Method by which the coordinates of objects to be measured are specified.
+If "center" then a single object at the center of each image is measured.
+If "mark1" then the \fIimagecur\fR parameter, typically the interactive
+image display cursor, defines the coordinates of one or more objects in the
+first image ending with a 'q' key value and then the same coordinates are
+automatically used in subsequent images.  If "markall" then the
+\fIimagecur\fR parameter defines the coordinates for objects in each image
+ending with a 'q' key value.
+.le
+.ls wcs = "logical" (logical|physical|world)
+Coordinate system for input coordinates.  When using image cursor input
+this will always be "logical".  When using cursor input from a file this
+could be "physical" or "world".
+.le
+.ls display = yes, frame = 1
+Display the image or images as needed?  If yes the image display is checked
+to see if the image is already in one of the display frames.  If it is not
+the \fBdisplay\fR task is called to display the image in the frame
+specified by the \fBframe\fR parameter.  All other display parameters are
+taken from the current settings of the task.  This option requires that the
+image display be active.  A value of no is typically used when an input
+cursor file is used instead of the image display cursor.  An image display
+need not be active in that case.
+.le
+
+.ls level = 0.5
+The parameter used to quantify an object image size is the radius from the
+image center enclosing the fraction of the total flux given by this
+parameter.  If the value is greater than 1 it is treated as a percentage.
+.le
+.ls size = "FWHM" (Radius|FWHM|GFWHM|MFWHM)
+There are four ways the PSF size may be shown in graphs and given in
+the output.  These are:
+
+.nf
+    Radius - the radius enclosing the specified fraction of the flux
+    FWHM   - a direct FWHM from the measured radial profile
+    GFWHM  - the FWHM of the best fit Gaussian profile
+    MFWHM  - the FWHM of the best fit Moffat profile
+.fi
+
+The labels in the graphs and output will be the value of this parameter
+to distinguish the different types of size measurements.
+.le
+.ls beta = INDEF
+For the Moffat profile fit (size = MFWHM) the exponent parameter may
+be fixed at a specified value or left free to be determined from the
+fit.  The exponent parameter is determined by the fit if \fIbeta\fR
+task parameter is INDEF.
+.le
+.ls scale = 1.
+Pixel scale in user units per pixel.  Usually the value is 1 to measure
+sizes in pixels or the image pixel scale in arc seconds per pixel.
+.le
+.ls radius = 5., iterations = 3
+Measurement radius in pixels and number of iterations on the radius.  The
+enclosed flux profile is measured out to this radius.  This radius may be
+adjusted if the \fIiteration\fR parameter is greater than 1.  In that case
+after each iteration a new radius is computed from the previous direct FWHM
+estimate.  The new radius is three times direct FWHM (six times the
+half-maximum radius).  The purpose of this is so that if the initial PSF
+size of the image need not be known.  However, the radius should then be
+larger than true image size since the iterations best converge to smaller
+values.
+.le
+.ls sbuffer = 5, swidth = 5.
+Sky buffer and sky width in pixels.  The buffer is added to the specified
+measurement \fIradius\fR to define the inner radius for a circular sky
+aperture.  The sky width is the width of the circular sky aperture.
+.le
+.ls saturation=INDEF, ignore_sat=no
+Data values (prior to sky subtraction) to be considered saturated within
+measurement radius.  A value of INDEF treats all pixels as unsaturated.  If
+a measurement has saturated pixels there are two actions.  If
+\fIignore_sat\fR=no then a warning is given but the measurement is saved
+for use.  The object will also be indicated as saturated in the output
+log.  If \fIignore_sat\fR=yes then a warning is given and the object is
+discarded as if it was not measured.
+.le
+.ls xcenter = INDEF, ycenter = INDEF
+The optical field center of the image given in image pixel coordinates.
+These values need not lie in the image.  If INDEF the center of the image
+is used.  These values are used to make plots of size verse distance from
+the field center for studies of radial variations.
+.le
+.ls logfile = "logfile"
+File in which to record the final results.  If no log file is desired a
+null string may be specified.
+.le
+
+.ls imagecur = ""
+Image cursor input for the "mark1" and "markall" options.  If null then the
+image dispaly cursor is used interactively.  If a file name is specified
+then the coordinates come from this file.  The format of the file are lines
+of x, y, id, and key.  Values of x an y alone may be used to select objects
+and the single character 'q' (or the end of the file) may be used to end
+the list.
+.le
+.ls graphcur = ""
+Graphics cursor input.  If null then the standard graphics cursor
+is used otherwise a standard cursor format file may be specified.
+.le
+.ih
+CURSOR COMMANDS
+When selecting objects with the image cursor the following commands are
+available.
+
+.nf
+?  Page cursor command summary
+g  Measure object and graph the results.
+m  Measure object.
+q  Quit object marking and go to next image.
+   At the end of all images go to analysis of all measurements.
+
+:show  Show current results.
+.fi
+
+When in the interactive graphics the following cursor commands are available.
+All plots may not be available depending on the number of stars.
+
+.nf
+?  Page cursor command summary
+a  Spatial plot
+d  Delete star nearest to cursor
+e  Enclosed flux for all stars
+i  Information about star nearest the cursor
+m  Size and ellipticity vs relative magnitude
+n  Normalize enclosed flux at x cursor position
+o  Offset enclosed flux by adjusting background
+p  Radial profiles for all stars
+q  Quit
+r  Redraw
+s  Toggle magnitude symbols in spatial plot
+t  Size and ellipticity vs radius from field center
+u  Undelete all deleted points
+x  Delete nearest point or star (selected by query)
+z  Zoom to a single measurement
+<space> Step through different stars in some plots
+
+:beta <val>     Set the beta parameter for the Moffat profile fit
+:level <val>	Level at which the size parameter is evaluated
+:overplot <y|n> Overplot the profiles from the narrowest profile?
+:radius <val>   Change profile radius
+:show <file>	Page all information for the current set of objects
+:size <type>	Size type (Radius|FWHM)
+:scale <val>	Pixel scale for size values
+:xcenter <val>	X field center for radius from field center plots
+:ycenter <val>	Y field center for radius from field center plots
+.fi
+.ih
+DESCRIPTION
+This task measures the point-spread function (PSF) width of stars or other
+unresolved objects in digital images.  The width is measured from the
+enclosed flux verses radius profile.  The details of this are described in
+the ALGORITHMS section.  Measurements of multiple stars in multiple images
+may be made.  When there are multiple stars, variations in the PSF with
+position may be examined.  The task has three stages; selecting objects and
+measuring the PSF width and other parameters, an interactive graphical
+analysis, and a final output of the results to the terminal and to a
+logfile.
+
+If a saturation value is specified then all pixels within the specified
+measurement radius are checked for saturation.  If any saturated pixels are
+found a warning is given and \fIignore_sat\fR parameter may be used ot
+ignore the measurement.  If not ignored the object will still be indicated
+as saturated in the output log.  In a focus sequence only the saturated
+objects are discarded and not the whole sequence.
+
+The input images are specified by an image template list.  The list may
+consist of explicit image names, wildcard templates, and @ files.
+Identifying the object or objects to be measured may be accomplished in
+several ways.  If a single object near the center of the image is to be
+measured then the \fIcoords\fR parameter takes the value "center".  When
+the "center" option is used the \fIdisplay\fR and \fIimagecur\fR parameters
+are ignored.
+
+If there are multiple objects or the desired object is not at the center of
+the frame the object coordinates are entered with the \fIimagecur\fR
+parameter.  This type of coordinate input is selected by specifying either
+"mark1" or "markall" for the \fIcoords\fR parameter.  If the value is
+"mark1" then the coordinates are entered for the first image and the same
+values are automatically used for subsequent images.  If "markall" is
+specified then the objects in each image are marked.
+
+Normally the \fIimagecur\fR parameter would select the interactive image
+display cursor though a standard cursor file could be used to make this
+part noninteractive.  When the image display cursor is used either the
+image must be displayed previously by the user, or the task may be allowed
+to load the image display using the \fBdisplay\fR task by setting the
+parameter \fIdisplay\fR to yes and \fIframe\fR to a display frame.  If yes
+the image display must be active.  The task will look at the image names as
+stored in the image display and only load the display if needed.
+
+If one wants to enter a coordinate list rather than use the interactive
+image cursor the list can consist of just the column and line coordinates
+since the key will default to 'm'.  To finish the list either the end
+of file may be encountered or a single 'q' may be given since the
+coordinates are irrelevant.  For the "markall" option with multiple
+images there would need to be a 'q' at the end of each object except
+possibly the last.
+
+When objects are marked interactively with the image cursor there
+are a four keys which may be used as shown in the CURSOR COMMAND section.
+The important distinction is between 'm' to mark and measure an
+object and 'g' to mark, measure, and graph the results.  The former
+accumulates the results until the end while the latter can give an
+immediate result to be examined.  Unless only one object is marked
+the 'g' key also accumulates the results for later graphical analysis.
+It is important to note that the measurements are done as each
+object is marked so there can be a significant delay before the
+next object may be marked.
+
+The quantities measured and the algorithms used are described in the
+ALGORITHMS section.  Once all the objects have been measured an
+interactive (unless only one object is measured) graphical presentation
+of the measurements is entered.
+
+When the task exits it prints the results to the terminal (STDOUT) and also
+to the \fIlogfile\fR if one is specified.  The results may also be
+previewed during the execution of the task with the ":show" command.  The
+results begin with a banner and the overall estimate of the PSF size.
+Following this the individual measurements are given.  The columns give the
+image name, the column and line position, the relative magnitude, the PSF
+size as either the enclosed flux radius or the various FWHM, the
+ellipticity, and the position angle.
+.ih
+ALGORITHMS
+The PSF of an object is characterized using a radially symmetric
+enclosed flux profile.  First the center of the object is determined from
+an initial rough coordinate.  The center is computed from marginal profiles
+which are sums of lines or columns centered at the initial coordinate and
+with a width given by the sum of the \fIradius\fR, \fIsbuffer\fR, and
+\fIswidth\fR parameters.  The mean of the marginal profile is determined
+and then the centroid of the profile above this is computed.  The centroids
+from the two marginal profiles define a new object center.  These steps of
+forming the marginal profiles centered at the estimated object position and
+then computing the centroids are repeated until the centroids converge or
+three iterations have been completed.
+
+Next a background is determined from the mode of the pixel values in the
+sky annulus defined by the object center and \fIradius\fR, \fIsbuffer\fR,
+and \fIswidth\fR parameters.  The pixel values in the annulus are sorted
+and the mode is estimated as the point of minimum slope in this sorted
+array using a width of 5% of the number of points.  If there are multiple
+regions with the same minimum slope the lowest pixel value is used.
+
+The background subtracted enclosed flux profile is determined next.
+To obtain subpixel precision and to give accurate estimates for small
+widths relative to the pixel sampling, several things are done.
+First interpolation between pixels is done using a cubic spline surface.
+The radii measured are in subpixel steps.  To accommodate small and
+large PSF widths (and \fIradius\fR parameters) the steps are nonuniform
+with very fine steps at small radii (steps of 0.05 pixels in the
+central pixel) and coarser steps at larger radii (beyond 9 pixels
+the steps are one pixel) out to the specified \fIradius\fR.  Similarly each
+pixel is subsampled finely near the center and more coarsely at larger
+distances from the object center.  Each subpixel value, as obtained by
+interpolation, is background subtracted and added into the enclosed flux
+profile.  Even with subpixel sampling there is still a point where a
+subpixel straddles a particular radius.  At those points the fraction of
+the subpixel dimension in radius falling within the radius being measured
+is used as the fraction of the pixel value accumulated.
+
+Because of errors in the background determination due to noise and
+contaminating objects it is sometimes the case that the enclosed flux
+is not completely monotonic with radius.  The enclosed flux
+normalization, and the magnitude used in plots and reported in
+results, is the maximum of the enclosed flux profile even if it
+occurs at a radius less than the maximum radius.  It is possible
+to change the normalization and subtract or add a background correction
+interactively.
+
+Because a very narrow PSF will produce significant errors in the cubic
+spline interpolation due to the steepness and rapid variation in the pixel
+values near the peak, the Gaussian profile with FWHM that encloses the same
+80% of the flux is computed as:
+
+    FWHM(80%) = 2 * r(80%) * sqrt (ln(2) / (ln (1/.2)))
+
+If this is less than five pixels the Gaussian model is subtracted from the
+data.  The Gaussian normalization is chosed to perfectly subtract the
+central pixel.  The resulting subtraction will not be perfect but the
+residual data will have much lower amplitudes and variations.  A spline
+interpolation is fit to this residual data and the enclosed flux profile is
+recomputed in exactly the same manner as previously except the subpixel
+intensity is evaluated as the sum of the analytic Gaussian and the
+interpolation to the residual data.
+
+The Gaussian normalization is chosed to perfectly subtract the central
+pixel.  The resulting subtraction will not be perfect but the residual data
+will have much lower amplitudes and variations.  A spline interpolation is
+fit to this residual data and the enclosed flux profile is recomputed in
+exactly the same manner as previously except the subpixel intensity is
+evaluated as the sum of the analytic Gaussian and the interpolation to the
+residual data.  This technique yields accurate FWHM for simulated Gaussian
+PSFs down to at least a FWHM of 1 pixel.
+
+In addition to the enclosed flux profile, an estimate of the radially
+symmetric intensity profile is computed from the enclosed flux profile.
+This is based on the equation
+
+.nf
+    F(R) = integral from 0 to R { P(r) r dr }
+.fi
+
+where F(R) is the enclosed flux at radius R and P(r) is the intensity per
+unit area profile.  Thus the derivative of F(R) divided by R gives an
+estimate of P(R).
+
+Cubic spline interpolation functions are fit to the normalized enclosed
+flux profile and the intensity profile.  These are used to find the radius
+enclosing any specified fraction of the flux and to find the direct FWHM of
+the intensity profile.  These are output when \fIsize\fR is "Radius" or
+"FWHM" respectively.
+
+In addition to enclosed flux radius and direct FWHM size measurements
+there are also two size measurements based on fitting analytic profiles.
+A Gaussian profile and a Moffat profile are fit to the final enclosed flux
+profile to the points with enclosed flux less than 80%.  The limit is
+included to minimize the effects of poor background values and to make the
+profile fit be representative of the core of the PSF profile.  These profiles
+are fit whether or not the selected \fIsize\fR requires it.  This is done
+for simplicity and to allow quickly changing the size estimate with the
+":size" command.
+
+The intensity profile functions (with unit peak) are:
+
+.nf
+    I(r) = exp (-0.5 * (r/sigma)**2)			Gaussian
+    I(r) = (1 + (r/alpha)**2)) ** (-beta)		Moffat
+.fi
+
+with parameters sigma, alpha, and beta.  The normalized enclosed flux
+profiles, which is what is actually fit, are then:
+
+.nf
+    F(r) = 1 - exp (-0.5 * (r/sigma)**2)		Gaussian
+    F(r) = 1 - (1 + (r/alpha)**2)) ** (1-beta)		Moffat
+.fi
+
+The fits determine the parameters sigma or alpha and beta (if a
+beta value is not specified by the users).  The reported FWHM values
+are given by:
+
+.nf
+    GFWHM = 2 * sigma * sqrt (2 * ln (2))		Gaussian
+    MFWHM = 2 * alpha * sqrt (2 ** (1/beta) - 1)	Moffat
+.fi
+
+were the units are adjusted by the pixel scale factor.
+
+In addition to the four size measurements there are several additional
+quantities which are determined.  
+Other quantities which are computed are the relative magnitude,
+ellipticity, and position angle.  The magnitude of an individual
+measurement is obtained from the maximum flux attained in the enclosed
+flux profile computation.  Though the normalization and background may be
+adjusted interactively later, the magnitude is not changed from the
+initial determination.  The relative magnitude of an object is then
+computed as
+
+.nf
+    rel. mag. = -2.5 * log (object flux / maximum star flux)
+.fi
+
+The maximum star magnitude over all stars is used as the zero point for the
+relative magnitudes (hence it is possible for an individual object relative
+magnitude to be less than zero).
+
+The ellipticity and positional angle of an object are derived from the
+second central intensity weighted moments.  The moments are:
+
+.nf
+	Mxx = sum { (I - B) * x * x } / sum { I - B }
+	Myy = sum { (I - B) * y * y } / sum { I - B }
+	Mxy = sum { (I - B) * x * y } / sum { I - B }
+.fi
+
+where x and y are the distances from the object center, I is
+the pixel intensity and B is the background intensity.  The sum is
+over the same subpixels used in the enclosed flux evaluation with
+intensities above an isophote which is slightly above the background.
+The ellipticity and position angles are derived from the moments
+by the equations:
+
+.nf
+	M1 = (Mxx - Myy) / (Mxx + Myy)
+	M2 = 2 * Mxy / (Mxx + Myy)
+	ellip = (M1**2 + M2**2) ** 1/2
+	pa = atan (M2 / M1) / 2
+.fi
+
+where ** is the exponentiation operator and atan is the arc tangent
+operator.  The ellipticity is essentially (a - b) / (a + b) where a
+is a major axis scale length and b is a minor axis scale length.  A
+value of zero corresponds to a circular image.  The position angle is
+given in degrees counterclockwise from the x or column axis.
+
+The overall size when there are multiple stars is estimated by averaging
+the individual sizes weighted by the flux of the star as described above.
+Thus, when there are multiple stars, the brighter stars are given greater
+weight in the average size.  This average size is what is given in the
+banner for the graphs and in the printed output.
+
+One of the quantities computed for the graphical analysis is the
+FWHM of a Gaussian or Moffat profile that encloses the same flux
+as the measured object as a function of the level.  The equation are:
+
+.nf
+   FWHM = 2 * r(level) * sqrt (ln(2.) / ln (1/(1-level)))  Gaussian
+
+   FWHM = 2 * r(level) * sqrt (2**(1/beta)-1) /
+	  sqrt ((1-level)**(1/(1-beta))-1)		   Moffat
+.fi
+
+where r(level) is the radius that encloses "level" fraction of the total
+flux.  ln is the natural logarithm and sqrt is the square root.  The beta
+value is either the user specified value or the value determined by fitting
+the enclosed flux profile.
+
+This function of level will be a constant if the object profile matches
+the Gaussian or Moffat profile.  Deviations from a constant show
+the departures from the profile model.  The Moffat profile used in making
+the graphs except for the case where the \fIsize\fR is GFWHM.
+.ih
+INTERACTIVE GRAPHICS MODE
+The graphics part of \fBpsfmeasure\fR consists of a number of different
+plots selected by cursor keys.  The available plots depend on the number of
+stars.  The various plots and the keys which select them are summarized
+below.
+
+.nf
+a  Spatial plot
+e  Enclosed flux for all stars
+m  Size and ellipticity vs relative magnitude
+p  Radial profiles for all stars
+t  Size and ellipticity vs radius from field center
+z  Zoom to a single measurement
+.fi
+
+If there is only one object the only available plot is
+the 'z' or zoom plot.  This has three graphs; a graph of the normalized
+enclosed flux verses scaled radius, a graph of the intensity profile verses
+scaled radius, and equivalent Moffat/Gaussian full width at half maximum verses
+enclosed flux fraction.  The latter two graphs are derived from the
+normalized enclosed flux profile as described in the ALGORITHMS section.
+In the graphs the measured points are shown with symbols, a smooth curve is
+drawn through the symbols and dashed lines indicate the measurement level
+and enclosed flux radius at that level.
+
+Overplotted on these graphs are the Moffat profile fit or the
+Gaussian profile fit when \fIsize\fR is GFWHM.
+
+The zoom plot is always available from any other plot.  The cursor position
+when the 'z' key is typed selects a particular object measurement.
+This plot is also the one presented with the 'g' key when marking objects for
+single exposure images.  In that case the graphs are drawn followed by
+a return to image cursor mode.
+
+There are two types of symbol plots showing the measured PSF size (either
+enclosed flux radius or FWHM) and ellipticity.  These plot the measurements
+verses relative magnitude ('m' key) and radius from the field center ('t'
+key).  These plots are only available when there are multiple stars
+measured.  The magnitude plot is the initial plot in this case.  The field
+center for the field radius graph may be changed interactively using the
+":xcenter" and ":ycenter" commands.
+
+Grids of enclosed flux vs. radius, intensity profile vs. radius, and
+FWHM vs. enclosed flux fraction are shown with the 'e', 'p', and
+'g' keys respectively when there is more than one star.  The grid shows
+a profile for each star.  The profiles in the grid have no axis labels or
+ticks.  Within each box are the coordinates of the object
+and the PSF size.  Below the grid is shown a graph of a single objects
+including axis labels and ticks.
+
+In the grid there is one profile which is highlighted (by a second box or
+by a color border).  This is the profile shown in the lower graph.  To
+change the star in the lower graph on can type the space bar to advance to
+the next star or use the cursor and the 'e', 'p', or 'g' key again.  Other
+keys will select another plot using the star nearest the cursor to select a
+measurement.
+
+Any of the graphs with enclosed flux or intensity profiles vs radius may
+have the profiles of the object with the smallest size overplotted.  The
+overplot has a dashed line, a different color on color graphics devices,
+and no symbols marking the measurement points.  The overplots may be
+enabled or disabled with the ":overplot" command.  Initially it is
+disabled.
+
+The final plot, the 'a' key, gives a spatial representation.  This requires
+more than one star.  This plot has a central graph of column and line
+coordinates with symbols indicating the position of an object.  The objects
+are marked with a circle (when plotted at unit aspect ratio) whose size is
+proportional to the measured PSF size.  In addition an optional asterisk
+symbol with size proportional to the relative brightness of the object may
+be plotted.  This symbol is toggled with the 's' key.  On color displays
+the circles may have two colors, one if object size is above the average
+best size and the other if the size is below the best size.  The purpose of
+this is to look for a spatial pattern in the PSF sizes.
+
+Adjacent to the central graph are graphs with column or line as one
+coordinate and radius or ellipticity as the other.  The symbols
+are the same as described previously.  These plots can show spatial
+gradients in the PSF size and shape across the image.
+
+In addition to the keys which select plots there are other keys which
+do various things.  These are summarized below.
+
+.nf
+?  Page cursor command summary
+d  Delete star nearest to cursor
+i  Information about point nearest the cursor
+n  Normalize enclosed flux at x cursor position
+o  Offset enclosed flux by adjusting background
+q  Quit
+r  Redraw
+s  Toggle magnitude symbols in spatial plots
+u  Undelete all deleted points
+x  Delete nearest point or star (selected by query)
+<space> Step through different stars in current plot type
+.fi
+
+The help, redraw, and quit keys are provide the standard functions.
+The 's' and space keys were described previously.  The 'i' key
+locates the nearest object to the cursor in whatever plot is shown and
+prints one line of information about the object on the graphics device
+status area.
+
+The 'd' key deletes the star nearest the cursor in whatever plot is
+currently displayed.  To delete all objects from an image, all
+values for one star (the same as 'd'), or a
+single measurement, the 'x' key is used.  Typing this key produces a query
+for which type of deletion and the user responds with 'i', 's', or
+'p'.  Deleted measurements do not appear in any subsequent
+graphics, are excluded from all computations, and are not output in the
+results.  The 'u' key allows one to recover deleted measurements.  This
+undeletes all previously deleted data.
+
+Due to various sources of error the sky value may be wrong causing
+the enclosed flux profile to not converge properly but instead
+decreases beyond some point (overestimated sky) or linearly
+increases with radius (underestimated sky).  This affects the size
+measurement by raising or lowering the normalization and altering
+the shape of the enclosed flux profile.  The 'n' and 'o' keys allow
+fudging the enclosed flux profiles.  These keys apply only in
+the zoom plot or 'e' key plot of the enclosed flux profile.
+
+The 'n' key normalizes the enclosed flux profile at the point
+set by the x position of the cursor.  The 'o' key increases or
+decreases the background estimate to bring curve up or down to
+the point specified by the cursor.  The effect of this is to
+add or subtract a quadratic function since the number of pixels
+at a particular radius varies as the square of the radius.
+To restore the original profile, type 'n' or 'o' at a radius
+less than zero.
+
+The colon commands, shown below, allow checking or changing parameters
+initially set by the task parameters, toggling the overplotting of the
+smallest PSF profiles, and showing the current results.  The overplotting
+option and the contents of the results displayed by :show were described
+previously.
+
+.nf
+:beta <val>     Beta value for Moffat profile fits
+:level <val>	Level at which the size parameter is evaluated
+:overplot <y|n> Overplot the profiles from the narrowest profile?
+:radius <val>   Change profile radius
+:show <file>	Page all information for the current set of objects
+:size <type>	Size type (Radius|FWHM)
+:scale <val>	Pixel scale for size values
+:xcenter <val>	X field center for radius from field center plots
+:ycenter <val>	Y field center for radius from field center plots
+.fi
+
+The important values which one might want to change interactively are
+the measurement level and the profile radius.  The measurement level
+directly affects the results reported.  When it is changed the sizes
+of all object PSFs are recomputed and the displayed plots and title
+information are updated.  The profile radius is the
+maximum radius shown in plots and used to set the enclosed flux normalization.
+It does not affect the object centering or sky region definition and
+evaluation which are done when the image data is accessed.  Because
+the objects are not remeasured from the image data the radius may
+not be made larger than the radius defined by the task parameter though
+it may be decreased and then increased again.
+.ih
+EXAMPLES
+1.  An image of a star field is studied with default values.
+
+.nf
+cl> psfmeasure field1
+<The image is displayed and the image cursor activated>
+<A number of brighter stars are marked>
+<Marking is finished with 'q'>
+<Graph of FWHM and ellipticity vs relative magnitude are shown>
+<A couple of bad measurements due to blending are deleted>
+<Exit with 'q'>
+NOAO/IRAF IRAFV2.10.3 valdes@puppis Tue 18:22:36 06-Jul-93
+  Average full width at half maximum of 4.5722
+
+       Image  Column    Line     Mag    FWHM   Ellip      PA SAT
+      field1   68.96   37.87    0.75   5.636    0.03      15
+	      488.41  116.78    1.61   5.376    0.03     -68
+	       72.17  156.35    1.47   4.728    0.06     -14
+	       33.72  211.86    2.74   4.840    0.05     -52
+	      212.80  260.73    2.99   3.888    0.11      83
+	      250.51  277.37    1.92   3.914    0.02     -14
+	      411.81  292.83    1.93   5.032    0.04      34
+	      131.85  301.12    2.67   4.028    0.06       4
+	      168.37  413.70    2.20   4.408    0.05      75
+	      256.02  255.99    0.00   3.940    0.00     -70
+
+The estimated average FWHM is 4.5722.  The variation in size is real
+in this artificial image having a radial variation in PSF.
+.ih
+SEE ALSO
+.nf
+imexamine, implot, pprofile, pradprof, radlist, radplt, radprof,
+specfocus, starfocus, splot
+.endhelp
diff --git a/noao/obsutil/src/doc/shutcor.hlp b/noao/obsutil/src/doc/shutcor.hlp
new file mode 100644
index 00000000..6968bdff
--- /dev/null
+++ b/noao/obsutil/src/doc/shutcor.hlp
@@ -0,0 +1,93 @@
+.help shutcor Nov01 noao.obsutil
+.ih
+NAME
+shutcor -- shutter correction from images of varying exposure
+.ih
+SYNOPSIS
+SHUTCOR calculate the shutter correction for a detector given a
+sequence of overscan corrected images of varying durations.  Typically
+these would be flat field exposures.  The shutter correction is the
+intercept on a plot of exposure duration versus exposure level.
+.ih
+USAGE
+shutcor images
+.ih
+PARAMETERS
+.ls images
+List of overscan corrected images.  These would usually be flat
+field exposures.
+.le
+.ls section = ""
+The selected image section for the statistics.  This should be chosen
+to exclude bad columns or rows, cosmic rays, and other non-linear
+features.
+.le
+.ls center = "mode"
+The statistical measure of central tendency that is used to estimate
+the data level of each image.  This can have the values:  \fBmean\fR,
+\fBmidpt\fR, or \fBmode\fR.  These are calculated using the same
+algorithm as the IMSTATISTICS task.
+.le
+.ls nclip = 3
+Number of sigma clipping iterations.  If the value is zero then no clipping
+is performed.
+.le
+.ls lsigma = 4, usigma = 4
+Lower and upper sigma clipping factors used with the mean value and
+standard deviation to eliminate cosmic rays.
+Since \fBfindgain\fR is sensitive to the statistics of the data the
+clipping factors should be symmetric (the same both above and below the
+mean).
+.le
+.ls exposure = "exptime"
+Keyword giving the exposure time.
+.le
+.ls verbose = yes
+Verbose output?
+.le
+.ih
+DESCRIPTION
+SHUTCOR calculate the shutter correction for a detector given a
+sequence of overscan corrected images of varying durations.  Typically
+these would be flat field exposures.  The shutter correction is the
+intercept on a plot of exposure duration versus exposure level.
+
+The images must contain the keyword OVERSCAN otherwise and error will
+be given.
+
+Bad pixels should be eliminated to avoid affecting the statistics.
+This can be done with sigma clipping and/or an image section.
+The sigma clipping should not significantly affect the assumed gaussian
+distribution while eliminating outlyers due to cosmic rays and
+unmasked bad pixels.  This means that clipping factors should be
+symmetric.
+.ih
+EXAMPLES
+A sequence of flat fields with varying exposure times are taken and
+processed to subtract the overscan.
+
+.nf
+    cl> shutcor flat*
+
+    Shutter correction = 0.538 +/- 0.043 seconds
+
+    Information about the mode versus exptime fit:
+
+	   intercept        slope     (and errors)
+	    5.347105      9.933618
+	   0.4288701    0.01519613
+	
+	chi sqr:  0.2681   ftest: 419428.   correlation:      1.
+	 nr pts:      4.   std dev res: 0.422769
+	
+	x(data)     y(calc)     y(data)     sigy(data)
+	     3.      35.148     34.6725          0.
+	    12.     124.551     125.015          0.
+	    27.     273.555     273.778          0.
+	    48.     482.161     481.949          0.
+.fi
+.le
+.ih
+SEE ALSO
+imstatistics
+.endhelp
diff --git a/noao/obsutil/src/doc/specfocus.hlp b/noao/obsutil/src/doc/specfocus.hlp
new file mode 100644
index 00000000..137eca23
--- /dev/null
+++ b/noao/obsutil/src/doc/specfocus.hlp
@@ -0,0 +1,375 @@
+.help specfocus Nov01 noao.obsutil
+.ih
+NAME
+specfocus -- Determine spectral focus and alignment variations
+.ih
+USAGE
+specfocus images
+.ih
+PARAMETERS
+.ls images
+List of 1D or 2D focus images.  Typically the input is a list of raw
+2D CCD images of arc slit spectra.  The 1D image input is provided to
+allow use of extraction techniques beyond those provided by this task.
+.le
+.ls focus = ""
+List of focus identification values to be associated with each input image
+or an image header keyword containing the values.  The list may be an
+explicit list of values, a range specification, an @ file containing the
+values, or an image header keyword.  If none of these is given the
+identification values are simple index values in the order of the input
+images.  A range specification has the forms A, AxC, A-BxC where A is a
+starting value, B is an ending value, and C is an increment.
+.le
+.ls corwidth = 20.
+Correlation width in pixels.
+.le
+.ls level = 0.5
+Percent or fraction of the correlation peak at which to measure focus
+widths.  The default is 50% or full width at half maximum.
+.le
+.ls shifts = yes
+Compute dispersion shifts across the dispersion when there are multiple
+samples?  If yes and there are multiple samples across the dispersion
+(\fIndisp\fR > 1), pixel shifts relative to the central sample are
+determine by crosscorrelation.
+.le
+
+.ls dispaxis = 2
+Dispersion axis for 2D images.  The image header keyword DISPAXIS has
+precedence over this value.
+.le
+.ls nspectra = 1, ndisp = 1
+The number of spectral samples across the dispersion
+and the number of subpieces along the dispersion to divide the spectra
+into.  If \fInspectra\fR is greater than one then information about
+variations across the dispersion will be determined and if \fIndisp\fR is
+greater than 1 information about variations along the dispersion will be
+determined.  \fINspectra\fR applies only to 2D images.  For 1D spectra in
+multispec format each line is used as a separate sample.
+.le
+.ls slit1 = INDEF, slit2 = INDEF
+The lower and upper edges of the slit (or data region) in pixel
+coordinates (lines or columns) across the dispersion axis.  A value
+of INDEF specifies the image edges.
+.le
+
+.ls logfile = "logfile"
+File in which to record the results.  If no file is specified no log
+output is produced.
+.le
+.ih
+CURSOR COMMANDS
+All keys select an image and a sample (one of the \fIndisp\fR samples along
+the dispersion and one of the \fInspectra\fR samples across the dispersion)
+which is then generally highlighted.
+
+.nf
+   ?  Help summary
+   b  Best focus at each sample summary graphs
+   d  Delete image, sample, or point
+   p  Profiles at one sample for all images and all samples for one image
+   q  Quit
+   r  Redraw
+   s  Spectra at one sample for all images and all samples for one image
+   u  Undelete spectrum, sample, or point
+   w  Profile widths verses focus and distribution of widths
+   z  Zoom on a single sample showing correlation profile and spectrum
+   <space>  Status line output for selected image and sample
+.fi
+
+.ih
+DESCRIPTION
+This task estimates the dispersion width of spectral lines in sequences of
+arc spectra taken at different focus settings (or with some other parameter
+varied).  The widths can be measured at different spatial and dispersion
+positions, called "samples", on the detector.  The width estimates are
+recorded and displayed graphically to investigate dependencies and
+determine appropriate settings for the spectrograph setup.  The task may
+also measure dispersion shifts when multiple spectral samples are
+specified.  This task does not measure the focus point-spread-function
+width across the dispersion.
+
+The input images are specified with an image template list.  The list may
+consist of explicit image names, wildcard templates, and @ files.  A
+"focus" value is associated with each image.  This may be any numeric
+quantity (integer or floating point).  The focus values may be specified in
+several ways.  If no value is given then index numbers are assigned to
+the images in the order in which they appear in the image list.  A range
+list may be specified as described in the help topic \fBranges\fR.  This
+consists of individual values, ranges of values, a starting value and a
+step, and a range with a step.  The elements of the list are separated by
+commas, ranges are separated by hyphens, and a step is indicated by the
+character 'x'.  Long range lists, such as a list of individual focus
+values, may be placed in a file and specified with the @<filename>
+convention.  Finally, a parameter in the image header may be used for the
+focus values by simply specifying the parameter name.
+
+Two dimensional long slit images are summed into one or more one
+dimensional spectra across the dispersion.  The dispersion axis is defined
+either by the image header parameter DISPAXIS or the \fIdispaxis\fR task
+parameter with the image header parameter having precedence.  The range of
+lines or columns across the dispersion to be used is specified by the
+parameters \fIslit1\fR and \fIslit2\fR.  If specified as INDEF then the
+image limits are used.  This range is then divided into the number of
+spectra given by the parameter \fInspectra\fR.  Use of more than one
+spectrum across the dispersion allows investigation of variations along the
+slit.  In addition, if the parameter \fIshifts\fR is set the spectrum
+nearest the center is used as a reference against which shifts in the
+dispersion positions of the features in the other spectra are determined by
+crosscorrelation.
+
+The conversion of two dimensional spectra to one dimensional spectra may
+also be performed separately using the tasks in the \fBapextract\fR
+package.  This would be done typically for multifiber or echelle format
+spectra.  If the two dimensional spectra have been extracted to one
+dimensional spectra in this way the task ignores the dispersion axis and
+number of spectra parameters.  The data limits (\fIslit1\fR and
+\fIslit2\fR) are still used to select a range of lines in  "multispec"
+format images.  The \fIshifts\fR parameter also applies when there are
+multiple spectra per image.  However, it does not make sense in the case of
+echelle spectra and so it should be set to no in that case.
+
+In addition to dividing the spatial axis into a number of spectra the
+dispersion axis may also be divided into a set of subspectra.  The number
+of divisions is specified by the \fIndisp\fR parameter which applies to
+both long slit and 1D extracted spectra.  When the dispersion axis is
+divided into more than one sample, the dependence of the dispersion widths
+and shifts along the dispersion may be investigated.
+
+Each spectral sample has a low order continuum subtracted using a
+noninteractive iterative rejection algorithm to exclude the spectral
+lines.  This technique is described further under the topic
+\fIcontinuum\fR.  The continuum subtracted spectrum is then tapered with a
+cosine bell function and autocorrelated.  The length of the taper and the
+range of shifts for the correlation is set by the \fIcorwidth\fR
+parameter.  This parameter should be only slightly bigger than the expected
+feature widths to prevent correlations between different spectral lines.
+The correlation profile is offset to zero at the edges of the profile and
+normalized to unity at the profile center.  The profiles may be viewed as
+described below.
+
+If there is more than one spatial sample the central spectrum is also
+crosscorrelated against the other spectra at the same dispersion
+sample.  The crosscorrelation is computed in exactly the same way as
+the autocorrelation.  The crosscorrelation profiles are only used for
+determining shifts between the two samples and are not used in the
+width determinations.
+
+A cubic spline interpolator is fit to the profiles and this interpolation
+function is used to determined the profile width and center.  The width is
+measured at a point given by the \fIlevel\fR parameter relative to the
+profile peak.  It may be specified as a fraction of the peak if it is less
+than one or a percentage of the peak if it is greater than one.  The
+default value of 0.5 selects the full width at half maximum.  The
+autocorrelation width is divided by the square root of two to yield an
+estimate of the width of the spectral features in the spectrum in units of
+pixels.
+
+Having computed the width and shift for each input image at each sample,
+the "best focus" values (focus, width, and shift) are estimated for each
+sample.  As discussed later, it is possible to exclude some samples
+from this calculation by deleting them graphically.
+First the images with the smallest measured width at each distinct
+focus are selected since it is possible to input more than one image at the
+same focus.  The selected images are sorted by focus value and the image
+with the smallest width is found.  If that image has the lowest or highest
+focus (which will always be the case if there are only one or two images)
+then the best focus, width, and shift are those measured for that image.
+If there are three or more focus values and the minimum width focus image
+is not an endpoint then parabolic interpolation is used to find the minimum
+width.  The focus at this minimum width is the "best focus".
+The dispersion shift is the parabolic interpolation of the shifts at
+the best focus.  The "average best focus" values are then the average of
+the "best focus" values over all samples.
+
+After computing the correlation profiles, the profile widths and shifts,
+and the best focus values, an interactive graphics mode is entered.  This
+is described in detail below.  The graphics mode is exited with the 'q'
+key.  At this point the results are written to the standard output (usually
+the terminal) and to a logfile if one is specified.  The output begins with
+a banner identifying the task, version of IRAF, the user, and the date and
+time.  The next line gives the best average focus and width.  This banner
+also appears in all plots.  Then each image is listed with the focus value
+and average width (over all samples).  Finally the image with the smallest
+average width is identified and tables showing the width and shifts (if
+computed) at each sample position are printed.  If there is only one sample
+then the tables are not output.
+
+INTERACTIVE GRAPHICS MODE
+
+There are five types of plot formats which are selected with the 'b', 'p',
+'s', 'w', and 'z' keys.  The available formats and their content are
+modified depending on the number of images and the number of samples.  If
+there is only one image or one sample per image some of the plot formats
+are not available.  If there are a large number of images or a large number
+of samples the content of the plot formats may be abbreviated for
+legibility.
+
+In all plots there is a concept of the current image and the current
+sample.  In general there is an indication, usually a box, of which image
+and sample is the current one.  The current image and sample are
+changed by pointing at a particular point, box, circle, or symbol for that
+image and sample and typing a key.
+
+The 'b' key produces summary graphs of the best focus values (as described
+above) at each sample position.  There must be more than one image and more
+than one sample (either along or across the dispersion or both).  This is
+the initial plot shown when this condition is satisfied.  The central graph,
+which is always drawn, represents the best focus (smallest) width at each
+sample by circles of size proportional to the width.  The position of the
+circle indicates the central line and column of the sample.  If there are
+multiple samples across the dispersion and the \fIshifts\fR parameter is
+set then little vectors are also drawn from the center of the circle in the
+direction of the shift and with length proportional to the shift.  If there
+are 5 or fewer samples in each dimension the values of the best focus and
+the width and shift (if computed and nonzero) at that focus, are printed on
+the graph next to the circles.  If there are more samples this information
+may be obtained by pointing at the sample and typing the space key.
+
+In addition to the spatial graph there may be graphs along the line or column
+axes.  These graphs again show the widths as circles but one axis is either
+the line or column and the other axis is either the best focus value or the
+shift.  The focus graph marks the best average focus (over all samples) by
+a dashed line and a solid line connects the mean focus at each column or
+line.  The focus graphs will only appear if there is more than one sample
+along a particular image axis.  The shift graphs will only appear if the
+shifts are computed (\fIshifts\fR parameter is yes) and there is more than
+one sample along a particular dimension.  Lines are drawn at zero shift and
+connecting the mean shift at each point along the spatial axis.  Note that
+there is always a point at zero shift which is the reference sample.
+
+The best focus graphs are the exception in showing a current image and
+sample.  When changing to one of the other plots based on a current image
+and sample the circle from the central spatial graph nearest the cursor is
+used (note that the other focus and shift graphs are ignored).  The sample
+is defined by it's spatial position and the image is the one with
+focus closest to the best focus value of that sample.
+
+The 'w' key produces a graph showing the sample widths as a function of
+focus value.  There must be more than one image and more than one sample
+for this type of graph.  The top graph is a symbol plot of width verses
+focus.  The symbols are crosses except for the current image which is shown
+with pluses.  The current sample is highlighted with a box.  Also shown is
+a long dashed line connecting the widths for the current sample at each
+focus value and short dashed lines showing the best average focus and
+width.
+
+The lower portion of the 'w' key are graphs showing the
+widths as circles with size proportional to the width and position
+corresponding to the spatial position of the sample in the image.  If there
+are more than 5 samples in either dimension the graph is for the current
+image.  Otherwise there is a box for each image with the focus value
+(provided there are not too many images) indicated.  The circles are
+arranged as they would be spatially in columns and rows.  The samples
+closest to the best focus are indicated by pluses.  This allows seeing
+where the best focus values cluster.  The current image and sample are
+indicated by highlighting boxes.
+
+The 'p' key produces graphs of the autocorrelation profiles.  This also
+requires more than one image and more than one sample.  The top graph shows
+the profiles of all images at a particular sample and the bottom graph shows
+the profiles of all samples at a particular image.  The bottom sample boxes
+are arranged in columns and rows in the same way the samples are
+distributed in the image.  The current image and current sample are
+highlighted by a box.
+
+The profiles are drawn with a solid line using the interpolator function
+and the actual pixel lags are indicated with pluses.  The profiles are
+drawn shifted by the amount computed from the crosscorrelation.
+Note that the shift is added to the autocorrelation profile
+and the crosscorrelation profile is not what is plotted.  The zero shift
+position is indicated by a vertical line.  If there are less than 25 boxes
+the boxes are labeled by the width, shift (if nonzero), and focus.
+
+The 's' key plot is similar to the 'p' key plot but shows the spectra
+rather than the profiles.  The top graphs are the spectra of each image at
+a particular sample and the bottom graphs are the spectra of each sample
+for a particular image.  The current image and sample are highlighted by a
+box.
+
+The 'z' key graphs the autocorrelation profile and the spectrum
+of a single sample.  This graph provides scales which are not
+provided with the 'p' and 's' graphs.  If there is only one image
+and one sample then this is the only plot available.
+
+It is possible to exclude some of the samples from the calculation
+of the best focus and best average focus values.  This is done by
+deleting them using the 'd' key.  When using the 'd' key you must
+specify the sample to be deleted in one of the graphs.  You are
+then asked if only that sample (point) is to be deleted, if all
+samples from that image are to be deleted, or if the same sample
+from all images is to be deleted.  The deleted data is no longer
+shown explicitly but the space occupied by the data is still present
+so that the data may be included again by typing the 'u' undelete
+key.  When the task is exited with the 'q' key the printed and
+logged results will have the deleted data excluded.
+
+The remaining cursor keys do the following.  The '?' key gives a
+summary of the cursor keys.  The 'r' key redraws the current plot.
+The space key prints information about the current sample.  This
+is mostly used when there are too many images or samples to annotate
+the graphs with the focus, width, and shift.  Finally the 'q'
+key quits the task.
+.ih
+EXAMPLES
+1.  A series of 2D focus images is obtained with focus values
+starting at 400 in steps of -50.  The slit is between columns 50
+and 130.  There are 3 samples across the dispersion and 3 along
+the dispersion.
+
+.nf
+    cl> lpar specfocus
+	   images = "@imlist"       List of images
+	   (focus = "400x-50")     Focus values
+	(corwidth = 20)             Correlation width
+	   (level = 0.5)            Percent or fraction of peak
+	  (shifts = yes)            Compute shifts across the disp?\n
+	(dispaxis = 2)              Dispersion axis (long slit only)
+	(nspectra = 3)              Number of spec samples (ls only)
+	   (ndisp = 3)              Number of dispersion samples
+	   (slit1 = 50)             Lower slit edge
+	   (slit2 = 130)            Upper slit edge\n
+	 (logfile = "logfile")      Logfile
+	    (mode = "ql")
+    cl> specfocus @imlist
+    <Interactive graphics which is exited with the 'q' key>
+    SPECFOCUS: NOAO/IRAF V2.10EXPORT valdes Thu 19:41:41 17-Sep-92
+      Best avg focus at 206.6584 with avg width of 2.91 at 50% of peak
+
+      -- Average Over All Samples
+
+				     Image  Focus  Width
+				jdv011.imh   100.   3.78
+				jdv010.imh   150.   3.28
+				jdv009.imh   200.   2.95
+				jdv008.imh   250.   3.17
+				jdv007.imh   300.   3.41
+				jdv006.imh   350.   3.74
+				jdv005.imh   400.   4.16
+
+      -- Image jdv009.imh at Focus 200. --
+
+
+	    Width at 50% of Peak:
+
+			 Columns
+			   50-76      77-103    104-130 
+	       Lines  +---------------------------------
+	       2-267  |    2.93       2.58       2.74   
+	     268-533  |    3.17       2.76       2.89   
+	     534-799  |    3.77       2.23       3.50   
+
+	    Position Shifts Relative To Central Sample:
+
+			 Columns
+			   50-76      77-103    104-130 
+	       Lines  +---------------------------------
+	       2-267  |    0.68       0.00       0.18   
+	     268-533  |    0.64       0.00       0.13   
+	     534-799  |    0.92       0.00       0.16   
+.fi
+.ih
+SEE ALSO
+imexamine, implot, ranges, splot
+.endhelp
diff --git a/noao/obsutil/src/doc/sptime.hlp b/noao/obsutil/src/doc/sptime.hlp
new file mode 100644
index 00000000..a2c0f242
--- /dev/null
+++ b/noao/obsutil/src/doc/sptime.hlp
@@ -0,0 +1,1218 @@
+.help sptime Nov01 noao.obsutil
+.ih
+NAME
+sptime -- spectroscopic exposure time calculator
+.ih
+USAGE
+sptime
+.ih
+PARAMETERS
+The parameters in this task have certain common features.
+.ls (1)
+All parameters, except \fIspectrograph\fR and \fIsearch\fR, may be
+specified as spectrograph table parameters of the same name.  Some
+parameters may also be specified in other tables.  The tables in which the
+paramters may be specified are shown in brackets.  Table values are used
+only if a string parameter is "" or a numeric parameter is INDEF.
+Therefore parameter set values override values in the tables.  To override
+a table specified in the spectrograph file by no file the special value
+"none" is used.  This task also uses default values, shown below in
+parenthesis, for parameters that have no value specified either in the
+parameter set or in a table.
+.le
+.ls (2)
+Parameters that specify a table take the value of a file or a numeric
+constant.  A constant is like a table with the same values for all value
+of the independent variable(s).
+.le
+.ls (3)
+Tables which are specified as filenames are sought first in the current
+working directory, then in one of the directories given by the
+\fIsearch\fR parameter, and finally in the package library directory
+sptimelib$.
+.le
+
+
+.ls time = INDEF (INDEF) [spectrograph]
+Total exposure time in seconds.  This time may be divided into shorter
+individual exposure times as defined by the \fImaxexp\fR parameter.  If
+the value is INDEF then the exposure time needed to achieve the
+signal-to-noise per pixel specified by the \fIsn\fR parameter is computed.
+.le
+.ls sn = 25. (25.) [spectrograph]
+Desired signal-to-noise per pixel at the central wavelength if the
+exposure \fItime\fR parameter is not specified.
+.le
+
+
+The following parameters define the source and sky/atmosphere background
+spectra.
+.ls spectrum = "blackbody"
+Source spectrum.  This may be a table or one of the following  special words:
+.ls blackbody
+Blackbody spectrum with temperature given by the \fItemperature\fR
+parameter.
+.le
+.ls flambda_power
+Power law in f(lambda) with index given by the \fIindex\fR parameter;
+f(lambda) proportional to lambda^(index).
+.le
+.ls fnu_power
+Power law in f(nu) with index given by the \fIindex\fR parameter;
+f(nu) proportional to nu^(index).
+.le
+
+The table is a two column text file of wavelength in Angstroms and flux in
+ergs/s/cm^2/A.
+.le
+.ls spectitle = "" [spectrum|spectrograph]
+Spectrum title.
+.le
+.ls E = 0. (0.) [spectrum|spectrograph]
+The E(B-V) color excess to apply a reddening to the source spectrum.  The
+reddening maintains the same table or reference flux at the reference
+wavelength.  A value of zero corresponds to no reddening.
+.le
+.ls R = 3.1 (3.1) [spectrum|spectrograph]
+The R(V) = A(V)/E(B-V) for the extinction law.  The extinction law is that
+of Cardelli, Clayton, and Mathis, \fBApJ 345:245\fR, 1989.  The default
+R(V) is typical of the interstellar medium.
+.le
+.ls sky = "" ("none") [spectrograph]
+Sky or background table.  The table is a two or three column text file
+consisting of wavelength in Angstroms, optional moon phase between 0 (new
+moon) and 14 (full moon), and flux in ergs/s/cm^2/A/arcsec^2.
+.le
+.ls skytitle = "" [sky|spectrograph]
+Sky title.
+.le
+.ls extinction = "" ("none") [spectrograph]
+Extinction table.  The table is a two column text file consisting of
+wavelength in Angstroms and extinction in magnitudes per airmass.
+.le
+.ls exttitle = "" [spectrograph]
+Extinction title.
+.le
+
+
+The following parameters are used with the source spectrum is specified
+by the special functions.
+.ls refwave = INDEF (INDEF) [spectrum|spectrograph]
+Reference wavelength, in units given by the \fIunits\fR parameter, defining
+the flux of the source.  This is also used as the wavelength where
+reddening does not change the spectrum flux.  A value of INDEF uses the
+observation central wavelength.
+.le
+.ls refflux = 10. (10.) [spectrograph]
+Reference source flux or magnitude at the reference wavelength for the
+model spectral distributions.  The units are specified by the funits parameter.
+.le
+.ls funits = "AB" ("AB") [spectrograph]
+Flux units for the reference flux.  The values are "AB" for monochromatic
+magnitude, "F_lambda" for ergs/s/cm^2/A, "F_nu" for ergs/s/cm^2/Hz,
+and standard bandpasses of U, B, V, R, I, J, H, Ks, K, L, L' and M.
+.le
+.ls temperature = 6000. (6000.) [spectrograph]
+Blackbody temperature for a blackbody source spectrum in degrees Kelvin.
+.le
+.ls index = 0. (0.) [spectrograph]
+Power law index for the power law source spectrum.
+.le
+
+
+The following parameters are observational parameters describing either
+the observing conditions or spectrograph setup.
+.ls seeing = 1. (1.) [spectrograph]
+The full width at half maximum (FWHM) of a point source in arc seconds.
+.le
+.ls airmass = 1. (1.) [spectrograph]
+The airmass of the observation.  This is only used if an extinction table
+is specified.
+.le
+.ls phase = 0. (0.) [spectrograph]
+The moon phase running from 0 for new moon to 14 for full moon.  This is
+used if the sky spectrum is given as a function of the moon phase.
+.le
+.ls thermal = 0. (0.) [telescope|spectrograph]
+Temperature in degress Kelvin for the thermal background of the telescope
+and spectrograph.  If greater than zero a blackbody surface brightness
+background is computed and multiplied by an emissivity specified by
+the \fIemissivity\fR table.
+.le
+.ls wave = INDEF (INDEF) [spectrograph]
+Central wavelength of observation in units given by the \fIunits\fR
+parameter.  If the value is INDEF it is determined from the efficiency peak
+of the disperser.
+.le
+.ls order = INDEF (INDEF) [spectrograph]
+Order for grating or grism dispersers.  If the value is INDEF it is
+determined from the order nearest the desired central wavelength.  If both
+the order and central wavelength are undefined the first order is used.
+.le
+.ls xorder = INDEF (INDEF) [spectrograph]
+Order for grating or grism cross dispersers.  If the value is INDEF it
+is determined from the order nearest the desired central wavelength.  If
+both the order and central wavelength are undefined the first order is
+used.
+.le
+.ls width = INDEF (-2.) [aperture|spectrograph]
+The aperture width (dispersion direction) for rectangular apertures
+such as slits.  Values may be positive to specify in arc seconds or
+negative to specify in projected pixels on the detector.
+.le
+.ls length = INDEF (-100.) [aperture|spectrograph]
+The aperture length (cross dispersion direction) for rectangular
+apertures such as slits.  Values may be positive to specify in arc seconds
+or negative to specify in projected pixels on the detector.
+.le
+.ls diameter = INDEF (-2.) [fiber|aperture|spectrograph]
+The aperture diameter for circular apertures.  Values
+may be positive to specify in arc seconds or negative to specify in
+projected pixels on the detector.  If it is found in the fiber table,
+positive values are treated as mm at the focal plane instead of arc seconds.
+.le
+.ls xbin = 1 (1) [detector|spectrograph]
+Detector binning along the dispersion direction.
+.le
+.ls ybin = 1 (1) [detector|spectrograph]
+Detector binning along the spatial direction.
+.le
+
+
+The following parameters a miscellaneous parameters for the task.
+.ls search = "spectimedb$"
+List of directories to search for the various table files.  The current
+direction is always searched first and the directory sptimelib$ is searched
+last so it is not necessary to include these directories.  The list may be
+a comma delimited list of directories, an @file, or a template.
+.le
+.ls minexp = 0.01 (0.01) [spectrograph]
+Minimumm time in seconds per individual exposure time.  This only applies
+when \fItime\fR is INDEF.  Adjustment of the exposure time for saturation
+will not allow the exposure time to fall below this value.
+.le
+.ls maxexp = 3600. (3600.) [spectrograph]
+Maximum time in seconds per individual exposure.  The minimum exposure time
+has precedence over this value.  If the total exposure time exceeds this
+amount by more than 1% then the total exposure time will be divided up into
+the fewest individual exposures with equal exposure time that are less than
+this amount.  Note that by making the minimum and maximum times the same a
+fixed integration time can be defined.
+.le
+.ls units = "Angstroms" ("Angstroms") [spectrograph]
+Dispersion units for input and output dispersion coordinates.  The
+units syntax is described in the UNITS section.  The most common units
+are "Angstroms", "nm", "micron", and "wn".  Note that this does not
+apply to the dispersion units in the tables which are always in Angstroms.
+.le
+.ls skysub = "" (default based on context) [spectrograph]
+Type of sky and background subtraction.  The values are "none" for no
+background subtraction, "longslit" for subtraction using pixels in the
+aperture, "multiap" for background determined from a number of other
+apertures, and "shuffle" for shuffled observations.  The multiap case is
+typical for fiber spectrographs.  For shuffle the duty cycle is 50% and the
+exposure times are the sum of both sky and object.  If no sky or thermal
+background is specified then the default is "none".  If a fiber table or
+circular aperture is specified the default is "multiap" otherwise the
+default is "longslit".
+.le
+.ls nskyaps = 10  (10) [spectrograph]
+Number of sky apertures when using "multiap" sky subtraction.
+.le
+.ls subpixels = 1 (1) [spectrograph]
+Number of subpixels within each computed pixel.
+The dispersion pixel width is divided into this number of equal
+width subpixels.  The flux at the dispersions represented by the subpixels
+are computed and then summed to form the full pixel flux.  This option is used
+when there is structure in the tables, such as the sky and filter tables to
+simulate instrumental masking of sky lines, which is finer than a pixel
+dispersion width.
+.le
+.ls sensfunc = "" [spectrograph]
+Sensitivity function table.  This is a two column text file consisting
+of wavelength in Angstroms and sensitivity defined as
+2.5*(log(countrate)-log(flambda)),
+where countrate is the count rate (without extinction) in counts/s/A
+and flambda is the source flux in ergs/s/cm^2/A.  This table is used
+to compute an efficiency correction given a measurement of the
+sensitivity function from standard stars for the instrument.
+.le
+
+
+The following parameters control the output of the task.  The task
+always prints a result page at the central wavelength but additional
+graphical and text output may be produced at a set of equally spaced
+points across the size of the detector.
+.ls output = "object" ("") [spectrograph]
+List of quantities to output as graphs and/or in a text file.  These are
+given as a function of dispersion (as specified by units parameters)
+sampled across the dispersion coverage of the detector.  The choices are:
+.ls counts
+Object and background counts per individual exposure.
+.le
+.ls snr
+Signal-to-noise ratio per pixel per individual exposure.
+.le
+.ls object
+Object counts per individual exposure.  This includes contribution
+from other orders if there is no cross dispersion and the blocking
+filters do not completely exclude other orders.
+.le
+.ls rate
+Photons/second/A per individual exposure for the object and background.
+.le
+.ls atmosphere
+Percent transmission of the atmosphere.
+.le
+.ls telescope
+Percent transmission of the telescope.
+.le
+.ls adc
+Percent transmission of the ADC if one is used.
+.le
+.ls aperture
+Percent transmission of the aperture.
+.le
+.ls fiber
+Percent transmission of the fiber if one is used.
+.le
+.ls filter
+Percent transmission of the first filter if one is used.
+.le
+.ls filter2
+Percent transmission of the second filter if one is used.
+.le
+.ls collimator
+Percent transmission of the collimator.
+.le
+.ls disperser
+Percent efficiency of the disperser.
+.le
+.ls xdisperser
+Percent efficiency of the cross disperser if one is used.
+.le
+.ls corrector
+Percent transmission of the corrector if one is used.
+.le
+.ls camera
+Percent transmission of the camera.
+.le
+.ls detector
+Percent DQE of the detector.
+.le
+.ls spectrograph
+Percent transmission of the spectrograph if a transmission
+function is defined.
+.le
+.ls emissivity
+Emissivity of the telescope/spectrograph if an emissivity function
+is defined.
+.le
+.ls thruput
+Percent system thruput from telescope to detected photons.
+.le
+.ls sensfunc
+Sensitivity function values given as 2.5*(log(countrate)-log(flambda)),
+where countrate is the count rate (without extinction) in counts/s/A
+and flambda is the source flux in ergs/s/cm^2/A.
+.le
+.ls correction
+Multiplicative correction factor needed to convert the computed
+count rate to that given by an input sensitivity function.
+.le
+.ls ALL  
+All of the above.
+.le
+.le
+.ls nw = 101 (101) [spectrograph]
+Number of dispersion points to use in the output graphs and text
+file.  Note that this is generally less than the number of pixels in
+the detector for execution speed.
+.le
+.ls list = "" [spectrograph]
+Filename for list output of the selected quantities.  The output
+will be appended if the file already exists.
+.le
+.ls graphics = "stdgraph" ("stdgraph") [spectrograph]
+Graphics output device for graphs of the output quantities.
+.le
+.ls interactive = "yes" ("yes") [spectrograph]
+Interactive pause after each graph?  If "yes" then cursor input is
+enabled after each graph otherwise all the graphs will be drawn without
+pause.  When viewing the graphs interactively this should be "yes" otherwise
+the graphs will flash by rapidly leaving the last graph on the screen.
+When outputing only one graph or when redirecting the graphs to a
+printer or file then setting this parameter to "no" is suggested.
+.le
+
+The last parameter is a "parameter set" ("pset") containing all the
+spectrograph parameters.
+.ls specpars = ""
+Spectrograph parameter set.  If "" then the default pset \fBspecpars\fR
+is used otherwise the named pset is used.
+.le
+
+
+
+SPECPARS PARAMETERS
+.ls spectrograph = ""
+Spectrograph efficiency table.  This text file may contain parameters and an
+efficiency table.  The table consists of two columns containing
+wavelengths and efficiencies.  The efficiencies are for all elements
+which are not accounted for by other tables.
+.le
+.ls title = "" [spectrograph]
+Title for the spectrograph.
+.le
+.ls apmagdisp = INDEF (1.), apmagxdisp = INDEF (1.) [spectrograph]
+Magnification between the entrance aperture and the detector along and
+across the dispersion direction.  This describes any magnification (or
+demagnification) in the spectrograph other than that produced by the ratio
+of the collimator and camera focal lengths and anamorphic magnification
+from the disperser.  The may consist of actual magnification optics or
+projection effects such as tilted aperture plates (when the aperture size
+is specified in the untilted plate).
+.le
+.ls inoutangle = INDEF (INDEF) [spectrograph]
+Incident to diffracted grating angle in degrees for grating dispersers.
+For typical spectrographs which are not cross dispersed this is the
+collimator to camera angle.  If the value is INDEF derived from the grating
+parameters.
+.le
+.ls xinoutangle = INDEF (INDEF) [spectrograph]
+Incident to diffracted grating angle in degrees for grating cross
+dispersers.  If the value is INDEF it is derived from the grating
+parameters.
+.le
+
+
+.ls telescope = "" [spectrograph]
+Telescope efficiency table as a function of wavelength.  
+.le
+.ls teltitle = "" [telescope|spectrograph]
+Telescope title.
+.le
+.ls area = INDEF (1.) [telescope|spectrograph]
+Effective collecting area of the telescope in m^2.  The effective area
+includes reductions in the primary area due to obstructions.
+.le
+.ls scale = INDEF (10.) [telescope|spectrograph]
+Telescope plate scale, in arcsec/mm, at the entrance aperture of the
+spectrograph.
+.le
+.ls emissivity = "" [telescope|spectrograph]
+Emissivity table.  The emissivity is for all elements in the telescope
+and spectrograph.  If an emissivity is specified and an the \fIthermal\fR
+temperature parameter is greater than zero then a thermal background
+is added to the calculation.
+.le
+.ls emistitle = "" [emissivity|spectrograph]
+Title for the emissivity table used.
+.le
+
+
+.ls corrector = "" [spectrograph]
+Efficiency table for one or more correctors.
+.le
+.ls cortitle = "" [corrector|spectrograph]
+Title for corrector table used.
+.le
+.ls adc = "" [spectrograph]
+Efficiency table for atmospheric dispersion compensator.
+.le
+.ls adctitle = "" [adc|spectrograph]
+Title for ADC table used.
+.le
+
+
+.ls disperser = "" [spectrograph]
+Disperser table.  If this file contains an efficiency table it applies
+only to first order.  An alternate first order table and tables for
+other orders are given by table parameters "effN", where N is the order.
+.le
+.ls disptitle = "" [disperser|spectrograph]
+Title for disperser.
+.le
+.ls disptype = "" ("grating") [disperser|spectrograph]
+Type of disperser element.  The chocies are "grating", "grism", or "generic".
+The generic setting will simply use the desired central wavelength and
+dispersion without a grating or grism model.  One effect of this is that
+the mapping between detector pixel and wavelength is linear; i.e. a constant
+dispersion per pixel.
+.le
+.ls gmm = INDEF (300.) [disperser|spectrograph]
+Ruling in lines per mm.  If not specified it will be derived from the
+other disperser parameters.  If there is not enough information to
+derive the ruling then an ultimate default of 300 lines/mm is used.
+.le
+.ls blaze = INDEF (6.) [disperser|spectrograph]
+Blaze (grating) or prism (grism) angle in degrees.  If not specified it
+will be derived from the other disperser parameters.  If there is not
+enough information to derive the angle then an ultimate default of 6
+degrees is used.
+.le
+.ls oref = INDEF (1) [disperser|spectrograph]
+When a central (blaze) wavelength is specified this parameter indicates
+which order it is for.
+.le
+.ls wavelength = INDEF (INDEF) [disperser|spectrograph]
+Central (blaze) wavelength in Angstroms for the reference order.  This
+parameter only applies to gratings.  If it is not specified it will
+be derived from the other disperser parameters.
+.le
+.ls dispersion = INDEF (INDEF) [disperser|spectrograph]
+Central dispersion in A/mm for the reference order.  This parameter only
+applies to gratings.  If it is not specified it will be derived from the
+other disperser parameters.
+.le
+.ls indexref = INDEF (INDEF) [disperser|spectrograph]
+Grism index of refraction for the reference order.  This parameter only
+applies to grisms.  If it is not specified it will be derived from
+the other disperser parameters.
+.le
+.ls eff = INDEF (1.) [disperser|spectrograph]
+Peak efficiency for the theoretical disperser efficiency function.
+When an efficiency table is not specified then a theoretical efficiency
+is computed for the disperser.  This theoretical efficiency is scaled
+to peak efficiency given by this parameter.
+.le
+
+
+.ls xdisperser = "" [spectrograph]
+Crossdisperser table.  If this file contains an efficiency table it applies
+only to first order.  An alternate first order table and tables for
+other orders are given by table parameters "xeffN", where N is the order.
+.le
+.ls xdisptitle = "" [xdisperser|spectrograph]
+Title for crossdisperser.
+.le
+.ls disptype = "" ("grating") [xdisperser|spectrograph]
+Type of crossdisperser element.  The chocies are "", "grating", "grism",
+or "generic".  The empty string eliminates use of a cross disperser.
+The generic setting will simply use the desired central wavelength and
+dispersion without a grating or grism model.  One effect of this is that
+the mapping between detector pixel and wavelength is linear; i.e. a constant
+dispersion per pixel.
+.le
+.ls gmm = INDEF (INDEF) [xdisperser|spectrograph]
+Ruling in lines per mm.  If not specified it will be derived from the
+other crossdisperser parameters.
+.le
+.ls xblaze = INDEF (6.) [xdisperser|spectrograph]
+Blaze (grating) or prism (grism) angle in degrees.  If not specified it
+will be derived from the other crossdisperser parameters.
+.le
+.ls xoref = INDEF (1) [xdisperser|spectrograph]
+When a central (blaze) wavelength is specified this parameter indicates
+which order it is for.
+.le
+.ls xwavelength = INDEF (INDEF) [xdisperser|spectrograph]
+Central (blaze) wavelength in Angstroms for the reference order.  This
+parameter only applies to gratings.  If it is not specified it will
+be derived from the other crossdisperser parameters.
+.le
+.ls xdispersion = INDEF (INDEF) [xdisperser|spectrograph]
+Central dispersion in A/mm for the reference order.  This parameter only
+applies to gratings.  If it is not specified it will be derived from the
+other crossdisperser parameters.
+.le
+.ls xindexref = INDEF (INDEF) [xdisperser|spectrograph]
+Grism index of refraction for the reference order.  This parameter only
+applies to grisms.  If it is not specified it will be derived from
+the other crossdisperser parameters.
+.le
+.ls xeff = INDEF (1.) [xdisperser|spectrograph]
+Peak efficiency for the theoretical crossdisperser efficiency function.
+When an efficiency table is not specified then a theoretical efficiency
+is computed for the crossdisperser.  This theoretical efficiency is scaled
+to peak efficiency given by this parameter.
+.le
+
+
+.ls aperture = "" (default based on context) [spectrograph]
+Aperture table.  The text file gives aperture thruput as a function of the
+aperture size in units of seeing FWHM.  For rectangular apertures there are
+two independent variables corresponding to the width and length while for
+circular apertures there is one independent variable corresponding to the
+diameter.  If not specified a default table is supplied.  If a fiber table
+or a diameter is specified then the table "circle" is used otherwise the
+table "slit" is used.  Because "sptimelib$" is the last directory searched
+there are default files with these names in this directory for Gaussian
+seeing profiles passing through a circular or slit aperture.
+.le
+.ls aptitle = "" [aperture|spectrograph]
+Title for aperture used.
+.le
+.ls aptype = "" (default based on context) [aperture|spectrograph]
+The aperture types are "rectangular" or "circular".  If the
+parameter is not specified then if the aperture table has two columns the
+type is "circular" otherwise it is "rectangular".
+.le
+
+
+.ls fiber = "" [spectrograph]
+Fiber transmission table.  The transmission is a function of wavelength
+in Angstroms.  If no fiber transmission is specified then no fiber
+component is included.
+.le
+.ls fibtitle = "" [fiber|spectrograph]
+Title for fiber transmission used.
+.le
+
+
+.ls filter = "" [spectrograph]
+Filter transmission table.  The transmission is a function of wavelength
+in Angstroms.  If no filter transmission is specified then no filter
+component is included.
+.le
+.ls ftitle = "" [filter|spectrograph]
+Title for filter transmission used.
+.le
+.ls filter2 = "" [spectrograph]
+Filter transmission table.  The transmission is a function of wavelength
+in Angstroms.  If no filter transmission is specified then no filter
+component is included.
+.le
+.ls f2title = "" [filter|spectrograph]
+Title for filter transmission used.
+.le
+.ls block = "" ("no") [filter|spectrograph]
+If "yes" then no check will be made for other orders.
+.le
+
+
+.ls collimator = "" (1.) [spectrograph]
+Collimator transmission table.  The transmission is a function of
+wavelength in Angstroms.  If no collimator is specified then a unit
+transmission is used.
+.le
+.ls coltitle = "" [collimator|spectrograph]
+Title for collimator.
+.le
+.ls colfl = INDEF (1.) [collimator|spectrograph]
+Collimator focal length in meters.  The ratio of the collimator to camera
+focal lengths determines the magnification between the aperture and the
+detector.
+.le
+
+.ls camera = "" (1.) [spectrograph]
+Camera transmission table.  The transmission is a function of wavelength
+in Angstroms.  If no camera is specified then a unit transmission
+is used.
+.le
+.ls camtitle = "" [camera|spectrograph]
+Title for camera.
+.le
+.ls camfl = "" (1.) [camera|spectrograph]
+Camera focal length in meters.  The ratio of the collimator to
+camera focal lengths determines the magnification between the aperture
+and the detector.  The camera focal length also determines the dispersion
+scale at the detector.
+.le
+.ls resolution = "" (2 pixels) [camera|spectrograph]
+Camera resolution on the detector in mm.
+.le
+.ls vignetting = "" (1.) [camera|spectrograph]
+Vignetting table.  The independent variable is distance from the center
+of the detector in mm.  The value is the fraction the light transmitted.
+If no vignetting table is specified then no vignetting effect is applied.
+.le
+
+
+.ls detector = "" (1.) [spectrograph]
+Detector DQE table.  The DQE is a function of wavelength in Angstroms.
+.le
+.ls dettitle = "" [detector|spectrograph]
+Title for detector.
+.le
+.ls ndisp = INDEF (2048) [detector|spectrograph]
+Number of pixels along the dispersion.
+.le
+.ls pixsize = INDEF (0.02) [detector|spectrograph]
+Pixel size (assumed square) in mm.
+.le
+.ls gain = INDEF (1.) [detector|spectrograph]
+The conversion between photons and detector data numbers or counts.
+This is given as photons/ADU where ADU is analog-to-digital unit.
+.le
+.ls rdnoise = INDEF (0.) [detector|spectrograph]
+Readout noise in photons.
+.le
+.ls dark = INDEF (0.) [detector|spectrograph]
+Dark count rate in photons/s.
+.le
+.ls saturation = INDEF [detector|spectrograph]
+Number of detected photons in a pixel resulting in saturation.
+The default is no saturation.  The time per exposure will be reduced,
+but no lower than the minimum time per exposure,
+and the number of exposures increased to try and avoid saturation.
+.le
+.ls dnmax = INDEF [detector|spectrograph]
+Maximum data number or ADU allowed.  The default is no maximum.
+The time per exposure will be reduced,
+but no lower than the minimum time per exposure,
+and the number of exposures increased to try and avoid overflow.
+.le
+.ls xbin = 1 (1) [detector|spectrograph]
+Detector binning along the dispersion direction.
+.le
+.ls ybin = 1 (1) [detector|spectrograph]
+Detector binning along the spatial direction.
+.le
+.ih
+DISCUSSION
+
+
+OVERVIEW
+
+The spectroscopic exposure time package, \fBSPECTIME\fR, consists of a
+general calculation engine, \fBSPTIME\fR, and a collection of user or
+database defined IRAF scripts.  The scripts are one type of user interface
+for \fBSPTIME\fR.  Other user interfaces are Web-based forms and IRAF
+graphics/window applications.  The user interfaces customize the general
+engine to specific spectrographs by hiding components and parameters not
+applicable to that spectrograph and guiding the user, through menus or
+other facilities, in the choice of filters, gratings, etc.  However,
+\fBSPTIME\fR is a standard IRAF task that can be executed directly.
+
+\fBSPTIME\fR takes an input source spectrum (either a reference blackbody,
+a power law, or a user spectrum), a background "sky" spectrum and a
+instrumental thermal background, reddening to apply to the spectrum,
+observing parameters such as exposure time, central wavelength, seeing,
+airmass, and moon phase, instrument parameters such as aperture sizes and
+detector binning, a description of the spectrograph, and produces
+information about the expected signal and signal-to-noise ratio in the
+extracted one-dimensional spectrum.  The output consists of a description
+of the observation, signal-to-noise statistics, and optional graphs and
+tables of various quantities as a function of wavelength over the
+spectrograph wavelength coverage.
+
+\fBSPTIME\fR models a spectroscopic system as a flow of photons from a
+source to the detector through various optical components.  Background
+photons from the sky, atmosphere, and the thermal emission from the
+telescope and spectrograph are added.  It then computes signal-to-noise
+ratios from the detected photons of the source and background and the
+instrumental noise characteristics.  The spectroscopic system components
+are defined at a moderate level of detail.  It is not so detailed that
+every optical element has to be described and modeled and not so coarse
+that a single throughput function is used (though one is free to put all
+the thruput information into one component).  Not all components modeled by
+the task occur in all spectroscopic systems.  Therefore many of the
+components can be left out of the calculation.
+
+The components currently included in \fBSPTIME\fR are:
+
+.nf
+    - the atmosphere (extinction and IR transmission)
+    - the telescope (all elements considered as a unit)
+    - an optional atmospheric dispersion compensator
+    - the entrance aperture (slits, fibers, masks, etc.)
+    - an optional fiber feed
+    - a spectrograph (for components not represented elsewhere)
+    - filters
+    - a collimator
+    - a disperser (grating, grism, prism, etc)
+    - a optional cross disperser (grating, grism, prism, etc)
+    - a corrector (either in the telescope of spectrograph)
+    - a camera
+    - a detector
+.fi
+
+Each of these components represent a transmission function specifying the
+fraction of incident light transmitted or detected as a function of some
+parameter or parameters.  Except for the aperture, which is a function of
+the incident source profile (typically the seeing profile) relative to the
+aperture size, the transmissions of the components listed above are all
+functions of wavelength.
+
+All the component transmission functions may be specified as either numeric
+values or as tables.  A numeric value is considered to be a special type of
+table which has the same value at all values of the independent parameters.
+By specifying only numeric values the task may be run without any table
+files.  To obtain information at a single wavelength this is all that is
+needed.
+
+To specify a dependence on wavelength or other parameter a text file table
+with two or more columns may be specified.  The tables are interpolated in
+the parameter columns to find the desired value in the last column.  The
+tables are searched for in the current directory and then in a list of user
+specified directories.  Thus, users may place files in their work area to
+override system supplied files and observatories can organize the data
+files in a database directory tree.
+
+In addition to transmission or DQE functions the spectrograph is described
+by various parameters.  All the parameters are described in the PARAMETERS
+section.  For flexibility parameters may be defined either in the
+parameter set or in one or more table files.  In all cases the parameter
+set values have precedence.   But if the values are "" for string  parameters
+or INDEF for numeric parameters the values are found either in the
+spectrograph table or in a table that is associated with the parameter.
+
+Therefore table files provide for interchangeable components, each with
+their own transmission curves, and for organizing parameters for different
+instruments.  Note that a table file may contain only parameters, only
+a table, or both.
+
+There is also another way to maintain a separate file for different
+instruments.  The \fIspecpars\fR parameter is a "parameter set" or "pset".
+The default value of "" corresponds to the pset task \fBspecpars\fR.
+However, using \fBeparam\fR one can edit this pset and then save the
+parameters to a named parameter file with ":e <name>.par".  This
+pset can be edited with \fBeparam\fR and specified in the
+\fIspecpars\fR parameter.  One other point about pset parameters is that
+they can also be included as command line arguments just as any other
+parameter in the main task parameters.
+
+Many spectrographs provide a wide variety of wavelength regions and
+dispersions.  For gratings (and to some extent for grisms) this means use
+of different gratings, orders, tilts, and possibly camera angles in the
+spectrograph.  The transmission as a function of wavelength (the grating
+efficiency) changes with these different setups.  If the transmission
+function is given as an interpolation table this would require data files
+for each setup of each disperser.  The structure of \fBSPTIME\fR allows
+for this.
+
+However, it is also possible to specify the grating and spectrograph
+parameters and have the task predict the grating efficiency in any
+particular setup.  In many cases it may be easier to use the calculated
+efficiencies rather than measure them.  Depending on the level of accuracy
+desired this may be adequate or deviations from the analytic blaze function
+can be accounted for in another component.
+
+
+TABLES
+
+\fBSPTIME\fR uses text files to provide parameters and interpolation
+tables.  The files may contain comments, parameters, and tables.
+
+Comment lines begin with '#' and may contain any text.  They can occur
+anywhere in the file, though normally they are at the beginning of the file.
+
+Parameters are comment lines of the form
+
+.nf
+    # [parameter] = [value]
+.fi
+
+where whitespace is required between each field, [parameter] is a single
+word parameter name, and [value] is a single word value.  A quoted string
+is a single word so if the value field contains whitespace, such as in
+titles, it must be quoted.  Any text following the value is ignored and may
+be used for units (not read or used by the program) or comments.
+
+The parameters are those described in the PARAMETERS section.  The tables
+in which the parameters may be included are identified in that section
+in the square brackets.  Note that it is generally true that any parameter
+may appear in the spectrograph table.
+
+The table data is a multicolumn list of numeric values.  The list must be
+in increasing order in the independent columns.  Only 1D (two columns) and
+2D (three columns) tables are currently supported.  2D tables must form a
+regular grid.  This means that any particular value from column one must
+occur for all values of column 2 and vice versa.   The table is
+interpolated as needed.  The interpolation is linear or bi-linear.
+Extrapolation outside of the table consists of the taking the nearest
+value; thus, a single line may be used to define a constant value for all
+values of the independent variable(s).
+
+Normally the table values, the dependent variable in the last column, are
+in fractional transmission or DQE.  There is a special parameter,
+"tablescale", which may be specified to multiply the dependent variable
+column.  This would mainly be used to provide tables in percent rather
+than fraction.
+
+The independent variable columns depend on the type of table.  Most tables
+are a function of wavelength.  Currently wavelengths must be in Angstroms.
+
+The types of tables and the units of the columns are listed below.
+
+.nf
+        spectrum - Angstroms ergs/s/cm^2/A
+             sky - Angstroms ergs/s/cm^2/A/arcsec^2
+      extinction - Angstroms mag/airmass
+    spectrograph - Angstroms transmission
+       telescope - Angstroms transmission
+      emissivity - Angstroms emissivity
+             adc - Angstroms transmission
+           fiber - Angstroms transmission
+      collimator - Angstroms transmission
+          filter - Angstroms transmission
+       disperser - Angstroms transmission
+      xdisperser - Angstroms transmission
+       corrector - Angstroms transmission
+          camera - Angstroms transmission
+        detector - Angstroms transmission
+     sensitivity - Angstroms 2.5*(log(countrate)-log(flambda)),
+
+             sky - Angstroms moonphase ergs/s/cm^2/A/arcsec^2
+        aperture - diameter/FWHM transmission
+        aperture - width/FWHM length/FWHM transmission
+      vignetting - mm transmission
+.fi
+
+The disperser and crossdisperser files have an additional feature to allow
+for efficiency curves at different orders.  The parameter "effN" (or "xeffN
+for crossdispersers), where N is the order, may be specified whose value is
+a separate table (or constant).  If there is no "eff1/xeff1" (efficiency in
+first order) then any efficiency table in the disperser table is used.  In
+other words, any table in the disperser file applies only to first order
+and only if there is no "eff1/xeff1" parameter defining a separate first
+order efficiency file.
+
+DISPERSION UNITS
+
+The output results, text file, and graphs are presented in dispersion
+units defined by the \fIunits\fR parameter.  In addition the \fIwave\fR
+and \fIrefwave\fR input parameters are specified in the selected units.
+All other dispersion values must currently be specified in Angstroms.
+
+The dispersion units are specified by strings having a unit type from the
+list below along with the possible preceding modifiers, "inverse", to
+select the inverse of the unit and "log" to select logarithmic units. For
+example "log angstroms" to select the logarithm of wavelength in Angstroms
+and "inv microns" to select inverse microns.  The various identifiers may
+be abbreviated as words but the syntax is not sophisticated enough to
+recognize standard scientific abbreviations except for those given
+explicitly below.
+
+.nf
+	   angstroms - Wavelength in Angstroms
+	  nanometers - Wavelength in nanometers
+	millimicrons - Wavelength in millimicrons
+	     microns - Wavelength in microns
+	 millimeters - Wavelength in millimeters
+	  centimeter - Wavelength in centimeters
+	      meters - Wavelength in meters
+	       hertz - Frequency in hertz (cycles per second)
+	   kilohertz - Frequency in kilohertz
+	   megahertz - Frequency in megahertz
+	    gigahertz - Frequency in gigahertz
+	         m/s - Velocity in meters per second
+	        km/s - Velocity in kilometers per second
+	          ev - Energy in electron volts
+	         kev - Energy in kilo electron volts
+	         mev - Energy in mega electron volts
+
+	          nm - Wavelength in nanometers
+	          mm - Wavelength in millimeters
+	          cm - Wavelength in centimeters
+	           m - Wavelength in meters
+	          Hz - Frequency in hertz (cycles per second)
+	         KHz - Frequency in kilohertz
+	         MHz - Frequency in megahertz
+	         GHz - Frequency in gigahertz
+		  wn - Wave number (inverse centimeters)
+.fi
+
+The velocity units require a trailing value and unit defining the
+velocity zero point.  For example to transform to velocity relative to
+a wavelength of 1 micron the unit string would be:
+
+.nf
+	km/s 1 micron
+.fi
+
+
+CALCULATIONS
+
+This section describes the calculations, and assumptions behind the
+calculations, performed by \fBSPTIME\fR.  These include the dispersion and
+efficiencies of gratings and grisms, the dispersion resolution, the spatial
+resolution and how it applies to the number of object and sky pixels in the
+apertures, the object and sky detected photons/counts, the signal-to-noise
+ratio , and the exposure time for a given S/N.
+
+
+Gratings
+
+Gratings are assumed to tilted only around the axis parallel to the
+groves and with the incident angle greater than the blaze angle.  The
+grating equation is then
+
+.nf
+    g * m * w = sin(tilt+phi/2) + sin(beta)
+.fi
+
+where g is the number of groves per wavelength unit, m is the order, w is
+the wavelength, tilt is the grating tilt measured from the grating normal,
+phi is the angle between the incident and diffracted rays, and beta is the
+diffracted angle.  Phi is a spectrograph parameter and g is a grating
+parameter.  At the desired central wavelength beta is tilt-phi/2 and at the
+blaze peak it is 2*blaze-tilt-phi/2 where blaze is the blaze angle.
+
+The tilt is computed from the desired central wavelength.  It is
+also used to compute the grating magnification
+
+.nf
+    magnification = cos(tilt-phi/2) / cos(tilt+phi/2)
+.fi
+
+which is used in calculating the projected slit size at the detector.
+This number is less than zero so the aperture is actually demagnified.
+
+The dispersion, treated as constant over the spectrum for the sake of
+simplicity, is given by the derivative of the grating equation at
+the blaze peak,
+
+.nf
+    dispersion = cos(blaze-phi/2) / (g * m * f)
+.fi
+
+where f is the camera focal length.
+
+The grating efficiency or blaze function is computed as described by
+Schroeder and Hilliard (Applied Optics, vol 19, 1980, p. 2833).  The
+requirements on the grating noted previously correspond to their case A.
+As they show, use of incident angles less than the blaze angle, their case
+B, significantly degrades the efficiency due to back reflection which is
+why this case is not included.  The efficiency formulation includes
+variation in the peak efficiency due light diffracted into other orders,
+shadowing of the groves, and a reflectance parameter.  The reflectance
+parameter is basically the blaze peak normalization and does not currently
+include a wavelength dependence.  Thus the peak efficiency is near the
+reflectance value but somewhat lower and is order dependent due to the other
+effects.
+
+
+Grisms
+
+Grisms are assumed to have a prism angle equal to the blaze angle of
+the inscribed grating.  The index of refraction is treated as constant
+over the wavelength range of an order, though different index of refraction
+values can be specified for each order.
+
+The grism formula used is a variation on the grating equation.
+
+.nf
+    g * m * w = n * sin (theta+prism) - sin (beta+prism)
+.fi
+
+where n is the index of refraction, prism is the prism or blaze angle,
+theta is the incident angle relative to the prism face, and beta is the
+refracted angle relative to the prism face.  Theta and beta are defined so
+that at the undeviated wavelength they are zero.  In other words at the
+undeviated wavelength the light path is a straight through transmission.
+
+The efficiency is also computed in an analogous manner to the
+reflection grating except that shadowing is not included (a consequence of
+the blaze face being parallel to the prism face and theta being near
+zero).  Instead of a reflectance value normalizing the blaze function a
+transmission value is used.
+
+
+Scales and Sizes
+
+The scale between arc seconds on the sky and millimeters at the
+aperture(s) of the spectrograph is specified by the \fIscale\fR parameter.
+This parameter is used to convert aperture sizes between arc seconds and
+millimeters.
+
+The aperture sizes are magnified or demagnified by three possible factors.
+The basic magnification is given by the ratio of the collimator focal
+length to the camera focal length.  This magnification applies both along
+and across the dispersion.
+
+The camera focal length also determines the dispersion scale on the detector.
+It converts radians of dispersion to mm at the detector.
+
+For grating dispersers there is a demagnification along the dispersion
+due to the tilt of the grating(s).  The demagnification is computed (as
+given previously) from the grating parameters and the spectrograph
+parameter giving the angle between the incident and diffracted rays at the
+detector center.
+
+The last magnification factor is given by the spectrograph parameters
+"apmagdisp" and apxmagdisp".  These define magnifications of the aperture
+along and across the dispersion apart from the other two magnifications.
+These parameters are often missing which means no additional
+magnifications.
+
+One use for the last magnification parameters is to correct aperture
+sizes given as millimeters or arc seconds on a plane tilted with respect to
+the focal plane.  Such tilted apertures occur with aperture mechanisms
+(usually slits) that reflect light for acquisition and guiding.  Note that
+one only needs to use these terms if users are expected to define the
+apertures sizes on the tilted plane.  If instead the projection factors are
+handled by the spectrograph system and users specify aperture size as
+millimeters or arc seconds on the sky then these terms are not needed.
+
+The above scale factors map arc seconds on the sky and aperture sizes
+in millimeter to arc seconds and millimeters projected on the detector.  To
+convert to pixels on the detector requires the pixel size.
+One option in \fBSPTIME\fR is to specify aperture
+sizes as projected pixels on the detector (either in the user parameters or
+in the aperture description file).  Using the detector pixel size and the
+scale factors allows conversion of aperture sizes specified in this way
+back to the actual aperture size.
+
+
+Resolution
+
+A camera resolution parameter may be set in the camera description.  If
+a resolution value is not given it is taken to be 2 pixels.  This parameter
+is used to define the dispersion resolution element and the number of
+pixels across the dispersion imaged by the detector for the aperture and
+the object.  The latter usage is discussed in the next section.
+
+The dispersion resolution element, in pixels, is given by
+
+.nf
+				 |  2 pixels
+    disp resolution = maximum of |  camera resolution
+				 |  1 + min (seeing, apsize)
+.fi
+
+where seeing is the FWHM seeing diameter in pixels and apsize is the
+aperture size in pixels.  For circular apertures the aperture size is
+the diameter and for rectangular apertures it is the width.  The first term
+comes from sampling considerations, the second from the camera resolution,
+and the third from the finite resolution of a pixel (the factor of 1) and
+the spread of wavelengths across the aperture or seeing disk.  The
+dispersion resolution is printed for information and the S/N per dispersion
+resolution element is given in addition to the per pixel value.
+
+
+Object and Sky Pixels Across the Dispersion
+
+The number of pixels across the dispersion in the object and the sky
+are required to compute the S/N statistics.  The number of pixels
+in the projected aperture image is taken to be
+
+.nf
+		       | diameter + resolution  (circular apertures)
+    aperture pixels =  |
+		       | length + resolution    (rectangular apertures)
+.fi
+
+where resolution is the camera resolution discussed previously.  The value
+is rounded up to an integer.
+
+Objects are assumed to fill circular (fiber) apertures.  Therefore the
+number of object pixels is the same as the number of pixels in the
+aperture.  In rectangular (slit) apertures the number of object pixels is
+taken to be
+
+.nf
+				| 3*seeing + resolution
+    object pixels = minimum of  |
+				| number of aperture pixels
+.fi
+
+where seeing is the FWHM seeing diameter converted to pixels.  The values
+are rounded up to an integer.
+
+The number of sky pixels depends on the type of sky subtraction.
+For "longslit" sky subtraction the number of sky pixels is given
+by the difference of the number of aperture pixels and the number of
+object pixels.  For circular apertures this always comes out to zero so
+it does not make sense to use longslit sky subtraction.  For rectangular
+apertures the number of sky pixels in the aperture depends on the
+aperture size and the seeing.  If the number of sky pixels comes out to
+zero a warning is printed.
+
+For "multiap" sky subtraction the number of sky pixels is the
+number of sky apertures times the number of pixels per aperture.
+
+
+Source Counts
+
+The source spectrum flux at each wavelength, either given in a spectrum
+table or as a model distribution, is in units of
+photons per second per Angstrom per square centimeter.  This is multiplied
+by the telescope effective area, the exposure time, and the pixel size in
+Angstroms to give the source photons per dispersion pixel per exposure.
+This is then multiplied by any of the following terms that apply to arrive
+at the number of source photons detected over all spatial pixels.  The
+spatial integration is implicit in the aperture function.
+
+.nf
+    - the extinction using the specified airmass
+    - the telescope transmission
+    - the ADC transmission
+    - the aperture transmission based on the aperture size relative
+      to the seeing
+    - the fiber transmission
+    - the filter transmission (one or two filters)
+    - the collimator transmission
+    - the disperser efficiency (one or two dispersers)
+    - the corrector transmission
+    - the camera transmission
+    - the detector DQE
+.fi
+
+
+Background Counts
+
+The sky or atmospheric background spectrum, if one is given, defines a
+photon flux per square arc second.  When it is given as a function of the
+moon phase it is interpolated to the specified moon phase.  In addition
+if a thermal temperature and an emissivity are given then a thermal
+background is computed and added to the sky/atmospheric background.
+
+The surface brightness of the background is multiplied by the area of the
+aperture occupied by the object (in arc seconds) and divided by the
+aperture transmission of the source.  This is the quantity reported in the
+output for the sky photon flux.  It is comparable to the source photon
+flux.
+
+Next this flux is multiplied by the telescope effective area, the
+exposure time, and the pixel size in Angstroms.  Finally it is multiplied
+by the same transmission terms as the object except for the extinction.
+Note that this removes the aperture transmission term included earlier
+giving the background photons as the number passing through the aperture per
+object profile.  The final value is the number of background photons from the
+object.  To get the background photons per spatial pixel the value is divided by
+the number of spatial pixels occupied by the source.
+
+If no background subtraction is specified then the background counts are added
+to the source counts to define the final source counts and the background
+counts are set to zero.
+
+
+Signal-to-Noise Ratio
+
+The noise attributed to the source and background is based on Poisson
+statistics; namely the noise is the square root of the number of photons.
+The detector noise is given by a dark count component and a readout noise
+component.  The noise from the dark counts is obtain by multiplying the
+dark count rate by the exposure time and the number of spatial pixels used
+in extracting the source and taking the square root.  The readout noise is
+the detector readout noise parameter multiplied by the square root of the
+number of spatial source pixels.
+
+If background subtraction is selected and the number of available
+background pixels is greater than zero then the uncertainty in the
+background estimation is computed.  The uncertainty in a single pixel is
+the square root of the background photons per pixel, the dark counts per
+pixel, and the readout noise per pixel.  This is divided by the square root
+of the number of background pixels to get the uncertainty in the background
+estimation for subtraction from the source.
+
+The total noise is the combination of the source, background, dark count,
+and readout noise values and the background subtraction uncertainty added
+in quadrature.
+
+The signal-to-noise ratio per pixel per exposure is the source counts
+divided by total noise.  This value is multiplied by the square root of
+number of pixels per resolution element to get the S/N per resolution
+element.  If multiple exposures are used to make up the total exposure time
+then the single exposure S/N is multiplied by the square root of the number
+of exposures.
+
+
+Exposure Time From Signal-to-Noise Ratio
+
+If no exposure time is specified, that is a value of INDEF, then
+the exposure time required to reach a desired signal-to-noise ratio
+per pixel is determined.  The computation is done at the specified central
+wavelength.  The task iterates, starting with the specified maximum time per
+exposure, by computing the S/N and adjusting the exposure time
+(possibly breaking the total exposure up into subexposures) until
+the computed S/N matches the desired S/N to 0.1%.
+
+In addition to breaking the exposure time into individual exposure less
+than the maximum per exposure, the task will break single exposures that
+exceed the specified saturation and maximum data number values at the
+reference wavelength.  If other wavelengths are then saturated or exceed
+the data maximum a warning is printed.
+.endhelp
diff --git a/noao/obsutil/src/doc/starfocus.hlp b/noao/obsutil/src/doc/starfocus.hlp
new file mode 100644
index 00000000..351bf14c
--- /dev/null
+++ b/noao/obsutil/src/doc/starfocus.hlp
@@ -0,0 +1,820 @@
+.help starfocus Nov01 noao.obsutil
+.ih
+NAME
+starfocus -- Measure focus variations using stellar images
+.ih
+USAGE
+starfocus images
+.ih
+PARAMETERS
+.ls images
+List of images.  The images may be either taken at a sequence
+of focus values or be multiple shifted exposures at a sequence of
+focus settings.
+.le
+.ls focus = "1x1"
+If the parameter \fIfstep\fR is not set (a "" null string) then this
+parameter is interpreted as either a list of focus values or an
+image header keyword to one focus value per image.  A list may be an explicit
+list of values, a range specification, or an @ file containing the values.
+If there is only a single exposure per image then the focus list gives one
+value per image while if there are multiple exposures per image the list
+applies to the multiple exposures with the same values reused for other
+images.  If the parameter \fIfstep\fR is given then this parameter is
+interpreted as a single starting focus value and the focus step
+defines the increment between subsequent single exposure images or
+for the various exposures in a multiple exposure image.
+.le
+.ls fstep = ""
+A focus increment value or an image header keyword to the focus increment.
+.le
+
+.ls nexposures = "1"
+The number of exposures per image specified either as a value or as
+an image header keyword.  A double step gap in a multiple
+exposure sequence does not count as an exposure.
+.le
+.ls step = "30."
+The step in pixels between exposures specified either as a value or
+as an image header keyword.
+.le
+.ls direction = "-line" (-line|+line|-column|+column)
+The direction of the exposure sequence in the image.  The values are
+"-line" for successive object images appearing at smaller line numbers,
+"+line" for objects appearing at larger line numbers, "-column" for
+objects appearing at smaller column numbers, and "+column" for objects
+appearing at larger column numbers.
+.le
+.ls gap = "end" (none|beginning|end)
+Location of a double step gap in a sequence with the specified direction.
+The available cases are "none" for an even sequence with no gap,
+"beginning" where a double step is taken between the first and
+the second exposure, and "end" where a double step is taken before
+the last exposure.  Note that "beginning" and "end" are defined in
+terms of the \fIdirection\fR parameter.
+.le
+
+.ls coords = "mark1" (center|mark1|markall)
+Method by which the coordinates of objects to be measured are specified.
+If "center" then a single object at the center of each image is measured.
+If "mark1" then the \fIimagecur\fR parameter, typically the interactive
+image display cursor, defines the coordinates of one or more objects in the
+first image ending with a 'q' key value and then the same coordinates are
+automatically used in subsequent images.  If "markall" then the
+\fIimagecur\fR parameter defines the coordinates for objects in each image
+ending with a 'q' key value.
+.le
+.ls wcs = "logical" (logical|physical|world)
+Coordinate system for input coordinates.  When using image cursor input
+this will always be "logical".  When using cursor input from a file this
+could be "physical" or "world".
+.le
+.ls display = yes, frame = 1
+Display the image or images as needed?  If yes the image display is checked
+to see if the image is already in one of the display frames.  If it is not
+the \fBdisplay\fR task is called to display the image in the frame
+specified by the \fBframe\fR parameter.  All other display parameters are
+taken from the current settings of the task.  This option requires that the
+image display be active.  A value of no is typically used when an input
+cursor file is used instead of the image display cursor.  An image display
+need not be active in that case.
+.le
+
+.ls level = 0.5
+The parameter used to quantify an object image size is the radius from the
+image center enclosing the fraction of the total flux given by this
+parameter.  If the value is greater than 1 it is treated as a percentage.
+.le
+.ls size = "FWHM" (Radius|FWHM|GFWHM|MFWHM)
+There are four ways the PSF size may be shown in graphs and given in
+the output.  These are:
+
+.nf
+    Radius - the radius enclosing the specified fraction of the flux
+    FWHM   - a direct FWHM from the measured radial profile
+    GFWHM  - the FWHM of the best fit Gaussian profile
+    MFWHM  - the FWHM of the best fit Moffat profile
+.fi
+
+The labels in the graphs and output will be the value of this parameter
+to distinguish the different types of size measurements.
+.le
+.ls beta = INDEF
+For the Moffat profile fit (size = MFWHM) the exponent parameter may
+be fixed at a specified value or left free to be determined from the
+fit.  The exponent parameter is determined by the fit if \fIbeta\fR
+task parameter is INDEF.
+.le
+.ls scale = 1.
+Pixel scale in user units per pixel.  Usually the value is 1 to measure
+sizes in pixels or the image pixel scale in arc seconds per pixel.
+.le
+.ls radius = 5., iterations = 2
+Measurement radius in pixels and number of iterations on the radius.  The
+enclosed flux profile is measured out to this radius.  This radius may be
+adjusted if the \fIiteration\fR parameter is greater than 1.  In that case
+after each iteration a new radius is computed from the previous FWHM
+estimate to be the radius the equivalent gaussian enclosing 99.5% of the
+light.  The purpose of this is so that if the initial PSF size of the image
+need not be known.  However, the radius should then be larger than true
+image size since the iterations best converge to smaller values.
+.le
+.ls sbuffer = 5, swidth = 5.
+Sky buffer and sky width in pixels.  The buffer is added to the specified
+measurement \fIradius\fR to define the inner radius for a circular sky
+aperture.  The sky width is the width of the circular sky aperture.
+.le
+.ls saturation=INDEF, ignore_sat=no
+Data values (prior to sky subtraction) to be considered saturated within
+measurement radius.  A value of INDEF treats all pixels as unsaturated.  If
+a measurement has saturated pixels there are two actions.  If
+\fIignore_sat\fR=no then a warning is given but the measurement is saved
+for use.  The object will also be indicated as saturated in the output
+log.  If \fIignore_sat\fR=yes then a warning is given and the object is
+discarded as if it was not measured.  In a focus sequence only the
+saturated objects are discarded and not the whole sequence.
+.le
+.ls xcenter = INDEF, ycenter = INDEF
+The optical field center of the image given in image pixel coordinates.
+These values need not lie in the image.  If INDEF the center of the image
+is used.  These values are used to make plots of size verse distance from
+the field center for studies of radial variations.
+.le
+.ls logfile = "logfile"
+File in which to record the final results.  If no log file is desired a
+null string may be specified.
+.le
+
+.ls imagecur = ""
+Image cursor input for the "mark1" and "markall" options.  If null then the
+image dispaly cursor is used interactively.  If a file name is specified
+then the coordinates come from this file.  The format of the file are lines
+of x, y, id, and key.  Values of x an y alone may be used to select objects
+and the single character 'q' (or the end of the file) may be used to end
+the list.
+.le
+.ls graphcur = ""
+Graphics cursor input.  If null then the standard graphics cursor
+is used otherwise a standard cursor format file may be specified.
+.le
+.ih
+CURSOR COMMANDS
+When selecting objects with the image cursor the following commands are
+available.
+
+.nf
+?  Page cursor command summary
+g  Measure object and graph the results.
+m  Measure object.
+q  Quit object marking and go to next image.
+   At the end of all images go to analysis of all measurements.
+
+:show  Show current results.
+.fi
+
+When in the interactive graphics the following cursor commands are available.
+All plots may not be available depending on the number of focus values and
+the number of stars.
+
+.nf
+?  Page cursor command summary
+a  Spatial plot at a single focus
+b  Spatial plot of best focus values
+d  Delete star nearest to cursor
+e  Enclosed flux for stars at one focus and one star at all focus
+f  Size and ellipticity vs focus for all data
+i  Information about point nearest the cursor
+m  Size and ellipticity vs relative magnitude at one focus
+n  Normalize enclosed flux at x cursor position
+o  Offset enclosed flux to by adjusting background
+p  Radial profiles for stars at one focus and one star at all focus
+q  Quit
+r  Redraw
+s  Toggle magnitude symbols in spatial plots
+t  Size and ellipticity vs radius from field center at one focus
+u  Undelete all deleted points
+x  Delete nearest point, star, or focus (selected by query)
+z  Zoom to a single measurement
+<space> Step through different focus or stars in current plot type
+
+
+:beta <val>     Beta parameter for Moffat fit
+:level <val>	Level at which the size parameter is evaluated
+:overplot <y|n> Overplot the profiles from the narrowest profile?
+:radius <val>   Change profile radius
+:show <file>	Page all information for the current set of objects
+:size <type>	Size type (Radius|FWHM)
+:scale <val>	Pixel scale for size values
+:xcenter <val>	X field center for radius from field center plots
+:ycenter <val>	Y field center for radius from field center plots
+
+The profile radius may not exceed the initial value set by the task
+parameter.
+.fi
+.ih
+DESCRIPTION
+This task measures the point-spread function (PSF) width of stars or other
+unresolved objects in digital images.  The width is measured based on the
+circular radius which encloses a specified fraction of the background
+subtracted flux.  The details of this are described in the ALGORITHMS
+section.  When a sequence of images or multiple exposures in a single image
+are made with the focus varied the program provides an estimate of the best
+focus and various views of how the PSF width varies with focus and position
+in the image.  A single star may be measured at each focus or measurements
+of multiple stars may be made and combined.  The task has three stages;
+selecting objects and measuring the PSF width and other parameters, an
+interactive graphical analysis, and a final output of the results to the
+terminal and to a logfile.
+
+If a saturation value is specified then all pixels within the specified
+measurement radius are checked for saturation.  If any saturated pixels are
+found a warning is given and \fIignore_sat\fR parameter may be used ot
+ignore the measurement.  If not ignored the object will still be indicated
+as saturated in the output log.  In a focus sequence only the saturated
+objects are discarded and not the whole sequence.
+
+The input images are specified by an image template list.  The list may
+consist of explicit image names, wildcard templates, and @ files.  A
+"focus" value or values is associated with each image; though this may be
+any numeric quantity (integer or floating point) and not just a focus.  The
+focus values may be specified in several ways.  If each image has a focus
+value recorded in the image header, the keyword name may be specified.  If
+the images consists of multiple exposures the \fIfstep\fR parameter would
+specify a second image header keyword (or constant value) giving the
+focus increment per exposure.  
+
+The focus values may also be specified as a range list
+as described in the help topic \fBranges\fR.  This consists of
+individual values, ranges of values, a starting value and a step, and a
+range with a step.  The elements of the list are separated by commas,
+ranges are separated by hyphens, and a step is indicated by the character
+'x'.  Long range lists, such as a list of individual focus values, may be
+placed in a file and specified with the @<filename> convention.  The
+assignment of a focus value from a list depends on whether the images
+are single or multiple exposure as specified by the \fInexposure\fR
+parameter.  Single exposure images are assigned focus values from the
+list in the order in which the images and focus values are given.  If
+the images are multiple exposure focus frames in which each offset exposure
+has a different focus, the focus values from the list are assigned in
+order to the multiple exposures and if there are multiple images the
+assignments are repeated.
+
+For a simple sequence of a starting focus value and focus increment,
+either for multiple single exposure images or multiple exposure
+images the \fIfocus\fR and \fIfstep\fR parameters by be used
+togther as single values or image header keywords.  Note that if
+\fIfstep\fR is specified then the focus parameter is NOT interpreted
+as a list.
+
+There are two common ways of doing focus sequences.  One is to take an
+exposure at each focus value.  In this case the parameter \fInexposure\fR
+is given the value 1.  The second is to take an image with multiple
+exposures where the objects in the image are shifted between exposures and
+the focus is changed.  In this case \fInexposure\fR is greater than 1 and
+other parameters are used to specify the shift size and direction.  The
+\fInexposure\fR parameter may be a number of an image header keyword.
+
+Currently the task allows only multiple exposure shifts along either the
+column or line dimension and the shifts must be the same between each
+exposure except that there may be a double shift at either end of the
+sequence.  The shift magnitude, in pixels, is specified as either a number
+or image header keyword.  The shift direction is given by the
+\fIdirection\fR parameter.  It is specified relative to the image; i.e. it
+need not be the same as the physical shifts of the telescope or detector
+but depends on how the image was created.  Steps in which the object
+positions decrease in column or line are specified with a leading minus and
+those which increase with a leading plus.  The step is specified as a
+positive number of pixels between exposures.  Often a double shift is made
+at the beginning or end of the sequence.  If this is done the \fIgap\fR
+parameter is used to identify which end the gap is on.  Note that one may
+change the sense of the exposure sequence from that used to make the focus
+frame by properly adjust the direction, the gap, the focus list, and which
+object is marked as the start of the sequence.
+
+Identifying the object or objects to be measured may be accomplished in
+several ways.  If a single object near the center of the image is to be
+measured then the \fIcoords\fR parameter takes the value "center".  This
+may be used with multiple exposure focus frames if the first exposure of
+the object sequence is at the center.  When the "center" option is used
+the \fIdisplay\fR and \fIimagecur\fR parameters are ignored.
+
+If there are multiple objects or the desired object is not at the center of
+the frame the object coordinates are entered with the \fIimagecur\fR
+parameter.  This type of coordinate input is selected by specifying either
+"mark1" or "markall" for the \fIcoords\fR parameter.  If the value is
+"mark1" then the coordinates are entered for the first image and the same
+values are automatically used for subsequent images.  If "markall" is
+specified then the objects in each image are marked.
+
+Normally the \fIimagecur\fR parameter would select the interactive image
+display cursor though a standard cursor file could be used to make this
+part noninteractive.  When the image display cursor is used either the
+image must be displayed previously by the user, or the task may be allowed
+to load the image display using the \fBdisplay\fR task by setting the
+parameter \fIdisplay\fR to yes and \fIframe\fR to a display frame.  If yes
+the image display must be active.  The task will look at the image names as
+stored in the image display and only load the display if needed.
+
+If one wants to enter a coordinate list rather than use the interactive
+image cursor the list can consist of just the column and line coordinates
+since the key will default to 'm'.  To finish the list either the end
+of file may be encountered or a single 'q' may be given since the
+coordinates are irrelevant.  For the "markall" option with multiple
+images there would need to be a 'q' at the end of each object except
+possibly the last.
+
+When objects are marked interactively with the image cursor there
+are a four keys which may be used as shown in the CURSOR COMMAND section.
+The important distinction is between 'm' to mark and measure an
+object and 'g' to mark, measure, and graph the results.  The former
+accumulates the results until the end while the latter can give an
+immediate result to be examined.  Unless only one object is marked
+the 'g' key also accumulates the results for later graphical analysis.
+It is important to note that the measurements are done as each
+object is marked so there can be a significant delay before the
+next object may be marked.
+
+The quantities measured and the algorithms used are described in the
+ALGORITHMS section.  Once all the objects have been measured an
+interactive (unless only one object is measured) graphical presentation
+of the measurements is entered.
+
+When the task exits it prints the results to the terminal (STDOUT)
+and also to the \fIlogfile\fR if one is specified.  The results may
+also be previewed during the execution of the task with the
+":show" command.  The results begin with a banner and the overall
+estimate of the best focus and PSF size.  If there are multiple
+stars measured at multiple focus values the best focus estimate
+for each star is printed.  The star is identified by it's position
+(the starting position for multiple exposure images).  The average
+size, relative magnitude, and best focus estimate are then given.
+If there are multiple focus values the average of the
+PSF size over all objects at each focus are listed next.
+Finally, the individual measurements are given.  The columns
+give the image name, the column and line position, the relative
+magnitude, the focus value, the PSF size as either the enclosed
+flux radius or the FWHM, the ellipticity, the position angle, and
+an indication of saturation.
+.ih
+ALGORITHMS
+The PSF of an object is characterized using a radially symmetric
+enclosed flux profile.  First the center of the object is determined from
+an initial rough coordinate.  The center is computed from marginal profiles
+which are sums of lines or columns centered at the initial coordinate and
+with a width given by the sum of the \fIradius\fR, \fIsbuffer\fR, and
+\fIswidth\fR parameters.  The mean of the marginal profile is determined
+and then the centroid of the profile above this is computed.  The centroids
+from the two marginal profiles define a new object center.  These steps of
+forming the marginal profiles centered at the estimated object position and
+then computing the centroids are repeated until the centroids converge or
+three iterations have been completed.
+
+Next a background is determined from the mode of the pixel values in the
+sky annulus defined by the object center and \fIradius\fR, \fIsbuffer\fR,
+and \fIswidth\fR parameters.  The pixel values in the annulus are sorted
+and the mode is estimated as the point of minimum slope in this sorted
+array using a width of 5% of the number of points.  If there are multiple
+regions with the same minimum slope the lowest pixel value is used.
+
+The background subtracted enclosed flux profile is determined next.
+To obtain subpixel precision and to give accurate estimates for small
+widths relative to the pixel sampling, several things are done.
+First interpolation between pixels is done using a cubic spline surface.
+The radii measured are in subpixel steps.  To accommodate small and
+large PSF widths (and \fIradius\fR parameters) the steps are nonuniform
+with very fine steps at small radii (steps of 0.05 pixels in the
+central pixel) and coarser steps at larger radii (beyond 9 pixels
+the steps are one pixel) out to the specified \fIradius\fR.  Similarly each
+pixel is subsampled finely near the center and more coarsely at larger
+distances from the object center.  Each subpixel value, as obtained by
+interpolation, is background subtracted and added into the enclosed flux
+profile.  Even with subpixel sampling there is still a point where a
+subpixel straddles a particular radius.  At those points the fraction of
+the subpixel dimension in radius falling within the radius being measured
+is used as the fraction of the pixel value accumulated.
+
+Because of errors in the background determination due to noise and
+contaminating objects it is sometimes the case that the enclosed flux
+is not completely monotonic with radius.  The enclosed flux
+normalization, and the magnitude used in plots and reported in
+results, is the maximum of the enclosed flux profile even if it
+occurs at a radius less than the maximum radius.  It is possible
+to change the normalization and subtract or add a background correction
+interactively.
+
+Because a very narrow PSF will produce significant errors in the cubic
+spline interpolation due to the steepness and rapid variation in the pixel
+values near the peak, the Gaussian profile with FWHM that encloses the same
+80% of the flux is computed as:
+
+    FWHM(80%) = 2 * r(80%) * sqrt (ln(2) / (ln (1/.2)))
+
+If this is less than five pixels the Gaussian model is subtracted from the
+data.  The Gaussian normalization is chosed to perfectly subtract the
+central pixel.  The resulting subtraction will not be perfect but the
+residual data will have much lower amplitudes and variations.  A spline
+interpolation is fit to this residual data and the enclosed flux profile is
+recomputed in exactly the same manner as previously except the subpixel
+intensity is evaluated as the sum of the analytic Gaussian and the
+interpolation to the residual data.
+
+The Gaussian normalization is chosed to perfectly subtract the central
+pixel.  The resulting subtraction will not be perfect but the residual data
+will have much lower amplitudes and variations.  A spline interpolation is
+fit to this residual data and the enclosed flux profile is recomputed in
+exactly the same manner as previously except the subpixel intensity is
+evaluated as the sum of the analytic Gaussian and the interpolation to the
+residual data.  This technique yields accurate FWHM for simulated Gaussian
+PSFs down to at least a FWHM of 1 pixel.
+
+In addition to the enclosed flux profile, an estimate of the radially
+symmetric intensity profile is computed from the enclosed flux profile.
+This is based on the equation
+
+.nf
+    F(R) = integral from 0 to R { P(r) r dr }
+.fi
+
+where F(R) is the enclosed flux at radius R and P(r) is the intensity per
+unit area profile.  Thus the derivative of F(R) divided by R gives an
+estimate of P(R).
+
+Cubic spline interpolation functions are fit to the normalized enclosed
+flux profile and the intensity profile.  These are used to find the radius
+enclosing any specified fraction of the flux and to find the direct FWHM of
+the intensity profile.  These are output when \fIsize\fR is "Radius" or
+"FWHM" respectively.
+
+In addition to enclosed flux radius and direct FWHM size measurements
+there are also two size measurements based on fitting analytic profiles.
+A Gaussian profile and a Moffat profile are fit to the final enclosed flux
+profile to the points with enclosed flux less than 80%.  The limit is
+included to minimize the effects of poor background values and to make the
+profile fit be representative of the core of the PSF profile.  These profiles
+are fit whether or not the selected \fIsize\fR requires it.  This is done
+for simplicity and to allow quickly changing the size estimate with the
+":size" command.
+
+The intensity profile functions (with unit peak) are:
+
+.nf
+    I(r) = exp (-0.5 * (r/sigma)**2)			Gaussian
+    I(r) = (1 + (r/alpha)**2)) ** (-beta)		Moffat
+.fi
+
+with parameters sigma, alpha, and beta.  The normalized enclosed flux
+profiles, which is what is actually fit, are then:
+
+.nf
+    F(r) = 1 - exp (-0.5 * (r/sigma)**2)		Gaussian
+    F(r) = 1 - (1 + (r/alpha)**2)) ** (1-beta)		Moffat
+.fi
+
+The fits determine the parameters sigma or alpha and beta (if a
+beta value is not specified by the users).  The reported FWHM values
+are given by:
+
+.nf
+    GFWHM = 2 * sigma * sqrt (2 * ln (2))		Gaussian
+    MFWHM = 2 * alpha * sqrt (2 ** (1/beta) - 1)	Moffat
+.fi
+
+were the units are adjusted by the pixel scale factor.
+
+In addition to the four size measurements there are several additional
+quantities which are determined.  
+Other quantities which are computed are the relative magnitude,
+ellipticity, and position angle.  The magnitude of an individual
+measurement is obtained from the maximum flux attained in the enclosed
+flux profile computation.  Though the normalization and background may be
+adjusted interactively later, the magnitude is not changed from the
+initial determination.  The relative magnitude of an object is then
+computed as
+
+.nf
+    rel. mag. = -2.5 * log (object flux / maximum star flux)
+.fi
+
+The maximum star magnitude over all stars is used as the zero point for the
+relative magnitudes (hence it is possible for an individual object relative
+magnitude to be less than zero).
+
+The ellipticity and positional angle of an object are derived from the
+second central intensity weighted moments.  The moments are:
+
+.nf
+	Mxx = sum { (I - B) * x * x } / sum { I - B }
+	Myy = sum { (I - B) * y * y } / sum { I - B }
+	Mxy = sum { (I - B) * x * y } / sum { I - B }
+.fi
+
+where x and y are the distances from the object center, I is
+the pixel intensity and B is the background intensity.  The sum is
+over the same subpixels used in the enclosed flux evaluation with
+intensities above an isophote which is slightly above the background.
+The ellipticity and position angles are derived from the moments
+by the equations:
+
+.nf
+	M1 = (Mxx - Myy) / (Mxx + Myy)
+	M2 = 2 * Mxy / (Mxx + Myy)
+	ellip = (M1**2 + M2**2) ** 1/2
+	pa = atan (M2 / M1) / 2
+.fi
+
+where ** is the exponentiation operator and atan is the arc tangent
+operator.  The ellipticity is essentially (a - b) / (a + b) where a
+is a major axis scale length and b is a minor axis scale length.  A
+value of zero corresponds to a circular image.  The position angle is
+given in degrees counterclockwise from the x or column axis.
+
+The overall size when there are multiple stars is estimated by averaging
+the individual sizes weighted by the flux of the star as described above.
+Thus, when there are multiple stars, the brighter stars are given greater
+weight in the average size.  This average size is what is given in the
+banner for the graphs and in the printed output.
+
+One of the quantities computed for the graphical analysis is the
+FWHM of a Gaussian or Moffat profile that encloses the same flux
+as the measured object as a function of the level.  The equation are:
+
+.nf
+   FWHM = 2 * r(level) * sqrt (ln(2.) / ln (1/(1-level)))  Gaussian
+
+   FWHM = 2 * r(level) * sqrt (2**(1/beta)-1) /
+	  sqrt ((1-level)**(1/(1-beta))-1)		   Moffat
+.fi
+
+where r(level) is the radius that encloses "level" fraction of the total
+flux.  ln is the natural logarithm and sqrt is the square root.  The beta
+value is either the user specified value or the value determined by fitting
+the enclosed flux profile.
+
+This function of level will be a constant if the object profile matches
+the Gaussian or Moffat profile.  Deviations from a constant show
+the departures from the profile model.  The Moffat profile used in making
+the graphs except for the case where the \fIsize\fR is GFWHM.
+
+The task estimates a value for the best focus and PSF size at that focus
+for each star.  This is done by finding the minimum size at each focus
+value (in case there are multiple measurements of the same star at the same
+focus), sorting them by focus value, finding the focus value with the
+minimum size, and parabolically interpolating using the nearest focus
+values on each side.  When the minimum size occurs at either extreme of the
+focus range the best focus is at that extreme focus; in other words there
+is no extrapolation outside the range of focus values.
+
+The overall best focus and size when there are multiple stars are estimated
+by averaging the best focus values for each star weighted by the
+average flux of the star as described above.  Thus, when there are
+multiple stars, the brighter stars are given greater weight in the
+overall best average focus and size.  This best average focus and
+size are what are given in the banner for the graphs and in the
+printed output.
+
+The log output also includes an average PSF size for all measurements
+at a single focus value.  This average is also weighted by the
+average flux of each star at that focus.
+.ih
+INTERACTIVE GRAPHICS MODE
+The graphics part of \fBstarfocus\fR consists of a number of different
+plots selected by cursor keys.  The available plots depend on the
+number of stars and the number of focus values.  The various plots
+and the keys which select them are summarized below.
+
+.nf
+a  Spatial plot at a single focus
+b  Spatial plot of best focus values
+e  Enclosed flux for stars at one focus and one star at all focus
+f  Size and ellipticity vs focus for all data
+m  Size and ellipticity vs relative magnitude at one focus
+p  Radial profiles for stars at one focus and one star at all focus
+t  Size and ellipticity vs radius from field center at one focus
+z  Zoom to a single measurement
+.fi
+
+If there is only one object at a single focus the only available plot is
+the 'z' or zoom plot.  This has three graphs; a graph of the normalized
+enclosed flux verses scaled radius, a graph of the intensity profile verses
+scaled radius, and equivalent Moffat/Gaussian full width at half maximum verses
+enclosed flux fraction.  The latter two graphs are derived from the
+normalized enclosed flux profile as described in the ALGORITHMS section.
+In the graphs the measured points are shown with symbols, a smooth curve is
+drawn through the symbols and dashed lines indicate the measurement level
+and enclosed flux radius at that level.
+
+Overplotted on these graphs are the Moffat profile fit or the
+Gaussian profile fit when \fIsize\fR is GFWHM.
+
+The zoom plot is always available from any other plot.  The cursor position
+when the 'z' key is typed selects a particular object measurement.
+This plot is also the one presented with the 'g' key when marking objects for
+single exposure images.  In that case the graphs are drawn followed by
+a return to image cursor mode.
+
+There are three types of symbol plots showing the measured PSF size (either
+enclosed flux radius or FWHM) and ellipticity.  These plot the measurements
+verses focus ('f' key), relative magnitude ('m' key), and radius from the
+field center ('t' key).  The focus plot includes all measurements and shows
+dashed lines at the estimated best focus and size.  This plot is only
+available when there are multiple focus values.  It is the initial plot in
+this case for both the 'g' key when there are multiple exposures and when
+the graphical analysis stage is entered after defining the objects.
+
+The magnitude and field radius plots are only available when there are
+multiple objects measured.  The relative magnitude used for a particular
+measurement is the average magnitude of the star over all focus values and
+not the individual object magnitude.  The data shown is for a single focus
+value.  The focus value is selected when typing 'm' or 't' by the focus of
+the nearest object to the cursor in the preceding plot.  When in one of
+these plots, other focus values may be shown by typing <space>, the space
+bar.  This scrolls through the focus values.  The field center for the
+field radius graph may be changed interactively using the ":xcenter" and
+":ycenter" commands.
+
+Grids of enclosed flux vs. radius, intensity profile vs. radius, and
+FWHM vs. enclosed flux fraction are shown with the 'e', 'p', and
+'g' keys respectively.  If there are multiple objects at multiple focus
+values there are two grids. One grid is all objects at one focus and the
+other is one object at all focuses.  The titles identify the object (by
+location) and focus.  The profiles in the grids have no axis labels or
+ticks.  Within each box are the coordinates of the object or the focus
+value, and the PSF size are given.  When there is only one object at
+multiple focus values or multiple objects at only one focus value then
+there is only one grid and a graph of a one object.  The single object
+graph does have axis labels and  ticks.
+
+In the grids there is one profile which is highlighted (by a second
+box or by a color border).  The highlighted profile is the current
+object.  To change the current object, and thus change either
+the contents of the other grid or the single object graphed, one
+can type the space bar to advance to the next object or
+use the cursor and the 'e', 'p', or 'g' key again.  Other keys
+will select another plot using the object nearest the cursor to select
+a focus or object.
+
+Any of the graphs with enclosed flux or intensity profiles vs radius may
+have the profiles of the object with the smallest size overplotted.  The
+overplot has a dashed line, a different color on color graphics devices,
+and no symbols marking the measurement points.  The overplots may be
+enabled or disabled with the ":overplot" command.  Initially it is
+disabled.
+
+The final plots give a spatial representation.  These require more than one
+object.  The 'a' key gives a spatial plot at a single focus.  The space bar
+can be used to advance to another focus.  This plot has a central graph of
+column and line coordinates with symbols indicating the position of an
+object.  The objects are marked with a circle (when plotted at unit aspect
+ratio) whose size is proportional to the measured PSF size.  In addition an
+optional asterisk symbol with size proportional to the relative
+brightness of the object may be plotted.  This symbol is toggled with the
+'s' key.  On color displays the circles may have two colors, one if object
+size is above the average best size and the other if the size is below the
+best size.  The purpose of this is to look for a spatial pattern in the
+smallest PSF sizes.
+
+Adjacent to the central graph are graphs with column or line as one
+coordinate and radius or ellipticity as the other.  The symbols
+are the same as described previously.  These plots can show spatial
+gradients in the PSF size and shape across the image.
+
+The 'b' key gives a spatial plot of the best focus estimates for each
+object.  This requires multiple objects and multiple focus values.
+As discussed previously, given more than one focus a best focus
+value and size at the best focus is computed by parabolic interpolation.
+This plot type shows the object positions in the same way as the 'a'
+plot except that the radius is the estimated best radius.  Instead
+of adjacent ellipticity plots there are plots of best focus verses
+columns and lines.  Also the two colors in the symbol plots are
+selected depending on whether the object's best focus estimate is
+above or below the overall best focus estimate.  This allows seeing
+spatial trends in the best focus.
+
+In addition to the keys which select plots there are other keys which
+do various things.  These are summarized below.
+
+.nf
+?  Page cursor command summary
+d  Delete star nearest to cursor
+i  Information about point nearest the cursor
+n  Normalize enclosed flux at x cursor position
+o  Offset enclosed flux by adjusting background
+q  Quit
+r  Redraw
+s  Toggle magnitude symbols in spatial plots
+u  Undelete all deleted points
+x  Delete nearest point, star, or focus (selected by query)
+<space> Step through different focus or stars in current plot type
+.fi
+
+The help, redraw, and quit keys are provide the standard functions.
+The 's' and space keys were described previously.  The 'i' key
+locates the nearest object to the cursor in whatever plot is shown and
+prints one line of information about the object on the graphics device
+status area.
+
+The 'd' key deletes the star nearest the cursor in whatever plot is
+currently displayed.  Deleting a star deletes all measurements of an object
+at different focus values.  To delete all objects from an image, all focus
+values for one star (the same as 'd'), all objects at one focus, or a
+single measurement, the 'x' key is used.  Typing this key produces a query
+for which type of deletion and the user responds with 'i', 's', 'f', or
+'p'.  The most common use of this is to delete all objects at the extreme
+focus values.  Deleted measurements do not appear in any subsequent
+graphics, are excluded from all computations, and are not output in the
+results.  The 'u' key allows one to recover deleted measurements.  This
+undeletes all previously deleted data.
+
+Due to various sources of error the sky value may be wrong causing
+the enclosed flux profile to not converge properly but instead
+decreases beyond some point (overestimated sky) or linearly
+increases with radius (underestimated sky).  This affects the size
+measurement by raising or lowering the normalization and altering
+the shape of the enclosed flux profile.  The 'n' and 'o' keys allow
+fudging the enclosed flux profiles.  These keys apply only in
+the zoom plot of the enclosed flux profile or the case where
+a single enclosed flux profile is shown with the 'e' key; in other
+words plots of the enclosed flux which have axes labels.
+
+The 'n' key normalizes the enclosed flux profile at the point
+set by the x position of the cursor.  The 'o' key increases or
+decreases the background estimate to bring curve up or down to
+the point specified by the cursor.  The effect of this is to
+add or subtract a quadratic function since the number of pixels
+at a particular radius varies as the square of the radius.
+To restore the original profile, type 'n' or 'o' at a radius
+less than zero.
+
+The colon commands, shown below, allow checking or changing parameters
+initially set by the task parameters, toggling the overplotting of the
+smallest PSF profiles, and showing the current results.  The overplotting
+option and the contents of the results displayed by :show were described
+previously.
+
+.nf
+:beta <val>     Beta parameter for Moffat fits
+:level <val>	Level at which the size parameter is evaluated
+:overplot <y|n> Overplot the profiles from the narrowest profile?
+:radius <val>   Change profile radius
+:show <file>	Page all information for the current set of objects
+:size <type>	Size type (Radius|FWHM)
+:scale <val>	Pixel scale for size values
+:xcenter <val>	X field center for radius from field center plots
+:ycenter <val>	Y field center for radius from field center plots
+.fi
+
+The important values which one might want to change interactively are
+the measurement level and the profile radius.  The measurement level
+directly affects the results reported.  When it is changed the sizes
+of all object PSFs are recomputed and the displayed plots and title
+information are updated.  The profile radius is the
+maximum radius shown in plots and used to set the enclosed flux normalization.
+It does not affect the object centering or sky region definition and
+evaluation which are done when the image data is accessed.  Because
+the objects are not remeasured from the image data the radius may
+not be made larger than the radius defined by the task parameter though
+it may be decreased and then increased again.
+.ih
+EXAMPLES
+1.  A multiple exposure frame is taken with 7 exposures of a bright
+star, each exposure shifted by 50 pixels to lower line positions, with a
+double gap at the end.  The exposure pattern is typical of Kitt Peak and
+the default values for the direction and gap position are applicable.  The
+default focus value numbering and measurements in pixels are also used.
+
+.nf
+cl> starfocus focus1 nexp=7 step=50
+<The image is displayed and the image cursor activated>
+<The bright star is marked with 'm'>
+<Marking is finished with 'q'>
+<A graph of FWHM vs focus index is shown>
+<Exit with 'q'>
+NOAO/IRAF IRAFV2.10.3 valdes@puppis Wed 16:09:39 30-Jun-93
+  Best focus of 4.12073 with FWHM (at 50% level) of 3.04
+
+   Image  Column    Line     Mag   Focus    FWHM   Ellip      PA SAT
+  focus1  536.63  804.03    0.07      1.  13.878    0.06     -11
+	  535.94  753.28   -0.11      2.   8.579    0.09      89
+	  535.38  703.96   -0.08      3.   5.184    0.11     -87
+	  537.12  655.36   -0.02      4.   3.066    0.07     -77
+	  534.20  604.59    0.00      5.   4.360    0.10      74
+	  534.41  554.99   -0.00      6.   9.799    0.09     -35
+	  534.83  456.08    0.16      7.  12.579    0.13     -10
+.fi
+
+The estimated best focus is between the 4th and 5th focus setting
+and the best focus FWHM is 3.04 pixels.
+
+Note that in more recent Kitt Peak multiple exposure focus images the
+starting focus value, the focus step, the number of exposures, and
+the shift are recorded in the image header with the keywords
+FOCSTART, FOCSTEP, FOCNEXPO, and FOCSHIFT.  Thus the task parameters
+\fIfocus\fR, \fIfstep\fR, \fInexposures\fR, and \fIstep\fR may be
+set to those names.  However, rather than use \fBstarfocus\fR
+one would use the more convenient \fBkpnofocus\fR.
+.ih
+SEE ALSO
+.nf
+imexamine, implot, kpnofocus, pprofile, pradprof, psfmeasure, radlist,
+radplt, radprof, ranges, specfocus, splot
+.endhelp