STILTS-VOTLINT(1)

📦
version 3.5.4 · 5 versions
, in ubuntu stonking

💖 STILTS-VOTLINT — validating VOTable documents, bestie edition 💖

okay so you're about to meet stilts-votlint, a lil command-line icon from the Stilts commands lineup, and honestly? she's here to tell you whether your VOTable is serving or absolutely not it. 🎀

✨ NAME ✨

stilts-votlint — she validates VOTable documents. that's it, that's the job. 💅

📜 SYNOPSIS 📜

stilts votlint [votable=<location>] [ucd=true|false]
               [unit=true|false|null] [maxrepeat=<int-value>]
               [validate=true|false] [version=1.0|1.1|1.2|1.3|1.4|1.5]
               [out=<location>]

🌸 DESCRIPTION 🌸

so the VOTable standard? not, like, wildly complicated. but it has a whole bunch of subtleties, and ngl it is genuinely not hard to produce a VOTable document that violates it in several different ways at once. lowkey iconic behaviour from a spec, honestly. 😭

sometimes the errors are tiny, and a parser will probably just process the document without even noticing anything's up. sometimes the errors are SO serious that basically no software can make sense of the whole thing. and then there's the big middle zone: different software reacts in different ways, and in the worst case it looks like it parsed a VOTable fine but actually understood the wrong data. bestie that's cursed. 💀

votlint is the program that checks a VOTable document and spots places where it doesn't conform to the VOTable standard, plus places that look like they might not mean what the author intended. she's built for two main scenarios:

  • for authors of VOTables and VOTable-producing software — so they can check that the documents they produce are legal and problem-free. 🫶
  • for users of VOTables (yes, including authors of VOTable-processing software) who are having problems with one and want to know whether it's the data or the software that's at fault. the classic who-did-this dilemma. 🙈

validating a VOTable document against the VOTable schema or DTD obviously goes a long way toward checking it for errors — but it by no means does the whole job, simply because the schema/DTD specification languages just 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 that actually makes sense in a VOTable depends on the datatype attribute of the corresponding FIELD element. and there are so many other examples. ✨

votlint tackles this by parsing the VOTable document in a way that understands its structure, and assessing the content as critically as she possibly can. for any incorrect or questionable content she finds, she'll output a short message describing the problem and giving its location in the document. what you do with that info after? entirely up to you, bestie. 💅

using votlint is very straightforward. the votable argument gives the location (filename or URL) of a VOTable document. otherwise, the document gets read from standard input. error and warning messages get written on standard output. every message is prefixed with the location at which the error was found — if possible the line and column are shown, though that's dependent on your JVM's default XML parser. if multiple instances of the same problem show up, by default only a few repeats of the message are reported; you control that 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 she ought to pick up many of the most serious errors that are commonly made in authoring VOTables. no cap. 🌈

Note: votlint's handling of XML namespaces seems to be somewhat dependent on the XML parser in use. as far as the author 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> — the location of the VOTable to be checked. this can be a filename, a URL, or "-" (which is the default) to indicate standard input. the input may be compressed using one of the known compression formats (Unix compress, gzip or bzip2). she's flexible like that. 💜
  • 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|null — 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 standard version 1.4 and later recommends use of VOUnits (there are some inconsistencies in the text on this topic in VOTable 1.4, but these are cleared up in V1.5). 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 parameter. 🎀

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. she's not mad, she's just disappointed energy. 😭

  • maxrepeat=<int-value> — puts a limit on the number of times that the same issue will be reported. set it to a relatively small number and the output won't be cluttered with many repetitions of the same problem. spam filter but for your own VOTable.
  • validate=true|false — whether to validate the input document against 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, though — 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 that case, many violations of the VOTable standard concerning document structure will go unnoticed. so pick your poison, bestie. 💀
  • 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 issued. 👀

if no value is provided for this parameter (the default), the version will be determined from the VOTable itself. she'll just figure it out herself, main character energy. 💅

  • out=<location> — destination file for output messages. may be a filename or "-" to indicate standard output. 📝

🦋 SEE ALSO 🦋

if the package stilts-doc is installed, the full documentation SUN/256 is available in HTML format at:

file:///usr/share/doc/stilts/sun256/index.html

⭐ VERSION ⭐

STILTS version 3.5.4-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)

okay that's the whole page, bestie. go forth and validate. and just so you know — this was the Stilts commands manual for STILTS-VOTLINT(1), dated Mar 2017. mwah 💅✨🍓

📦 where this page comes from