rb-appscript 0.4.0 → 0.5.0

data/CHANGES

@@ -1,3 +1,40 @@
+2007-12-18 -- 0.5.0 (beta 2)
+
+- OSAX module no longer errors on import in 10.5 if a ScriptingAdditions folder (e.g. ~/Library/ScriptingAdditions) doesn't exist
+
+- added Appscript::Application#is_running? method
+
+- added hfs_path, #hfs_path methods to MacTypes::Alias, MacTypes::FileURL; existing path, #path methods now use CFURL functions to convert between POSIX paths and URLs
+
+- aem/appscript now raises Connect::CantLaunchApplicationError instead of AE::MacOSError if unable to launch an application. Users should update existing code as necessary.
+
+- fixed extconf.rb so that universal binaries build correctly
+
+- built-in help system now uses ASDictionary 0.9.0+ instead of AppscriptHelpAgent. (AppscriptHelpAgent is no longer used as-of rb-appscript 0.5.0 and may be removed if previously installed.)
+
+- #help method now writes messages to stderr instead of stdout
+
+- Appscript::Reference#respond_to? now has identical signature to Object#respond_to? (optional second argument was previously missing)
+
+- fixed bug in AE.convert_long_date_time_to_unix_seconds (used to unpack AEDescs of typeLongDateTime) where it would crash if passed a FixNum instead of a BigNum
+
+- now allow methods that have been added to Object class at runtime (e.g. importing the 'pp' module adds #pretty_print and #pretty_inspect) to be invoked on Appscript::Reference and Appscript::Application instances, assuming that the reference object doesn't already have a property/element/command by the same name. In other words, instances of these classes now behave more or less the same as instances of ordinary subclasses that use bound methods rather than #method_missing to handle incoming messages. Previously, calling (e.g.) #pretty_inspect on an appscript reference would result in a 'property/element/command not found' error.
+
+- improved behaviour of Appscript::Application#AS_new_reference when argument is nil (now returns a new reference to the root application object)
+
+- OSAX::Application initialiser now optionally accepts static terminology 'glue' module as its second argument. This is partly to provide scripts that need to run in 64-bit processes with a workaround for accessing the OSAX module, which can't yet automatically obtain osax terminology under 64-bit (see TODO file).
+
+- added process_exists_for_path?, process_exists_for_pid?, process_exists_for_url?, process_exists_for_desc? class methods to AEM::Application
+
+- deprecated AEM::Application.is_running? (will be removed in 1.0.0); any existing code that uses this method should be updated to use AEM::Application.process_exists_for_path? instead
+
+- fixed minor formatting flaw in generic references' #to_s method
+
+- AEM::Application is now a subclass of AEMReference::Base, allowing aem Codecs instances to pack it
+
+- added AB_export_vcard.rb sample script
+
+
 2007-08-17 -- 0.4.0 (beta 1)
 
 - renamed the following aem/appscript methods to be consistent with AppleScript:

data/LICENSE

@@ -1,9 +1,13 @@
-(All modules are released under the MIT License, except safeobject.rb which is a modified version of basicobject <http://facets.rubyforge.org> released under the Ruby License.)
+All code is released under the MIT License, except for the following:
+
+- safeobject.rb which is a modified version of basicobject <http://facets.rubyforge.org> released under the Ruby License (see below) 
+
+- SendThreadSafe.h/SendThreadSafe.m, which are modified versions of Apple code (http://developer.apple.com/samplecode/AESendThreadSafe/); see SendThreadSafe.h for the original Apple license
 
 ======================================================================
 MIT LICENSE
 
-Copyright (C) 2006 HAS
+Copyright (C) 2006 - 2007 HAS
 
 ======================================================================
 THE RUBY LICENSE

data/README

@@ -27,11 +27,14 @@ Please note that the version of Ruby included with Mac OS X 10.4 is missing the
 ======================================================================
 NOTES
 
-- rb-appscript 0.4.0 is the first beta release. Except for bug fixes, no further changes are planned prior to the 1.0 release.
+- rb-appscript 0.5.0 is the second beta release. Please file bug reports if you encounter any problems.
 
-- rb-appscript 0.4.0 contains a couple of API changes from earlier versions; see the CHANGES file and documentation for details
+- rb-appscript 0.5.0 contains bug fixes, minor API changes and requested enhancements; see the CHANGES file and documentation for details.
+
+- rb-appscript 0.5.0  provides 64-bit support for OS X 10.5 in the following modules: AE, AEM, Appscript. The OSAX module provides partial 64-bit support; see the osax manual for details.
+
+- ASDictionary 0.9.0 or later is required to use rb-appscript's built-in #help method. If ASDictionary isn't installed, interactive help won't be available but appscript will continue to operate as normal.
 
-- rb-appscript 0.4.0  provides preliminary 64-bit support for OS X 10.5 in the following modules: AE, AEM, Appscript. Note that the OSAX module currently remains 32-bit only; this will be addressed after OS X 10.5 is released.
 
 ======================================================================
 AUTHOR
@@ -41,6 +44,6 @@ AUTHOR
 ======================================================================
 COPYRIGHT
 
-Copyright (C) 2006 HAS 
+Copyright (C) 2006 - 2007 HAS 
 
 Appscript is released under the MIT License. See the LICENSE file for more information.

data/TODO

@@ -1,7 +1,11 @@
 TO DO
 
-- Add a libxml2-based sdef parser for use by Terminology.dump, OSAX::ScriptingAddition in 64-bit Leopard as OSAGetAppTerminology is not available there. Also use weak binding for OSAGetAppTerminology, OSACopyScriptingDefinition in rbae.c
+- Add a libxml2-based sdef parser for use by OSAX::ScriptingAddition in 64-bit Leopard as OSAGetAppTerminology is not available there. (note: OSAGetAppTerminology, OSACopyScriptingDefinition should be weakly bound in rbae.c)
 
 - can numbers in range (2**63)..(2**64 - 1) safely be packed as typeUInt64 on 10.5+? Or stick with packing those as lossy 64-bit floating point for compatibility?
 
-- _aem/connect.rb module refers directly to Send::Event instead of going via the AEM::Application::Event hook, which might cause problems when used in an OSA component or other situation where client needs to customise all event creation and/or dispatch.
+- unpack support for typeISO8601DateTime (10.1+), typeCFAbsoluteTime (10.5+)?
+
+- _aem/connect.rb module refers directly to Send::Event instead of going via the AEM::Application::Event hook, which might cause problems when used in an OSA component or other situation where client needs to customise all event creation and/or dispatch.
+
+- #== and #hash methods in MacTypes::Alias, MacTypes::FileURL lack robustness; see notes in mactypes manual for details. Could these be improved? (Note: some mactypes unit tests may fail in some situations due to 'dumb' nature of these methods.)

data/doc/aem-manual/01_introduction.html

@@ -43,6 +43,6 @@
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/aem-manual/02_apioverview.html

@@ -84,6 +84,6 @@
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/aem-manual/03_packingandunpackingdata.html

@@ -23,7 +23,7 @@
 
 <h2>Codecs</h2>
 
-<p>The <code>AEM::Codecs</code> class provides methods for converting Python data to <code>AE::AEDesc</code> objects, and vice-versa.</p>
+<p>The <code>AEM::Codecs</code> class provides methods for converting Ruby data to <code>AE::AEDesc</code> objects, and vice-versa.</p>
 
 <pre><code>Codecs
 
@@ -59,7 +59,7 @@ TO DO: customisation options: subclassing and extending pack/unpack, overriding
 
 <h2>AE types</h2>
 
-<p>The Apple Event Manager defines several types for representing type/class names, enumerator names, etc. that have no direct equivalent in Python. Accordingly, aem defines several classes to represent these types on the Python side. All share a common abstract base class, <code>AETypeBase</code>:</p>
+<p>The Apple Event Manager defines several types for representing type/class names, enumerator names, etc. that have no direct equivalent in Ruby. Accordingly, aem defines several classes to represent these types on the Ruby side. All share a common abstract base class, <code>AETypeBase</code>:</p>
 
 <pre><code>AETypeBase -- Abstract base class
 
@@ -93,6 +93,6 @@ AEKey &lt; AETypeBase -- represents an AE object of typeKeyword</code></pre>
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/aem-manual/04_references.html

@@ -39,7 +39,7 @@
 <dd>selector data (e.g. in a by-name specifier, this would be a string)</dd>
 </dl>
 
-<p>The Apple Event Manager (and, in turn, the ae extension) provides several ways to construct object specifiers and assemble them into a complete reference, but these are all rather verbose and low-level. Aem hides all these details behind an object-oriented wrapper that uses chained property and method calls to gather the data needed to create object specifiers and assemble them into linked lists.</p>
+<p>The Apple Event Manager provides several ways to construct object specifiers and assemble them into a complete reference, but these are all rather verbose and low-level. Aem hides all these details behind an object-oriented wrapper that uses chained property and method calls to gather the data needed to create object specifiers and assemble them into linked lists.</p>
 
 <p>For example, consider the reference <code>text of document 1</code>. The code for constructing this reference using a relatively low-level bridge, in this case RubyAEOSA, would be:</p>
 
@@ -62,25 +62,25 @@ ref = OSX::AEDesc.record({
 p ref 
 #&lt;AEDesc:0x57594 type='obj '&gt;</code></pre>
 
-<p>(The ae extension is even lower-level and more verbose.)</p>
+<p>(The equivalent C code is even lower-level and more verbose.)</p>
 
 <p>This code works by creating each AEDesc of <code>typeAERecord</code> in turn, populating it, then coercing it to <code>typeObjectSpecifier</code>. Each AEDesc is nested within the next to form a linked list of object specifier records; the last (innermost) descriptor in the finished list indicates the reference's root object in the AEOM (in this case, the <code>application</code> object, which is represented by a null descriptor).</p>
 
-<p>Now, compare the above with the aem equivalent:</p>
+<p>Now, compare the above with the AEM equivalent:</p>
 
-<pre><code>AEM.app.elements('docu').by_index(1).property('ctxt')</code></pre>
+<pre><code>[[[AEMApp elements: 'docu'] at: 1] property: 'ctxt']</code></pre>
 
-<p>As you can see, aem still uses low-level four-character codes to identify the <code>text</code> property and <code>document</code> class, but is otherwise a high-level object-oriented API. Once again, each reference begins with a root object, in this case <code>app</code>. New aem specifiers are constructed by method calls; each call returning a new specifier object whose own methods can be called, and so on. This allows clients to build up a chain of aem specifier objects that aem can later pack into AEDescs for sending to applications.</p>
+<p>As you can see, AEM still uses low-level four-character codes to identify the <code>text</code> property and <code>document</code> class, but is otherwise a high-level object-oriented API. Once again, each reference begins with a root object, in this case <code>AEMApp</code>. New AEM specifiers are constructed by method calls; each call returning a new specifier object whose own methods can be called, and so on. This allows clients to build up a chain of AEM specifier objects that aem can later pack into AEDescs for sending to applications.</p>
 
-<p>One more thing to notice: in aem, specifying a class of elements and indicating which of those elements should be selected are performed by separate method calls, although the information provided will eventually be packed into a single AEDesc of <code>typeObjectSpecifier</code>. This two-step approach makes it easier to integrate aem with the higher-level appscript bridge, which also uses two calls to construct element specifiers (one to specify the element class, e.g. <code>document</code>, and another to specify the selection, e.g. <code>[1]</code>).</p>
+<p>One more thing to notice: in AEM, specifying a class of elements and indicating which of those elements should be selected are performed by separate method calls, although the information provided will eventually be packed into a single AEDesc of <code>typeObjectSpecifier</code>. This two-step approach makes it easier to integrate aem with the higher-level appscript bridge, which also uses two calls to construct element specifiers (one to specify the element class, e.g. <code>-document</code>, and another to specify the selection, e.g. <code>-at:</code>).</p>
 
-<p>Note that <code>AEM.app.elements('docu')</code> is itself a valid reference, identifying <em>all</em> the document elements of the application class. You do not have to call an explicit <code>all</code> selector (indeed, none is provided) as aem automatically handles the details for you. Aem even allows for some convenient shorthand, e.g. writing:</p>
+<p>Note that <code>[AEMApp elements: 'docu']</code> is itself a valid reference, identifying <em>all</em> the document elements of the application class. You do not have to call an explicit <code>all</code> selector (indeed, none is provided) as AEM automatically handles the details for you. AEM even allows for some convenient shorthand, e.g. writing:</p>
 
-<pre><code>AEM.app.elements('docu').by_filter(...).first</code></pre>
+<pre><code>[[[AEMApp elements: 'docu'] byTest: ...] first]</code></pre>
 
 <p>is equivalent to writing:</p>
 
-<pre><code>AEM.app.elements('docu').by_filter(...).elements('docu').first</code></pre>
+<pre><code>[[[[AEMApp elements: 'docu'] byTest: ...] elements: 'docu'] first]</code></pre>
 
 <p>This allows clients to specify the first document that matches the given condition without having to specify the element class a second time. In AppleScript, the equivalent to this is:</p>
 
@@ -109,15 +109,20 @@ p ref
 <li>elements by test</li>
 </ul>
 
-<p>(Actually, there's nine forms if you count the 'user property' reference form, although this is only used by OSA applets to identify script properties. Aem supports this extra form more for sake of completeness than usefulness.)</p>
+<p>(Actually, there's nine forms if you count the 'user property' reference form, although this is only used by OSA (e.g. Script Editor) applets to identify script properties. AEM supports this extra form more for sake of completeness than usefulness.)</p>
 
-<p>Each of these reference forms is represented by a different aem specifier class, apart from the absolute position form which is represented by three different classes according to the kind of selector used: a numerical index (e.g. <code>1</code>, <code>-3</code>), a named ordinal identifying a single element (<code>first</code>, <code>middle</code>, <code>last</code>, <code>any</code>), or a named ordinal identifying all elements (<code>all</code>).</p>
+<p>Each of these reference forms is represented by a different AEM specifier class, apart from the absolute position form which is represented by three different classes according to the kind of selector used: a numerical index (e.g. <code>1</code>, <code>-3</code>), a named ordinal identifying a single element (<code>first</code>, <code>middle</code>, <code>last</code>, <code>any</code>), or a named ordinal identifying all elements (<code>all</code>).</p>
 
 <p>The following diagram shows the aem reference class hierarchy (slightly simplified for legibility); concrete classes are shown in bold:</p>
 
 <p><img src="aemreferenceinheritance.gif" title="aem reference class hierarchy" />
 
-<p>Note that the user shouldn't instantiate these classes directly; instead, aem will instantiate them as appropriate when the client calls the methods of other aem reference objects, starting with the <code>app</code>, <code>con</code> and <code>its</code> objects that form the root of all aem references.</p>
+<p>Note that the user shouldn't instantiate these classes directly; instead, AEM will instantiate them as appropriate when the client calls the methods of other AEM specifier objects, starting with the <code>app</code>, <code>con</code> and <code>its</code> objects that form the root of all aem references.</p>
+
+
+
+TO DO: finish
+
 
 <p>In fact, it really isn't necessary to remember the reference class hierarchy at all, only to know which concrete classes implement which methods. All user-accessible properties and methods are defined by just four superclasses:</p>
 
@@ -396,6 +401,6 @@ ObjectBeingExamined &lt; PropertySpecifier -- AEM.its returns an instance
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/aem-manual/05_targettingapplications.html

@@ -25,19 +25,39 @@
 
 <h2>The <code>Application</code> class</h2>
 
-<p>The <code>Application</code> class represents an application to which Apple events will be sent. Its constructor allows applications to be identified in one of four ways: by full path, by eppc URL, by custom <code>AEAddressDesc</code>, or the host application if no other value is given. Its main method, <code>event</code>, is used to construct the Apple events to send. Several utility methods are also provided.</p>
+<p>The <code>Application</code> class represents an application to which Apple events will be sent. Its constructor allows applications to be identified in one of four ways: by full path, by eppc URL, by custom <code>AEAddressDesc</code>, or the host application if no other value is given. Its main method, <code>#event</code>, is used to construct the Apple events to send. Several utility methods are also provided.</p>
 
 <pre><code>Application -- the target application
 
     Class methods:
 
-        launch(path) -- launch an application in background if not
-                already running, and send it a 'ascrnoop' event
+        process_exists_for_path?(path) -- Does a local process launched
+                from the specified application file exist?
             path : string -- application's path, e.g. '/Applications/iCal.app'
+            Result : boolean -- Note: if path is invalid, an AE::MacOSError
+                    is raised.
 
-        is_running?(path) -- Is an application currently running?
-            path : string -- application's path, e.g. '/Applications/iCal.app'
+        process_exists_for_pid?(pid) -- Is there a local application process
+                with the given Unix process id?
+            pid : integer
             Result : boolean
+		
+        process_exists_for_url?(url) -- Does an application process specified
+                by the given eppc:// URL exist?
+            url : string -- url for remote process
+                    (e.g. 'eppc://user:pass@0.0.0.1/TextEdit')
+            Result : boolean -- Returns false if process doesn't exist, or if
+                    access isn't allowed.
+
+        process_exists_for_desc?(desc) -- Does an application process specified
+                by the given AEAddressDesc exist?
+            desc : AE::AEDesc -- AEAddressDesc for application
+            Result : boolean -- Returns false if process doesn't exist, or if
+                    access isn't allowed.
+
+        launch(path) -- launch an application in background if not
+                already running, and send it a 'ascrnoop' event
+            path : string -- application's path, e.g. '/Applications/iCal.app'
     
     Constructors:
 
@@ -81,7 +101,7 @@
 
 <h2>Creating <code>Application</code> objects</h2>
 
-<p>When targetting a local application by path, the full path to the application (or application bundle) must be given, including a <code>.app</code> suffix if present. Note that aem identifies local applications by process serial number for reliability. If the target application is not already running when a new <code>Application</code> instance is created, it will be started automatically so that a PSN can be acquired.</p>
+<p>When targetting a local application by path, the full path to the application (or application bundle) must be given, including a <code>.app</code> suffix if present. Note that aem identifies local applications by process serial number for reliability. If the target application is not already running when a new <code>Application</code> instance is created, it will be started automatically so that a PSN can be acquired. If the application can't be launched for some reason (e.g. if it's in the Trash), an <code>AEM::CantLaunchApplicationError</code> error will be raised.</p>
 
 <p>If the <code>by_url</code> constructor is used, its <code>url</code> argument should be an eppc URL string. Aem will pack this as an <code>AEDesc</code> of <code>typeApplSignature</code>. The target machine must have Remote Apple Events enabled in its Sharing preferences.</p>
 
@@ -104,22 +124,22 @@ KAE::TypeProcessSerialNumber</code></pre>
 
 <h2>Transactions</h2>
 
-<p>The <code>begin_transaction</code> and <code>end_transaction</code> methods are used to start and stop transaction sessions for applications that support this. All events <em>created</em> while a transaction session is active will be identified as part of that transaction.</p>
+<p>The <code>#begin_transaction</code> and <code>#end_transaction</code> methods are used to start and stop transaction sessions for applications that support this. All events <em>created</em> while a transaction session is active will be identified as part of that transaction.</p>
 
 <p>Note that during a transaction, sending the application an event not created during that transaction will cause an error. Similarly, sending the application an event created during a transaction after that transaction has ended will cause an error.</p>
 
-<p>The <code>end_transaction</code> method must be called to close both successful and failed transactions on completion. If a transaction session is accidentally left open, aem will attempt to close it when the <code>Application</code> object is garbage-collected, although this cannot be guaranteed to succeed.</p>
+<p>The <code>#end_transaction</code> method must be called to close both successful and failed transactions on completion. If a transaction session is accidentally left open, aem will attempt to close it when the <code>Application</code> object is garbage-collected, although this cannot be guaranteed to succeed.</p>
 
 
 <h2>Reconnecting to local applications</h2>
 
-<p>Because local applications are identified by process serial number, an existing <code>Application</code> object created using the <code>path</code> argument will no longer hold a valid <code>AEAddressDesc</code> if the target application quits. Sending events to an invalid address will cause a <code>CommandError</code> -600 ("application isn't running") or -609 ("connection is invalid") to be raised.</p>
+<p>Because local applications are identified by process serial number, an existing <code>Application</code> object created using the <code>by_path</code> constructor will no longer hold a valid <code>AEAddressDesc</code> if the target application subsequently quits. Sending events to an invalid address will cause a <code>CommandError</code> -600 ("application isn't running") or -609 ("connection is invalid") to be raised.</p>
 
-<p>The <code>is_running?</code> class method can be used to check if a local application is running or not, given its full path.</p>
+<p>The <code>process_exists_for_path?</code> class method can be used to check if a local application is running or not, given its full path.</p>
 
-<p>Calling the <code>reconnect</code> method will create a new <code>AEAddressDesc</code> for an existing <code>Application</code> object. If the application is not running at the time, it will be started automatically.</p>
+<p>Calling the <code>#reconnect</code> method will create a new <code>AEAddressDesc</code> for an existing <code>Application</code> object that was originally created via the <code>by_path</code> constructor. If the application is not running at the time, it will be started automatically.</p>
 
-<p>Note that only <code>Event</code> instances created after <code>reconnect</code> is called will receive the new <code>AEAddressDesc</code>.  Any <code>Event</code> instances created before <code>reconnect</code> is called will still contain the old <code>AEAddressDesc</code>. Also note that the <code>reconnect</code> method will only work for <code>Application</code> objects created using the <code>by_path</code> constructor.</p>
+<p>Note that only <code>Event</code> instances created after <code>#reconnect</code> is called will receive the new <code>AEAddressDesc</code>.  Any <code>Event</code> instances created before <code>reconnect</code> is called will still contain the old <code>AEAddressDesc</code>.</p>
 
 
 </div>
@@ -130,6 +150,6 @@ KAE::TypeProcessSerialNumber</code></pre>
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/aem-manual/06_buildingandsendingevents.html

@@ -170,6 +170,6 @@ KAE::KAECanSwitchLayer</code></pre>
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/aem-manual/07_findapp.html

@@ -49,6 +49,6 @@ by_creator(creator) -- Find the application with the given creator type.
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/aem-manual/08_examples.html

@@ -80,6 +80,6 @@ textedit.event('corecrel', {
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/aem-manual/index.html

@@ -37,6 +37,6 @@
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/appscript-manual/01_introduction.html

@@ -78,6 +78,6 @@ app('TextEdit').documents.end.make(
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/appscript-manual/02_aboutappscripting.html

@@ -67,12 +67,12 @@
 
 <p><img src="application_architecture.gif" alt="Application with Graphical and Apple event interfaces." /></p>
 
-<p>A scriptable application also contains a built-in definition of its scripting interface in the form of an <code>aete</code> or <code>sdef</code> resource. This resource can be obtained programmatically and used:</p>
+<p>A scriptable application also contains a built-in definition of its scripting interface in the form of an <code>aete</code> or <code>sdef</code> resource. This resource can be obtained programmatically and used to:</p>
 
 <ul>
-<li>to support automatic translation of human-readable terminology to four-letter codes in high-level bridges such as AppleScript and appscript</li>
+<li>support automatic translation of human-readable terminology to four-letter codes in high-level bridges such as AppleScript and appscript</li>
 
-<li>to generate basic human-readable documentation by applications such as Script Editor and HTMLDictionary.</li>
+<li>generate basic human-readable documentation by applications such as Script Editor and HTMLDictionary.</li>
 </ul>
 
 <p>(Note that the <code>aete</code> and <code>sdef</code> formats do not provide an exhaustive description of the application's scripting interface, and additional documentation is usually required - if not always provided - to form a complete understanding of that interface and how to use it effectively.)</p>
@@ -231,6 +231,6 @@ app('TextEdit').documents[1].text.paragraphs</code></pre>
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/appscript-manual/03_quicktutorial.html

@@ -151,6 +151,6 @@ irb> te.documents.text.get
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>

data/doc/appscript-manual/04_gettinghelp.html

@@ -20,7 +20,15 @@
 
 <!-- content -->
 <div id="content">
-<p>When developing appscript-based scripts, there are several ways to get information about applications' scripting interfaces: the built-in <code>help</code> method, the ASDictionary and <code>osadict</code> tools, and introspection.</p>
+<p>When developing appscript-based scripts, there are several ways to get information about applications' scripting interfaces: the ASDictionary application and its bundled <code>asdict</code> command-line tool, appscript's powerful built-in <code>help</code> method, and introspection.</p>
+
+
+
+<h2>ASDictionary</h2>
+
+<p>ASDictionary, available from the appscript website's <a href="http://rb-appscript.rubyforge.org/downloads.html">Downloads page</a>, provides a convenient GUI interface for exporting application terminology resources in plain text and HTML formats. ASDictionary can export HTML dictionaries in both single-file format and a frame-based format similar to rdoc's.</p>
+
+<p>In addition, the <code>asdict</code> tool bundled with ASDictionary can be used to export application dictionaries in HTML format, or browse them interactively from the command line. See ASDictionary's documentation for more information.</p>
 
 
 
@@ -28,13 +36,9 @@
 
 <p>Appscript's <code>Application</code> and <code>Reference</code> classes include a powerful interactive help system that allows you to explore applications' scripting interfaces from within running scripts and Ruby's interactive <code>irb</code> interpreter. The <code>help</code> method can provide information on any suite, class, command or reference, and display the inheritance and relationships for a selected class or the entire application.</p>
 
-<div class="hilitebox">
-<p>Rb-appscript's built-in <code>help</code> method relies on the AppscriptHelpAgent application, available separately from the <a href="http://rb-appscript.rubyforge.org">appscript website</a>. See the AppscriptHelpAgent Read Me for installation instructions.</p>
+<div class="hilitebox">Note that rb-appscript's built-in help system is only available when ASDictionary 0.9.0 or later is installed. If ASDictionary isn't available or is too old, invoking <code>help</code> will simply result in a "No help available" message and the script will continue to run as normal.</div>
 
-<p>Note that AppscriptHelpAgent is <em>not</em> required to access any other feature of rb-appscript, and its installation it is entirely optional. If AppscriptHelpAgent is not installed, invoking <code>help</code> will simply result in a "No help available" message being displayed and the script will continue to run as normal.</p>
-</div>
-
-<p>Built-in help is invoked by calling an <code>app</code> object's <code>help</code> method, optionally passing it a string indicating the type of information you want. For example, to view the help system's own help, call the <code>help</code> method with <code>'-h'</code> as its argument:</p>
+<p>Built-in help is invoked by calling an <code>app</code> object's <code>help</code> method, optionally passing it a string indicating the type of information you want. The resulting help message is printed to <code>stderr</code> and script execution continues as normal. For example, to view the help system's own help, call the <code>help</code> method with <code>'-h'</code> as its argument:</p>
 
 <pre><code>app('TextEdit').help('-h')</code></pre>
 
@@ -90,42 +94,9 @@ app('TextEdit').documents.help('-t count -t close')</code></pre>
 
 
 
-<h2>ASDictionary</h2>
-
-<p>ASDictionary, available from the <a href="http://sourceforge.net/projects/appscript"> py-appscript website</a>, provides a convenient GUI interface for exporting application terminology resources in plain text and HTML formats. ASDictionary can export HTML dictionaries in both single-file format and a frame-based format similar to rdoc's.</p>
-
-
-
-<h2>osadict</h2>
-
-<p>The <code>osadict</code> tool, bundled with the <a href="http://sourceforge.net/projects/appscript">py-appscript package</a>, can be used to export application dictionaries in HTML format, or browse them interactively from the command line.</p>
-
-<p>To view osadict's full documentation:</p>
-
-<pre><code>osadict -h</code></pre>
-
-<p>Use osadict's <code>-s</code> option or <code>default</code> command to set the formatting style for rb-appscript.</p>
-
-<p>Examples:</p>
-
-<pre><code># Export TextEdit's dictionary to HTML:
-osadict -Hs rb TextEdit.app > TextEdit.html
-
-# Browse iCal's dictionary:
-osadict -s rb eppc://remote-mac.local/iCal
-iCal&gt; -u
-iCal&gt; -t view_calendar
-iCal&gt; -t calendar -i calendar -r calendar
-iCal&gt; exit
-
-# View a Standard Additions command:
-osadict -Ns rb StandardAdditions -t display dialog</code></pre>
-
-
-
 <h2>Introspection</h2>
 
-<p>Appscript's <code>Application</code> and <code>Reference</code> classes define several instance methods for obtaining information on the target application: </p>
+<p>In addition to supporting Ruby's standard <code>#methods</code> and <code>#respond_to?</code> methods, appscript's <code>Application</code> and <code>Reference</code> classes also define several instance methods for obtaining information on the target application: </p>
 
 <dl>
 <dt><code>properties</code></dt>
@@ -184,6 +155,6 @@ p te.parameters('make')
 </div>
 
 <!--footer-->
-<p class="footer">&copy; 2006 HAS</p>
+<p class="footer">&copy; 2007 HAS</p>
 </body>
 </html>