TAP v1.1 - References Suggestion

Markus Demleitner msdemlei at ari.uni-heidelberg.de
Wed Feb 7 08:38:03 CET 2018


Hi James,

On Wed, Feb 07, 2018 at 07:17:48AM +0000, James.Dempsey at csiro.au wrote:
> I'm revisiting the TAP v1.1 spec and it struck me that the way it
> references other standards makes the document harder to read.
> 
> An example from 2.7.6 Upload is
> 
> "The UPLOAD parameter is described in (Dowler and Demleitner et
> al., 2017). Services should support the upload of temporary tables
> (in (Ochsenbein and Williams et al., 2013) format) via the...."

I agree.  In the ivoatex documentation
(http://ivoa.net/documents/Notes/IVOATex, sect. 3.3.2), I wrote the
following on this:

  To reference an IVOA recommendation, locate its bibcode either using
  ADS or directly within ivoatex/docrepo.bib and then use one of the cite
  macros. The preferred style is to introduce a short name for the standard
  once with a citation and then use that short name in the remainder of the
  document to have expressive texts not overciting. For instance,

    IVOA Identifiers \citep{2007ivoa.spec.0314P} introduces URIs to
    reference Registry records, which are typically transmitted in
    VOResource \citep{2008ivoa.spec.0222P} format. Both VOResource
    and IVOA Identifiers are based on various W3C standards.
  
  ...

Recently, in ADQL, Dave wrote a couple of macros where you could
write \VOTableSpec -- on the first use, that would expand to "the
VOTable specification \citep{...}", subsequently then just "the
VOTable specification".  I'm not 100% happy with it, partly on
technical grounds[1], partly because sometimes the expanded text comes
out fairly clumsy, but it may be worth a look.

It's in ivoa-cite.tex in ADQL's volute repo:

https://volute.g-vo.org/svn/trunk/projects/dal/ADQL

> Should we wish to make this change, I am volunteering to make it.

Whatever style you eventually choose (where my vote at this point is
for ivoatexDoc style; oh, and note that the optional arguments to
citep and citet are not (yet) supported in ivoatex -- they'll not
come out in the HTML rendering), +1 from me.

      -- Markus


[1] Mainly: if there is such a facility, it should be autogenerated,
presumably from docrepo.bib plus perhaps a bit.


More information about the dal mailing list