Registering Documents
To make educational material (tutorials, notebooks, use cases, etc) more visible and discoverable, you can put them into the VO Registry. This process uses a Registry extension currently described in an
IVOA Note from 2018. It lets people find them in general Registry query interfaces (e.g.,
Documents in WIRR) or in the formatted list at
VO Text Treasures.
To do that, you have to
- create an XML document, and
- get that into the Registry.
Creating a DocRegExt Resource Record
To describe your resource, start from an existing resource, for instance
gavo_addpms or, for documents available in multiple languages,
aida_andromeda.
In practice, you proabably want to use the following template:
<ri:Resource
status="active"
xsi:type="doc:Document"
created="(YYYY-MM-DDThh:mm:ssZ)"
updated="(initially, as created)"
xmlns:doc="http://www.ivoa.net/xml/DocRegExt/v1"
xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
xmlns:ri="http://www.ivoa.net/xml/RegistryInterface/v1.0">
<title>(Be succinct but expressive here)</title>
<identifier>(see below)</identifier>
<altIdentifier>doi:(if you have one, else delete the element)</altIdentifier>
<curation>
<publisher>(your institute's name</publisher>
<creator>
<name>(author name in Last, I. format)</name>
</creator>
<!-- more creator elements as necessary -->
<date role="Inspected">(YYYY-DD-MM of when you last tried it)</date>
<contact>
<name>(Real name)</name>
<email>(ideally, an institutional address)</email>
<telephone>(if you want, else delete this element)</telephone>
</contact>
</curation>
<content>
<subject>(choose from http://www.ivoa.net/rdf/uat)</subject>
<subject>(this, too)</subject>
<type>Education</type>
<type>Outreach</type> <-- remove if your document is
unsuitable for the general public -->
<description>(about 100 words saying what happens in your
resource, and ideally even why you made it)</description>
<referenceURL>(a landing page if you have one, the document
itself it not)</referenceURL>
<contentLevel>(pick one from
http://www.ivoa.net/rdf/voresource/content_level,
repeat the element if you want more than one)</contentLevel>
<relationship>
<!-- you'll usually want to say what tools/services you use;
just edit or delete the following examples. Be sure to
give ivo-id attributes when you use registered resources. -->
<relationshipType>Cites</relationshipType>
<relatedResource>TOPCAT</relatedResource>
<relatedResource ivo-id="ivo://org.gavo.dc/tap"
>GAVO DC TAP service</relatedResource>
</relationship>
</content>
<capability xsi:type="doc:Edition">
<interface role="rendered" xsi:type="vr:WebBrowser">
<accessURL use="full">(a rendered version -- e.g., a PDF -- of
your document)</accessURL>
</interface>
<interface role="source" xsi:type="vr:WebBrowser">
<accessURL>(source code -- e.g., LaTeX in a VCS, or an ODT --
of your document)</accessURL>
</interface>
<languageCode>(RFC 3066 language code)</languageCode>
<!-- if you have translations, list en first if available,
and add one capability per language -->
</capability>
</ri:Resource>
The
identifier you have to put in here depends on how you will get your document into the Registry, which will be discussed in a moment. In both cases, you need to come up with a short name consisting of lower-case characters, dashes, underscores, and digits. Although not many people will ever type it, it's probably good to not exceed 20 characters here.
If you use purx, just put “ivo://ignored/” in front of that name and put that into identifier. If you use another registry, the registry operator will tell you what to prepend.
Before proceeding, make your your record is
valid XML; this does not catch everything that could possibly go wrong, but a valid record will at least work reasonably well. The simplest way to do that on most platforms is to get yourself
stilts newer than 3.4-3 and then run stilts xsdvalidate.
Getting the Record into the Registry
Unless you run your own publishing registry, the simplest way to make the Registry pick up your record is by using the
purx service. This reads registry records from somewhere on the internet, makes sure they are somewhat sane, and then hands them on to the searchable registries for indexing. To use it, simply put your records next to where you serve your PDF from and paste the resulting URL into purx' enrollment box. You will receive an e-mail to whatever contact address you gave above, and after confirming you really want to publish that resource using the URL in that mail, just wait a day and you should find your record in the searchable registries (and in VOTT).
An alternative is to get an account at the
Euro-VO registry and paste your XML resource into a suitable place; that may be preferable if you really cannot put the XML file online.
Finally, if you have a VO publishing registry (for a list of these, see “Currently Registered Publishing Registries” at the
RofR) near you, they can usually put your resource online, too. Just ask them what do to.