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

  1. create an XML document, and
  2. 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.


Topic revision: r2 - 2022-05-04 - MarkusDemleitner
 
This site is powered by the TWiki collaboration platformCopyright © 2008-2022 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback