Initial commit

1 files changed, 107 insertions, 0 deletions

diff --git a/vo/votools/doc/votget.hlp b/vo/votools/doc/votget.hlp
new file mode 100644
index 00000000..cdbf7637
--- /dev/null
+++ b/vo/votools/doc/votget.hlp
@@ -0,0 +1,107 @@
+.help votget Mar12 votools
+.ih
+NAME
+votget -- Download data referenced in a VOTable
+.ih
+USAGE
+votget input base
+.ih
+PARAMETERS
+.ls input
+The list of input VOTables.
+.le
+.ls base
+The base output filename.
+.le
+.ls extn = "fits"
+Filename extension.  The \fIextn\fR string will be appended to each
+downloaded filename.
+.le
+.ls format
+Format to download.  If not a null string and the \fIextn\fR string is a
+substring of the value of the column containing the UCD "VOX:Image_Format",
+the referenced file will be downloaded.
+.le
+.ls acref = "VOX:Image_AccessReference"
+The UCD of the column containing the image access reference.
+.le
+.ls col = INDEF
+The (one-indexed) column number containing the image access reference.  If
+specified, the UCD values will be ignored and the specific column will be
+used.
+.le
+.ls sequential = yes
+If enabled, sequential file numbers will be appended to the \fIbase\fR
+name for each downloaded file.  Otherwise, an image name will be constructed
+from the access URL.  In the latter case, no check is made to prevent 
+overwriting of files.
+.le
+.ls nthreads = 4
+Number of simultaneous download threads to execute.
+.le
+.ls list = no
+List access references instead of downloading?  Enabling this option may
+be used to extract a list of access URLs from the table.
+.le
+
+.ih
+DESCRIPTION
+
+The \fIVOTGET\fR task is used to download data referenced in a VOTable
+(e.g.  the result of a query to an image or spectral service) to the local
+machine.  The \fIinput\fR parameter may be a list of VOTables, in which
+case the parameters will apply to all files in input the list.  The
+\fIformat\fR parameter is used to select the image format to download from
+the file, it is a case-insensitive substring of the VOTable column
+containing the UCD "VOC:Image_Format".  If this column does not exist, or
+if the \fIformat\fR parameter is the null string, then all images will be
+retrieved.  The \fIacref\fR parameter parameter specified the UCD that
+identifies the access reference to retrieve (i.e. a table may contain
+multiple URLs per row, the UCD uniquely identifies the desired data
+column), the default value of "VOX:Image_AccessReference" is the standard
+value used for current VO data services.  Alternatively, the \fIcol\fR
+parameter may be used to specify the column number (one-indexed) to
+retrieve (e.g. to download other URLs in the table).
+
+The \fIbase\fR parameter defines the root part of the saved image name, and
+\fIextn\fR provides the extension.  If the \fIsequential\fR parameter is
+set then files will be numbered in the order they were retrieved and saved
+to a filename of the form "\fI<base><seqno>.<extn>\fR".  Otherwise, a
+filename is constructed from the access URL and may or may not be either
+unique or helpful.
+
+Data are retrieved using multiple simultaneous threads in order make most
+efficient use of the network and data service.  The \fInthreads\fR
+parameter determines how many simultaneous downloads will be in progress at
+any one time.  Once a download completes, a new thread is started until all
+files have been retrieved.
+
+The \fIlist\fR parameter may be used to simply extract a list of URLs from
+all of the input tables.  When enabled, the \fIbase\fR paramter is not
+required and a list of URLs, one per line, will be printed on the standard
+output.
+
+
+.ih
+EXAMPLES
+1.  Download all images referenced in the test Simple Image Access service
+result table, saved files will
+
+.nf
+  votools> votget data$sia.xml test
+.fi
+
+2.  Extrace the access URLs from the same table without actually downloading
+the files: 
+
+.nf
+  votools> votget data$sia.xml list+
+.fi
+
+.ih
+REVISIONS
+.le
+.ih
+SEE ALSO
+votcopy
+.endhelp