21.5 Help files without tears


Software Engineering and Computer Games is about software engineering and about games development. As part of the package, you need to learn how to make a fully complete program all on your own. This means you need some minimal knowledge about how to make a help file , that is a file that users can read from within your program.

We've already mentioned that from the earliest build on, your program should always include a User's Guide. And that it's crucial to discipline yourself to do this. Working on the User 's Guide should go hand-in-hand with working on your project specification.

It turns out that you can use the very same text file as 'source' for both a print version of the User's Guide and a corresponding help file. So you might as well actually have a help file from quite early on. After all, as long as you have a User's Guide written, it makes sense to make it into a help file that your co-workers , professor , family, friends , etc. can look at when they test out your new build of the program. People are sometimes more willing to look at a help file than at written documentation. And written documentation can so easily be misplaced.

One might initially suspect that turning written documentation into a help file is so difficult that it's something you should put off for later. But this isn't true if you keep things simple. If all you want is a vanilla , single-file help display with no table of contents, index, or hyperlinks , creating a help file is a snap. The fact is, the key thing about a help file is what's written in it . All the other stuff is just glitz that's only occasionally useful.

Help systems are often spoken of as having separate topics , and the topics are often kept in separate source-text files that are then compiled into a single, large help file. In order to keep our help development process as simple as possible we are going to only have one topic in our system, one topic in one big source-text file.

By limiting yourself to a single, large topic file, you can focus on making it a useful document. An additional benefit of working with a single topic file is that then you have a file you can print out as is for a hard-copy User's Guide.

Be aware that this is a somewhat non-standard approach. In a commercial program you would eventually want to break your help into separate topics, providing a table of contents and an index. But for now, we'll just keep it simple.

In defense of our approach, let it be said that if you have a limited amount of time to spend on the help, it's better to spend it on the writing than on electronic help features. One does encounter help systems in which the priorities have been skewed the other way. Thus, when the user wonders what a control like, say, Clavier Deviance does, he or she has to navigate through a contents page that doesn't list it in the topics, use the search tool, follow a string of hyperlinks and end up with a single- sentence nugget of non-help such as, 'The Clavier Deviance Tool deviates the clavier.'

In the following subsections, we first have some notes about how best to create a User's Guide that's appropriate for converting into a help file. Then we discuss the troublesome fact that there are presently two possible kinds of help file: the newer HTML help and the old Windows help. Then we have a section about how to make each kind of help file. And finally we have a note about a mixed case that can arise for some developers.

Writing the User's Guide

Write the source documentation for your help as if it's something you might actually expect a human being to read. Don't fill up line after line with obvious and uninformative things like 'The File Save command saves a file.'

It's good to break the guide into sections. You can use a format similar to what we used for the Pop User's Guide; this is the document that appears both as Appendix B of this book, and as the help file that comes with the Pop Framework. Start with a little introduction, describe what the user sees on the screen, including the cursor appearance, explain how the game is played and scored, explain all the non-standard menu items, tell about any other controls, explain any peculiar features of your program's interface, and add some tips for play. It's good to have a 'Getting Started' section at the beginning of the Guide to walk the user through the first few things he or she should try.

Let's stress again that when you're writing, you should always imagine that you're talking to a real person. Write as if you are explaining the game to a friend, not to a boss or to a professor. Be generous with the information. If there's some hint or suggestion or motivation that you always verbally tell someone when you watch them play your game, then this information should be part of your written documentation. Also be sure to put your name , the date, copyright info , and contact information at the end of your file.

Now for some remarks about the technicalities of word-processing.

Which word-processor?

Most people use a recent version of Microsoft Word, which is part of Microsoft Office. Word supports a variety of file formats; in particular you can use it to create the native *.doc (Word format) files, *.rtf (rich text format) files, or *.htm (HTML format) files. A nice feature of Word for this purpose is that you can format your text in any fashion you like, and when you save to *.rtf or *.htm , all of your fonts, spaces, indents, included bitmaps, figures, tables, and so on will be preserved though you may want to double check the tables.

