.\" @(#)votopic.1 1.0 Feb-2013 MJF
.TH VOTOPIC 1 "Feb 2013" "VOClient Package"
.SH NAME
votopic \- Query for data from resources specified by topic keyword

.SH SYNOPSIS
\fBvotopic\fP [<opts>] <topic> { <object> | <ra> <dec> } [ <size> ]

.SH OPTIONS
The \fIvotopic\fP application accepts the following options:
.TP 6
.B \-h, --help
Print a help summary to the terminal and exit.  No processing is done 
following this flag.

.TP 6
.B All VODATA task options

.SH DESCRIPTION
The \fIvotopic\fP task is a convenience application built on top of the
\fIvodata\fP and \fIvoregistry\fP applications.  Its main purpose is to 
allow a query for data using logical concepts (e.g. "galaxies", "observation
logs") rather than a specific list of resources.  This should limit the
number of resources that need to be queried when querying all data services
and return more relevant results.  This is done by using the \fI<topic>\fP
argument as a keyword search value for the Registry, the resulting resource
list
is then used as input for the VODATA task to query only those resources
returned by the Registry query at the position listed by the \fI<object>fP 
or \fI<ra> <dec>\fP position.   As an example, the topic 'AGN' may be used 
to query only those resources that claim to have something to do with AGN
as opposed to the many hundreds or thousands more that may not contain data
for that field at all but would be queried anyway using the more generalized
approach of \fIVODATA\fP.
.PP
The actual effectiveness or suitability of this approach will depend greatly
on the keywords (i.e. \fItopic\fP) chosen and the aims of a specific query.
.PP
For a complete list of options and a description of the task behavior, see
the \fIVODATA\fP and \fIVOREGISTRY\fP man page.

.SH RETURN STATUS
On exit the \fBvotopic\fP task will return a zero indicating success, or a
one indicating an error.

.SH EXAMPLES
.TP 4
1)  Query for catalog data of A2712 from Resources related to gravitational lensing:

.nf
  % votopic -t catalog lens A2712
.fi
.TP 4
This query is against only 142 services (data found for 128), a similar query against ALL catalog services would require more than 8000 services to be queried.  This is equivalent to the commands

.nf
  % voregistry -t catalog -d -o lens.xml lens 
  % vodata lens.xml A2712
.fi
.TP 4
Here the 'lens.xml' output file contains the resources to be queried, the '-d' flag says to return only DAL services, the '-t' flag resticts by service type.  In the call to VODATA, the 'lens.xml' file defines the 142 resources to be queried, the contraint to service type and DAL-only was done in the registry query that produced the file.

.SH BUGS
No known bugs with this release.
.SH Revision History
Feb 2013 - First public release
.SH Author
Michael Fitzpatrick (fitz@noao.edu), Feb 2013
.SH "SEE ALSO"
vodata, vocatalog, voimage, vospectra, voregistry