Thank you for your reply. My first goal was to document what's in Dialog Toolkit. It seemed the natural first step towards saying how it works and then I would talk about how to use it. I had thought about examples of how to use it as going in last but in light of your comments perhaps that was a bad idea.
I first posted on this subject a while ago. The 2 post that show up today are only the last 2 posts. Once a post gets old enough it doesn't show up anymore. You make a lot of good points. I've worked with appleScript for a long time and some things just become automatic for me. I just don't think about them anymore. It is helpful for someone to point out all the oversights in the documentation that don't explain things, or explain things well enough. Everything you said was great input.
If by saying "standard alert" you mean NSAlert and by saying an "enhanced alert" you mean Shane's library then the "enhanced alert" uses NSAlert to display an enhanced alert. What makes the "enhanced alert" enhanced are the capabilities added by Shane's library (i.e. "Dialog Toolkit") and the fact that working with Alerts are simpler when using "Dialog Toolkit." I was not targeting this documentation to just working with NSAlert without using "Dialog Toolkit." Doing that would limit what could be done and would be more complicated to code.
You have a point about saying "TheAlert is a pointer." I included that to point out it was a pointer and not the actual alert. It makes a difference in how the alert is referenced.
NSWarningAlertStyle, NSInformationalAlertStyle and NSCriticalAlertStyle are all used in the official documentation from Apple for NSAlert. I wasn't aware they were deprecated. It doesn't say that in NSAlert documentation. But the AppKit documentation says it's deprecated. Deprecated does not mean it doesn't work any more but it's a sign that it can be dropped at anytime in the future.
I looked up NSAlert in the AppKit reference at
Then went to NSAlertStyle at
and found they have beta testing constants (enumerations) listed: NSAlertStyleCritical = 2, NSAlertStyleInformational = 1, NSAlertStyleWarning = 0.
The old constants (enumerations) were NSCriticalAlertStyle = 2, NSInformationalAlertStyle = 1, NSWarningAlertStyle = 0. So the actual numeric values will stay the same, but name of the constants will be changing after the beta test is over.
Changes in the NSAlert API would involve overriding things in the methods or objects. That was more then I was thinking of, but there are many ways to implement the Dialog Toolkit which uses NSAlert. What I mean by ways to implement the Dialog Toolkit is knowing enough to be able to change things inside dialog toolkit to fit a special need.
Something like that is best done by creating your own special case handler to perform the special tasks. The reason I say that is when Shane comes out with an update for "Dialog Toolkit" it won't turn into a nightmare trying to reintegrate your change into the new library. All that is required after a toolkit update is to fix any bugs that come up when the special case handler interfaces with a handler in "Dialog Toolkit."
The best practice for modifying an existing library is to change as little as possible to get the job done and to keep those changes contained to as small an area as possible, especially when the library ("dialog toolkit") is being updated from time to time. But using the library requires some understanding of what's going on inside "Dialog Toolkit" and modifying the library requires a lot of understanding of what's going on.
This is a big project to write this book to cover the different experience levels of scripters and I can see it is bigger then I expected when I started. I haven't even started on the "how to do something" part yet.
Writing such a book is often only as good as the input from people reading the book. If you or anyone else reading this sees something that's missing feel free to tell me.
With all that said is this kind of documentation something you would be interested in having? I rate whether doing this as being worth my time by people posting something about the project so I know there is some interest.