TweetFollow Us on Twitter

Application Help

Volume Number: 19 (2003)
Issue Number: 10
Column Tag: Programming

Application Help

Authoring and Deploying Help in a Multi-Platform World

by MacTech Reviews

Introduction

Every significant desktop application requires an integrated help system. Most successful applications will ultimately run on Mac OS X, Windows, and possibly other platforms like Mac OS 9, and Linux. Product development is seldom a one-time event, but rather an ongoing process of enhancement, evolution, and bug fixing. Developers need a strategy for authoring, deploying, and maintaining help systems in a multiple platform world.

Some IDE (Interactive Development Environment) vendors have recognized the need to develop for multiple platforms. With RealBasic, from Real Software, you can create your application once with a bit of conditional logic to handle platform-specific issues, then generate builds targeted for Mac OS X, Mac OS 9 and/or Windows. Likewise, Borland's Delphi is a popular IDE for Windows that has a source code compatible cousin on Linux named Kylix. These tools enable your application to take advantage of the unique features, and user interface, of each operating system, yet can substantially reduce the cost of multi-platform development.

MacHelp is the HTML based help format developed by Apple for Macintosh software. Most Windows applications use Microsoft's HTML Help or its predecessor, WinHelp. Many help authoring tools have been developed around these formats. Unfortunately, when Apple and Microsoft created their platform specific help formats, easy porting to competing platforms was not a high priority.

Linux started as a variant of Unix, with a command line interface, but in recent years improvements to the KDE and GNOME desktop environments have made Macintosh and Windows users feel right at home. Help information for Linux has traditionally been delivered as ReadMe files, MAN pages, or HTML files. These approaches are awkward and inadequate for new GUI programs arriving on Linux as it moves to the desktop in more organizations.

Help authoring approaches for Macintosh typically rely on editing a collection of topic files using HTML tags for formatting. Lots of time is spent on formatting pages, organizing topics and managing and maintaining hundreds of links between topics. Given enough time and effort, you'll end up with a nice help system for your Mac OS X application, but then must substantially rework it when porting to Windows or Linux.

QuickHelp is a new authoring tool based on the idea of writing help once, then deploying it to virtually any platform including Mac OS 9, Mac OS X, Windows 95 to XP and Linux KDE or GNOME. This article provides an overview of QuickHelp, shows how to develop a help system, add context sensitive application links to help topics, and then deploy your help system to Macintosh, Windows, and Linux computers.


QuickHelp Viewer on Mac OS X

QuickHelp Overview

Most help systems, including MacHelp, store topics as a folder of HTML pages that reference other files containing images and indexes. Microsoft's HTML Help lets you compile your help system to a compressed file, making it easier to deploy. When users activate help for an application, a separate viewer executable allows them to navigate and view topics. The help format and Viewer executable are tied to a specific platform.

QuickHelp stores the topic text, images and organizational information for your help system in a platform neutral XML file. XML (eXtensible Markup Language) is an industry standard format for storing and exchanging information. It describes information as tagged data in a text file that's human readable, self-documenting, and widely supported throughout the software industry by editing and parsing tools.

Like any help system, topics and navigational features are presented via a Viewer. There are four QuickHelp Viewers, one each for Mac OS 9, Mac OS X, Windows and Linux. The Windows Viewer runs on any Windows operating system from 95 through XP. The Linux Viewer runs on all popular Linux distributions including Mandrake, Red Hat and Suse, and supports the leading desktop environments KDE and GNOME. QuickHelp Viewers for MacOS X and Windows can be downloaded from shareware sites. QuickHelp developers can distribute the Viewer executable royalty-free along with their help file.

Regardless of the tools you use, help authoring can be characterized as an iterative Organize-Edit-Build-Test process. Most authoring tools give you a project environment where you can add and organize HTML files and images. Some tools let you edit topics directly while others require separate text or HTML editors. Creating topics with colored text, formatted images, and hypertext links can be a labor-intensive process when using HTML tags. Most tools use a build process that links everything together before you can view and test the finished help system. Depending on the authoring tool, there may be features for locating missing links and image references.

