Initial commit

1 files changed, 124 insertions, 0 deletions

diff --git a/vo/votools/doc/sesame.hlp b/vo/votools/doc/sesame.hlp
new file mode 100644
index 00000000..d2d3fbec
--- /dev/null
+++ b/vo/votools/doc/sesame.hlp
@@ -0,0 +1,124 @@
+.help sesame Mar12 votools
+.ih
+NAME
+sesame -- Resolve a target name into a coordinate position
+.ih
+USAGE
+sesame <target>
+.ih
+PARAMETERS
+.ls target
+List of objects to be resolved.  Targets may be specified as a
+comma-delimited list string or in an @file to resolve multiple targets.  When
+the \fIrange\fR parameter is non-null, this will be the root part of the
+target name.
+.le
+.ls range = ""
+A range string used to expand the \fItarget\fR parameter to a list of names
+to be resolved (e.g. if \fItarget\fR is "ngc" then \fIrange\fR may be
+specified as "1-100" to create a list of the first 100 NGC objects).
+.le
+.ls verbose = yes
+Print coordinates to the stdout?  If enabled the sexagesimal coordinates
+of the resolved target will be printed to the STDOUT where they may be easily
+scanned into variables in a script.  In all cases, the output parameters 
+below are updated with the target information once the task has completed.
+.le
+.ls long = no
+Print long-form output to the stdout?  If enabled the target name,
+sexagesimal coordinates, position error (in arcsec) and object type are
+printed on the output line.
+.le
+.ls pos = ""
+A sesagesimal string of the J2000 RA/Dec position (output).
+.le
+.ls ra = 0.0
+J2000 RA of the object in decimal degrees (output).
+.le
+.ls dec = 0.0
+J2000 Declination of the object in decimal degrees (output).
+.le
+.ls ra_err = 0.0
+Error of the RA position in arcsec (output).
+.le
+.ls dec_err = 0.0
+Error of the Dec position in arcsec (output).
+.le
+.ls otype = ""
+Object type (output).
+.le
+.ls status = ""
+Status return code of the web service (output).
+.le
+
+.ih
+DESCRIPTION
+
+The \fBSESAME\fR task invokes the Sesame name resolver service from CDS to
+convert an object identifier (e.g. catalog name) to an ICRS coordinate pair.
+The service will first try to resolve the object using the NED database, and
+if not found will use the Simbad database,  the VizieR database is used to 
+resolve the coordinates as a final option.  The \fItarget\fR parameter may
+be specified as a comma-delimited list or in an @file to resolve multiple
+target names.  If the \fIrange\fR parameter is set, it may contain a range
+string that will be expanded to append numeric values to the \fItarget\fR
+value (e.g. to dynamically create catalog names).
+
+If the \fBverbose\fR parameter is set the ra/dec coords are written to the
+STDOUT where they may be easily scanned into script variables.  If the
+\fIlong\fR parameter is enabled, all known information about the object is
+printed (as name, ra, dec, ra_err, dec_err and object type).
+
+In cases where only a single object is resolved the \fBpos\vR, \fBra\fR,
+\fBdec\fR, \fBraw_err\fR, \fBdec_err\fR, \fBotype\fR, and \fBstatus\fR
+parameters are updated with the resolved values.  The \fRstatus\fR
+parameter will be zero is successful, non-zero is the object could not be
+resolved or the service could not be reached.
+
+.ih
+EXAMPLES
+1. Find the coordinates of M51 (i.e. the dev$pix image):
+
+.nf
+  votools> sesame m51
+  13:29:55.72 +47:13:53.4
+
+  votools> sesame m51 long+
+  m51 13:29:52.69 +47:11:42. 0. 0. Sy
+
+  votools> sesame m51
+  votools> lpar sesame
+         target = "m51"           Target name to resolve
+       (verbose = no)             Print position to stdout?\n
+           (pos = "13:29:55.72 +47:13:53.4") Position (sexagesimal string)
+            (ra = 202.4821936)    Resolved RA (J2000 decimal degrees)
+           (dec = 47.2315089)     Resolved DEC (J2000 decimal degrees)
+        (ra_err = 134.)           Error on Resolved RA (arcsec)
+       (dec_err = 134.)           Error on Resolved DEC (arcsec)
+         (otype = "GPair")        Resolved object type description
+        (status = 0)              Resolved DEC (J2000 decimal degrees)
+          (mode = "ql")           
+.fi
+
+
+2. Create a local copy of the Messier catalog.
+
+.nf
+    votools> for (i=1; i < 100; i=i+1) {
+    >>>          printf ("m%d\n", i) | scan (s1)
+    >>>          sesame (s1, verb-)
+    >>>          printf ("m%d  %s  %s\n", i, sesame.pos, sesame.otype)
+    >>>      }
+
+	or
+
+    votools> sesame m range="1-110" long+ | fields STDIN "1-3"
+.fi
+
+.ih
+REVISIONS
+.le
+.ih
+SEE ALSO
+voclient
+.endhelp