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

beaTunes 4.6.14 - Organize your music co...
beaTunes is a full-featured music player and organizational tool for music collections. How well organized is your music library? Are your artists always spelled the same way? Any R.E.M. vs REM?... Read more
iDefrag 5.1.8 - Disk defragmentation and...
iDefrag helps defragment and optimize your disk for improved performance. Features include: Supports HFS and HFS+ (Mac OS Extended). Supports case sensitive and journaled filesystems. Supports... Read more
Day One 2.1.8 - Maintain a daily journal...
Day One is the easiest and best-looking way to use a journal / diary / text-logging application for the Mac. Day One is well designed and extremely focused to encourage you to write more through... Read more
Spotify 1.0.53.758. - Stream music, crea...
Spotify is a streaming music service that gives you on-demand access to millions of songs. Whether you like driving rock, silky R&B, or grandiose classical music, Spotify's massive catalogue puts... Read more
VirtualBox 5.1.20 - x86 virtualization s...
VirtualBox is a family of powerful x86 virtualization products for enterprise as well as home use. Not only is VirtualBox an extremely feature rich, high performance product for enterprise customers... Read more
Arq 5.7.9 - Online backup to Google Driv...
Arq is super-easy online backup for Mac and Windows computers. Back up to your own cloud account (Amazon Cloud Drive, Google Drive, Dropbox, OneDrive, Google Cloud Storage, any S3-compatible server... Read more
Vienna 3.1.10 :d05d7a5d: - RSS and Atom...
Vienna is a freeware and Open-Source RSS/Atom newsreader with article storage and management via a SQLite database, written in Objective-C and Cocoa, for the OS X operating system. It provides... Read more
WhiteCap 6.7 - Visual plug-in for iTunes...
WhiteCap is a sleek and sophisticated music visualizer and screensaver that features futuristic, wireframe mesh visuals with dynamic backgrounds and colors. WhiteCap contains thousands of visual... Read more
Dropbox 24.4.16 - Cloud backup and synch...
Dropbox is an application that creates a special Finder folder that automatically syncs online and between your computers. It allows you to both backup files and keep them up-to-date between systems... Read more
Amazon Chime 4.2.5645 - Amazon-based com...
Amazon Chime is a communications service that transforms online meetings with a secure, easy-to-use application that you can trust. Amazon Chime works seamlessly across your devices so that you can... Read more

Latest Forum Discussions

See All

Blizzard is looking to hire a mobile dev...
A new thread on the popular video game rumor forum, NeoGAF, uncovered an interesting job listing over at Blizzard Entertainment. It appears the studio behindStarCraft, World of WarCraft, Hearthstone,andOverwatch is looking to bring on a new hire... | Read more »
Legend of Zelda meets Cooking Mama in ne...
Dungeon Chef is what happens when you mix the RPG elements (and style) of a Legend of Zelda game, with cooking elements. Although, now that The Legend of Zelda: Breath of the Wild also has cookingelements, so maybe the gameplay is not so novel.... | Read more »
ChordFlow (Music)
ChordFlow 1.0.0 Device: iOS Universal Category: Music Price: $6.99, Version: 1.0.0 (iTunes) Description: ChordFlow is a chord sequencer with a unique 4-track polyphonic arpeggiator, extensive chord library, MIDI out and Ableton Link... | Read more »
The Walking Dead: A New Frontier is out...
The newest season of Telltale Games'The Walking Dead is well underway. After the release of the third episode, "Above the Law" about a month ago, episode four, "Thicker Than Water" is hot and ready for more zombies and gut-wrenching emotional... | Read more »
Best games we played this week
Another week, another new wave of mobile games do dive into. We've dug through the list of apps that came out this week to tell you which apps are worth your sweet time. And while there weren't too many games this week, there were some big ones.... | Read more »
Vignettes (Games)
Vignettes 1.0.1 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.1 (iTunes) Description: Vignettes is a casual but unique exploration game without text or characters, where objects shapeshift as you spin them around... | Read more »
Get Me Outta Here is an 80s retro shoote...
Are you ready to fight some aliens? Because Crescent Moon Games has released the retro shooter Get Me Outta Here on iOS devices today. [Read more] | Read more »
Get a bunch of Apple productivity apps f...
If you're an Apple Mac owner, you're probably aware of the host of Apple productivity apps the company includes in all new Mac purchases. Apps like iMovie, Keynote, and of course, GarageBand. While you used to be able to also buy these apps... | Read more »
Terra Mystica (Games)
Terra Mystica 1.03 Device: iOS Universal Category: Games Price: $9.99, Version: 1.03 (iTunes) Description: Short Summary:≈≈≈≈≈≈≈≈≈≈≈≈≈ | Read more »
Ms. Spell (Games)
Ms. Spell 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Cast spells and battle monsters in this turn based game, that has you delving into ever the changing Dreadwood to retrieve the lost... | Read more »

Price Scanner via MacPrices.net

15-inch Touch Bar MacBook Pros, Apple refurbi...
Apple is offering Certified Refurbished 2016 15″ Touch Bar MacBook Pros for $360 to $420 off original MSRP. An Apple one-year warranty is included with each model, and shipping is free: - 15″ 2.6GHz... Read more
13-inch MacBook Airs on sale for up to $150 o...
Overstock.com has 13″ MacBook Airs on sale for up to $150 off MSRP including free shipping: - 13″ 1.6GHz/128GB MacBook Air (sku MMGF2LL/A): $869.99 $130 off MSRP - 13″ 1.6GHz/256GB MacBook Air (sku... Read more
15-inch Touch Bar MacBook Pros on sale for $1...
B&H Photo has the new 2016 15″ Apple Touch Bar MacBook Pros in stock today and on sale for up to $200 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.7GHz Touch Bar... Read more
15-inch 2.7GHz Touch Bar MacBook Pros on sale...
Amazon has 2016 15″ 2.7GHz Apple Touch Bar MacBook Pros in stock today and on sale for $150-$200 off MSRP. Shipping is free: - 15″ 2.7GHz Touch Bar MacBook Pro Space Gray (sku MLH42LL/A): $2599 $200... Read more
Apple now offering Certified Refurbished 13-i...
Apple is now offering Certified Refurbished 2016 13″ Touch Bar MacBook Pros for $270-$300 off original MSRP. An Apple one-year warranty is included with each model, and shipping is free: - 13″ 2.9GHz... Read more
MyGiHealth Digestive Symptom Tracker Version...
My Total Health, Inc. has announced the release of MyGiHealth 2.1, an important update to their digestive symptom tracker developed exclusively for iPhone, iPad and iPod touch devices. MyGiHealth is... Read more
Galaxy S8 Materials Costs Highest by Far Comp...
The new Samsung Galaxy S8 equipped with 64 gigabytes (GB) of NAND flash memory carries a bill of materials (BOM) cost that comes out to US$301.60, much higher than for previous versions of the... Read more
iCarMode 4.0 Car Dashboard App For iOS Integr...
Indie developer Diego Resnik has announced the release of iCarMode 4.0, an update to his productivity app developed for iOS devices. iCarMode has positioned itself as a true car dashboard app,... Read more
How to save $150+ on Apple’s 13-inch 2.0GHz n...
Apple Authorized Reseller B&H Photo has non-Touch Bar 13″ 2.0GHz MacBook Pros on sale for $150 off MSRP for a limited time. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.0GHz... Read more
15-inch 2.2GHz Retina MacBook Pro, Apple refu...
Apple has Certified Refurbished 2015 15″ 2.2GHz Retina MacBook Pros available for $1699. That’s $300 off MSRP, and it’s the lowest price available for a 15″ MacBook Pro. An Apple one-year warranty is... Read more

Jobs Board

*Apple* Mac Computer Technician - GeekHampto...
…complex computer issues over the phone and in person? GeekHampton, Long Island's Apple Premium Service Provider, is looking for you! Come work with our crew Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Music Marketing Lead, iTunes & *Apple*...
# Music Marketing Lead, iTunes & Apple Music Job Number: 56868140 Culver City, California, United States Posted: Apr. 17, 2017 Weekly Hours: 40.00 **Job Summary** Read more
*Apple* Media Products - Commerce Engineerin...
Apple Media Products - Commerce Engineering Manager Job Number: 57037480 Santa Clara Valley, California, United States Posted: Apr. 18, 2017 Weekly Hours: 40.00 Job Read more
*Apple* Mac Computer Technician - GeekHampto...
…complex computer issues over the phone and in person? GeekHampton, Long Island's Apple Premium Service Provider, is looking for you! Come work with our crew Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.