Provided by: stilts_3.1.5-1_all bug

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.

SEE ALSO

       stilts(1)

       If  the  package  stilts-doc  is installed, the full documentation SUN/256 is available in
       HTML format:
       file:///usr/share/doc/stilts-doc/sun256/index.html

VERSION

       STILTS version 3.1-5-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

       Mark Taylor (Bristol University)

                                             Mar 2017                           STILTS-VOTCOPY(1)