On a related note, Mark Alldritt just put up a very good blog post
[...]
(I've already left my own 2c on the subject, of course.;)
I didn't see it there yet.
It may have been in a moderation queue initially. Try again now.
However, Scripting Interface Design now presumes an SDEF, so the
first questions should be about the SDEF schema because that now
defines everything.
For benefit of those who don't know their DTDs from their schemas
(e.g. me), could you be a bit more specific, with practical examples,
about where the DTD format falls short or where the schema format
could enhance the decriptiveness or reliability of sdefs?
I think what you're arguing for is turning the current sdef format
into a full-blown Interface Definition Language which would allow
developers to describe how an application's scripting interface works
down to the very last detail. I'm all in favour of that, of course,
but it'll make more sense to talk about what kinds of information
need to be expressible in an sdef before disappearing into an arcane
discussion of what meta-format (DTD or Schema) will need to be used
to describe the definition of the definition.
For example, one comment you made which I did pick up is the desire
for the sdef format to be extensible by third-parties. I can
certainly think of one area where third-party extensibility would be
valuable and fully justified: to support data-driven event handling
frameworks. At the moment, the sdef format is limited to supporting
only one event handling framework - Cocoa Scripting - however, a
third-party framework such as aemreceive could also benefit from a
data-driven approach. At the moment, anyone using aemreceive has to
write additional code to install their event handlers, but if I they
were allowed to put a few <implementation:aemreceive ...> tags into
their sdef then aemreceive could install those handlers for them.
Another good demonstration of where the sdef format currently falls
well short of being an IDL is in the way that commands are declared.
Let's take TextEdit's 'make' command as an example:
make
new type class : The class of the new object.
[at location reference] : The location at which to insert the object.
[with data anything] : The initial data for the object.
[with properties record] : The initial values for properties of the
object.
→ reference
At the moment, there's _no_ way for either a machine or a person to
tell from this definition what all the legal uses for the make
command are [1]. How do I know which classes of objects can be
created using make? For each of those classes, how do I know which
parameters are required, which are optional, and which should be
ignored? For each of those parameters, how do I know what sorts of
values are needed?
A proper IDL would allow developers to express all this information
to users in a consistent, machine-readable way. For example, an IDL
would tell you:
- To make a new document object, you must supply a 'document'
constant for the 'new' parameter, that the 'at' parameter is optional
but if you supply it it must be an insertion reference pointing to
the 'document' elements of the 'application' object, that the 'with
data' parameter should not be used, and that the 'with properties'
parameter is optional (it could even describe what the structure of
the record should look like, although I suspect that might be overkill).
- To add a paragraph to a document, you must supply a 'paragraph'
constant for 'new' (required), an insertion reference to a document's
character/word/paragraph elements (required), a string for 'with
data' (required), and an optional 'with properties' parameter.
And so on, and so on. Every legal permutation of 'make' command usage
would be documented, and likewise for every other command. That might
sound like it's creating a lot of additional work for the developer,
but it really wouldn't be any more than they should be doing - or
*would* be doing for any other public API. (e.g. If Apple's Cocoa
APIs were half as badly documented as most applications' Apple event
APIs are, we'd all be using Carbon or Win32 or Swing or some such
thing today.) Providing a minimum acceptable level of API
documentation is every API developer's responsibility. Providing a
documentation format capable of representing that minimum acceptable
level of API documentation is, in this case, Apple's responsibility.
...
I could go on, but I imagine most folks here will be falling asleep
aready so I won't. However, the basic upshot is this: making the sdef
format both comprehensive in detail and reliably robust will make it
clear to developers what information they must provide so that users
can understand how to use their application effectively. While
writing a more detailed sdef does mean a bit more work for
developers, I think they would much rather have that than no clear
sense of what they need to do or unhappy users because they failed to
do it correctly. And, most importantly, it would mean happier users,
since learning to script each new application would no longer be a
case of "Guess What All the Magic Invocations Are" as it currently is.
Cheers,
has
[1] Okay, the sdef format does provide a marginal improvement over
the old aete format in that it can now at least tell you which
classes of object can be used as the subject for a command, but this
still leaves a lot of information unspecified and so really doesn't
cut it. What I'd much rather see is a command declaration scheme that
takes its inspiration from multimethods (for all you Common Lisp and
Dylan fans), since Apple event handlers behave much like multimethods
do (i.e. an application event handler decides how an incoming event
should be handled by looking at the type of one or more of its
parameters).
