Re: New Tiger dictionary format example posted
Re: New Tiger dictionary format example posted
- Subject: Re: New Tiger dictionary format example posted
- From: Bill Cheeseman <email@hidden>
- Date: Wed, 04 May 2005 16:29:40 -0400
on 2005-05-04 2:14 PM, has at email@hidden wrote:
> Bill Cheeseman wrote:
>
>> The sdef file format, enhanced for Tiger, allows developers to include HTML
>> documentation, including formatted instructional text of unlimited length,
>> example script statements, and live Web links.
>
> While I'm delighted to see this feature appear at last, I am a little
> concerned that some developers may go over the top with adding sdef-embedded
> HTML documentation, leading to huge XML files that are a chore for developers
> to write and maintain and take a non-trivial amount of time to parse when all
> that's needed is the basic name-code translations needed to compile/execute
> scripts. I wonder if it'd be possible for the more extensive documentation to
> be put in separate help files within the application bundle, which could then
> be opened in, say, Help Viewer by clicking a hyperlink embedded in the sdef
> documentation?
>
> Thoughts?
The point you're making is extremely important. Now that we have the ability
to write in-dictionary instructions, we all have an obligation to make them
useful but not overwhelming. And to get the spelling and grammar right. And,
I think, to build up among us a common style, at least to the extent of
avoiding unnecessary confusion for users as they switch from one scriptable
app to another. It's very hard work.
Being a pioneer, I wanted to get this right. So I rewrote my UI Actions
dictionary again and again over a period of months, trying to find the happy
medium. (And trying to suppress my ingrown lawyer's stilted verbosity.)
You see what I ended up with. I would actually appreciate some feedback on
exactly this issue. Especially, where did I go wrong?
As to Help files and other documentation, it's still important! At least
with the new html dictionary support, no developer has an excuse for not
giving users at least that much instruction. But good developers will still
provide separate, more detailed AppleScript help and examples.
--
Bill Cheeseman - email@hidden
Quechee Software, Quechee, Vermont, USA
http://www.quecheesoftware.com
PreFab Software - http://www.prefab.com/scripting.html
The AppleScript Sourcebook - http://www.AppleScriptSourcebook.com
Vermont Recipes - http://www.stepwise.com/Articles/VermontRecipes
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Applescript-users mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden