[DALI] DAI-examples markup

[Markus Demleitner]

Dear DAL folks,

Let me briefly make my point again -- sorry if I'm boring you.

On Wed, Apr 24, 2013 at 03:10:33PM -0700, Patrick Dowler wrote:
> So, DALI-examples specifies how to markup an (xhtml) document so the
> exmaples for using the service are machine-readable. I have written a
> really simple bit of code that extracts the examples so they can
> actually be executed.

Well, when I wrote the /examples for TAP
(http://volute.googlecode.com/svn/trunk/projects/dal/TAPNotes/TAPNotes-fmt.html#tf-examples)
my goal was not to allow clients to execute something (though it may
be a side effect); the goal is to support clients to support the
*users*, with the prime use case of example queries that, for
TAP/ADQL, are IMHO crucially important.  In this concrete case, the
goal was, true, to let machines extract the queries, but not to
actually execute them but to show them to the user within their UI,
complete with a means for her to read associated prose.

So, I guess that's the first thing we should agree upon -- what's the
purpose of what /examples returns:

(1) Documentation for the user, marked up in a way that clients can
present it in a structured way.
(2) More generic documentation that allows, e.g., validation of the
type "is that documentation still valid?"
(3) If both, how much "inconvenience" for (1) or (2) are we prepared
to accept to support (2) or (1), respectively.

A case in point for the kind of issue that comes up with (3) is the
worry I've pointed out on
http://wiki.ivoa.net/twiki/bin/view/IVOA/DALI1RFC, starting with "I
don't think the base-url specification..."

> base URL for the service (to have found the <baseURL>/examples doc)
> so they don't need #2 and #3, but since a service could have multiple
> types of jobs with different resource URLs, all under the same base
> url, and with different behaviour/semantics, they cannot actually
> know how to execute the example without more information.

Right, and hence my suggestion that service specs that need that
kind of thing define this in their private vocabulary (and again,
preferably in "domain terms" rather than generically, e.g.,
"wavelength" rather than "a float-valued parameter called BAND").

> A3: is there a 3rd option? We have to assume that the examples
> document contains examples for using different sync or async
> resources that make up a  service...

My suggestion in a single sentence: "DALI should just say it's XML
that should be renderable by common HTML engines with a specific,
restricted kind of RDFa compatible markup and define the example,
name, and continuation properties, leaving everything else to
concrete protocols".

Cheers,

        Markus