Enabling Actionscript Help in TextMate

(Update 2007-06-15): James’s comment below reminded me of something I found while tinkering with this further: if you set the TM_FLASH_HELP variable with a full path including your hard drive the third slash in asd.rb is usually unnecessary. I’ve noted this below.

(Update 2007-05-17): It appears that this may not work with some versions of the asd.rb file, leading to the error described by Aaron in the comments section. I’ve added my version of asd.rb below)

For AS2 projects I’ve relied on the excellent Flash help file utility XASH. However, since XASH doesn’t support AS3 yet, I revisited the help utility in the TextMate Actionscript bundle to see if I could get it to work. As I understand it, the bundle help scripts read the contents of the help_toc.xml file that sits with the Flash help html pages. It then renders a list of the matches to your selected word to a screen, which when clicked should bring up the web page for that match. Unfortunately,Sometimes this doesn’t quite work out of the box. Two simple modifications are needed to get this to work Here’s what I tried:

1) The shell variable TM_FLASH_HELP needs to point to /Volumes[Hard Drive Name]/Library/Application Support/Adobe/Flash CS3/en/Configuration/HelpPanel/Help/ActionScriptLangRefV3. You define this in TextMate > Preferences > Shell Variables. Originally I was setting this to //Library/Application Support… but this necessitated the change to asd.rb detailed below. Note that if you want to get this to work for AS2, you can point TM_FLASH_HELP to //Users/Shared/Library/Application Support/Macromedia/Flash 8/en/Configuration/HelpPanel/Help/ActionScriptLangRef.

The change below is no longer needed if you use a full path with your hard drive volume included for TM_FLASH_HELP.

2) The file asd.rb needs to be modified. The file is located in /Applications/TextMate.app/Contents/SharedSupport/Bundles/ActionScript.tmbundle/Support/Tools/asd.rb. To open it you’ll need to right-click on the TextMate app, and select “Show Package Contents”. Within that window browse to the Actionscript.tmbundle, and again right-click and show the package contents. My copy of asd.rb looks like this:

#!/usr/bin/env ruby
#
# Ale Muñoz <ale@bomberstudios.com> - 2006-11-25
# Feel free to use and improve...

require "#{ENV["TM_SUPPORT_PATH"]}/lib/web_preview"
require "rexml/document"

WORD    = ENV['TM_CURRENT_WORD']
HELPDIR		= ENV['TM_FLASH_HELP']
HELPTOC		= 'help_toc.xml'

# Help dir not set?
if !HELPDIR
	puts html_head(
		:title => "Error!",
		:subtitle => "Find in ActionScript Dictionary"
	)
	puts <<heredoc
	<h1>Search failed for #{WORD}</h1>
	<p>In order for this command to work TextMate needs to know where to find the ActionScript Dictionary index file. This is set in <strong>Preferences > Advanced > Shell Variables</strong>.</p>
	<p>Click <strong>+</strong> and name the variable <code>TM_FLASH_HELP</code> with value of the path to the directory containing the help_toc.xml file on your system.</p>
	<p>Macromedia have made this tricky and the files arent always in the same place.</p>
	<p>Try clicking the following links:
	<ul>
	<li><a href="txmt://open?url=file:///Users/Shared/Library/Application Support/Macromedia/Flash 8/en/Configuration/HelpPanel/Help/ActionScriptLangRef/help_toc.xml">//Users/Shared/Library/Application Support/Macromedia/Flash 8/en/Configuration/HelpPanel/Help/ActionScriptLangRef</a></li>
	<li><a href="txmt://open?url=file:///Library/Application Support/Adobe/Flash CS3/en/Configuration/HelpPanel/Help/ActionScriptLangRefV3/help_toc.xml">//Library/Application Support/Adobe/Flash CS3/en/Configuration/HelpPanel/Help/ActionScriptLangRefV3</a></li>
	<li><a href="txmt://open?url=file:///Users/Shared/Library/Application Support/Macromedia/Flash MX 2004/en/Configuration/HelpPanel/Help/ActionScriptLangRef/help_toc.xml">//Users/Shared/Library/Application Support/Macromedia/Flash MX 2004/en/Configuration/HelpPanel/Help/ActionScriptLangRef</a></li>
	<li><a href="txmt://open?url=file:///Applications/Macromedia Flash MX 2004/First Run/HelpPanel/Help/ActionScriptDictionary">/Applications/Macromedia Flash MX 2004/First Run/HelpPanel/Help/ActionScriptDictionary</a></li>
	</ul>
	<p>If any of the links work (TextMate will open the help_toc.xml file) then copy and paste the link, omitting the /help_toc.xml on the end, to the path of the shell variable.
HEREDOC
	html_footer
else

	# Open TOC...
	toc_lines = IO.readlines(HELPDIR + "/" + HELPTOC)

	# ...find matching lines...
	search_results = []
	toc_lines.each do |line|
		search_results << line.strip if line[/name=\"#{WORD}/]
	end

	puts html_head( :title => "Documentation for ‘#{WORD}’", :sub_title => "ActionScript Dictionary" )

	# ...parse results for links...
	links = []
	puts "<ul>"
	search_results.each do |line|
		xml_line = REXML::Document.new(line)
		puts "<li><a href=\"tm-file:///#{HELPDIR}/#{xml_line.root.attributes['href']}\">#{xml_line.root.attributes['name']}</a></li>"
	end
	puts "</ul>"

	# ...or display error if no matches
	puts "No results :(" if search_results.size == 0

	html_footer

end

Once you have asd.rb open, you need to make one small change. Line 52 builds the url(s) to the help file html page(s). Add an extra slash to the “tm-file:” prefix. It should now read “tm-file:///” instead of “tm-file://”. Without this fix, you’ll get a listing of matches to your selected word, but the link won’t work.

Save asd.rb, rRestart TextMate, and you should now be able to highlight a word in your code and hit control-H to look for that word in the Flash help files. For example, try highlighting “MovieClip”. You should get a listing for both the MovieClip class, and the MovieClip() constructor.

One quirk of the bundle’s reliance on the help_toc.xml file is that the words show up twice in the xml, and thus you’ll see the listing of matches to your word twice. Still, it’s a small price to pay for a quicker help lookup than the IDE’s sluggish help panel.