The Builder edition of QuickHelp tightly integrates the Organize-Edit-Build-Test process into a single tabbed window. The Builder looks just like the Viewer, with the addition of the Edit and General panels for organizing, editing, and managing your help file. From the Edit panel, you can create, edit, and delete topics and organize them in the Contents tree. Your help information is stored directly in the XML file. When you're ready to view the finished help, just click the Contents or Index tab. QuickHelp eliminates the build process, and integrates the Viewer's features directly into the Builder for quick testing. By integrating the entire authoring process into one tabbed window, the learning curve for QuickHelp is reduced to about 10 minutes, and developer productivity is improved.

Creating Topics

The Edit panel is used to create topics in a help file. The left side of the panel has a table of contents that shows the title, indentation, and position of each topic. When a topic is selected, its information is shown in the fields on the right side of the Edit panel. There are fields to title the topic, assign conditions that affect its visibility, write its body text, identify index words that appear in the user's index, and assign a unique integer or string to identify the topic for an application's context sensitive help.


Edit Panel of QuickHelp Builder

The New button is used to create a topic in the table of contents below the selected topic. The Delete button deletes the selected topic. The Move button is used to move a single topic or group of topics to a different location or indentation within the table of contents. Use the arrow buttons to change the position or indentation of a selected topic.

Formatting Topics and Adding Images

The Insert Tag button, at the top right of the Body field, is used to insert a tag into the text of a topic for applying text styles, adding links to other topics, or inserting formatted images. Although it is possible to edit formatting tags directly in the Body field, it is easier to just click the Insert Tag button, and choose a popup menu command. For image tags, a dialog is presented to select an image and define caption text and formatting.


Image Definition Dialog

Linking Topics

Hypertext links connect highlighted words to other topics in the same help file, or in a different help file. Local and global link tables relate matching words in a topic body to the target topic. QuickHelp automates the process of creating and maintaining links when repositioning or renaming topics. To create a link, just select some text in the topic, click the Insert Tag button, and pick the target of that link from the Link Definition dialog.


Link Selected Text from One Topic to Another Topic

Like HTML approaches, topics in QuickHelp are created with text and formatting tags. Topic editing in QuickHelp trades some of the flexibility, and most of the complexity of creating HTML pages, for a simpler, more productive environment. The end result is professional looking topics that are consistently formatted and viewable on any platform.

Making Topics Conditional

Regardless of how similar your application is on each platform, there's bound to be a few platform specific features. You could create your help file for, say, the Macintosh platform, and then copy that file and modify it a bit to create a Windows version. While that's a lot less work than learning to use different help tools and rewriting the help system for each platform, you'll still have different help files to maintain for each new release of your application. Furthermore, larger applications are sometimes offered in several different editions on each platform, so you may want a customized help system for each edition. Using conditional topics, QuickHelp makes it easy to support multiple platforms and multiple editions of your application with a single help file.

For example, lets assume you have an application that's available in Demo, Standard and Professional editions, and it runs on Mac OS 9, Mac OS X, Windows, and Linux. During runtime, you'll probably want to present 12 slightly different flavors of your help system originating from one QuickHelp file.

Help topics can be conditional, and text or images within a topic can be conditional. When viewed in the Contents or Index panel of the QuickHelp Viewer, those topics, or portions of a topic, will be hidden or visible based on the current conditions.

To conditionally include a topic, define its condition in the Condition field of the Edit panel. The conditional expression contains names, and Boolean operations that evaluate TRUE or FALSE during runtime. Use the Conditionals dialog, accessible from the General tab, to define names and/or set the current state of those names. In this example, we'll use the names Demo, Standard, and Professional.

Within the condition you can use AND, OR, XOR, NOT, ( or ) to create the expression. Here is an example that conditionally includes the topic in just the Professional edition when running on the Mac OS X platform:

Professional AND MacOSX

If the State checkbox is set for the Professional name in the Conditionals dialog, and this help file is currently running on Mac OS X, then the topic is visible, otherwise it is hidden.