As we'll discuss in the following subsection, there are actually two different ways of making help files; you can make the old and nearly obsolete 'Windows' help files or you can make the newer HTML help files. If you plan to make Windows help files, you need to be able to save your files in the *.rtf format. If you plan to make HTML help files, you need to be able to save in the *.htm format.

If you don't have Microsoft Word, you can make *.rtf files with the WordPad accessory which comes free with Windows. If you don't have Word and wish to have a graphic HTML editor, you will need to find one; it may be that you have some Web design software that can help you create HTML.

Making an effective help file

There are a few key things you need to remember when you create a text file that's intended to be read onscreen.

  • Make your file single- spaced . People are going to be reading it onscreen, where space is at a premium.

  • Remember not to put a paragraph mark (an Enter key press) at the end of each line in a help file. This is because the help file text is going to be shown inside of a resizable window, and if you have 'hard' line breaks, then when the window is made narrow, the hard line breaks will appear at bad places. Only use Enter for the end of a paragraph or to skip a line.

  • You can paste in bitmaps, but don't overdo it. Too many bitmaps will increase the size of your help file resulting in (a) a larger file to distribute with your program and (b) slower loading time of the help when the user calls for it.

  • If using Word, format the lines at the heads of your sections with the styles Heading1, format the subsection lines with Heading2, and so on.

It's easier to avoid putting in unnecessary hard line breaks if you view your document in a mode where the breaks are visible. If you are using Microsoft Word, you can do this by putting a check into the Tools Options... View Paragraph marks box. This will display paragraph marks in your text as you edit it, so that you can visually see the spots where you pressed Enter and put a hard break into a line.

The reason for formatting your section headings is that, first of all, this makes them visually stand out and, second of all, it allows you to automatically insert a Table of Contents, as we'll mention in the 'Creating and reading HTML help files' section further below.

The two kinds of help

Here's a bit of bad news. There are now two incompatible standards for help files: the older Windows help standard and the newer HTML help standard.

It would be easier for the author to advocate and explain only one of these approaches. But, in order to make the Pop Framework code as widely usable as possible, we're going to explain three approaches.

  • Using HTML help with Visual Studio.NET, Version 7.0.

  • Using Windows help with Visual Studio, Version 6.0.

  • The mixed case: using HTML help with Visual Studio, Version 6.0.

The default behavior of the Pop Framework is to detect your compiler type and to use the first option if you have Visual Studio.NET, and use the second option if you have Visual Studio, Version 6.0.

The first approach is really the best, as this is where the future lies. And if you have Visual Studio.NET, it's the only way to go. If you plan to use this approach, you should now download the HTML Help Workshop from Microsoft. We have a link to the download site on our book's website www.rudyrucker.com/computergames, or you can go to www.microsoft.com and enter download htmlhelp in the Search box at the top corner of the Microsoft home page. Once you've done this, you can pretty much ignore the rest of this subsection, though you might just skim over it so you know what's here.

If most or all of the people in your group are using Version 6.0, the second approach is probably the best for you for now. In this case you also can ignore the rest of this subsection, though again, a quick glance through it might be useful.

If you are in a mixed group, it's probably best if the people with Version 6.0 make the effort to switch over to the HTML help. In this mixed case, you'll need to read the rest of this section as well as the special Mixed Case subsection at the end of the chapter.

Let's get an overview of the distinctions between the two kinds of help. We summarize these in Table 21.2.

Up through and including Version 6.0, Visual Studio shipped with a hcw.exe , known as the Help Workshop . The Help Workshop's function was to convert *.rtf (rich text format) files into *.hlp Windows help files.

Now there is a new tool, hhw.exe , known as the HTML Help Workshop . The HTML Help Workshop's function is to convert *.htm (HTML) files into *.chm HTML help files.

Visual Studio, Version 6.0, shipped with the hcw.exe Help Workshop . The hcw.exe Help Workshop is now classed as obsolete and is not available as a download.

