VEP-007: datalink-core#detached-header

[Markus Demleitner]

Hi François,

On Wed, Sep 15, 2021 at 11:25:14AM +0200, BONNAREL FRANCOIS wrote:
>        I know that VEP-007 will be discussed today and I will not
> participate.

Oh, dang.  So, what about VEP-006?  François, you seemed to still
have concerns with that, too -- or can that go on now?

>        I am strongly in favor of the new term itself.
>        My small concern (with a proposal) is that as it is stated now in
> "https://volute.g-vo.org/svn/trunk/projects/semantics/veps/VEP-007.txt"
>        The head-term of #detached-header is "documentation".
>        I think that a head term like #metadata would be better.
>        This term doesn't exist  up to now and I think it is  lacking.
>        #metadata is different from #documentation in the sense that the
> first one is machine readable while the other one is human readable
>        So usage by clients would be very different. Other example for
> #metadata would be #ivoa-provenance-metadata and #ivoa-obscore
>        If you think this is a good idea I would like to add this term either
> in the same VEP or as another VEP with the small modification of head-term
> in VEP-007 itself

First, I'm strongly against introducing terms on, effectively, a whim
-- experience has shown many times it's almost certain that'll be
trouble once we actually need a related concept.

Instead, we should rather 

(a) have a clear need for the term, which for datalink/core means
(for now): A link that either doesn't fit any of the existing
concepts at all or requires splitting an existing concept because the
link needs a different treatment (by a machine) from other members of
that existing concept.

(b) have a clear and plausible ("digital") *pragmatics* for that
concept.  What we're doing here is machine-readable semantics, so to
make a term worthwhile, there must be at least an idea (even better:
implementation) of what a machine should do with the information that
the link belongs to the new concept (rather than an old one).

Having said that, François has a point in that documentation's
definition currently says "Extra information on the item in
*human-readable* text form" (emphasis mine).  I think what we're
learning with this item is that "human-readable" was an error here;
the examples "processing logs" or "weather reports" already make that
clear: These are a lot more useful when they come in a structured
format, which very often will not have "text form" (unless you have a
very liberal idea of text).

Hence, I'd say we need to fix the definition #documentation to read

  Extra information aiding in understanding or interpreting the item.
  Such information can range from processing logs to weather reports
  to technical documents on instruments to related publications.

I give you that one of these days separating "human-readable" and
"machine-readable" (or structured, as for #detached-header)
documentation might be useful (so users could hide away stuff that'll
only give gobbledigook unless they have a matching client); that
could then approach what I think your *#metadata would comprise.  

But let's wait until we have cases where there's so much
#documentation that that's actually worth it.  For now, I'm sure
even in interactive use most people would actually like to see a FITS
header when they open #documentation.

François (and, of course, everyone else), would you be ok with a VEP
fixing #documentation's definition as above?  Since it just widens
the extension and probably won't conflict strongly with other
concepts in datalink/core, I'd be rather confident it's technically
sane.

           -- Markus

PS: talking about discussions that petered out over the holiday season,
I'd like to use this opportunity to remind everyone of
http://mail.ivoa.net/pipermail/semantics/2021-July/002829.html, where
I'm raising several points that I'm rather sure need to be addressed
before VEP-009 can go on.