publishing documentation resources

[Markus Demleitner]

Dear Laurent,

[for transparency: Laurent and I have just had a live chat here at
the Interop, and this is an attempt to give an actionable summary]

On Sun, May 07, 2023 at 04:22:52PM +0200, Laurent Michel wrote:
> https://saada.unistra.fr/esmail/
> - mailing list search engine
> - elasticsearch frontend
> - already accessible from https://ivoa.net/members/index.html
> - STATUS:  in operation and daily updated
>
> https://saada.unistra.fr/esdoc/interfacePDF.html?index=ivoa
> - IVOA standard search engine
> - elasticsearch frontend + PDF viewer
> - STATUS: in operation and updated on demand

So, these are just browser services; I don't think anyone will
realistically try to discover them through the Registry, so at least
for exposure there's no big win in registering them.  *Perhaps*
it's nice for something like documentation ("VO-related services
provided under authority X").  *If* you think that's worth it, create
a vs:DataService-typed record with an untyped capability having a
vr:WebBrowser-typed interface.  An example you might want to start
from is <ivo://org.gavo.dc/dexter/ui/ui>.

[Plug: whenever you see an ivo:// URI, replace the ivo:// with
http://dc.g-vo.org/I/ and you can resolve it in a common web browser:

  http://dc.g-vo.org/I/org.gavo.dc/dexter/ui/ui
]

This won't make your services show up in TOPCAT (after all: where
should they?), but generic Registry clients will show them, perhaps
like this:

  http://dc.zah.uni-heidelberg.de/wirr/q/ui/fixed?field0=textfields&operator0=%3D&operand0=dexter%20for%20your%20data

As I said, for all I can see that's marginally useful at best.

> https://saada.unistra.fr/voexamples/
> - static pages with examples related to different VO standards
> - individual pages follow the DALI example pattern
> - STATUS: dormant but being revived for MIVOT (not online yet)

These are a different matter, as I can totally see people going to the
registry for "Give me examples for standard X" or so.  Actually, this
is pretty much what DocRegExt is for:
<http://ivoa.net/documents/DocRegExt/>.

Writing DocRegExt records for the examples by standard would also
give you exposure at <https://dc.zah.uni-heidelberg.de/VOTT>, and you
could define relationships to the StandardsRegExt records for the
relevant standards (I'd say that's IsSupplementTo, and we could
actually mention this kind of thing in DocRegExt).

The cool part about this is that you can machine-readably say that
these are machine-readable.  Because DocRegExt records are derived
from vs:CatalogResource, you can add capabilities to them, and there
is a standard id for DALI examples.  So, you can just add a block
like

  <capability standardID="ivo://ivoa.net/std/DALI#examples">
    <interface xsi:type="vr:WebBrowser">
      <accessURL use="full">http://saada.xy.z/examples/tap</accessURL>
    </interface>
  </capability>

to your DocRegExt record, and people could discover TAP example
collections (either standalone or within TAP services) in RegTAP
somewhat like [untested]

  select res_title, access_url
  from rr.resource
    natural join rr.interface
    natural join rr.capability
    natural join rr.relationship
  where (related_resource='ivo://ivoa.net/std/tap'
    and relationship_type='issupplementto')
    or standard_id='ivo://ivoa.net/std/tap'

Considering the magic of that, I'd say that's a fairly reasonable
query -- which is to say: I like the idea.

        -- Markus