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

Dropbox 193.4.5594 - Cloud backup and sy...
Dropbox is a file hosting service that provides cloud storage, file synchronization, personal cloud, and client software. It is a modern workspace that allows you to get to all of your files, manage... Read more
Google Chrome 122.0.6261.57 - Modern and...
Google Chrome is a Web browser by Google, created to be a modern platform for Web pages and applications. It utilizes very fast loading of Web pages and has a V8 engine, which is a custom built... Read more
Skype 8.113.0.210 - Voice-over-internet...
Skype is a telecommunications app that provides HD video calls, instant messaging, calling to any phone number or landline, and Skype for Business for productive cooperation on the projects. This... Read more
Tor Browser 13.0.10 - Anonymize Web brow...
Using Tor Browser you can protect yourself against tracking, surveillance, and censorship. Tor was originally designed, implemented, and deployed as a third-generation onion-routing project of the U.... Read more
Deeper 3.0.4 - Enable hidden features in...
Deeper is a personalization utility for macOS which allows you to enable and disable the hidden functions of the Finder, Dock, QuickTime, Safari, iTunes, login window, Spotlight, and many of Apple's... Read more
OnyX 4.5.5 - Maintenance and optimizatio...
OnyX is a multifunction utility that you can use to verify the startup disk and the structure of its system files, to run miscellaneous maintenance and cleaning tasks, to configure parameters in the... Read more
Hopper Disassembler 5.14.1 - Binary disa...
Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32- and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about its... Read more

Latest Forum Discussions

See All

Zenless Zone Zero opens entries for its...
miHoYo, aka HoYoverse, has become such a big name in mobile gaming that it's hard to believe that arguably their flagship title, Genshin Impact, is only three and a half years old. Now, they continue the road to the next title in their world, with... | Read more »
Live, Playdate, Live! – The TouchArcade...
In this week’s episode of The TouchArcade Show we kick things off by talking about all the games I splurged on during the recent Playdate Catalog one-year anniversary sale, including the new Lucas Pope jam Mars After Midnight. We haven’t played any... | Read more »
TouchArcade Game of the Week: ‘Vroomies’
So here’s a thing: Vroomies from developer Alex Taber aka Unordered Games is the Game of the Week! Except… Vroomies came out an entire month ago. It wasn’t on my radar until this week, which is why I included it in our weekly new games round-up, but... | Read more »
SwitchArcade Round-Up: ‘MLB The Show 24’...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for March 15th, 2024. We’re closing out the week with a bunch of new games, with Sony’s baseball franchise MLB The Show up to bat yet again. There are several other interesting games to... | Read more »
Steam Deck Weekly: WWE 2K24 and Summerho...
Welcome to this week’s edition of the Steam Deck Weekly. The busy season has begun with games we’ve been looking forward to playing including Dragon’s Dogma 2, Horizon Forbidden West Complete Edition, and also console exclusives like Rise of the... | Read more »
Steam Spring Sale 2024 – The 10 Best Ste...
The Steam Spring Sale 2024 began last night, and while it isn’t as big of a deal as say the Steam Winter Sale, you may as well take advantage of it to save money on some games you were planning to buy. I obviously recommend checking out your own... | Read more »
New ‘SaGa Emerald Beyond’ Gameplay Showc...
Last month, Square Enix posted a Let’s Play video featuring SaGa Localization Director Neil Broadley who showcased the worlds, companions, and more from the upcoming and highly-anticipated RPG SaGa Emerald Beyond. | Read more »
Choose Your Side in the Latest ‘Marvel S...
Last month, Marvel Snap (Free) held its very first “imbalance" event in honor of Valentine’s Day. For a limited time, certain well-known couples were given special boosts when conditions were right. It must have gone over well, because we’ve got a... | Read more »
Warframe welcomes the arrival of a new s...
As a Warframe player one of the best things about it launching on iOS, despite it being arguably the best way to play the game if you have a controller, is that I can now be paid to talk about it. To whit, we are gearing up to receive the first... | Read more »
Apple Arcade Weekly Round-Up: Updates an...
Following the new releases earlier in the month and April 2024’s games being revealed by Apple, this week has seen some notable game updates and events go live for Apple Arcade. What The Golf? has an April Fool’s Day celebration event going live “... | Read more »

