Latest SAMP doc version

[Mark Taylor]

Dear apps-samp,

I have attached the most recent version (13 June 2008) of the SAMP
document to the wiki page

    http://www.ivoa.net/cgi-bin/twiki/bin/view/IVOA/SampProgress

This incorporates the decisions made at Trieste as well as discussions
since then on this list.  The Trieste version is also there for comparison.

A rough list of changes since Trieste follows at the end of this message.

If you have any comments on the current draft, please make them here.
However I would like to publish a copy as an IVOA Working Draft soon 
(I promised before the end of June) so I'm hoping that nothing too 
contentious will come up.  Of course WD status does not mean that 
this is set in stone - we can issue new WD versions in the future 
and of course make revisions before attempting to go to PR.

I am on holiday all next week - back 23 June.

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/


Changes to SAMP doc since Trieste:
----------------------------------

Added "Status of this document" section.

Added "Extensible Vocabularies" section, and referenced it in some places
which allows removal of repeated text (repeatedly explained concepts)
elsewhere.

Moved "Registering with the hub" section to after
"Scalar type encodings" section.

Moved some text from "SAMP Data Types" section to
"Scalar type encodings" section.

Added "MType Subscriptions" section.  Moved MType BNF into this section
from section 5, and added wildcard description.

Split "Message and Response Encoding" section into two, and changed the
way that responses are encoded.

Added description of Synchronous Call/Response timouts to Sending and Receving
Messages section

Added a comment to warn about badly-behaved recipients who never reply
to calls.

The following hub API calls have changed:
    register() - now returns map
    declareMetadata() - name change
    declareSubscriptions() - name and argument change
    getSubscriptions() name and argument change
    getSubscribedClients() - return value change
    getHubID() - removed
    callAndWait() - timeout added
    call(), callAndWait() - now return msg-id
    reply() - argument change
    ping() - new name for isAlive()  (Standard Profile only)

The following client API calls have changed:
    receiveResponse() - argument change

Some argument names have changed in the documentation (msg-id -> msg-tag
in some cases, so that the same arg name always refers to the same thing).

Added better crossreferencing to hub/client API descriptions.

Several wording changes and typo fixes.

Some formatting and stylistic rationalisation.

MType section introductory text revised to match current scope of the section.

Added section "MType Vocabulary: Extensibility and Process"

Provide more careful documentation for core MTypes
    samp.hub.event.shutdown
    samp.hub.event.register
    samp.hub.event.unregister
    samp.hub.event.metadata
    samp.hub.event.subscriptions
    samp.app.ping
    samp.app.status           (should this be samp.app.event.status?)
    samp.app.event.shutdown
    samp.msg.progress         (should this be samp.msg.event.progress?)

Dropped list of other MTypes - to be included in supplementary document.

Filled in PLASTIC/SAMP changes appendix.

Delivery Pattern section updated to match agreed changes to msg-id/msg-tag
handling.

Add an example of a notifyAll() message to the Standard Profile
examples section.