Ubuntu Manpage: stilts-votlint - Validates VOTable documents

NAME

       stilts-votlint - Validates VOTable documents

SYNOPSIS


       stilts votlint [votable=<location>] [ucd=true|false] [unit=true|false] [maxrepeat=<int-value>]
                      [validate=true|false] [version=1.0|1.1|1.2|1.3|1.4|1.5] [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 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 check‐
ing a VOTable document for errors, 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 output. 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). If multiple instances of the same problem are found, by default only a few repeats of the mes‐
sage are reported; this can be controlled with the maxrepeat parameter. 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 the 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 indi‐
cate standard input. The input may be compressed using one of the known compression formats (Unix
compress, gzip or bzip2).

ucd=true|false
If true, the ucd attributes on FIELD and PARAM elements etc are checked for conformance against
the UCD1+ standard or a list of known UCD1 terms.

unit=true|false
If true, the unit attributes on FIELD and PARAM elements are checked for conformance against the
VOUnits standard; if false, no such checks are made.

The VOTable 1.4 standard recommends use of VOUnits, though there are some inconsistencies in the
text on this topic. Earlier VOTable versions refer to a different (CDS) unit syntax, which is not
checked by votlint. So by default unit syntax is checked when the VOTable is 1.4 or greater, and
not for earlier versions, but that can be overridden by giving a true or false value for this pa‐
rameter.

The wording of the VOTable and VOUnit standards do not strictly require use of VOUnit syntax even
at VOTable 1.4, so failed checks result in Warning rather than Error reports.

maxrepeat=<int-value>
Puts a limit on the number of times that the same issue will be reported. With this set to a rela‐
tively small number, the output is not cluttered with many repetitions of the same problem.

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 val‐
idator 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|1.4|1.5
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 is‐
sued.

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.

VERSION

       STILTS version 3.4.9-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