Topics can be nested in a tree structure. If a topic is hidden, all topics nested under it are also hidden. It isn't necessary to repeat the conditions of any parent topic of a subtree, but it is okay to do so if it helps you remember exactly what conditions apply to each topic. QuickHelp automatically removes hyperlinks from the rest of your help system to those hidden topics during runtime.

To conditionally include a portion of text within the body of a topic, enclose it within #ifcondition, and #endcondition as shown below.

#ifcondition Professional AND MacOSX
You're running the Professional edition on Mac OS X
#endcondition

Locating Topics

The Index Words field of the Edit panel is used to automatically build an alphabetical index of keywords that the help author wants to associate with each topic. During runtime, the help user can locate, and navigate to topics from the Contents panel, or the Index panel by clicking hyperlinks within a topic, or by clicking on the Back and Forward buttons to step through recent viewing history.

The entire help system is usually deployed as a single XML file. For really large projects with different subject areas, you can chain separate help files together with hypertext links.

The help user can use the Find Topics dialog to locate help topics that contain specific words in its body.

Each Topic has an ID field that contains a unique number, or string, that can be used to identify that topic from the application when implementing context sensitive help. For example, if the user positions the mouse over a menu command, window, or dialog within your application, you can run the QuickHelp Viewer by having the user press F1, triggering the Viewer to present the related help topic. Context sensitive help is discussed below.

Working with Help Files

The General panel is used to read and write help files, edit global link definitions, and set preferences. There are command buttons to create, open, save, and verify help files. Help topics can be listed to text, or imported from text. The help developer can assign a default font which can later be changed by the help user.

Context Sensitive Help

You can double-click the QuickHelp executable or a help file to launch QuickHelp. More often, a user wants to view a help topic related to a specific feature in the application.

Once the help file has been developed and tested on the various platforms, and accounts for the slight user interface and feature differences, you're ready to add context sensitive links from the application. In Windows, users expect to press F1 when the cursor is positioned over a menu command, window, or dialog to see the related help topic. Likewise, you can support F1, or any approach of your choosing, for each platform using simple communication commands between your application and QuickHelp. These commands send the ID of a topic to QuickHelp, based on the user's context within the application.

Windows programs talk to QuickHelp using a couple of COM (Component Object Model) methods. COM is a Microsoft technology for sending data from one application to another that's supported by virtually every Windows programming language. Macintosh applications talk to QuickHelp utilizing a few different Apple Events. A Linux application would use a pipe for communication.

In each case, the application would need some code inserted to allow it to recognize that the F1 key was pressed, and ensure the appropriate topic ID was sent to QuickHelp using a COM method, AppleEvent, or Linux pipe. QuickHelp provides a description of these commands, and a snippet of code that can be customized for the language, or platform of choice.

QuickHelp also comes with a ready-to-use RealBasic QuickHelpController class, a Delphi TQuickHelpController class, and a Kylix THelpViewer class. To complete a multi-platform help authoring project, use these source code classes, or create something similar, in your own application code. Finally, add the appropriate topic IDs to each menu command, window, and dialog, then test to ensure that the appropriate topics get displayed in QuickHelp.

Conclusion

To create a good help system, a developer needs to understand what a help system is, and what it is not. The purpose of a help system is to quickly inform the user, not entertain them with flashy pictures, or moving video. Pictures can add a professional touch when used to guide and reinforce understanding, but don't waste screen space with snapshots that are quickly outdated when new features are added to your application.

Help topics should be short, cohesive, and to the point. Don't make users scroll through long topics to find the information they want, or expect them to read your help information page by page like a book. Users go to a help system when they have a specific question or problem, so most topics should be very task oriented. Listen to the questions users ask when learning to use your software, and make sure there's a topic that addresses each one, a descriptive title that clearly identifies it, and keywords that make it easy to locate.

If you're developing an application that will forever run on only one platform, you have many programming languages, IDEs, and help authoring tools to choose from. However, if your application resides in a multi-platform world, then you'll need to carefully weigh the alternatives for developing and maintaining your code and help system.