Visual Studio.NET, Version 7.0, ships with neither hcw.exe nor hhw.exe . As mentioned above, the hhw.exe HTML Help Workshop is available as a free download from Microsoft.

There are two different kinds of things a developer needs to do with help files.

  • Create a help file using some sort of 'help workshop' tool.

  • Add to the program code a function call which will read the help file.

What's required to do these things?

  • You need the HTML Help Workshop hhw.exe to create HTML help files.

  • In order to have your program be able to read a *.chm HTML help file, your program must include the special header file htmlhelp.h , and it must link to the special library file htmlhelp.lib . These files are pre-installed by Visual Studio.NET in a place where the compiler can easily find them, and the Pop Framework code is set to, respectively, include and link the files with Visual Studio.NET.

  • You need the Help Workshop hcw.exe to create Windows help files.

  • In order to have your program be able to read a *.hlp Windows help file, you don't need to add anything more to your system.

When you install Visual Studio.NET, Version 7.0, it installs the support files htmlhelp.lib and htmlhelp.h into, respectively, the include and lib subdirectories of Visual Studio.NET\Vc7\PlatformSDK . This means that your compiler will easily be able to find these files.

Table 21.2. The new HTML help compared with the old Windows help.
 

New HTML help

Old Windows help

Pop Framework default

Used for Visual Studio.NET, Version 7.0

Used for Visual Studio, Version 6.0

Authoring tool

hhw.exe (HTML Help Workshop)

hcw.exe (Help Workshop)

How to get the tool

Download from Microsoft

Shipped with Version 6.0.

Not available as a download

Source files

*.htm (HTML files)

*.rtf (rich text format files)

Project file extension

*.hhp

*. hpj

Help file extension

*.chm

*.hlp

Window opens help file with a special call to

::HtmlHelp

(..."pop.chm"...)

::WinHelp

(..."pop.hlp"...)

Include file needed for this special call

#include <htmlhelp.h>

None

Library needed to be linked in for this special call

htmlhelp.lib

None

How to get the include file and library file

Ships with Version 7.0. And downloads from Microsoft with the HTML Help Workshop tool

None needed

Where to put the include file and library file

With Version 7.0: no action needed.

With Version 6.0: either with your source code or in, respectively, Program Files\Microsoft Visual Studio\VC98\Include and Program Files\Microsoft Visual Studio\VC98\Lib

Doesn't apply

Visual Studio, Version 6.0, doesn't install the support files htmlhelp.lib and htmlhelp.h , but if you are using the Help Workshop, you won't need them.

When you download the HTML Help Workshop package the package will also install htmlhelp.lib and htmlhelp.h onto your machine, by the way. By default, the download puts these files into, respectively, the include and lib subdirectories of Program Files\HTML Help Workshop . Note that Program Files\HTML Help Workshop will also contain the new HTML Help Workshop tool hhw.exe , along with a bunch of documentation about how to use the tool.

If you already have Visual Studio.NET on your machine, you won't need these new copies of htmlhelp.lib and htmlhelp.h , so you can delete them. If you are using Visual Studio, Version 6.0, you will want to use these files, as we discuss in the Mixed Case subsection at the end of this chapter.

Creating and reading HTML help files

