1 files changed, 119 insertions, 0 deletions
diff --git a/vo/votools/doc/votpos.hlp b/vo/votools/doc/votpos.hlp
new file mode 100644
index 00000000..5a817327
--- /dev/null
+++ b/vo/votools/doc/votpos.hlp
@@ -0,0 +1,119 @@
+.help votpos Mar12 votools
+.ih
+NAME
+votpos -- Extract the position columns from a VOTable
+.ih
+USAGE
+votpos input
+.ih
+PARAMETERS
+.ls input
+The list of input VOTables.
+.le
+.ls output = STDOUT
+The output filename.
+.le
+.ls ra_col = INDEF
+RA column number (one-indexed).  If specified as other than INDEF, the named
+column will be used instead of the column determined by the primary position
+UCD (i.e. 'POS_EQ_RA_MAIN' or 'pos.eq.ra;meta.main').
+.le
+.ls dec_col = INDEF
+Dec column number (one-indexed).  If specified as other than INDEF, the named
+column will be used instead of the column determined by the primary position
+UCD (i.e. 'POS_EQ_DEC_MAIN' or 'pos.eq.dec;meta.main').
+.le
+.ls rows = "-"
+A range specification of rows to extract.
+.le
+.ls header = no
+Print a output header?
+.le
+.ls number = no
+Print the row number of each position?  If enabled, the output will consist
+of the (index,ra,dec) values from the table, otherwise just the (ra,dec) will
+be printed.
+.le
+.ls plot = no
+Plot the result table on the standard graphics stream?  If enabled, a plot 
+of the (ra,dec) positions will be drawn to the graphics terminal.
+.le
+.ls overplot = no
+Over an existing display/plot?  If enabled, and existing plot will be 
+appended using the same axis labels and scale.
+.le
+.ls color = 1
+Plot marker color (in the range 1 to 9).  
+.le
+.ls title = ""
+Title string to put on a plot.
+.le
+.ls verbose = yes
+Print verbose output?
+.le
+.ls status = 0
+Status of the service.  A non-zero value indicates no results were found.
+.le
+
+.ih
+DESCRIPTION
+
+The \fIVOTPOS\fR task is used to extract the primary position columns from
+a VOTable.  These columns are defined by the UCD 'POS_EQ_RA_MAIN' and 
+'POS_EQ_DEC_MAIN' for Cone Search services, or by 'pos.eq.ra;meta.main'
+and 'pos.eq.dec;meta.main' for other VO services.  If the \fIra_col\fR
+and \fIdec_col\fR parameters are set, the (one-indexed) column number in
+the table will be used regardless of the UCD value.  Rows of the table
+may be selected by specifying a range string to the \fIrows\fR parameter.
+
+If the \fIheader\fR parameter is enabled, a table header will prepend the
+list of extracted positions.  If the \fInumber\fR parameter is enabled, 
+the row number will be printed as the first column of the output.
+
+A plot of the positions may be displayed by setting the \fIplot\fR parameter.
+Subsequent tables may be appended to the plot by specifying the
+\fIoverplot\fR parameter.  When not overplotting, the \fIcolor\fR parameter
+number 1 will always be used, otherwise each overplot will automatically
+increment the marker color to make the points a unique color.  In all cases,
+the marker shape will be a box meaning that when overplotted points are at 
+the same position they will be drawn in the last color used and may be 
+confused with earlier points at the same position.  A title string may be
+put on the plot by specifying the \fItitle\fR parameter.
+
+
+.ih
+EXAMPLES
+1. Query for catalog positions of NGC188 and extract the (numbered) position
+columns to the file 'ngc188.pos'.
+
+.nf
+  votools> getcat gsc2.3 ngc188 size=0.1 output="ngc188.xml"
+  votools> votpos ngc188.xml number+ out="ngc188.pos"
+.fi
+
+2. Use the VOTable is the first example but plot the positions on the
+graphics terminal.  Overplot a second catalog query of the 2MASS Point
+SOurce Catalog without saving the extracted positions.
+
+.nf
+  votools> votpos ngc188.xml plot+ out="ngc188.pos"
+  votools> getcat 2mass-psc ngc188 size=0.1 output="2mass.xml"
+  votools> votpos 2mass.xml plot+ overplot+ out=""
+.fi
+
+3. Query the GSC 2.3 catalog to overlay an image displayed of the NGC188 field.
+
+.nf
+  votools> dss ngc188 size=0.1
+  votools> getcat gsc2.3 ngc188 size=0.1 output="ngc188.xml"
+  votools> votpos ngc188.xml number+ out="ngc188.pos"
+  votools> taboverlay ngc188 ngc188.pos
+.fi
+
+.ih
+REVISIONS
+.
+.ih
+SEE ALSO
+getcat, getimg
+.endhelp