In addition to simplifying the authoring process, QuickHelp makes it easy to create and maintain a single help file that can be deployed on different operating systems, supports multiple product editions, and works for applications written in virtually any programming language. It provides a consistent, professional help environment for both users and developers.


MacTech Staff

 
AAPL
$100.96
Apple Inc.
-0.83
MSFT
$47.52
Microsoft Corpora
+0.84
GOOG
$596.08
Google Inc.
+6.81

MacTech Search:
Community Search:

Software Updates via MacUpdate

Audio Hijack Pro 2.11.3 - Record and enh...
Audio Hijack Pro drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio with Audio Hijack... Read more
Airfoil 4.8.9 - Send audio from any app...
Airfoil allows you to send any audio to AirPort Express units, Apple TVs, and even other Macs and PCs, all in sync! It's your audio - everywhere. With Airfoil you can take audio from any... Read more
WhatRoute 1.13.0 - Geographically trace...
WhatRoute is designed to find the names of all the routers an IP packet passes through on its way from your Mac to a destination host. It also measures the round-trip time from your Mac to the... Read more
Chromium 37.0.2062.122 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. FreeSMUG-Free OpenSource Mac User Group build is... Read more
Attachment Tamer 3.1.14b9 - Take control...
Attachment Tamer gives you control over attachment handling in Apple Mail. It fixes the most annoying Apple Mail flaws, ensures compatibility with other email software, and allows you to set up how... Read more
Duplicate Annihilator 5.0 - Find and del...
Duplicate Annihilator takes on the time-consuming task of comparing the images in your iPhoto library using effective algorithms to make sure that no duplicate escapes. Duplicate Annihilator detects... Read more
jAlbum Pro 12.2 - Organize your digital...
jAlbum Pro has all the features you love in jAlbum, but comes with a commercial license. With jAlbum, you can create gorgeous custom photo galleries for the Web without writing a line of code!... Read more
jAlbum 12.2 - Create custom photo galler...
With jAlbum, you can create gorgeous custom photo galleries for the Web without writing a line of code! Beginner-friendly, with pro results Simply drag and drop photos into groups, choose a design... Read more
Quicken 2015 2.0.4 - Complete personal f...
Quicken 2015 helps you manage all your personal finances in one place, so you can see where you're spending and where you can save. Quicken automatically categorizes your financial transactions,... Read more
iMazing 1.0 - Complete iOS device manage...
iMazing (formerly DiskAid) is the ultimate iOS device manager with capabilities far beyond what iTunes offers. With iMazing and your iOS device (iPhone, iPad, or iPod), you can: Copy music to and... Read more

Latest Forum Discussions

See All

