From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001
From: Joe Hunkeler <jhunkeler@gmail.com>
Date: Tue, 11 Aug 2015 16:51:37 -0400
Subject: Repatch (from linux) of OSX IRAF

---
 pkg/obsolete/doc/owfits.hlp | 205 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 205 insertions(+)
 create mode 100644 pkg/obsolete/doc/owfits.hlp

(limited to 'pkg/obsolete/doc/owfits.hlp')

diff --git a/pkg/obsolete/doc/owfits.hlp b/pkg/obsolete/doc/owfits.hlp
new file mode 100644
index 00000000..9496192f
--- /dev/null
+++ b/pkg/obsolete/doc/owfits.hlp
@@ -0,0 +1,205 @@
+.help owfits Jan90 dataio
+.ih
+NAME
+owfits -- convert IRAF image files to FITS image files
+.ih
+USAGE
+owfits iraf_files fits_files
+.ih
+PARAMETERS
+.ls iraf_files
+String parameter specifying the input file(s), e.g. "file1" or "file*".
+.le
+.ls fits_files
+String parameter specifying the output destination.
+Magnetic tape output is assumed if the first two characters of fits_files
+are "mt", otherwise the output destination defaults to disk.
+Tape output will begin at the file
+number specified in fits_files, e.g. file 5 if fits_files =
+"mtb1600[5]". Data in file 5 and succeeding files will be overwritten.
+If no tape file number is specified in fits_files, the newtape parameter
+is requested. Tape output will begin at BOT (beginning of tape) if
+newtape = yes, otherwise at EOT (after the double EOF).
+Requesting a tape write at EOT on a blank tape may cause severe problems
+like tape runaway.
+In the case of disk output fits_files may be either a file name template
+or a root filename. In the former case there must be an output fits file
+name for every image. In the latter case the image sequence number is
+appended to fits_files if the number of input images > 1.
+.le
+.ls newtape
+Boolean parameter specifying whether an output tape is blank or contains
+data. Newtape is requested only if no tape file number is specified in
+fits_files, e.g. fits_files = "mtb1600".
+.le
+.ls bscale
+The FITS bscale parameter, defined as p = i * bscale + bzero, where
+p and i are the physical and tape data values respectively.
+The bscale parameter is only requested if the scale switch is set
+and the autoscale switch is turned off.
+.le
+.ls bzero
+The FITS bzero parameter (see bscale for a definition).
+Bzero is only requested if the scale switch is set and the autoscale
+switch is turned off.
+.le
+.ls make_image = yes
+By default owfits writes the FITS image(s) to the output destination.
+If the make_image switch is turned off, owfits prints the FITS headers
+on the standard output and no output file is created. In this way the
+output FITS headers can be examined before actually writing a FITS tape.
+.le
+.ls long_header = no
+If this switch is set the full FITS header will be printed on the standard
+output for each IRAF image converted.
+.le
+.ls short_header = yes
+If this switch is set only a short header, listing files processed and
+their dimensions will be printed on the standard output.
+The long_header switch must be turned off.
+.le
+.ls bitpix = 0
+A bitpix of 8, 16, or 32 will produce either an unsigned byte,
+twos-complement 16 bit integer, or twos-complement 32 bit integer FITS
+image. If bitpix is -32 or
+-64 IEEE real or double precision floating point FITS images are produced.
+If bitpix is set to 0 (the default), owfits will choose one of 8,
+16, 32, -32 or -64 based on the data type of the IRAF image.
+For example a short integer and real image will default to bitpix 16 and 
+-32 respectively.
+Users should be wary or overriding the default value of bitpix as loss
+of precision in their data may result. In this case owfits will issue a
+warning message and an estimate of the maximum loss of precision to be
+expected.
+.le
+.ls blocking_factor = 0
+The tape blocking factor for FITS.
+Wfits normally writes \fIblocking_factor\fR * 2880 byte records,
+where \fIblocking_factor\fR is an integer from 1 to 10.
+If \fIblocking_factor\fR = 0, owfits uses the default FITS blocking
+factor specified for the device  by the "fb" parameter in the
+file dev$tapecap, or 1 if the "fb" parameter is not present. For
+devices which support variable block sizes, e.g. 9-track tapes, exabytes
+and dats, "fb" is normally set to 10.
+The user may override this value by setting \fIblocking_factor\fR
+>= 1 or <= 10. If the device does not support variable block sizes, e.g.
+various types of cartridge drives, blocks of the size defined for the
+device by the "bs" parameter in the dev$tapecap file are written
+and \fIblocking_factor\fR is ignored.
+.le
+.ls scale = yes
+If the scale switch is set, the IRAF image will be scaled before output.
+Two types of scaling are available. The scaling parameters bscale and
+bzero may be entered by the user (autoscale = no), or the program can
+calculate the appropriate bscale and bzero factors (autoscale = yes).
+If the scale switch is turned off, the IRAF image data is converted
+directly to integers of the specified bitpix with possible loss of
+precision.
+.le
+.ls autoscale = yes
+If the autoscale switch is set, owfits calculates the appropriate bscale and
+bzero  factors
+based on the IRAF image data type, and the maximum and minimum
+values of the data.
+.le
+.ih
+DESCRIPTION
+IRAF data is read from disk and written to the specified destination,
+either disk or magnetic tape. The FITS header may optionally be printed
+on the standard output as either a full listing or a short description,
+with or without creating an output image file. If a the default value
+of bitpix (default = 0) is entered, owfits will select the appropriate
+bitpix value based on the precision of the IRAF data. Otherwise the
+user value is used with possible loss of precision. Two data scaling
+options are available. In autoscale mode owfits calculates the appropriate
+scaling factors based on the maximum and minimum data values in the
+IRAF image and the FITS bits per pixel. Alternatively the scaling factors
+can be entered directly. If no scaling is requested the IRAF data values
+will be converted directly to FITS integers or floating point values
+with possible loss of precision.
+.ih
+EXAMPLES
+1. Convert a series of IRAF image files to FITS image files on a blank
+magnetic tape, allowing owfits to select the appropriate bitpix
+and scaling parameters.
+
+.nf
+	cl> owfits iraf_file* mtb1600[1]
+.fi
+
+2. Convert a series of IRAF image files to FITS image files on disk,
+allowing owfits to select the appropriate bitpix and scaling parameters.
+In the first case the images specified by the template are written
+to fits001, fits002 etc. In the second case the list of input images
+specified one per line in the text file imlist are written to the
+files specified one per line in the text file fitslist.
+
+.nf
+	cl> owfits iraf_file* fits
+
+	cl> owfits @imlist @fitslist
+.fi
+
+3. Convert an IRAF image file to a 32 bits per pixel FITS file with no
+scaling and append to a tape already containing data.
+
+.nf
+	cl> owfits iraf_file mtb1600[EOT] bi=32 sc-
+.fi
+
+4. Convert an IRAF image to a 16 bit FITS image on disk, specifying
+bscale and bzero.
+
+.nf
+	cl> owfits iraf_file fits_file bi=16 au- bs=4.0 bz=0.0
+.fi
+
+5. Print the FITS headers on the standard output.
+
+.nf
+	cl> owfits iraf_file* ma-
+.fi
+
+6. Create a disk file called headers containing the FITS headers for a set
+of IRAF image files.
+
+.nf
+	cl> owfits iraf_file* ma- > headers
+.fi
+
+7. Write a FITS tape with 14400 bytes per record (5 2880 FITS records per
+tape block) on a 9-track tape.
+
+.nf
+	cl> owfits images* mtb[1] block=5
+.fi
+
+8. Write a FITS Exabyte tape with a blocking factor of 1 (1 2880 FITS record
+per block). Note that owfits will normally by default write a 28000 (
+10 2880 FITS logical records per block) byte record.
+
+.nf
+	cl> owfits images* mtb[1] block=1
+.fi
+.ih
+BUGS
+OWFITS does not attempt to recover from write errors. When an error is
+detected, OWFITS issues an error message and attempts to write a double
+EOF at the end of the last good record. In this case the last file on
+the tape will be a partial file. IF OWFITS is not successful in writing
+the double EOF, the message "Cannot close magtape file (name)" will be
+issued. Problems occur as some drives permit the double EOF to be
+written after the physical end of tape and some do not. Similarly
+some drives can read a double EOF after end of tape and some cannot. Depending
+on operating system and device driver, an attempt to read or write past
+end of tape may or may not be distinguishable from a normal write error.
+
+Blank pixel values are not correctly handled.
+
+Attempting to write at EOT on a blank tape will at best result in numerous
+error messages being issued and at worst result in tape runaway depending
+on the driver.
+.ih
+SEE ALSO
+orfits, reblock
+.endhelp
-- 
cgit 