Price Scanner via MacPrices.net

Apple Education is offering $100 discounts on...
If you’re a student, teacher, or staff member at any educational institution, you can use your .edu email address when ordering at Apple Education to take $100 off the price of a new M3 MacBook Air.... Read more
Apple Watch Ultra 2 with Blood Oxygen feature...
Best Buy is offering Apple Watch Ultra 2 models for $50 off MSRP on their online store this week. Sale prices available for online orders only, in-store prices may vary. Order online, and choose... Read more
New promo at Sams Club: Apple HomePods for $2...
Sams Club has Apple HomePods on sale for $259 through March 31, 2024. Their price is $40 off Apple’s MSRP, and both Space Gray and White colors are available. Sale price is for online orders only, in... Read more
Get Apple’s 2nd generation Apple Pencil for $...
Apple’s Pencil (2nd generation) works with the 12″ iPad Pro (3rd, 4th, 5th, and 6th generation), 11″ iPad Pro (1st, 2nd, 3rd, and 4th generation), iPad Air (4th and 5th generation), and iPad mini (... Read more
10th generation Apple iPads on sale for $100...
Best Buy has Apple’s 10th-generation WiFi iPads back on sale for $100 off MSRP on their online store, starting at only $349. With the discount, Best Buy’s prices are the lowest currently available... Read more
iPad Airs on sale again starting at $449 on B...
Best Buy has 10.9″ M1 WiFi iPad Airs on record-low sale prices again for $150 off Apple’s MSRP, starting at $449. Sale prices for online orders only, in-store price may vary. Order online, and choose... Read more
Best Buy is blowing out clearance 13-inch M1...
Best Buy is blowing out clearance Apple 13″ M1 MacBook Airs this weekend for only $649.99, or $350 off Apple’s original MSRP. Sale prices for online orders only, in-store prices may vary. Order... Read more
Low price alert! You can now get a 13-inch M1...
Walmart has, for the first time, begun offering new Apple MacBooks for sale on their online store, albeit clearance previous-generation models. They now have the 13″ M1 MacBook Air (8GB RAM, 256GB... Read more
Best Apple MacBook deal this weekend: Get the...
Apple has 13″ M2 MacBook Airs available for only $849 today in their Certified Refurbished store. These are the cheapest M2-powered MacBooks for sale at Apple. Apple’s one-year warranty is included,... Read more
New 15-inch M3 MacBook Air (Midnight) on sale...
Amazon has the new 15″ M3 MacBook Air (8GB RAM/256GB SSD/Midnight) in stock and on sale today for $1249.99 including free shipping. Their price is $50 off MSRP, and it’s the lowest price currently... Read more

Jobs Board

Early Preschool Teacher - Glenda Drive/ *Appl...
Early Preschool Teacher - Glenda Drive/ Apple ValleyTeacher Share by Email Share on LinkedIn Share on Twitter Read more
Senior Software Engineer - *Apple* Fundamen...
…center of Microsoft's efforts to empower our users to do more. The Apple Fundamentals team focused on defining and improving the end-to-end developer experience in Read more
Relationship Banker *Apple* Valley Main - W...
…Alcohol Policy to learn more. **Company:** WELLS FARGO BANK **Req Number:** R-350696 **Updated:** Mon Mar 11 00:00:00 UTC 2024 **Location:** APPLE VALLEY,California Read more
Medical Assistant - Surgical Oncology- *Apple...
Medical Assistant - Surgical Oncology- Apple Hill WellSpan Medical Group, York, PA | Nursing | Nursing Support | FTE: 1 | Regular | Tracking Code: 200555 Apply Now Read more
Early Preschool Teacher - Glenda Drive/ *Appl...
Early Preschool Teacher - Glenda Drive/ Apple ValleyTeacher Share by Email Share on LinkedIn Share on Twitter Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.