[DALI] DAI-examples markup

[Mark Taylor]

Hi Markus, Pat et al.,

On Thu, 25 Apr 2013, Markus Demleitner wrote:

> 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.

I can see the compelling reasons for (1) which is to provide examples
essentially directed towards humans, but with enough markup to enable
software clients to present them in an appropriate way to human
service users.

Pat is keen on a different use case along the lines of (2) which
would allow machine clients to execute the queries without human
intervention.  I can see that's kind of neat, and you might as
well write something that does it if the markup supports that,
but I don't see such a compelling requirement for it.  Pat, can you
want to comment on why you think this is a use case we should be
supporting?  I guess validation is, as Markus suggests, one answer.

> 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..."

I don't follow this argument from incredible tediousness, though
perhaps it's because I don't know enough about RDFa.  Couldn't
you hide the repeated base-url specifications somewhere it doesn't
make it into the user-visible HTML text, e.g. in attributes?

> > 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".

Currently, I'm persuaded by Markus's view, but arguments on the other
side may change my mind...

Mark

--
Mark Taylor   Astronomical Programmer   Physics, Bristol University, UK
m.b.taylor at bris.ac.uk +44-117-9288776  http://www.star.bris.ac.uk/~mbt/