1 files changed, 173 insertions, 0 deletions
diff --git a/pkg/plot/doc/calcomp.hlp b/pkg/plot/doc/calcomp.hlp
new file mode 100644
index 00000000..4595b614
--- /dev/null
+++ b/pkg/plot/doc/calcomp.hlp
@@ -0,0 +1,173 @@
+.help calcomp Mar86 plot
+.ih
+NAME
+calcomp -- plot a GKI metacode file on a Calcomp pen plotter
+.ih
+USAGE
+calcomp input
+.ih
+PARAMETERS
+.ls input
+Name of input GKI metacode file, file template, or list of files.
+.le
+.ls device = "calcomp"
+Name of the destination plotter (as referenced in graphcap).
+.le
+.ls generic = no
+Ignore remaining kernel dependent parameters -- if yes, then none of the
+following parameters will be used; this is automatically the case, for
+instance, when using ":.snap calcomp" from cursor mode.
+.le
+.ls debug = no
+Print decoded graphics instructions during processing -- print each GKI 
+metacode instruction on standard output.
+.le
+.ls verbose = no
+Print elements of polylines, etc. in debug mode -- if yes, this is essentially
+all of the information present in the input metacode file.
+.le
+.ls gkiunits = no
+Print coordinates in GKI rather than NDC units if in debug mode.
+.le
+.ls xscale = INDEF
+X scale in device units per GKI unit; e.g. 0.0003 is 3 ten-thousandths of an
+inch per GKI unit on a plotter calibrated in inches; normally a plot is 32767
+GKI units wide.  If the plotting task that generated the metacode file generated
+a scale, this will be used if xscale is INDEF.  Specify xscale only if you wish
+to override the scale in the metacode.
+.le
+.ls yscale = INDEF
+Y scale in device units per GKI unit -- see xscale.
+.le
+.ls txquality = "normal"
+Text quality; "normal" means use the text quality specified in the metacode
+file.  "Low" means override the metacode font with the Calcomp symbol font,
+while "medium" and "high" use IRAF fonts.  There is little difference in speed
+with the different fonts, except if the text is bold, in which case "high"
+takes twice as long as "low" or "medium".
+.le
+.ls lwtype = "ntracing"
+Type of line and text width implementation.  "Ntracing" causes the pen plotter
+to draw each line or character several times with slight offsets to simulate 
+boldness.  "Penchange", if implemented in the local Calcomp library, would
+cause the plotter to pause for an operator to change the pen when bold lines
+or text are requested.
+.le
+.ls ltover = no
+Line type override, if yes, causes the pen plotter to draw all lines solidly,
+rather than as dashed or dotted lines if these are specified in the metacode.
+This may be desired for previewing a plot quickly.
+.le
+.ls lwover = yes
+Line width override; causes all lines and text to come out with single width
+in order to speed up plotting.  If bold text, axes, etc. are desired and
+present in the parent plot, then set lwover = no.
+.le
+.ls lcover = no
+Line color override, if yes, causes the pen plotter to ignore any requests in
+the metacode for a colored pen change.  Pen change is not implemented at all
+sites with Calcomp plotters.
+.le
+.ls dashlen = INDEF
+Length of the dash in dashed lines in device units, usually inches.  Shorter
+dashes usually take longer to plot but may look nicer.  If left INDEF, a
+local default from dev$graphcap will be used; a good range is 0.1 to 0.5 inches.
+.le
+.ls gaplen = INDEF
+Length of the gap in dashed or dotted lines, in device units.  Longer gaps 
+result in faster plotting at the expense of clarity.  If left INDEF, a local
+default from dev$graphcap will be used.  A good range is 0.05 to 0.2 inches.
+.le
+.ls plwsep = INDEF
+Parallel line width separation -- if bold lines are implemented with "lwtype
+= ntracing", this is the right-angle distance between adjacent traces.  If
+INDEF, a local default is used from the device table dev$graphcap.
+.le
+.ih
+DESCRIPTION
+Task \fBcalcomp\fR is an IRAF graphics kernel.  It may be run standalone to
+plot a GKI metacode file, or from cursor mode via ":.snap calcomp".
+
+\fBCalcomp\fR may be used to draw any IRAF plot on a Calcomp pen plotter.  It is
+only available if the local site has a Calcomp library.  Task \fBcalcomp\fR
+is an exact-scaling graphics kernel, unlike the NSPP, or STDPLOT kernel.
+This means that if the task that generated the metacode input file passed an
+exact scale into the metacode, data can be plotted to a desired precise scale.
+
+The metacode scale may be overridden, or metacode files generated by tasks that
+do not implement exact scales may be plotted to a precise scale, by specifying
+xscale or yscale.  Note, however, that the only coordinates in a metacode file
+are GKI coordinates, usually running from 1 - 32767.  This means that to use
+xscale and yscale, the user must calculate the number of inches per GKI unit,
+not the number of world or data units per inch.
+
+\fBCalcomp\fR also implements dashed and dotted lines and bold lines and text.
+Thus high-quality plots may be produced, at the expense of requiring more time.
+If "lwtype=ntracing" and "lwover=no", any bold text or lines in the metacode
+file, such as are produced for axes, tickmarks, titles and axis labels by many
+IRAF plotting tasks, will appear bold on the Calcomp.  If txquality="low" or
+"medium", and bold text is requested, each character will be drawn 5 times --
+once in the center position and once to the right, top, left, and bottom of
+the original position.  Each of the side positions is drawn "plwsep" inches
+from the center.  If txquality="high", bold text is implemented with the same
+five tracings plus the four corners upper right, upper left, etc.  For most
+applications txquality="normal" or "medium" is adequate for nice-looking
+plots.
+
+When drawing data lines bold (only possible if the task originating the 
+metacode specifically requested it, not the case for most IRAF plotting
+tasks), the bounding parallel line traces are constructed to meet at sharp
+points.  This looks fine for line intersections that are not too acute.  If
+the intersection angle between two lines is very acute, say less than 5
+degrees, the vertex of the parallel lines bounding to the outside may lie
+quite a distance away from the actual vertex.  In the limit, if the 
+intersection angle is zero, the outer vertex will lie at infinity.  For
+this reason, all intersection angles less than 5 degrees are treated as
+though they were exactly 5 degrees.
+.ih
+EXAMPLES
+1. Plot a metacode file exactly as is:
+
+    cl> calcomp metacodefile
+
+2. Get the fastest plot you can -- no bold lines or text, no dashed or dotted
+lines:
+
+    cl> calcomp metacodefile lwover+ ltover+ txquality=low
+
+3. Get a plot half the size of the original; suppose the original plot had
+metacode scales = 0.0003 inches / GKI unit:
+
+    cl> calcomp metacodefile xscale=0.00015 yscale=0.00015
+
+4. Get the highest quality plot you can without having to change pens:
+
+    cl> calcomp metacodefile txqual=high 
+
+5. Get a high-quality plot where you have to change the pen each time the
+metacode switches from bold to single-width lines or text:
+
+    cl> calcomp metacodefile txqual=high lwtype=penchange
+
+.ih
+TIME REQUIREMENTS
+Pen plotters vary considerably in their plotting rates.  At NOAO, plotting a
+metacode file from a 1024-pixel image generated by \fBlongplot\fR, overriding
+bold lines and text, takes a couple of minutes.  The same plot with txquality
+= "medium" can take over twice as long due to bold text, axes, and tick labels.
+With txquality = "high", it may take 4 or 5 times as long to plot.
+
+Plots with dashed and dotted, or both, lines may take 2-5 times as long to 
+plot as single-width lines.  The slowest of all is to produce plots with
+a lot of bold text, or with dashed and dotted AND bold data lines.
+.ih
+BUGS
+When using multiple tracing to simulate bold lines that intersect at very
+acute angles, i.e. less than 5 degrees, each bold line will thin slightly
+as it approaches the obtuse vertex.
+.ih
+SEE ALSO
+See task \fBlongplot\fR, also in the plot package, for a task designed to
+use the \fBcalcomp\fR graphics kernel for exact scaling and/or long, e.g.
+spectral, plots.
+.endhelp