Apple Help Publisher

The standard Mac OS help format for Apple Help Viewer.

The Apple Help Publisher window allows you to customize the appearance of your help book interface by choosing background colors, icon colors, font face and font size, frame borders, and more! HelpLogic includes a variety of icon colors to match whatever background colors you decide to use for your TOC frames. The handy diagram in the top right corner of the window gives you a display preview of your chosen colors and options.

If you choose to assign either an Image Logo or Text Title Logo, then that logo will appear at the top of your Table of Contents frame.

You can also choose your own custom Apple Help Icon to be assigned as your help book icon. When listed in Apple Help Viewer's Mac Help Center, this icon will be displayed next to your help book name (if you properly registered your help book). Choosing a custom help icon is strictly optional. For help books that do not include a custom icon, the Mac Help Center simply displays a default Apple Help Icon next to their names. If you do use a custom icon, make sure it is exactly 16 pixels wide and 16 pixels tall (72 dpi) and saved in GIF format.

What gets published along with your help pages and Table of Contents is full support for Apple Help META tags, Apple Help Icon, etc. Based on the keywords and descriptions that you added to your TOC page topics, the published Apple Help page framesets will include the appropriate keyword and description META tags for compatibility with the Apple Help Indexing Tool and Apple Help Viewer's search engine.

IMPORTANT: The first topic in your TOC needs to be a Page so that the proper Apple Meta Tags get included (such as AppleTitle and AppleIcon). If your first TOC topic is a Chapter, then your published help will not get properly indexed or searched by Mac OS X.

Starting with Mac OS X 10.3 Panther, Apple Help Viewer now supports CSS, but the Apple Help Viewer in older versions of OS X and OS 9 only supports HTML 3.2. If you need to design your help system to be compatible with the Apple Help Viewer in Mac OS X 10.2 Jaguar and earlier, you have the option to set the TOC Compatibility to the older HTML 3.2 format. If you are only designing for Mac OS X 10.3 Panther and higher, then the CSS/HTML option is highly recommended for best visual results. Please note that when publishing, the TOC Compatibility setting only affects the formatting of the TOC (Table of Contents) and not your own help pages from the Source Files folder.

If your HTML source files use the MacRoman text encoding, then use that same one for your TOC Char Set for consistency. The TOC charset is used in the Contents frame that HelpLogic dynamically generates during the publishing process. Be very careful when setting a TOC Char Set, as well as when setting a charset tag in your HTML source files. Apple's official Apple Help documentation warns that in versions of Mac OS prior to 10.1, Help Viewer does not respect the charset tag when rendering HTML. Furthermore, prior to Mac OS X 10.1, Apple Help Viewer supports only a limited number of character encodings, such as the MacRoman, MacJapanese, MacKorean, MacChineseTrad, and MacChineseSimp. Although Apple Help Viewer in Mac OS X 10.1 and later renders Unicode content properly, it currently does not index or search Unicode content. It has been recommended on the Apple Help mailing list that for Chinese, use UTF-8 for best results. Otherwise, for Latin-based languages like English, use a non-Unicode charset like ISO-8859-1.

HelpLogic even supports context-sensitive help for Apple Help! After you have published your help system, you will find a "Context-Sensitive Help.txt" document in your help folder that lists all of the special index files for linking directly to specific help pages. See the Apple Help Documentation for details on how to call these help links from within your software application. IMPORTANT NOTE: The "Context-Sensitive Help.txt" document is for your reference only. This text file should be removed from your help book folder BEFORE indexing your help book with the Apple Help Indexing Tool (or Tiger's Help Indexer) or else the indexing utility will mistakenly include that text file in your help book index.

Making Your Help Book Searchable

In order to make your Apple Help Book searchable from within Apple Help Viewer, you must drop your help book folder on the old Apple Help Indexing Tool utility or the new Help Indexer to generate the appropriate .idx or .helpindex files. If you do not have the Apple Help Indexing Tool or the latest Help Indexer, it is included with Apple's free Developer Tools (available with the Mac OS X installation disks or as a download from Apple's Developer Connection web site).

Help Indexer can create either .idx or .helpindex files. It is important to note that the new .helpindex format was introduced in Mac OS X 10.4 Tiger and only works in Tiger and Leopard. So for optimal compatibility ranging from Mac OS X 10.2 Jaguar to 0.5 Leopard, you should generate both .idx and .helpindex files (which the Help Indexer allows you to do).

NOTE FOR FRONTPAGE USERS: Microsoft FrontPage adds a lot of extra meta tags and data to the HTML code that it generates for HTML pages. The Help Indexer and Apple Help Indexing Tool utilities are known to have problems with these FrontPage meta tags. So if you use FrontPage as an external editor with HelpLogic, be sure to remove those problematic FrontPage meta tags from your help pages before using either the Help Indexer or the Apple Help Indexing Tool.

After creating the appropriate .idx or .helpindex files with the Apple Help Indexing Tool or Help Indexer, in order for your Apple Help Book to be searchable from within Apple Help Viewer and to be listed in the Mac Help Center Library menu, you must also properly register your Apple Help Book with the OS within your application code and related .plist files. Please see the Apple Help Documentation for details.

Apple Help Resources

For information on how to register your help book with the Mac Help Center from within your software application, plus additional details on how to use special Apple Help hyperlinks (which are supported by Code Plugins in HelpLogic's Code Editor), please read the Apple Help Documentation. Below are some URLs for accessing the Apple Help Documentation online.

Apple Help Reference (HTML Online)
http://developer.apple.com/documentation/Carbon/Reference/
Apple_Help/index.html

Apple Help Reference (PDF Download)
http://developer.apple.com/documentation/Carbon/Reference/
Apple_Help/apple_help.pdf

Apple Help Refererence for Leopard (Requires an ADC Account)
https://developer.apple.com/leopard/devcenter/docs/documentation/
UserExperience/HelpTechnologies-date.html

 
Important Note: When selecting a publish location, do NOT choose a directory within your source files folder. Publishing from your source files folder into your source files folder will cause an endless loop, filling your hard drive with endless folders. As of HelpLogic 1.0a2, the Publish feature does not allow you to select the source files folder as your publish location.

When HelpLogic is run in Trial demo mode, Apple Help Table of Contents are limited to 3 topics per chapter. This publishing limitation is removed when you purchase a license and register the application with your serial number.