This subsection tells you how to work with HTML help files using either version of Visual Studio. If you plan to use Visual Studio, Version 6.0, with Windows help files, skip this subsection and go to the next one.

  1. We'll keep our Windows help in the Help\HTML Help subdirectory of the project. Edit your source text and, if using Word, use the File Save As selection to save as a web page ( *.html , *.htm ) file called, say, Myproject.htm . The HTML help will preserve any jumps or links that you put into your file. This is useful because Word has an Insert Index and Tables... Table of Contents feature that allows you to give your document a table of contents that's automatically generated by the heading styles used for your section headings ( assuming that you used these styles). When you save a file with this kind of contents table in the *.htm format, the table of contents links will be preserved. (This is a shortcut that lets you postpone or avoid the more complex issue of making a standard HTML Help Table of Contents.)

  2. Find HTML Help Workshop under your main Windows Start Programs HTML Help Workshop and start it up. Or, if you already have a Myproject.hhp HTML Help Workshop project file, click on it to open it.

  3. To make a new HTML Help Workshop project, select File New... Help Project file inside HTML Help Workshop. When the dialog asks the name for your project file, choose the same name as your executable, say Myproject.hhp , and save it to the same subdirectory where you put your source-text file Myproject.htm . You also get the chance to choose the name and location for the completed Myproject.chm file. It's convenient to give it the same name as your executable and to write it up into the directory where you keep your source code and executables. ( Don't call your help file Pop.chm !) Thus if you are making your help down in Help\HTML Help subsubdirectory of the source, you might want your target file to be ..\..\Myproject.chm . When, later on, your executable tries to open the help file, it will expect to find it in the directory where it lives.

  4. Use the HTML Help Workshop Add/Remove Topic Files ... button to add the Myproject.htm user guide file from step (1) as a so-called topic file. You also have the option of using the Add/Modify Window Definitions button to control the appearance of the window in which your help file will appear. In the case of the default Pop.hhp project, we added a PopHelp window style which has the 'Navigation' panel closed (as we didn't make a table of contents or an index to show in the panel), but which has Back, Forward, and Print buttons . Be sure to make the title of your window style match your project. There are other possible window style options you can explore.

  5. Click the Save and Compile button on the HTML Help Workshop window. It may show you one or two warnings, but it should in any case create your ..\..\Myproject.chm . Leave HTML Help Workshop open till after the next step.

  6. Find the newly built Myproject.chm help file in Windows Explorer and click on it to open (Windows can open any help file on its own). Before opening it, by the way, you might want to check its time and date in Explorer to be sure you're not opening an old version of the help file. If what you see in the file isn't satisfactory, open up your Myproject.htm in your word-processor and edit it. Then do a fresh save of the file, leaving the word-processor open if you like, go back into the HTML Help Workshop, and recompile. Repeat steps (5) and (6) till you're happy with the way your help file looks.

  7. Step (7) is already done for you in the Pop Framework, but we mention it for your future reference. Add a menu selection so the user can tell your app to open your help file, and link this menu selection to a handler in your code that will open the help file. To add the menu selection, use the Resource View to open up the project-specific IDR_POPTYPE menu, then add a selection named User's Guide to the Help popup. It gets the ID_HELP_USERSGUIDE . Add a handler for the selection; a good place to keep the handler is in the CMainFrame class, as when you open a help file, it must be linked to one of your onscreen windows. Your main frame window is the logical one to use. Thus the handler for the Help User's Guide menu selection is CMainFrame::OnHelpUsersguide .

  8. Edit the handler code. The generic Pop handler code for HTML help is as follows . You will need to edit the code so that it looks for your own Myproject.chm file rather than for the Pop.chm file.

     void CMainFrame::OnHelpUsersguide ()  {      ::HtmlHelp (GetSafeHwnd (), "Pop.chm", HH_DISPLAY_TOPIC, 0);  } 
  9. See if your project will build. It is possible that you will see an error message like this in your Output window when you reach the 'Linking' stage of the build.

     Pop error LNK2019: unresolved external symbol _HtmlHelpA@16      referenced in function "protected: void _thiscall      CMainFrame::OnHelpUsersguide (void)"      (?OnHelpUsersguide@CMainFrame@@IAEXXZ) 

    This message means that your project can't find the code for the ::HtmlHelp method, and this means, in turn , that your project isn't linking in the necessary htmlhelp.lib library.

    Open the Project Settings dialog and set the configurations being changed to All Configurations as described in Appendix C. Then edit the Configuration Properties Linker Input Additional Dependencies edit box to include htmlhelp.lib . Now your program should build.

    If you still have problems you may need to adjust the Visual Studio directory paths so that it can find htmlhelp.lib .

  10. Build and run the program and select Help User's Guide . There it is!

Creating and reading Windows help files

This subsection is only for those planning to use Windows Help with Visual Studio, Version 6.0. Do not bother with this subection if you use Visual Studio.NET.

  1. We'll keep our Windows help in the Help\Windows Help subdirectory of the project. Edit your source text and, if using Word, use the File Save As selection to save as a rich text format ( *.rtf ) file called, say, Myproject.rtf .

  2. Find Help Workshop under your main Windows Start Programs Microsoft Visual Studio Microsoft Visual Studio Tools and start it up. Or, if you already have a Myproject.hpj Help Workshop project file, click on it to open it.

  3. To make a new Help Workshop project, select File New... Help Project file inside Help Workshop. When the dialog asks the name for your project file, choose the same name as your executable, say Myproject.hpj , and save it to the same subdirectory where you put your source-text file Myproject.rtf . You also get the chance to choose the name and location for the completed Myproject.hlp file. It's convenient to give it the same name as your executable and to write it up into the directory where you keep your source code and executables. ( Don't call your help file Pop.hlp !) Thus if you are making your help down in Help\Windows Help subsubdirectory of the source, you might want your target file to be ..\..\Myproject.hlp . When, later on, your executable tries to open the help file, it will expect to find it in the directory where it lives.

  4. Use the Help Workshop Files... Add to add the Myproject.rtf user guide file from step (1) as a so-called topic file.

  5. Click the Save and Compile button on the Help Workshop window. It may shows you one or two warnings, but it should in any case create your ..\..\Myproject.hlp . Leave Help Workshop open till after the next step.

  6. Find the newly built Myproject.hlp help file in Windows Explorer and click on it to open (Windows can open any help file on its own). Before opening it, by the way, you might want to check its time and date in Explorer to be sure you're not opening an old version of the help file. If what you see in the file isn't satisfactory, open up your Myproject.rtf in your word-processor and edit it. Then do a fresh save of the file, leaving the word-processor open if you like, go back into the Help Workshop, and recompile. Repeat steps (5) and (6) till you're happy with the way your help file looks.

  7. Step (7) is already done for you in the Pop Framework, but we mention it for your future reference. Add a menu selection so the user can tell your app to open your help file, and link this menu selection to a handler in your code that will open the help file. To add the menu selection, use the Resource View to open up the project-specific IDR_POPTYPE menu, then add a selection named User's Guide to the Help popup. It gets the ID_HELP_USERSGUIDE . Add a handler for the selection; a good place to keep the handler is in the CMainFrame class as, when you open a help file, it must be linked to one of your onscreen windows. Your main frame window is the logical one to use. Thus the handler for the Help User's Guide menu selection is CMainFrame::OnHelpUsersguide .

  8. Edit the handler code. The generic Pop handler code for Windows help is as follows. You will need to edit the code so that it looks for your own Myproject.hlp file rather than for the Pop.hlp file.

     void CMainFrame::OnHelpUsersguide ()  {      ::WinHelp (GetSafeHwnd (), "Pop.hlp", HELP_CONTENTS, 0);  } 
  9. Build and run the program and select Help User's Guide . There it is!

