Ubuntu Manpage: stilts-votcopy - Transforms between VOTable encodings

NAME

       stilts-votcopy - Transforms between VOTable encodings

SYNOPSIS

       stilts votcopy [in=<location>] [out=<location>] [format=TABLEDATA|BINARY|BINARY2|FITS]
                      [version=1.0|1.1|1.2|1.3] [charset=<xml-encoding>] [cache=true|false]
                      [href=true|false] [nomagic=true|false] [base=<location>]

DESCRIPTION

The VOTable standard provides for three basic encodings of the actual data within each
table: TABLEDATA, BINARY and FITS. TABLEDATA is a pure-XML encoding, which is relatively
easy for humans to read and write. However, it is verbose and not very efficient for
transmission and processing, for which reason the more compact BINARY format has been
defined. FITS format shares the advantages of BINARY, but is more likely to be used where
a VOTable is providing metadata 'decoration' for an existing FITS table. In addition, the
BINARY and FITS encodings may carry their data either inline (as the base64-encoded text
content of a STREAM element) or externally (referenced by a STREAM element's href
attribute).

These different formats have their different advantages and disadvantages. Since, to some
extent, programmers are humans too, much existing VOTable software deals in TABLEDATA
format even though it may not be the most efficient way to proceed. Conversely, you might
wish to examine the contents of a BINARY-encoded table without use of any software more
specialised than a text editor. So there are times when it is desirable to convert from
one of these encodings to another.

votcopy is a tool which translates between these encodings while making a minimum of other
changes to the VOTable document. The processing may result in some changes to lexical
details such as whitespace in start tags, but the element structure is not modified.
Unlike tpipe it does not impose STIL's model of what constitutes a table on the data
between reading it in and writing it out, so subtleties dependent on the exact structure
of the VOTable document will not be mangled. The only important changes should be the
contents of DATA elements in the document.

OPTIONS

in=<location>
Location of the input VOTable. May be a URL, filename, or "-" to indicate standard
input. The input table may be compressed using one of the known compression formats
(Unix compress, gzip or bzip2).

out=<location>
Location of the output VOTable. May be a filename or "-" to indicate standard
output.

format=TABLEDATA|BINARY|BINARY2|FITS
Determines the encoding format of the table data in the output document. If null is
selected, then the tables will be data-less (will contain no DATA element), leaving
only the document structure. Data-less tables are legal VOTable elements.

The BINARY2 format is only available for version=1.3

version=1.0|1.1|1.2|1.3
Determines the version of the VOTable standard to which the output will conform. If
null (the default), the output table will have the same version as the input table.

charset=<xml-encoding>
Selects the Unicode encoding used for the output XML. The available options are
dependent on your JVM, use help=charset for a full listing. Setting the value null
will use the JVM's system default.

cache=true|false
Determines whether the input tables are read into a cache prior to being written
out. The default is selected automatically depending on the input table; so you
should normally leave this flag alone.

href=true|false
In the case of BINARY or FITS encoding, this determines whether the STREAM elements
output will contain their data inline or externally. If set false, the output
document will be self-contained, with STREAM data inline as base64-encoded
characters. If true, then for each TABLE in the document the binary data will be
written to a separate file and referenced by an href attribute on the corresponding
STREAM element. The name of these files is usually determined by the name of the
main output file; but see also the base flag.

nomagic=true|false
Eliminate the null attributes of VALUES elements where they are no longer required.
In VOTable versions <=1.2, the only way to specify null values for integer-type
scalar columns was to use the null attribute of the VALUES element to indicate an
in-band magic value representing null. From VOTable v1.3, null values can be
represented using empty <TD> elements or flagged specially in BINARY2 streams. In
these cases, it is recommended (though not required) not to use the VALUES/null
mechanism.

If this parameter is set true, then any VALUES/null attributes will be removed in
VOTable 1.3 BINARY2 or TABLEDATA output. If this results in an empty VALUES
element, it too will be removed.

This parameter is ignored if the output VOTable version is lower than 1.3 or if
format=BINARY/FITS.

base=<location>
Determines the name of external output files written when the href flag is true.
Normally these are given names based on the name of the output file. But if this
flag is given, the names will be based on the <location> string. This flag is
compulsory if href is true and out=- (output is to standard out), since in this
case there is no default base name to use.

VERSION

       STILTS version 3.1-2-debian

       This is the Debian version of Stilts, which lack the support  of  some  file  formats  and
       network protocols. For differences see
       file:///usr/share/doc/stilts/README.Debian

AUTHOR