From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001
From: Joseph Hunkeler <jhunkeler@gmail.com>
Date: Wed, 8 Jul 2015 20:46:52 -0400
Subject: Initial commit

---
 vendor/voclient/doc/voregistry.man | 384 +++++++++++++++++++++++++++++++++++++
 1 file changed, 384 insertions(+)
 create mode 100644 vendor/voclient/doc/voregistry.man

(limited to 'vendor/voclient/doc/voregistry.man')

diff --git a/vendor/voclient/doc/voregistry.man b/vendor/voclient/doc/voregistry.man
new file mode 100644
index 00000000..e4a16de2
--- /dev/null
+++ b/vendor/voclient/doc/voregistry.man
@@ -0,0 +1,384 @@
+.\" @(#)voregistry.1 1.0 June-07 MJF
+.TH VOREGISTRY 1 "July 2007" "VOClient Project"
+.SH NAME
+voregistry \- VO Registry search client
+
+.SH SYNOPSIS
+\fBvoregistry\fP [\-\fI<flags>\fP] [ \fI<keywords>\fP | <\fIterm\fP> ] [ ... ]
+
+.SH OPTIONS
+The \fIvoregistry\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 \-v, --verbose
+Verbose output.  The output will be more verbose than normal but exactly
+what is printed depends on whether other flags are enabled to changed the
+basic task behavior.
+.TP 8
+.B \--vverbose
+Very-verbose output.  Even more output.
+.TP 0
+The following flags control the major behavior of the task, i.e. the type
+of output to present.
+.TP 8
+.B \-c, --count
+Print a count of matching records.  For each of the search terms, a simple
+count of matching resources will be printed.  A breakdown by service type 
+will be printed if the verbose flag is enabled.
+.TP 8
+.B \-e, --exact
+Match exactly the search term (resolve mode only).  The \fIterm\fP in this
+case will normally be an IVO identifier, this flag can be used to match the
+identifier exactly rather than as a potential substring.  This option will
+return an empty string if no exact match is found.
+.TP 8
+.B \-l, --list
+List the full resource record for each matching resource.  For each matching
+resource, all (well, most) of the information available about a resource
+will be printed to the screen.  Additional information may be available from
+the Registry web interface.
+.TP 8
+.B \-m, --meta
+List the metadata for the data services associated with the resource.  For
+each resource found, the table metadata (i.e. the column UCD values)
+associated with the resource will be printed.  Currently only those DAL
+services supported by VOClient may be queried.
+.TP 8
+.B \-r, --resolve
+\fIResolve\fP the search term to a specified resource.  In \fIresolve mode\fP
+the search terms are assumed to be either the resource \fIShortName\fP or
+\fIIdentifier\fP and the match will be done using only these two fields in
+the Registry resource record.  The default output is simply the
+\fIServiceURL\fP for all matching records (i.e. resources where the search 
+string is part of the \fIShortName\fP or \fIIdentifier\fP fields) unless
+the \fI-f\fP flag is given to select other fields.
+.TP 0
+Shorthand Convenience Options:
+.TP 8
+.B \-I, --id
+Print only the \fIIdentifier\fP field for the resolved resource.
+.TP 8
+.B \-L, --long 
+Suppress the linebreaks imposed for output fields that would wrap around the
+normal 80-character output and allow long lines.  This allows tasks to parse
+the output more predictably.
+.TP 8
+.B \-R, --Resolve
+Print the \fIShortName\fP, \fIServiceType\fP and \fIIdentifier\fP fields for 
+the resolved resource.
+.TP 8
+.B \-S, --SName
+Print only the \fIShortName\fP field for the resolved resource.
+.TP 8
+.B \-T, --Title
+Print only the \fITitle\fP for the resolved resources.
+.TP 0
+Constraint Options:
+.PP
+The list of allowed constraint strings is generally specified in the
+\fIResource Metadata for the Virtual Observatory\fP document available on 
+the IVOA document repository.  These flags provide a convenient method to 
+limit a result list to resources that explicitly specify a value for the 
+given constraint.
+.TP 8
+.B \-b, --bandpass <bpass>
+Constrain the search to the specified bandpass string.  
+The text argument following the -f flag
+will be matched against the \fISpectralCoverage\fP field of the resource
+record.  Registry resources allow a list of values, however only a single
+argument may be used to constrain the search.  Permitted values include:
+"Radio", "Millimeter", "Infrared" (IR), "Optical", "Ultraviolet" (UV),
+"X-Ray" (XRay), and "Gamma-Ray" (GR).  The match is case insensitive, values
+shown in parentheses may be given and will be substituted automatically.
+.TP 8
+.B \-C, --clevel <content>
+Constrain the search to the specified ContentLevel string.  The Registry 
+may contain data for a variety of intended audiences;  Most often this
+constraint will be used to limit the results to 'Research' grade data.
+.TP 8
+.B \-d, --dal
+Constrain the search to only standard DAL services.  A general keyword search will
+normally return all resources, including those referring to custom services or
+non data-access entries.  Use of the \fI-d\fP flag will restrict results to only
+those resource records describing a standard VO data-access service.
+.TP 8
+.B \-g, --group
+Group the search terms to form a single query.
+.TP 8
+.B \-s, --subject <subject>
+Constrain the search to the specified Subject string.  Note that multi-word
+subjects (e.g. "cool stars") must either be quoted or have the space escaped
+for the subject to be queried correctly.  A substring, case-insensitive search
+of the Subject field is performed.
+.TP 8
+.B \-t, --type <type>
+Constrain the search to the specified ResourceType string.  The Registry 
+records may contain any user-specified string, however unless you know
+specifically how a specific resource is defined, this constraint should
+use the values 'catalog' (for Cone services), 'image' (for SIAP 
+services), 'spectra' (for SSAP services), 'table' (for Vizier tables), 
+or a literal string which appears in the
+resource record.  Additional aliases will be added as new
+data services are supported.
+.TP 8
+.B \-N, --new <time>
+Constrain the search to those resources that have been newly created during
+the specified <time>.  By default, <time> is an integer value assumed to be
+a number of days, the last character may contain one of the qualifying
+characters to change the time period:  'h' for hours, 'd' for days,
+'w' for weeks, and 'm' for months.  For example, the <time> string "6m"
+refers to the last siz months.  If no search term is given, all results
+for that period will be returned, otherwise only those results that match
+both the search terms and the time constraint will be listed.
+.TP 8
+.B \-U, --updated <time>
+Constrain the search to those resource records that have been updated during
+the specified time period.
+.TP 0
+Output Control Options:
+.TP 8
+.B \-a, --all
+Output all matching records (default).  When used with the constraint flags
+above, this flag will allow those constraint strings to be matched as a 
+substring, e.g. using "-t siap" will exactly match resources with type
+'siap', but using "-a -t siap" will also match 'siap/cutout' services.
+.TP 8
+.B \-f, --fields <fields>
+Output the specified fields from the resource record (used in Resolve Mode
+only).  The list of available fields is given below, an 'INDEF' string is
+printed for invalid field names or when no information is available.
+.TP 8
+.B \-O, --or
+Logically OR the search terms.  By default, all terms will be used when
+matching resource records.
+.TP 8
+.B \-n, --index <index>
+Output only the results for the matchng \fIindex\fP.  Results are 1-indexed,
+i.e. the first result is index 1 (one). 
+.TP 8
+.B \-o, --output <oname>
+Save the results in VOTable format to the file name \fIoname\fP.  The 
+verbose level of the query is increased when using this option.
+.TP 8
+.B \-B, --samp
+Broadcast the results as a SAMP message using a \fItable.load.votable\fP
+message type.
+.TP 8
+.B \-V, --votable
+Write results in VOTable format.
+.TP 8
+.B \-X, --xml
+Write results in VOTable format.
+
+
+.SH DESCRIPTION
+The \fIvoregistry\fP task provides a command-line interface to the \fINVO
+Registry\fP at STScI/JHU.  The task also provides a basic search capability
+for the Registry, as well as a "Resolve Mode" that can be used to lookup
+resource records given some familiar name (e.g. 'USNO-B1').  Constraint
+parameters allow the search to be restricted to resources declaring a
+specific type (the \fI-t\fP flag), spectral coverage (the \fI-b\fP flag), or
+content level (the \fI-C\fP flag). 
+.PP
+Search terms may be provided on the
+command-line, in a filename specified on the commandline, or read from the
+standard input (e.g. redirected from a file or other command).  Advanced 
+users can submit a quoted ADQL string to access specific fields of a resource
+record.  This is similar to using the "Advanced Search" capability on the 
+NVO Registry web page.  ADQL strings are required to be in double quotes 
+when given on the command line, the quotes are needed when query strings 
+come from a file.  Standard SQL operators apply for comparison and boolean
+operations, the 'like' operator is used to match strings (which must be in
+single quotes), one or more '%' metacharacters may be used in the string
+to indicate a wildcard match.
+.PP
+In the default search mode, keywords given on the command line will all be
+used to match resource records.  The \fI-o\fR flag may be used to logically
+OR the keyword terms, e.g. to allow a search of 'galaxy' or 'galaxies'.  The
+minimal output provides the resource title, type, subject and the 'ShortName'
+that can be used in the resolve mode or be passed to other tasks such as 
+vodata(1).  Additional output can be had with the \fI-v\fR or \fI-vv\fP
+verbose flags.  A simple count of the resources will be printed if the
+\fI-c\fP flag is set (e.g. the command "voregistry -oc chandra spitzer"
+will print a count of how many records match each term rather than display
+them directly, without the -o flag a count of resources mentioning both
+keywords will be printed).
+.PP
+The "Resolve mode" is activated by the \fI-r\fR flag;  In this mode the
+keywords will only be matched against the Registry \fIShortName\fP and
+\fIIdentifier\fR fields.  The default output is simply the  \fIServiceURL\fR,
+adding the verbose flags will instead print the ShortName, ResourceType and
+Title (with "-v") or Description (with "-vv").  The user can select specific
+fields to be printed using the \fI-f\fP flag followed by a comma-delimited
+list of fields.  The allowed fields are shown with the \fI-h\fP help flag.
+.PP
+The \fI-list\fP flag implies Resolve Mode and will cause all fields of the 
+matching resource to be printed.  Unless the \fI-a\fP flag is set, the 
+search term will be matched exactly, otherwise it will be considered to be 
+a substring of the ShortName or Identifier fields.  For example, searching
+with the term '2mass' will list only 2MASS image service, but using the
+\fI-a\fP flag will list all services where '2mass' appears in the ShortName.
+.PP
+The \fI-meta\fP flag likewise assumes the command line arg is a resource 
+ShortName to be resolved and will query the DAL service associated with it
+using a \fIFORMAT=METADATA\fP query.  The default position will be (0.0,0.0)
+with a search size of 0.1 degrees, the response will be a list of the column
+UCDs returned by the query (note that adding \fI-v\fP flags will likewise
+increase the VERBOSE of the query and may return additional columns).
+
+.SH RETURN STATUS
+The task will exit with a status of 0 if at least one search term could
+be successfully resolved, otherwise the status will be 1.
+
+.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 RESOURCE CACHING
+Registry resolution is a common activity of VO-CLI tasks and so results 
+will be cached in the $HOME/.voclient/cache/regResolver directory based
+on the search term, service type and bandpass parameters.  Defining the
+\fIVOC_NO_CACHE\fP environment variable will cause the task to ignore the
+cache.
+
+
+.SH EXAMPLES
+
+.TP 4
+1)
+Get a count of all the SIAP services available in the Registry, then
+list more information about each one:
+.nf
+
+	% voregistry --count -t image
+	142
+	% voregistry -rv -t image
+
+.fi
+.TP 4
+2)
+Find all catalog (i.e. Cone) services using the search words 'radio'
+and 'galaxies':
+.nf
+
+	% voregistry -t catalog radio galaxies
+
+.fi
+.TP 4
+3)
+Print the full resource record of the GSC2.2 catalog at STScI:
+.nf
+
+	% voregistry --list GSC2.2
+
+.fi
+.TP 4
+4)
+Find all services with radio data of Abell clusters.  Then print the
+full description of the first record associated with one of the matching
+Vizier tables:
+.nf
+
+	% voregistry -b radio abell
+	% voregistry -rvv -n 1 J/A+A/446/97/tab
+
+.fi
+.TP 4
+5)
+Find all image services that have WFPC data:
+.nf
+
+	% voregistry -v -t image wfpc
+
+.fi
+.TP 4
+6)
+Print a breakdown of VO services having Keck data:
+.nf
+
+	% voregistry -cv keck
+	keck           122   (Cat: 2  Tab: 117 SNode: 1  Other: 2)
+
+.fi
+.TP 4
+7)
+Print a count of services having all of Chandra, HST and Spitzer data,
+then break it down by each mission:
+.nf
+
+	% voregistry -c chandra hst spitzer
+	chandra hst spitzer         3
+	% voregistry -co chandra hst spitzer
+	chandra                   323
+	hst                       443
+	spitzer                    31
+
+.fi
+.TP 4
+8)
+Print the column metadata returned by the GSC2.2 service:
+.nf
+
+	% voregistry --meta gsc2.2
+
+.fi
+.TP 4
+9)
+Use the ADQL query format to find services in which HST was the used,
+and not simply a match of 'HST' in the resource record:
+.nf
+
+	% voregistry "Facility like 'HST'"
+
+.fi
+Note that use assumed knowledge of the Registry being queried, specifically
+that there exists a 'Facility' field with this information and that the
+syntax of the query requires the string to be in quotes.
+
+.TP 4
+10) Use the ADQL query format to find services in which 'Keck' appears in
+the Title of the resource:
+.nf
+
+	% voregistry "Title like '%Keck%'"
+
+		or
+
+	% cat query.txt
+	Title like '%Keck%'
+	% cat query.txt | voregistry
+
+.fi
+Note that here we use the '%' operator around the string so that we perform
+a substring match on the entire title.  As before, the ADQL string itself
+must be enclosed in double quotes.
+
+.TP 4
+11) Find all resources that are newly registered in the last 3 months, then
+find only those resources dealing with "cool stars", and finally just print
+a count of resources updated in the last year:
+.nf
+
+	% voregistry --new 3m
+	% voregistry --new 3m cool stars
+	% voregistry --updated 12m --count
+
+.fi
+
+.SH BUGS
+Some services don't repond properly to the metadata query and will print
+a "no attributes found" message.
+.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), vosesame(1), vodata(1)
-- 
cgit