View Source – HTML, JavaScript and CSS...
View Source – HTML, JavaScript and CSS 1.0 Device: iOS Universal Category: Utilities Price: $.99, Version: 1.0 (iTunes) Description: View Source is an app plus an iOS 8 Safari extension that makes it easy to do one key web developer... | Read more »
Avenged Sevenfold’s Hail To The King: De...
Avenged Sevenfold’s Hail To The King: Deathbat is Coming to iOS on October 16th Posted by Jessica Fisher on September 19th, 2014 [ permalink ] Just in time for Halloween, on October 16 Avenged Sevenfold will be launching | Read more »
Talisman Has Gone Universal – Can Now be...
Talisman Has Gone Universal – Can Now be Played on the iPhone Posted by Jessica Fisher on September 19th, 2014 [ permalink ] | Read more »
Tap Army Review
Tap Army Review By Jennifer Allen on September 19th, 2014 Our Rating: :: SHOOT EM ALLUniversal App - Designed for iPhone and iPad Mindless but fun, Tap Army is a lane-based shooter that should help you relieve some stress.   | Read more »
Monsters! Volcanoes! Loot! Epic Island f...
Monsters! Volcanoes! Loot! | Read more »
Plunder Pirates: Tips, Tricks, Strategie...
Ahoy There, Seadogs: Interested in knowing our thoughts on all this plundering and pirating? Check out our Plunder Pirates Review! Have you just downloaded the rather enjoyable pirate-em-up Plunder Pirates and are in need of some assistance? Never... | Read more »
Goat Simulator Review
Goat Simulator Review By Lee Hamlet on September 19th, 2014 Our Rating: :: THE GRUFFEST OF BILLY GOATSUniversal App - Designed for iPhone and iPad Unleash chaos as a grumpy goat in this humorous but short-lived casual game.   | Read more »
A New and Improved Wunderlist is Here fo...
A New and Improved Wunderlist is Here for iOS 8 Posted by Jessica Fisher on September 19th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Evernote Update for iOS 8 Adds Web Clipp...
Evernote Update for iOS 8 Adds Web Clipping, Quick Notes, and More Posted by Ellis Spice on September 19th, 2014 [ permalink ] | Read more »
Apple Names Ultimate Productivity Bundl...
Apple Names Ultimate Productivity Bundle by Readdle as the Essential Bundle on the App Store Posted by Jessica Fisher on September 19th, 2014 [ permalink | Read more »

Price Scanner via MacPrices.net

iFixIt Tears Down iPhone 6; Awards Respectabl...
iFixit notes that even the smaller 4.7″ iPhone 6 is a giant among iPhones; so big that Apple couldn’t fit it into the familiar iPhone form factor. In a welcome reversal of a recent trend to more or... Read more
Phone 6 Guide – Tips Book For Both iPhone 6...
iOS Guides has announced its latest eBook: iPhone 6 Guide. Brought to you by the expert team at iOS Guides, and written by best-selling technology author Tom Rudderham, iPhone 6 Guide is packed with... Read more
How to Upgrade iPhone iPad to iOS 8 without D...
PhoneClean, a iPhone cleaner utility offered by iMobie Inc., reveals a solution for upgrading iPhone and iPad to iOS 8 without deleting photos, apps, the new U2 album or anything. Thanks to more than... Read more
Inpaint 6 – Photo Retouching Tool Gets Faster...
TeoreX has announced Inpaint 6, a simple retouching tool for end users that helps remove scratches, watermarks, and timestamps as well as more complex objects like strangers, unwanted elements and... Read more
Worldwide PC Monitor Market Sees Growth in To...
Worldwide PC monitor shipments totaled 32.5 million units in the second quarter of 2014 (2Q14), a year-over-year decline of -2.9%, according to the International Data Corporation (IDC) Worldwide... Read more
Updated Price Trackers
We’ve updated our Mac Price Trackers with the latest information on prices, bundles, and availability on systems from Apple’s authorized internet/catalog resellers: - 15″ MacBook Pros - 13″ MacBook... Read more
Mac Pros available for up to $260 off MSRP
Adorama has Mac Pros on sale for up to $260 off MSRP. Shipping is free, and Adorama charges sales tax in NY & NJ only: - 4-core Mac Pro: $2839.99, $160 off MSRP - 6-core Mac Pro: $3739.99, $260... Read more
13-inch 2.6GHz/256GB Retina MacBook Pros avai...
B&H Photo has the 13″ 2.6GHz/256GB Retina MacBook Pro on sale for $1379 including free shipping plus NY sales tax only. Their price is $120 off MSRP. Read more
Previous-generation 15-inch 2.0GHz Retina Mac...
B&H Photo has leftover previous-generation 15″ 2.0GHz Retina MacBook Pros now available for $1599 including free shipping plus NY sales tax only. Their price is $400 off original MSRP. B&H... Read more
21″ 2.7GHz iMac available for $1179, save $12...
Adorama has 21″ 2.7GHz Hawell iMacs on sale for $1179.99 including free shipping. Their price is $120 off MSRP. NY and NJ sales tax only. Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** At the Apple Store, you connect business professionals and entrepreneurs with the tools they need in order to put Apple solutions to work in their Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** The Apple Store is a retail environment like no other - uniquely focused on delivering amazing customer experiences. As an Expert, you introduce people Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** As businesses discover the power of Apple computers and mobile devices, it's your job - as a Solutions Engineer - to show them how to introduce these Read more
Position Opening at *Apple* - Apple (United...
…Summary** As a Specialist, you help create the energy and excitement around Apple products, providing the right solutions and getting products into customers' hands. You Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.