1 files changed, 201 insertions, 0 deletions
diff --git a/noao/onedspec/doc/bplot.hlp b/noao/onedspec/doc/bplot.hlp
new file mode 100644
index 00000000..f2214b94
--- /dev/null
+++ b/noao/onedspec/doc/bplot.hlp
@@ -0,0 +1,201 @@
+.help bplot Mar92 noao.onedspec
+.ih
+NAME
+bplot -- Plot spectra noninteractively using SPLOT
+.ih
+USAGE
+bplot images [records]
+.ih
+PARAMETERS
+.ls images
+List of images to be plotted.  These may be one dimensional, multiaperture,
+long slit, or nonspectral images.
+.le
+.ls records (imred.irs and imred.iids only)
+List of records to be appended to the input image root names when
+using record number extension format.  The syntax of this list is comma
+separated record numbers or ranges of record numbers.  A range consists of
+two numbers separated by a hyphen.  A null list may be used if no record
+number extensions are desired.
+.le
+.ls apertures = ""
+List of apertures/lines/columns to be plotted in each image.  If
+\fIapertures\fR is null all of the apertures/lines/columns will be plotted.
+.le
+.ls band = 1
+The band or plane of a three dimensional image to be plotted in each image.
+.le
+.ls graphics = "stdgraph"
+Output graphics device.  This may be one of "stdgraph", "stdplot",
+"stdvdm", or the actual device name.
+.le
+.ls cursor = "onedspec$gcurval.dat"
+File(s) containing cursor commands for the SPLOT task.
+The files will be cycled sequentially.  If there is more than one file
+usually the number of files will agree with the number of apertures
+for each image since otherwise different cursor/aperture pairings will
+occur.  The default is a file containing only the (q)uit command.
+.le
+
+The following parameters are used in response to particular keystrokes.
+In \fBsplot\fR they are query parameters but in \fBbplot\fR they are hidden
+parameters.
+.ls next_image = ""
+In response to 'g' (get next image) this parameter specifies the image.
+.le
+.ls new_image = ""
+In response to 'i' (write current spectrum) this parameter specifies the
+name of a new image to create or existing image to overwrite.
+.le
+.ls overwrite = yes
+Overwrite an existing output image?  If set to yes it is possible to write
+back into the input spectrum or to some other existing image.  Otherwise
+the user is queried again for a new image name.
+.le
+.ls spec2 = ""
+When adding, subtracting, multiplying, or dividing by a second spectrum
+('+', '-', '*', '/' keys in the 'f' mode) this parameter is used to get
+the name of the second spectrum.
+.le
+.ls constant = 0.
+When adding or multiplying by a constant ('p' or 'm' keys in the 'f' mode)
+the parameter is used to get the constant.
+.le
+.ls wavelength = 0.
+This parameter is used to get a dispersion coordinate value during deblending or
+when changing the dispersion coordinates with 'u'.
+.le
+.ls linelist = ""
+During deblending this parameter is used to get a list of line positions
+and widths.
+.le
+.ls wstart = 0., wend = 0., dw = 0.
+In response to 'p' (convert to a linear wavelength scale) these parameter
+specify the starting wavelength, ending wavelength, and wavelength per pixel.
+.le
+.ls boxsize = 2
+In response to 's' (smooth) this parameter specifies the box size in pixels
+to be used for the boxcar smooth
+.le
+.ih
+DESCRIPTION
+The spectra in the input image list are successively processed by the task
+\fBsplot\fR with input supplied by the cursor parameter and the output sent
+to the specified graphics device.  The range of apertures and bands
+specified by \fIapertures\fR and \fIbands\fR will be processed for each
+image.  In the \fBiids/irs\fR packages the record extension syntax is used
+with input root names and a record number list.  The hidden parameters from
+\fBsplot\fR apply to this task.
+
+The cursor file(s) consists of line(s) of the form:
+
+	[x y 1] key [command]
+
+where x and y are the position of the cursor (may be zero or absent if the
+cursor position is irrelevant) and key is one of the keystrokes understood
+by \fBsplot\fR.  If the key is ":" then the \fIcolon\fR command string follows.
+The default cursor file consists of the single line:
+
+	0 0 1 q
+
+If more than one cursor file is specified they are sequentially assigned to
+each aperture and the list is repeated as needed.  This allows the aperture
+to be manipulated in differing ways.
+.ih
+EXAMPLES
+1. To plot all of apertures of the multiaperture spectra indicated by the file
+"nite1.lst" on the default plotter and run in the background:
+
+.nf
+    cl> bplot @nite1.lst graphics=stdplot &
+.fi
+
+2. To preview the plots:
+
+.nf
+    cl> bplot @nite1.lst graphics=stdgraph
+.fi
+
+3.  To produce a histogram type plot about Balmer alpha for aperture 5 of
+each spectrum with the IRAF banner suppressed:
+
+.nf
+    cl> type curfile
+    6555 0 1 a
+    6570 0 1 a
+    q
+    cl> splot.options="auto hist nosysid"
+    cl> splot.xmin=6555
+    cl> splot.xmax=6570
+    cl> bplot @nite1.lst apertures=5 cursor=curfile
+.fi
+
+4. To produce plots with four spectra per page:
+
+.nf
+    cl> bplot @nite1.lst ... >G nite1.mc
+    cl> gkimosaic nite1.mc dev=stdplot
+.fi
+
+The first command redirects the output of the graphics to the metacode
+file nite1.mc.  The task \fBgkimosaic\fR is used to make multiple plots
+per page.  Other tasks in the \fBplot\fR package may be used to
+manipulate and redisplay the contents of the metacode file.
+
+5. To plot a list of apertures with a different cursor file for each aperture:
+
+.nf
+    cl> bplot @nite1.lst apertures=3,9,14 cursor=@nite1.cur
+.fi
+
+In this case the file "nite1.cur" is assumed to be a list of
+individual cursor file names, for instance:
+
+.nf
+	cur.03
+	cur.09
+	cur.14
+.fi
+
+that are in one to one correspondence with the range of apertures.
+.ih
+REVISIONS
+.ls BPLOT V2.10.3
+The query parameters from SPLOT were added as hidden parameters in BPLOT
+to allow use of those keys in a batch way.
+.le
+.ls BPLOT V2.10
+The \fIapertures\fR and \fIband\fR parameters been added to select
+apertures from multiple spectra and long slit images, and bands from 3D
+images.  Since the task is a script calling \fBsplot\fR, the many revisions
+to that task also apply.  The version in the \fBirs/iids\fR packages
+selects spectra using the record number extension syntax.
+.le
+.ih
+BUGS
+The cursor file command keystrokes cannot include any of the cursor
+mode (CAPITALIZED) keys.  This results from the implementation of
+the cursor mode commands as external to both BPLOT and SPLOT.
+
+When first entered, SPLOT will always display an initial plot.  BPLOT
+calls SPLOT once for each aperture in each image and thus produces
+N(apertures)*N(images) initial plots.  The plots are not optional because
+of the possible confusion a blank screen might cause an inexperienced
+user.  If the initial plots are unwanted they must be edited out of the
+graphics stream.  This can be done as follows, by directing the
+graphics output of BPLOT to a metacode file and then using GKIEXTRACT
+to remove only the desired plots from the metacode file:
+
+.nf
+    cl> bplot @nite1.lst cursor=curfile >G nite1.mc
+    cl> gkiextract nite1.mc 2x2 | gkimosaic dev=stdplot
+.fi
+
+This assumes that curfile is designed to produce only one plot in
+addition to the non-optional initial plot.  In this case there will be
+two plots per aperture per image and we extract every other plot starting
+with the second (as encoded in the range string:  "2x2").
+.ih
+SEE ALSO
+splot, specplot, slist, gkiextract, gkimosaic, implot, graph, ranges
+.endhelp