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

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

calibre 2.17 - Complete e-library manage...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital librarian... Read more
OmniGraffle Pro 6.1.2 - Create diagrams,...
OmniGraffle Pro helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use... Read more
OmniGraffle 6.1.2 - Create diagrams, flo...
OmniGraffle helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use Graffle to... Read more
RoboForm 2.0.2 - Password manager; syncs...
RoboForm is a password manager that offers one-click login, mobile syncing, easy form filling, and reliable security. Password Manager. RoboForm remembers your passwords so you don't have to! Just... Read more
Apple MainStage 3.1 - Live performance t...
Love the sound you got on your recording? MainStage 3 makes it easy to bring all the same instruments and effects to the stage. Everything from the Sound Library and Smart Controls you're familiar... Read more
Freeway Pro 7.0.2 - Drag-and-drop Web de...
Freeway Pro lets you build websites with speed and precision... without writing a line of code! With its user-oriented drag-and-drop interface, Freeway Pro helps you piece together the website of... Read more
A Better Finder Rename 9.44 - File, phot...
A Better Finder Rename is the most complete renaming solution available on the market today. That's why, since 1996, tens of thousands of hobbyists, professionals and businesses depend on A Better... Read more
Stacks 2.6.9 - New way to create pages i...
Stacks is a new way to create pages in RapidWeaver. It's a plugin designed to combine drag-and-drop simplicity with the power of fluid layout. Features: Fluid Layout: Stacks lets you build pages... Read more
Sid Meier's Civilization: Beyond Ea...
Sid Meier's Civilization: Beyond Earth is a new science-fiction-themed entry into the award-winning Civilization series. Set in the future, global events have destabilized the world leading to a... Read more
Logic Pro X 10.1 - Music creation and au...
Apple Logic Pro X is the most advanced version of Logic ever. Sophisticated new tools for professional songwriting, editing, and mixing are built around a modern interface that's designed to get... Read more

Choice Provisions is Set to Launch Destr...
Choice Provisions is Set to Launch Destructamundo on iOS This Month Posted by Tre Lawrence on January 23rd, 2015 [ permalink ] Choice Provisions – home stable to | Read more »
King of Thieves – An Interview With Zept...
Ahead of the release of ZeptoLab’s King of Thieves, we were able to ask ZeptoLab’s co-founder, Semyon Voinov, a few questions about the inspiration behind the game and what that means for the Cut the Rope franchise. | Read more »
Handle Review
Handle Review By Jennifer Allen on January 23rd, 2015 Our Rating: :: SPEEDY ORGANIZINGUniversal App - Designed for iPhone and iPad Handle is a very convenient way of juggling your emails, To Do list, and Calendar all through one... | Read more »
The New Disney Inquizitive App Offers a...
The New Disney Inquizitive App Offers a Place for Fans to Take Disney Quizzes Posted by Tre Lawrence on January 23rd, 2015 [ permalink ] | Read more »
Hands-On With Cut the Rope Developer Zep...
Marking quite a departure from ZeptoLab’s past successes, namely the Cut The Rope series, King of Thieves is shaping up to be quite promising. Due for release in February, we were lucky enough to have some time with a preview build to see exactly... | Read more »
Fast Fishing Review
Fast Fishing Review By Jennifer Allen on January 23rd, 2015 Our Rating: :: LIVES UP TO ITS NAMEUniversal App - Designed for iPhone and iPad Fishing is far from relaxing in Fast Fishing, but it is fun.   | Read more »
The LEGO Movie Video Game is Available N...
The LEGO Movie Video Game is Available Now for iOS Posted by Ellis Spice on January 23rd, 2015 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Satellina Review
Satellina Review By Jennifer Allen on January 23rd, 2015 Our Rating: :: TWITCHY BUT TACTICALUniversal App - Designed for iPhone and iPad Satellina requires quick thinking and twitchy fingers, and it’s pretty fun.   | Read more »
Tail Drift, the Crazy 360 Degree Flyer,...
Tail Drift, the Crazy 360 Degree Flyer, Has Gone Free-to-Play in a New Update Posted by Jessica Fisher on January 22nd, 2015 [ permalink ] | Read more »
PureSkate 2 Review
PureSkate 2 Review By Tre Lawrence on January 22nd, 2015 Our Rating: :: ALMOST ALL AIRUniversal App - Designed for iPhone and iPad PureSkate 2 lets one’s fingers do the skateboarding.   | Read more »

Price Scanner via MacPrices.net

College Student Deals are back, additional $5...
Take an additional $50 off all MacBooks and iMacs at Best Buy Online with their College Students Deals Savings, valid through April 11, 2015. Anyone with a valid .EDU email address can take advantage... Read more
iPhone 6 and 6 Plus GIve Apple Half Of US Mob...
Chicago-based Consumer Intelligence Research Partners, LLC (CIRP) have released analysis of the results of its research on mobile phone manufacturers for the calendar quarter that ended December 31,... Read more
Save $100 on MacBook Airs with 256GB of stora...
B&H Photo has 256GB MacBook Airs on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 11″ 1.4GHz/256GB MacBook Air: $999 $100 off MSRP - 13″ 1.4GHz/256GB MacBook... Read more
21-inch 2.7GHz iMac on sale for $1179, save $...
B&H Photo has the 21″ 2.7GHz iMac on sale for $1179 including free shipping plus NY sales tax only. Their price is $120 off MSRP, and it’s the lowest price available for this model from any... Read more
iPhone Usage Rates by State Correlate With Ed...
Chitika Insights notes that despite iPhones being the largest source of smartphone Internet traffic in North America, their latest study finds a relatively high degree of variation of iPhone usage... Read more
ProGearX Extendable Pole “Pov/Selfie Stick” M...
There’s something inescapably narcissistic about the concept of selfies as they’ve developed as a smartphone-driven social (particularly social media) phenomenon that rubs me the wrong way. However,... Read more
iPad Air 2 on sale for up to $100 off MSRP, 2...
 Best Buy has iPad Air 2s on sale for up to $100 off MSRP on their online store for the next two days. Choose free shipping or free local store pickup (if available). Sale prices available for online... Read more
Roundup of Apple refurbished MacBook Pros and...
The Apple Store has Apple Certified Refurbished 2014 MacBook Pros and MacBook Airs available for up to $400 off the cost of new models. An Apple one-year warranty is included with each model, and... Read more
Sale! 13-inch 2.8GHz Retina MacBook Pro for $...
 B&H Photo has the 13″ 2.8GHz Retina MacBook Pro on sale for $1599 including free shipping plus NY sales tax only. Their price is $200 off MSRP, and it’s the lowest price available for this model... Read more
Next OS X/iOS Version Upgrades Should Concent...
On stage at Apple’s World Wide Developers’ Conference in June 2009, Bertrand Serlet, the company’s Senior Vice President of Software Engineering at the time, announced that the forthcoming OS X... Read more

Jobs Board

*Apple* Solutions Consultant (ASC)- Retail S...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
*Apple* Lead Operator, GSOC - Apple (United...
**Job Summary** Apple is seeking an exceptional, customer service oriented and experienced persons to fulfill the role of Apple Lead Operator (ALO) as part of the Read more
Order Support Supervisor- *Apple* Online Sto...
**Job Summary** The Apple Online Store (AOS) Order Administration team is looking for an Order Support Supervisor to manage and lead a team of Specialists through the Read more
Senior Program Manager, *Apple* Online Supp...
**Job Summary** The Apple Online Support Planning team is looking for an experienced Senior Project Manager to lead key Quality program initiatives across the Online Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.