AIR Help: Proto 3 - Misc Notes
=======================================================================

main.mxml - Defines the layout of the application as well as the ActionScript code that drives it. You may need to change some of the string globals, but don't have to touch it (unless you want just one TOC .. see below for info on disabling the multi TOCs).

main-app.xml - The "Application Descriptor File" .. mostly a bunch of comments. Change the exposed values when making your own version of an AIR Help file.

help/ - Contains all of the HTML files that make up the Help system. This also contains the Perl script (build-index.pl) for generating the search index.

airhelp_48.png - The application icon, referenced in the main-app.xml file.

help/_searchIndex.xml - The search index file.

_remoteSearchIndex.xml - The "remote" search index file.

airhelp-ix.xml - The Keyword Index file.

airhelp-toc.xml and airhelp-toc2.xml - The two Table of Contents files.


Search: The full text search is achieved by creating a search index from all of the content in the HTML files. This index is made up of all of the content (without the HTML tags and coding), and has stopwords and punctuation removed and spaces collapsed. A Perl script is provided that will properly generate a search index (XML file) from a folder of HTML files. Additional information about building the index is provided in the build-index.pl file in the help folder. The search code matches forst on the entire query string, then on each word in the query. A match on the whole string or a match in a title is weighted higher than other matches. The weighting algorithm is very crude but works reasonably well (definitely come room for improvement there). It might be nice to eventually do some word stemming and provide a method for defining synonyms.

Keyword Index: This is defined by an XML file that is made up of nested elements. The element can have two attributes, navtitle and href. The navtitle attribute is required and defines the text of the node. The href attribute is optional, if it exists, it defines the topic that is displayed when the node is selected. The value of hte href attribute is relative to the "app", and can specify a full URL if you want to link to an external website.

Table of Contents: Similar to the Keyword Index in structure, the TOC is made up of nested elements with href and navtitle attributes. The current prototype provides two TOC panels, if you want only one, search for "ONETOC" in the main.mxml file and you'll see which lines to comment out.

Context-sensitive Help calls: To make a context sensitive Help call, I've set it up so that when an HTML filename is passed to the AIR executable as a command line argument, that topic is displayed. Because only one instance of the EXE can run at one time, if you run the EXE with an HTML filename after it's already running, it will update the running instance with the new topic. You can also pass the keyword "search" followed by a quoted query string to perform a search from an external app.

Examples:

- To display the "image.html" file..
"AIR Help - Proto Three.exe" image.html

- To display the Search panel, prepopulated with a query..
"AIR Help - Proto Three.exe" search "this is a test"