The mixed case: reading HTML help files with a Version 6.0 build

Now let's talk about using HTML Help Workshop with Visual Studio, Version 6.0. First of all you need to read the subsection about HTML help. And in addition, you need to read this subsection about how to adjust your build so as to work with these files.

In order to build programs that can read HTML help files, each Version 6.0 team member needs to add a new library file htmlhelp.lib and header file htmlhelp.h to their build environment.

As we mentioned before, when you download the HTML Help Workshop package the package will also install htmlhelp.lib and htmlhelp.h onto your machine, by default putting them into, respectively, the include and lib subdirectories of Program Files\HTML Help Workshop . And, again, the Program Files\HTML Help Workshop will also contain the new HTML Help Workshop tool hhw.exe , along with a bunch of documentation about how to use the tool.

If you are using Visual Studio, Version 6.0, you will need to either (a) move these files to a spot where your Visual Studio can find them when it compiles and links your project, or (b) remember to prefix references to these files in your Visual Studio code or project with the path information about where the files are located, or (c) use the Version 6.0 dialog Tools Options Directories to add the appropriate paths to the lists of include and library directory paths searched.

If you are working with people who may easily get confused , the safest initial option is to (a) just put the two htmlhelp.* files in with your source code. Otherwise have them download the files themselves and either (b) put them in, respectively, their local directories Program Files\Microsoft Visual Studio\VC98\Include and Program Files\Microsoft Visual Studio\VC98\Lib , so that their Version 6.0 compiler can find them, or (c) change the include path list to have Program Files\HTML Help Workshop\Include and the compiler's library path list to have Program Files\HTML Help Workshop\Library .

