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