Submit Application Automation Documentation

Content

Submit Application Automation Documentation

The Mugginsoft OS X application automation documentation archive is a browsable repository of scripting documentation for a range of Apple and third party applications. Documentation can be submitted for any scriptable application that runs on OS X 10.6 or above. Documentation requests will be accepted from both users and application developers.

Identifying a Scriptable Application

Not all applications are scriptable. A scriptable application can be identified in one of two ways.

  1. The application is listed in the AppleScript Editor dictionary browser. Select File - Open Dictionary from the AppleScript Editor menu.
  2. Browse to the application bundle Contents/info.plist file using the Show Package Contents context menu item. Scriptable applications have an entry named Scriptable or NSAppleScriptEnabled set to YES.

As long as the application is scriptable you can either request that it be included in the archive or submit the application automation documentation directly as detailed below.

Submitting a Documentation Request

You can request that a particular application's automation dictionary be added to the archive. Mugginsoft LLP will download the application and generate the documentation as required using KosmicTask. In order for us to accept a documentation request for a particular application one of the following conditions must be met:

  1. The application is freely available for download either as a trial or full version. Commercial and open source applications are all acceptable.
  2. You are the developer of a scriptable application and are supplying us with a link to your application for the purposes of including it in the archive.

Send documentation requests to support@mugginsoft.com making sure to include a direct download link to the application.

Submitting Documentation Directly

Two types of scripting documentation can be submitted directly to the archive. This approach may be most appropriate if you wish to submit documentation for a number of applications simultaneously or the application is not freely available for download. In this case you generate the documentation locally and then submit the generated files to us for final preparation.

  1. AppleScript HTML documentation - submit via email or github
  2. ScriptingBridge header documentation - submit via email or github

See below for details on how to generate the documentation sets.

Submitting AppleScript Documentation

Submitted AppleScript documentation must be generated using ASDictionary in order for it to be suitable for inclusion into the documentation archive. See the ASDictionary page for help on using the application. AppleScript documentation submitted directly to the archive must have been generated with the following ASDictionary options selected in the user interface:

  1. File formats - select both HTML (frames) and Compact classes
  2. Terminology styles - select AppleScript

ASDictionary generated documentation will be accepted by email for inclusion in the archive. Send the following to support@mugginsoft.com.

  1. Application company name (Apple, Adobe, etc).
  2. Application name and link.
  3. OS X version of machine that generated the documentation (OS X 10.6 and above only please).
  4. Application version as quoted in the About panel.
  5. The html documentation itself, either in the body of the email or as an attachment. Use the ASDictionary tool as detailed above.

Download ASDictionary. For more information see the ASDictionaryDocs project.

Submitting ScriptingBridge Documentation

The Apple Xcode developer toolchain includes a number of commands that be used to generate a ScriptingBridge header file from a scriptable application. When a ScriptingBridge header file is submitted to the archive it is rendered into HTML using Doxygen before being included in the documentation archive.

The sdp tool is used in conjunction with the sdef tool to generate a ScriptingBridge header file from an application bundle, say appname.app. sdp is included as part of Apple's Xcode developer tool chain. When using Xcode 4 it will be necessary to install the command line tools under Preferences - Downloads - Components. To generate the documentation header file from an application use the following command sequence:

sdef "/path/to/appname.app" | sdp -fh -N appname -o appname.h 

The -N (name) option sets the application prefix that will be used within the generated header file. Failure to set this correctly may result in the use of the default Application term which results in less readable output e.g: the generated application classname will be ApplicationApplicationas opposed to AppnameApplication. This option is also required for application bundles containing spaces in the app name such as Adobe Photoshop CS5.

SB application headers will be accepted by email for inclusion in the archive. Send the following to support@mugginsoft.com.

  1. Application company name (Apple, Adobe, etc).
  2. Application name and link.
  3. OS X version of machine that generated the header (OS X 10.6 and above only please).
  4. Application version as quoted in the About panel.
  5. The SB header itself, either in the body of the email or as an attachment. Use the sdp tool as described above.

For more information see the ScriptingBridgeDox project.