In addition you will need to do two more things.

  • Override the Pop Framework's default choice of Windows Help for Version 6.0.

  • Add htmlhelp.lib to your Visual Studio, Version 6.0, *.dsw project file.

You do the first thing by commenting in a //#define POPHTMLHELP line in the mainfrm.cpp file. We print the line here and its comment, along with the preliminary code that detects which version of Visual Studio is being used and automatically defines or doesn't define POPHTMLHELP accordingly .

 #if _MSC_VER >= 1300 /* Version abcd means your Visual C++ is      version ab.cd. It turns out "Visual Studio.NET, Version 7.0"      gives an _MSC_VER of 1300, or Build 13.00, and "Version 6.0"      has _MSC_VER of 1200, or Build 12.00 for a _MSC_VER of 1200.      We could also have distinguised the two by detecting the MFC      version, with _MFC_VER. The _MFC_VER is, perversely, returned      as a hexadecimal number. Version 6.0 uses MFC version 0x0060,      while Version 7.0 uses 0x0070. */  #define POPHTMLHELP /* Normally don't use this with Version 6.0,      though you can if you want, see the next comment down. */  #endif //End the _MSC_VER switch  //#define POPHTMLHELP //Comment in to force on for Version 6.0      /* At this point POPHTMLHELP is turned on for Version 7.0 and      off for Version 6.0. If you want to force it on anyway in      Version 6.0, then comment in this #define POPHTMLHELP. Note that      Version 7.0 puts two necessary files htmlhelp.h and htmlhelp.lib      onto your machine in standard directories where the compiler can      find them. If you are using Version 6.0, you have to get these      files yourself, and put them in a place where the current      Visual Studio Directories settings can find them. Note that      for Version 6.0, you also need to add htmlhelp.lib to the list      of Link files. Our Version 7.0 solution file already has the      library in the link list, but the Version 6.0 workspace file      does not.*/  #ifdef POPHTMLHELP  #include <htmlhelp.h>  #endif // POPHTMLHELP 

To add htmlhelp.lib to your Version 6.0 project do the following. Open the Project Settings dialog. Activate Settings For All Configurations in the upper left corner of the Settings dialog. Now find the Project Settings Link General Object/Library Modules edit box, and type in htmlhelp.lib .

As we discussed above, you should have htmlhelp.lib in a place where the compiler's current directory settings can find it. Alternately you can put a path name in front of the htmlhelp.lib name, but this makes your project fairly non-portable.

By the way the POPHTMLHELP switch gets used as follows:

 void CMainFrame::OnHelpUsersguide ()  {  #ifndef POPHTMLHELP      //If not POPHTMLHELP do it the old way with a *.hlp      ::WinHelp (GetSafeHwnd (), "Pop.hlp", HELP_CONTENTS, 0);  #else // POPHTMLHELP means use a *.chm.      ::HtmlHelp (GetSafeHwnd (), "Pop.chm", HH_DISPLAY_TOPIC, 0);  #endif //End POPHTMLHELP switch  } 


Software Engineering and Computer Games
Software Engineering and Computer Games
ISBN: B00406LVDU
EAN: N/A
Year: 2002
Pages: 272

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net