diff options
Diffstat (limited to 'vendor/voclient/doc/OLD/vosesame.man')
| -rw-r--r-- | vendor/voclient/doc/OLD/vosesame.man | 260 |
1 files changed, 260 insertions, 0 deletions
diff --git a/vendor/voclient/doc/OLD/vosesame.man b/vendor/voclient/doc/OLD/vosesame.man new file mode 100644 index 00000000..4e5d5f5c --- /dev/null +++ b/vendor/voclient/doc/OLD/vosesame.man @@ -0,0 +1,260 @@ +.\" @(#)vosesame.1 1.0 June-07 MJF +.TH VOSESAME 1 "July 2007" "NVO VO-CLI Project" +.SH NAME +vosesame \- call the Sesame name resolver service +.SH SYNOPSIS +\fBvosesame\fP [\-\fIadefhinstACHT\fP] [\fIfile\fP | \fItarget\fP ] [ ... ] + +.SH OPTIONS +The \fIvosesame\fP task accepts the following options: +.TP 8 +.B \-h, --help +Print a help summary to the terminal and exit. No processing is done +following this flag. +.TP 8 +.B \-q, --quiet +Quiet mode (suppress warning output). +.TP 8 +.B \-v, --verbose +Verbose output. Normally used to print warnings when an object could not be +resolved. +.TP 0 +The following flags may be combined as a single option to indicate the +desired output fields. The order of the flags implies the order of the +output values, e.g. "-dnt" prints the decimal position, name and type in +that order. +.TP 8 +.B \-a, --all +Output all available information about the object. +.TP 8 +.B \-d, --decimal +Output the position as J2000 decimal degrees. This is the default output if +no format flags are specified. +.TP 8 +.B \-e, --errors +Output the estimated position errors. +.TP 8 +.B \-n, --name +Output the object name. +.TP 8 +.B \-t, --type +Output the object type. +.TP 8 +.B \-s, --sex +Output the position as sexagesimal RA and Dec. + +.TP 0 +Control Flags: +.TP 8 +.B \-c <ra> <dec> or \-c <ra>,<dec> or \--coord-<ra>,<dec> +Specify a coordinate to be explicitly used. If set an RA and DEC are +expected as either the next argument if they are a comma-separated string, +or as the next two arguments. Values may be input as floating point +decimal or sexagesimal strings. Upon receipt, the task will create an +artifical record for the object and output the values requested with the +output flags described above. Multiple \fI-c\fP options may be specified +may be specified and mixed with object names, user coordinates are processed +before the object names are resolved in the order they occur on the command +line. +.TP 8 +.B \-i, --invert +Invert the sense of the search and print only objects which cannot be +resolved to coordinates. +.TP 8 +.B \-f, --force +Force the object(s) to be resolved even if it is cached. This option will +cause the task to call the Sesame service rather than output a previously +cached value, however the result will still be cached unless the VOC_NO_CACHE +environment variable is defined. +.TP 8 +.B \-o <name> or --output=<name> +Specify the output file. The default is to write the results to the +standard output. + +.TP 0 +Formatting Flags: +.TP 8 +.B \-A, --ascii +Print the results as a whitespace delimited ascii table. If an output file +is specified it will have a ".txt" extension appended automatically. +.TP 8 +.B \-C, --csv +Print the results as a comma-separated-value (CSV) table. If an output file +is specified it will have a ".csv" extension appended automatically. +.TP 8 +.B \-H, --header +Print a table header. The table header will be a single line beginning with +a '#' character to indicate a comment, and followed by the name of each +column in the specified format. +.TP 8 +.B \-T, --tsv +Print the results as a tab-separated-value (TSV) table. If an output file +is specified it will have a ".csv" extension appended automatically. + +.SH DESCRIPTION +The \fIvosesame\fP task provides a command-line interface to the +\fISesame\fP name +resolver service at CDS that convert a familiar object name to the J2000 +coordinates required by VO services. Additional information +such such as the object type is also available. The \fISesame\fP service +queries NED, Simbad and Vizier databases for this information. If no +flags are provided, the default output is simply the RA and Dec of the +object in decimal degrees (this is what most VO services expect), however +command-line flags provide a method to specify the desired output and +the order in which they are printed. +.PP +Object names may be specified on the commandline individually (multiple +arguments are allowed), as the name of a file containing a list of +objects to be resolved, or both. If no object or file names are given on +the command line the task will read from the standard input, allowing the +task to be used as a command filter or interactively from the keyboard. +Files containing object names are assumed +to list the name of one object-per-line where whitespace in the object name +is allowed on the line (e.g. "M 51"). From the command line, most shell +interpreters will require that the whitespace be escaped (e.g. "M\ 51") +so it is interpreted properly. A warning will be printed if an object name +cannot be resolved and the \fI-v\fP verbose flag is set, otherwise no +output will be printed for the failed request. +.PP +The \fIOPTIONS\fP section describes the formatting options available. +For each of these options, the order in which it appears controls the order of +where it appears in the output string for the object. Output format +flags control how the values are printed. Supported formats include +comma-separated-values (CSV, the \fI-C\fP flag), tab-separated-values (TSV, +the \fI-T\fP flag), whitespace-delimited values (the \fI-A\fP default), +and may include an optional head (the \fI-H\fP) flag) that precedes the +output with a line of text listing the output colums where the first +character of the header is a '#' to indicate a comment. + +.SH VOCLIENT DAEMON PROCESSING +All VO-CLI tasks are built upon the VOClient interface an rely on a +separate \fIvoclientd\fP process to provide the VO functionality. The +voclientd task is distributed as part of VO-CLI and will be started +automatically by each task if it is not already running. If problems +are encountered, you may want to manually start the voclientd in a separate +window before running the task so you can monitor the output for error +messages. + +.SH OBJECT CACHING +The \fBSesame\fP service at CDS is normally fairly reliable, however there +are times when it is either unavailable, or simply returns a null result +without indicating an error. Additionally, the access time is on the +order of ~1 sec/object and so resolving many objects creates an overhead +for applications using this service. +.PP +The \fBvosesame\fP task's only function is to resolve objects, however it +still uses the object caching capability in the VOClient interface. Once +an object is resolved, it will automatically be cached unless the +\fBVOC_NO_CACHE\fP environment variable is defined. The \fI-f\fP +command-line option can be used to override any existing cached values and +force the Sesame service to be invoked. The object cache may be initialized +completely by deleting the $HOME/.voclient/cache/sesame directory. + +.SH RETURN STATUS +If all objects were successfully resolved the task will exit with a +status code of 0. If one or more of the objects failed to be resolved for +any reason, the exit status will be the number of unresolved objects. + + +.SH EXAMPLES + +.TP 4 +1) +Print the coordinates of NGC4456, first in decimal degrees and +then as sexagesimal values: + +.nf + % vosesame ngc4456 + 186.960000 -30.120000 + % vosesame -s ngc4456 + 12:27.8 -30:07 +.fi + +.TP 4 +2) +Print the sexagesimal coordinates of multiple objects, include the type: + +.nf + % vosesame -st m31 m51 m99 + 00:42:44.31 +41:16:09.4 LINER + 13:29:52.36 +47:11:40.8 Seyfert_2 + 12:18:49.51 +14:25:00.4 HII_G +.fi + +.TP 4 +3) +Print the decimal coordinates of those same objects listed in +the file 'myobjs.txt', output as CSV, include a header, and print +the id, coords, and type: + +.nf + % vosesame -CHndt myobjs.txt + #Name,DRA,DDEC,Type, + m31,10.684625,41.269278,LINER + m51,202.468208,47.194667,Seyfert_2 + m99,184.706333,14.416778,HII_G + : : : : +.fi + +.TP 4 +4) +Extract the object names from column 17-25 of a file and pipe the +list to vosesame to create a new table of id, ra and dec: + +.nf + % cut -c17-25 data.txt | vosesame -ns + m51 13:29:52.36 +47:11:40.8 + m23 17:57:00.00 -18:58:59.9 + m67 08:51:17.99 +11:48:00.0 + : : : +.fi + +.TP 4 +5) +Interactively resolve coordinates by enterying object names on the +standard input: +.nf + + % vosesame -a + m98 + m98 12:13:48.37 +14:53:57.9 183.45154 14.89944 10.0 10.0 LINER + [EOF] + +.fi +Type the EOF character (typically Ctrl-D or Ctrl-Z) to quit. + + +.TP 4 +6) +Print the sexagesimal and decimal values for multiple user coords: +.nf + + % vosesame -sd -c 12:30:0.0 -45:00:0.0 -c 187.5 2.05 + 12:30:00.0 -45:00:00.0 12.500000 -45.000000 + 12:30:00.0 02:03:00.0 187.500000 2.050000 + +.fi + + +.SH BUGS +The Sesame service can sometimes respond without resolving the object. In +this case all values are returned as zero or a null string. \fIVosesame\fP +will sense this as a non-response and not print a result. If the +\fIverbose\fP flag is set a warning message will be printed. +.SH Revision History +June 2007 - This task is new. +.SH Author +Michael Fitzpatrick (fitz@noao.edu), July 2007 +.SH "SEE ALSO" +voclient(1), voclientd(1), vodirectory(1), vodata(1) +.SH BUGS +The Sesame service can sometimes respond without resolving the object. In +this case all values are returned as zero or a null string. \fIVosesame\fP +will sense this as a non-response and not print a result. If the +\fIverbose\fP flag is set a warning message will be printed. +.SH Revision History +June 2007 - This task is new. +.SH Author +Michael Fitzpatrick (fitz@noao.edu), July 2007 +.SH "SEE ALSO" +voclient(1), voclientd(1), vodirectory(1), vodata(1) |