Annotations [was Re: Apps Messaging -- A New Approach

[Mark Taylor]

Hallo Mike,

On Thu, 3 May 2007, Mike Fitzpatrick wrote:

>> No.  The task just knows that applications may issue annotations,
>> and yes it ought to structure its menus with that in mind.  But in the
>> kind of case we're talking about here it has no knowledge, at any
>> stage of the interaction, about what any of these annotations (if there
>> are any) mean.  The user selects one of the available options, and
>> the sending app blindly passes the annotation along to the recieving
>> app.  Any message parameters, return values etc are treated precisely
>> the same at the sending end regardless of which annotation, or whether
>> any annotation at all, is selected.
>
> 	I think I understand:  Task A posts a message with an annotation
> and Task B creates a menu entry, if the user selects that entry then that
> message is sent back to Task A as the command?

that's right.

> 	As it's being used currently I'll admit it's clever, but how do
> we describe this in the spec?  The problems I see are that
>
> 	- tasks must implicitly assume that a base message of a particuar
> 	  type means it should create a menu entry e.g. only do this for
>          the process.table.votable messages

No application has to respond like this.  But applications which are
already offering to send the message as a menu option (or in some 
other user-driven way) may choose to offer multiple differently-annotated 
versions of the same message if a destination application indicates
that it provides these.  The menu thing is an illustration of
a common use case rather than a requirement of this idea.

This kind of annotation is only going to be appropriate for rather 
generic types of message, such as "send me a table".
For a message like "calculate the flux of the source at these coordinates
on this image" there are not many ways you can interpret it, so it's 
not so likely to be supplied with annotations (though, come to think
of it, you might possibly use this mechanism to offer different 
algorithms for that sort of thing...)

> 	- messages are assumed to have a fixed format when sent back, e.g.
> 	  can contain only a single arg which must be a filename to
> 	  operate on

Yes, exactly.  It doesn't have to be a single argument of course, it
could be e.g. 4 FITS files and an integer, but all differently-annotated 
versions of the same message will have the exact same argument structure 
as each other.  The mtype defines the basic semantics and the syntax
(argument structure) of the message.  The annotations provide 
recipient-defined refinements of the semantics, but can have nothing
to say about the syntax.

> 	- suppose in IRAF I want to post that I can do 20 things with a
> 	  votable, does each of them become a menu entry?

That's possible, but probably not a very good idea, if only because
20 is a large number of menu options (and also 20 is likely to be
an underestimate for a system as complex as IRAF).  Most likely 
this sort of situation would be better served by defining a number 
of different mtypes.

None of this is designed to restrict the number of mtypes that we can
define where defining new mtypes looks like a sensible thing to do.
The problem it is addressing is refining the semantics of messages
in cases where it's so application-specific that there's no point
trying to make some centralised decision about what they should be.
For example, an mtype could mean "mark a subset of rows in a given table".
There are a number of things TOPCAT could reasonably do with this: 
for instance create a new RowSubset, or redefine the contents of a
specially labelled "from SAMP" subset, or set the Current Subset of
the table in question.  These options don't even make sense unless
you are talking in the specific domain of TOPCAT's capabilities,
so there's no point trying to capture the difference between them
in a general discussion of what different mtypes ought to mean.
The benefit of the annotation idea is that the application which 
gives (detailed) meaning to these things is the one which describes
and enumerates them, so that the other applications talking to 
it don't need to attempt to understand these things.

> In the first case the spec would need to identify 'process.table' as the
> special message type and prescribe some sort of behavior an application
> should take as well (but only when it sees the annotation?).  Why not just
> use a more explicit 'gui.addMenu' message to instruct the app, the args
> to that message could then be variable and be returned just as they are
> now (we could even have a syntax that says '$F' in the arg string should
> be replaced with the file name).

If you have messages which are sufficiently different to require 
different arguments, then you should definitely be using different
mtypes and not different annotations of the same mtype.

Mark

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