Initial commit

1 files changed, 235 insertions, 0 deletions

diff --git a/pkg/proto/doc/imextensions.hlp b/pkg/proto/doc/imextensions.hlp
new file mode 100644
index 00000000..d67c961f
--- /dev/null
+++ b/pkg/proto/doc/imextensions.hlp
@@ -0,0 +1,235 @@
+.help imextensions Jul97 proto
+.ih
+NAME
+imextensions -- make a list of image extensions
+.ih
+USAGE   
+.nf
+imextensions input
+.fi
+.ih
+PARAMETERS
+.ls input
+List of input files containing image extensions to be listed.  This list
+may not contain any image kernel but it can contain an image section.  The
+image filename extension, such as ".fits", is optional in the same way as
+with other IRAF image tasks.
+.le
+.ls output = "file" (none|list|file)
+Output type for the list of image extensions.  The choices are:
+
+.nf
+    none - no output
+    list - a list as a single line
+    file - a list of one image extension per line
+.fi
+
+The "none" output is used to just set the number of image extensions in the
+\fInimages\fR parameter.  The "list" output is used for a short list that
+can be scanned into a CL variable.  The "file" output is used for a long
+list and to be redirected to a file for use as an "@file".  If "list"
+output is selected and the list length exceeds 255 characters (the
+size of a CL string) the task will abort with an error.
+.le
+.ls index = "1-"
+Extension index range list.  The range list syntax is specified under the
+help topic \fBranges\fR.  Note that the range list may be specified that
+includes 0 to select the primary image header in FITS files.
+.le
+.ls extname = ""
+Extension name pattern.  If a null string is specified then there is
+no check on the extension name.  If a pattern is specified then only
+image extensions with an extension name matching the pattern will be
+selected.  The pattern syntax is described under the help topic \fImatch\fR.
+.le
+.ls extver = ""
+Extension version range list.  If a null list is specified then there is
+no check on the extension version.  If a list is given then only image
+extensions with extension versions in the list will be selected.
+The range list syntax is described under the help topic \fBranges\fR.
+.le
+.ls lindex = yes
+List the image extensions with the extension index?  If the value is
+"no" then the extension index will not be listed if the extension
+name and/or the extension version is listed.  If there is no
+extension name or extension version then the extension index is
+always listed regardless of the value of this parameter.
+.le
+.ls lname = no
+List the image extensions with the extension name if there is one?
+.le
+.ls lver = no
+List the image extensions with the extension version if there is one?
+.le
+.ls ikparams = ""
+Include the specified image kernel parameters in the image extension
+names.  The image kernel parameters are specific to the various
+IRAF image formats.
+.le
+
+.ls nimages
+This is an output parameter which is set to the number of image extensions
+selected in the last execution of the task.  Note that if the task
+is run as a background job this parameter will not be set in the
+disk parameter file though it can be made available in a background
+script using this task by caching the parameter set; i.e. 
+include the command "cache imextensions" at the beginning of the script.
+.le
+.ih
+DESCRIPTION
+\fBImextensions\fR selects and lists image extensions in files.  Image
+extensions currently occur in multi-extension FITS files and multi-group
+Geiss (STF format) files.  The image extension names are given in proper
+syntax for IRAF image names for use in tasks expecting image names.
+The output format type may be a one line list, a list of one image
+extension name per line, or no output.  These options allow capturing
+the expanded list in a CL string variable, in a file for use as
+an "@file", or to simply count the number of image extensions matching
+the selection criteria.  Note that if the "list" output type is selected
+and the list of image extensions exceeds 255 characters (the limit
+for a CL string) then the task aborts with an error.
+
+Image extensions may be selected by index value (the position in the file),
+by extension name (keyword EXTNAME used in FITS image extensions), and by
+extension version number (keyword EXTVER).  The numeric selection uses
+range lists and the extension name selection uses pattern matching.  The
+primary image in a multi-extension FITS file may also be selected by
+including an index value of 0 in the index range list.
+
+The output image extension names may be given with the index value and/or
+the image kernel specification.  The image kernel specification, which is
+image type dependent, may include the extension name, extension version,
+and other kernel parameters.  Note that if the image does not have an
+extension name or version then the index value is always given whether or
+not the \fIlindex\fR parameter is set to insure that a proper image name is
+generated.
+
+.ih
+EXAMPLES
+1.  Get a list of image extensions in a CL string and use it to select
+header keywords.  This illustrates the use of the "list" output and
+a CL variable.
+
+.nf
+    cl> imext obj001 output=list | scan (s1)
+    cl> = s1
+    obj001[1],obj001[2],obj001[3]
+    cl> if (imext.nimages > 0)
+    >>> hselect (s1, "$I,title", yes)
+    obj001[1]   Alpha Leo
+    obj001[2]   Beta Leo
+    obj001[3]   Gamma Leo
+.fi
+
+2.  Do the same thing as in the first example using an "@file".
+
+.nf
+    cl> imext obj001 output=file > list.dat
+    cl> type list.dat
+    obj001[1]
+    obj001[2]
+    obj001[3]
+    cl> if (imext.nimages > 0)
+    >>> hselect @list.dat $I,title yes
+    obj001[1]   Alpha Leo
+    obj001[2]   Beta Leo
+    obj001[3]   Gamma Leo
+.fi
+
+3.  Create a list selecting only the first and third extension and using the
+image extension name, version, and an image kernel section.
+
+.nf
+    cl> imext obj*[1:100,1:100] index=1,3 lindex- lname+ lver+ ikparams=expand
+    obj001.fits[aleo,1,expand][1:100,1:100]
+    obj003.fits[gleo,1,expand][1:100,1:100]
+    obj002.fits[im1,1,expand][1:100,1:100]
+    obj002.fits[im3,1,expand][1:100,1:100]
+    cl> = imext.nimages
+    4
+.fi
+
+4.  List only the primary images in a set of multi-extension FITS files.
+A primary image need not contain image data; i.e. this will select
+global headers with NDIM=0 as well as headers with image data.
+
+.nf
+    cl> imext *.fits index=0
+    abc.fits[0]
+    def.fits[0]
+    ghi.fits[0]
+.fi
+
+5.  Use this task in a script to test on the existence of extension name
+"joy".  This example shows the use of the pattern matching and of the
+\fBcache\fR command to insure the script works as a background task.
+
+.nf
+    procedure example (image)
+
+    file    image   {prompt="Image"}
+
+    begin
+	    file    im
+
+	    cache imextensions
+	    im = image
+
+	    imextensions (im, output="none", extname="joy")
+	    if (imextensions.nimages == 0)
+		call printf ("No joy found with %s\n", im) 
+    end
+.fi
+
+Note that proper script programming would make all the hidden parameters
+explicit.
+
+
+6.  Example of the extension name pattern matching.
+
+.nf
+    cl> imext obj.fits extname=joy lindex- lname+
+    obj.fits[joy]
+    obj.fits[nojoy]
+    obj.fits[joyfull]
+    cl> imext obj.fits extname="^joy$" lindex- lname+
+    obj.fits[joy]
+    cl> imext obj.fits extname="{joy}$" lindex- lname+
+    obj.fits[joy]
+    obj.fits[Joy]
+    obj.fits[nojoy]
+.fi
+
+The first example matches "joy" anywhere in the extension name, the
+second requires an exact match with the begin and end string characters,
+and the last example ignores the case and requires the name end with
+joy.
+
+7.  An example with a Geiss file.
+
+.nf
+    cl> imext y00vk102r.d0h index="x5"
+    y00vk102r.d0h[1]
+    y00vk102r.d0h[6]
+    y00vk102r.d0h[11]
+    y00vk102r.d0h[16]
+    y00vk102r.d0h[21]
+    y00vk102r.d0h[26]
+    y00vk102r.d0h[31]
+    y00vk102r.d0h[36]
+.fi
+
+.ih
+REVISIONS
+.ls IMEXTENSIONS V2.11.?
+Image sections are now allowed in the input names.
+.le
+.ls IMEXTENSIONS V2.11
+This task is new in this release.
+.le
+.ih
+SEE ALSO
+.nf
+files, sections, ranges, match
+.fi
+.endhelp