16 March 2001
Robert Basler is the president of Aurora Systems, Inc. and a dedicated OS/2 user since he tired of rebooting Windows 3.1 twenty times a day.
If you have a comment about the content
of this article, please feel free to vent in the OS/2 eZine discussion forums.
Do You Write Documentation? You Must Have VyperHelp.
VyperHelp is a quick and easy help editor for anyone needing to produce OS/2 or Windows help files in INF, HLP and HTMLHelp format, or in generic or framed HTML ready for use on the web. You can create new help files in the VyperHelp Editor, or use VyperHelp Convertor to do the heavy-lifting to convert existing help source files in TXT, HPJ, or IPF help formats into VyperHelp's native format, VYD.
InstallationVyperHelp uses IBM's great old installer, so installation is pretty much a matter of unzipping vhelp111.zip and running INSTALL. Tell the installer where you want it to go and after a few moments, the VyperHelp folder will appear on your desktop.
Getting Started with VyperHelpThe first thing I wanted to do was to import my HPJ and RTF help source files into VyperHelp for editing. The recommended way to do this is to use the standalone VyperHelp Converter program. This is a heavy duty version of the conversion routines available in VyperHelp Editor and is recommended for first-time conversions. If you are working with IPF source, VyperHelp can import that as well.
My first import didn't go as well as I would have liked, apparently my RTF source files had become somewhat overcomplicated over the years of editing them with Microsoft Word for Windows 2. Vyperhelp Converter was able to transfer all the text, but many of the bitmaps and links ended up getting dropped from the resulting VyperHelp VYD file. It would have been a lot of work to redo all of those, so I consulted MekTek tech support. I got a lot of help and suggestions from Mat Kramer, the author of VyperHelp, but I finally found the solution on my own. I loaded up a copy of Word 97, read in and saved my RTF file sources, and afterwards VyperHelp was able to translate the files perfectly. Apparently the newer version of Word took out a lot of extra and unnecessary formatting information inserted by Word 2, resulting in files that were easier to parse. As anyone familiar with RTF will explain, it is more art than an exact science.
Once I had the source files massaged, I did one other little trick, I rearranged the order of the RTF source files in the HPJ file so that all of the main subjects were in the order I wanted them to appear in the final help file.
Editing with VyperHelpOnce I had my help files imported, I needed to rearrange all the topics so that they were in an order that made sense. My adjustment of the HPJ file had done a lot of the work, but one thing you learn about Windows online help source files is that they are usually in the order that people thought to add stuff, not necessarily an order that helps the reader. You can see in the screenshot that the left hand panel has a tree view of all the topics, and the right contains the text, bitmaps and links for that topic.
Moving topics around is easy, there are hotkeys which allow you to move a topic, or branch of topics up or down, and even to promote or demote branches. It took me about half an hour to rearrange the 115 or so help sections I had.
One of the things that I really like about VyperHelp is that there are hotkeys for everything. Once you learn the program, you don't have to spend any time looking through menus to get to commonly needed operations such as inserting links.
Editing the help topics is straightforward. Enter your text, set the fonts, do whatever layout work you need to do, insert pictures where you need them, and move on to the next topic. VyperHelp has a particularly nice feature for translators which allows you to easily insert symbols and accented characters into the text. My only criticism is that although VyperHelp Editor is WYSIWYG, it always shows the markup tags such as font change boundaries and end of line characters which I find distracting. It would be nice if these could be turned off and on.
Producing INF and Help FilesIn order to produce the final HLP or INF files, you need either IBM's IPF Compiler, or Microsoft's Help Compiler. VyperHelp just produces source code, not the finished help files. When you are ready to link the help files to your application, VyperHelp can also generate the C header file you will need. Although I was just looking to produce HTML versions of my help, I experimented with both OS/2 INF and Windows HLP and HTMLHelp formats, and found that the help compilers had no problems with the source code generated by VyperHelp.
Producing HTMLI mainly wanted to be able to generate HTML that could be used as documentation by my end-users, as well as on my website. VyperHelp's Export facility can generate either a framed document with the table of contents on the left, content on the right, as well as an index, or a single giant HTML file with the entire help system included minus the table of contents and index.
The single HTML file is not my favourite layout since it basically flattens the hierarchy of help topics you create using VyperHelp, but you may need to use it if you have users who are limited to 8.3 filenames, I'll talk about why next.
I really love the frames version of the HTML help files created by VyperHelp. This creates a 2 pane document, the left pane is either the table of contents or an index, and the right contains the text of the section you are interested in. You can see what this looks like at http://www.aurora-systems.com/manual/index.html This is really slick, I've gotten a lot of really positive feedback from my users on this. The one limitation of the frames version is that you can't specify an .htm extension so that you can make the filenames fit onto an 8.3 drive.
SupportI have been impressed by MekTek's support. All of my questions were answered promptly and helpfully, and a few of my feature suggestions even made it into the current 1.11 version.
Wish ListIts a good thing MekTek continues to develop VyperHelp because there are two additional features I'd like to see. The first is an expanded frames version that supports a collapsible tree view on the left, maybe even using Java. This would really increase the readability of the table of contents.
The other feature that would be nice is a way to import long text documents easily into VyperHelp. Currently if you have a document such as a manual that you want to bring into VyperHelp, you have to create the sections in VyperHelp, then use cut and paste to fill each section with text. An automated way to do this, even if it involved some special markup in the source text, would be helpful.
SummaryIf you need to create help files just for OS/2, or for multiple platforms, you should definitely take a look at VyperHelp. It provides all the necessary tools for help creation at a very affordable price and it is so much faster and easier than manually editing text source files that you cannot make an economic case for not picking up a copy. I really like VyperHelp, I think you will too.
VyperHelp 1.11 by MekTek
Download: vhelp111.zip 30-day timed trial.
Price: U.S. $49 from BMT Micro www.bmtmicro.com