Provided by: stilts_3.1.5-1_all bug

NAME

       stilts-votlint - Validates VOTable documents

SYNOPSIS

       stilts votlint [votable=<location>] [validate=true|false] [version=1.0|1.1|1.2|1.3]
                      [out=<location>]

DESCRIPTION

       The VOTable standard, while not hugely complicated, has a number of  subtleties  and  it's
       not  difficult to produce VOTable documents which violate it in various ways. In fact it's
       probably true to say that most VOTable documents out there are not strictly legal. In some
       cases the errors are small and a parser is likely to process the document without noticing
       the trouble. In other cases, the errors are so serious that it's hard for any software  to
       make  sense  of  it.  In many cases in between, different software will react in different
       ways, in the worst case appearing to parse a VOTable but in fact understanding  the  wrong
       data.

       votlint  is a program which can check a VOTable document and spot places where it does not
       conform to the VOTable standard, or places which look like they  may  not  mean  what  the
       author intended. It is meant for use in two main scenarios:

       * For authors of VOTables and VOTable-producing software, to check that the documents they
         produce are legal and problem-free.

       * For users of VOTables (including authors of VOTable-processing software) who are  having
         problems with one and want to know whether it is the data or the software at fault.

       Validating  a VOTable document against the VOTable schema or DTD of course goes a long way
       towards checking a VOTable document for  errors  (though  it's  clear  that  many  VOTable
       authors don't even go this far), but it by no means does the whole job, simply because the
       schema/DTD specification languages don't  have  the  facilities  to  understand  the  data
       structure of a VOTable document. For instance the VOTable schema will allow any plain text
       content in a TD element, but whether this makes sense in a VOTable depends on the datatype
       attribute  of  the  corresponding  FIELD  element.  There are many other examples. votlint
       tackles this by parsing the VOTable document in a way which understands its structure  and
       assessing  the  content as critically as it can. For any incorrect or questionable content
       it finds, it will output a short message describing the problem and giving its location in
       the document. What you do with this information is then up to you.

       Using  votlint  is very straightforward. The votable argument gives the location (filename
       or URL) of a VOTable document. Otherwise, the document will be read from  standard  input.
       Error  and  warning  messages  will be written on standard error. Each message is prefixed
       with the location at which the error was found (if possible the line and column are shown,
       though  this  is dependent on your JVM's default XML parser). The processing is SAX-based,
       so arbitrarily long tables can be processed without heavy memory use.

       votlint can't guarantee to pick up every possible error in  a  VOTable  document,  but  it
       ought  to  pick  up  many  of  the most serious errors that are commonly made in authoring
       VOTables.

       Note: votlint's handling of XML namespaces seems to  be  somewhat  dependent  on  the  XML
       parser  in  use.  As  far  as  I can see, Crimson (the default in many JREs) works for any
       namespace arrangements, but Xerces seems to have problems when validating documents  which
       use  namespace  prefixes.  Not  sure  about  other  parsers. This probably won't cause you
       trouble, but if it does you may need to set validate=false to work around it. Contact this
       author if this seems to be a serious issue for you.

OPTIONS

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

       validate=true|false
              Whether  to  validate  the  input  document  aganist  the VOTable DTD. If true (the
              default), then as well  as  votlint's  own  checks,  it  is  validated  against  an
              appropriate  version  of the VOTable DTD which picks up such things as the presence
              of unknown elements and attributes,  elements  in  the  wrong  place,  and  so  on.
              Sometimes however, particularly when XML namespaces are involved, the validator can
              get confused and may produce a lot of spurious  errors.  Setting  this  flag  false
              prevents  this  validation step so that only votlint's own checks are performed. In
              this case many violations of the VOTable  standard  concerning  document  structure
              will go unnoticed.

       version=1.0|1.1|1.2|1.3
              Selects  the  version  of the VOTable standard which the input table is supposed to
              exemplify. The version  may  also  be  specified  within  the  document  using  the
              "version"  attribute  of  the document's VOTABLE element; if it is and it conflicts
              with the value specified by this flag, a warning is issued.

              If no value is provided for this parameter  (the  default),  the  version  will  be
              determined from the VOTable itself.

       out=<location>
              Destination file for output messages. May be a filename or "-" to indicate standard
              output.

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-VOTLINT(1)