[DALI] DAI-examples markup

[Patrick Dowler]

I'm not so much wanting strictly machine-readable document. In fact, my 
prototype is a JSP page that users are supposed to read. The bits that 
are machine readable are embedded in there and, while my text does show 
things like the base-url that is because the visible part is usually a 
curl command someone can cut and paste. If that were not the case, the 
http-action and base-url could certainly be encoded in non-visible 
elements and remain useful.

I guess the main usage I see from an implementer point of view is that 
you can document some useful/interesting examples for using your service 
*in one place* to serve both a user with a web browser and an app that 
extracts the marked up (technical bits). The extra work to make it 
machine readable (the subject of DALI-examples) is relatively small 
beyond just writing a  document. The visible document would use terms 
like "region of interest" and the marked up (possibly hidden) bits would 
have POS and SIZE (eg). Maybe you make POS and SIZE visible, maybe you 
don't -- that depens on the audience for the prose.

I think the only difference is that I want DALI-examples to be 
stand-alone so (i) future specs don't need to say anything more specific 
about it, and (ii) implementers can use it to mark up any param-based 
(eg DALI-like) web service they implement and it would be consumable. 
That makes DALI-examples useful for custom stuff and IVOA-standard stuff.

The alternative is that DAL services have to specify how to encode their 
examples and there is no point in people doing anything for 
custom/prototype services.

This page is a DALI-examples prototype and it describes two different 
services.

http://beta.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/caom2proto/examples

IMPORTANT: Don' be fooled by the fact that I am showing URLs and GET or 
POST in the text. That is my choice because I want to show how to use 
the services with curl and not required.

Pat

PS-The whole point of a microformat is to make a human readable document 
*also* machine readable with minimal extra fuss.

PPS-Yes, those are prototype DataLink and Cutout services :-)


On 04/26/2013 02:21 AM, Mark Taylor wrote:
> 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/
> .
>

-- 

Patrick Dowler
Canadian Astronomy Data Centre
National Research Council Canada
5071 West Saanich Road
Victoria, BC V9A 2L9

250-363-0044 (office) 250-363-0045 (fax)