How to Use the Help File

Help a man against his will and you do the same as murder him.
—Horace, Ars Poetica

When we decided to offer an electronic version of the VFP 6 edition of this book, HTML Help seemed to be the obvious candidate. Microsoft had decreed it the “help of the future” (at least until the next “help of the future”), and VFP 6’s Help used the technology.

For the most part, we haven’t regretted our choice, and for this edition, continue to offer an HTML Help version of the Hacker’s Guide. In fact, with this edition, we’re depending even more on the HTML Help version by including the Reference section only in the electronic book, and not in the printed book.

However, one of our biggest gripes about HTML Help is that it doesn’t come with “Help on Help.” Fortunately, we found a separate help file for HTML Help on Microsoft’s Web site and we’ve included it in the downloads for this book. Of course, it’s in HTML Help format, too, so if you don’t know how to use HTML Help, it may not be much help. All things considered, this section is devoted to teaching you how to use the Hacker’s Guide help file effectively. It covers both things specific to this help file and a number of the tricks we’ve learned to make working with HTML Help easier. Do check Microsoft’s help file, too, for additional tidbits.

All the things we said in “How to Use this Book” apply to the help file as well, though we suspect that most of you (except those who bought only the electronic version of this book) won’t choose the help file as the right way to read the front and back of the book. It’s the Reference section that really is effective this way (and, of course, that’s one of the reasons for the change in this version).

Download the help file from hackfox.chm.

Getting There

The first challenge you may run into with HTML Help is getting it to run. HTML Help depends on many of the same DLLs as Microsoft’s Internet Explorer (IE). In fact, IE is really just a simple shell around the DLLs that render HTML, interpret scripts, provide navigation, and the rest of the features we take for granted on the Web. For this reason, the easiest way to be sure your computer has the correct files to run HTML Help is to install Internet Explorer. Some folks go ballistic upon hearing this, but please understand—IE does not have to have an icon on the desktop, it does not have to be the default browser, and it does not take up significantly more space than is required to install all the gew-gaws needed for HTML Help. Even if you are convinced that IE is just another step in Microsoft’s plan for world domination, installing it is the easiest way to read HTML Help files.

We encourage you to get the latest version of IE to be sure you have the most recent fixes for bugs and security problems. In addition, you might want to consider installing HTML Help Workshop and HTML Help Runtime Update (HHUpd.EXE) also available on Microsoft’s Web site. (We don’t give links here, because we’re sure they’ll change within a month or two. But the main search page at Microsoft should be able to turn them up.) Both of these files install updated OCX and DLL files that may make reading the help file a more positive experience.

What’s In There?

A structure becomes architectural, and not sculptural, when its elements no longer have their justification in nature.
—Guillaume Apollinaire, The Cubist Painters

Like so many applications these days, HTML Help has two panes. The left pane controls what you see in the right pane. The left pane has three pages (tabs): Contents, Index and Search. The right pane contains one chunk of the book at a time—a chapter from the front or back of the book or a listing from the Reference section.

The pages in the left pane have two things in common. First, each provides a way of getting to the entry you want. Second, each includes a way of re-synching the list if you jump around using links.

In the Reference section, the items in the See Also listing are links, as are some other items, like the lists of properties, events and methods in the entries for the base classes. Just click on them to go to the named item.

If you’d like to make more room for the content, you can adjust the ratio between the two panes by dragging the bar between them left or right. You can also get rid of the left pane by clicking the Hide button. Non-intuitively and inexplicably (and totally the opposite of what Internet Explorer does), clicking Hide shrinks HTML Help to the size of the right pane. You can then stretch it out (or maximize it) to make the right pane (guess it’s not really the “right pane” at that moment) bigger. Use the Show button to make the left pane reappear.

As in a browser, the Back and Forward buttons take you back or forward one action. (Interestingly, it appears that scrolling sometimes counts as an action, so you may find yourself at the bottom of the page rather than the top. We kind of think this is a good thing.) Pressing Backspace is the same as clicking the Back button. Use Shift+Backspace (really!) as a keyboard replacement for the Forward button.

HTML Help demonstrates the confusion at Microsoft these days when it comes to interface design. The top of the HTML Help form contains no true menu (text prompts dropping down lists of options). Neither is what’s there truly a toolbar, as it cannot be undocked. Worst of all, just to prove they know how to mangle a metaphor but good, the Options button on the thing-that’s-not-a-toolbar does call a drop-down menu.

I’d Be Content To Do That

Strong and content I travel the open road.
—Walt Whitman, Song of the Open Road

The Contents page shows you the table of contents for the book. It looks an awful lot like the one in the printed version, except that it’s set up in a drilldown format. If you want to go through the book sequentially, this is the page for you.

In the listing for the Reference section, every command, function, class, property, event, method and system variable is included (along with some of the more unusual operators). We didn’t write a separate Reference entry for each item, though—they’re logically grouped. Choosing an item from the Contents list takes you right to the appropriate Reference section.

We’ve also added to the Contents list some keywords that aren’t commands, just to make them easier to find. So you can go to ENDCASE and click, and it’ll bring up the entry for DO CASE, for example.

When you click a link in the right pane, the Contents list keeps up with you. It always highlights the item you’re now looking at.

Index, Outdex

And for the citation of so many authors, ‘tis the easiest thing in nature. Find out one of these books with an alphabetical index, and without any farther ceremony, remove it verbatim into your own . . .
—Miguel de Cervantes, Prologue to Don Quixote

The Index page is the same as the Reference portion of the Contents list, except for two things. First, it provides a text box to let you type in what you’re looking for. Second, when you click on a link in the right pane, the Index doesn’t follow along. So you can come back to where you were in the Index after wandering down a path of links.

The Search text box offers incremental search—that is, you start typing and it jumps to the first item that matches what you've typed so far. Unfortunately, there seem to be some bugs in the search algorithm—it has trouble with similar items in different cases. For example, if you type "deleted", the highlight lands on the Deleted property, shown in the Index as "Deleted". However, if you add a left parenthesis (so your search string is now "Deleted("), the highlight does not move to "DELETED()", as it should. More interestingly, if you type "DELETED" in the first place, you land on "DELETED()," missing "Deleted" entirely.

Choosing Clicking the Display button on the Index page takes you back (in the right pane) to the currently highlighted item in the Index. Clicking Locate on the toolbar/menu brings up the Contents list with the item that’s currently displayed in the right pane highlighted in the Contents list.

The Search is On

The philosophic spirit of inquiry may be traced to brute curiosity, and that to the habit of examining all things in search of food.
—W. Winwood Reade, The Martyrdom of Man

The Search page lets you look for things in ways we didn’t consider. Type in any string, press Enter (or choose the List Topics button) and a list of items containing your string appears. Then choose the one you want to see.

As with the Index page, the Search page doesn’t keep up with you as you follow links. Instead, it patiently sits there displaying the matches from the last search. As on the Index page, choosing the Display button returns you to the highlighted item in the list. The Locate button also behaves as it does on the Index page, taking you to the Contents page with the current item highlighted.

A couple of pointers when using the Search tab. The search engine is not the brightest star in the heavens, and many common VFP phrases stump its somewhat limited intellect. First, it ignores non-alphabetic characters, so searching for #DEFINE finds DEFINE MENU and DEFINE WINDOW, as well as #DEFINE. Second, we suspect the help authors had some special intentions for parentheses, as we have never been able to include them without getting “Help cannot search for that phrase.” This is maddening when searching for something like USER(), because every use of “user” comes up if you do not include the parentheses. (As an aside, because “similar word” searching is turned on, a search for “user” also turns up matches to “using,” “used” and even “us.” (We understand the first two; we can’t imagine why “us” is considered a “similar word” to “user.”)

Enclose phrases in quotation marks to locate topics that contain that exact phrase. Note that this technique does not work with single words to prevent similar word matching.

You can use the Boolean operators AND, OR and NOT as well as the NEAR operator to limit your search. Use “ugly” AND “interface” to locate that one section, “ugly” NOT “interface” for the others, “Julian” OR “Gregorian” for calendar discussions.

The Key to the Future

Woe unto you, lawyers! for ye have taken away the key of knowledge
—The Bible

Most of us are touch typists and, as a result, like to keep our hands on the keyboard (not to mention avoiding the physical wear and tear of moving the arm back and forth between keyboard and mouse). It turns out you can do pretty much everything in HTML Help with the keyboard, but it ain’t easy to figure it out. Some of the keyboard shortcuts are pretty obscure, and, to make matters worse, the relevant topic in the Help for HTML Help is called “Use accessibility shortcut keys.” Sounds like something that’s only for those with physical disabilities, doesn’t it? How about calling it “Keyboard shortcuts”?

The one that took us the longest to find (in fact, we didn’t find it until we got the help file) is moving focus from the left to the right pane. We tried everything we could think of (tabs, Shift+tabs, arrows, Shift+arrows, you name it), even asking other people, and came up empty. It turns out the magic key is F6. Now that’s intuitive, isn’t it?

Once you get to the right pane, you can use the keyboard to navigate within the entry and to follow a link. Once you follow a link, for some reason it takes two tabs to land on the first link in the new section. Same thing when you back up. We’re not sure where focus is when you get there or after that first tab. (This seems to be an HTML Help “feature,” since we see it in every HTML Help file we try.)

To go back from right to left, you can use F6 again. In addition, all three pages of the left pane have hot keys, as does the Options drop-down menu.

Not only are many of the keystrokes unintuitive, some of them don’t work as documented and others don’t seem to be documented at all. For instance, Alt+LeftArrow and Alt+RightArrow seem to navigate back and forth in the history list, but this behavior is undocumented. To open and close folders, use the numeric keypad’s + and – when the appropriate item is highlighted. Also undocumented is that Shift+LeftArrow and Shift+RightArrow move you up and down a level in the Contents hierarchy. It’s worth spending some time trying various keystrokes to see what they do. You can’t damage anything by doing so, so why not check it out?

Icon Take Much More

HTML Help offers the capability to set the icon of each topic to have its own individual bitmap. We decided not to go hog-wild, and just kept to a few different ones. The book icon is for the front of the book. Each major section appears as a folder. The individual sections appear as a text icon. Every language item or chapter that’s new or changed in VFP 6 Service Pack 3 or VFP 7 is marked in the Contents listing with a red star.

Just the Way You Want It

Custom, then, is the great guide of human life.
—David Hume, An Enquiry Concerning Human Understanding

We had many difficult design decisions to make in creating the help file. If for some reason you cannot abide our choices in fonts, font sizes or colors, all is not lost. First, if your problem is just the font size, use the Font button to cycle among five different choices. We hope one of them will suit you. The Font button is a hack—obviously, the code is somewhere within the HTML Help engine, but there is no way to add it to your help file using the HTML Help Workshop interface. The good news is that we got it to work; the bad news is that we haven’t figured out if it has a keyboard shortcut.

If the fonts and colors we’ve chosen really drive you nuts, you can change it, but it’s not easy. We used a cascading style sheet (CSS), which is compiled into the Help file. You can decompile the file, edit the CSS, then recompile it. Alternatively, if you want to change all Internet content (not just HTML Help, but all pages viewed in a browser), you can use the Internet Options item under the Options button and click the Accessibility and Fonts buttons to have things your way.

You can also filter what’s available on the Contents page. Right-click anywhere within the Contents page and choose Customize from the context menu. When you choose it, a Customize dialog appears with a wizard that lets you limit the items shown to those introduced in particular versions of FoxPro. So, if you want to know what’s new in VFP 7, choose the Custom option button on the first page, and then uncheck everything except Visual FoxPro 7.0 on the second. When you finish the wizard, Contents shows you only the items that were introduced in VFP 7. (We’ve chosen to leave all of the front and back of the book chapters available, no matter which subset you’re in.) To restore the list to include all items, either choose the All option button or check every version.

LoOKs LIke a RaNSom NoTE

At first glance, the alphabetical listings of language elements on the Contents and Index pages look like someone forgot to proofread it. Some items are all caps, some are mixed case, some have parentheses, others don’t, and sometimes the same item appears more than once.

Relax—there is method to our madness. Due to its long evolution and liberal borrowing from other languages (see “It’s Always Been That Way” for details), VFP has not only an assortment of traditions in terms of capitalization, but also quite a few keywords that have multiple meanings. We’ve done our best to sort things out so you can find what you need.

Here are our rules (which we tried to follow universally). Xbase and SQL commands, functions and keywords are listed in ALL CAPS. Properties, events, methods and other OOP keywords use Mixed Case. Functions are shown with trailing parentheses. Events and methods are not.

So, for example, NewObject is a method, while NewObject() is a function. Similarly, Alias refers to the property, and ALIAS() is the function. DEBUG is a command and Debug is a property.

For the most part, this system provides us with a unique string for each language item. But once in a while, it breaks down. For example, there’s a Run event and a Run method. In those cases, we’ve included the additional phrasing needed to clarify things.

What all this means, in practice, is that after you’ve typed enough to get to the right word, sometimes you’ll have to press an extra down arrow or two to get to the item you want.

Keep it Handy

More helpful than all wisdom is one draught of
simple human pity that will not forsake us.
—George Eliot, The Mill on the Floss, 1860

When we were working on the VFP 6 version of the book, it didn’t take us long to figure out that keeping a shortcut to HackFox.CHM on the desktop means that it’s only a double-click away.

Other people prefer to access the file from within VFP. You can replace the VFP help file with this one by issuing SET HELP TO HackFox.CHM, including the appropriate path, of course. (For some reason, doing it this way turns off the F1 shortcut, but typing Help or choosing Help from the menu works.)

If you’d like to keep Microsoft’s help file available, but also put the Hacker’s Guide on the menu, try code like this:

DEFINE BAR 10 OF _msystem KEY Alt+F1 PROMPT "Hacker's Guide"
ON SELECTION BAR 10 OF _msystem RUN /n hh.exe hackfox.chm

Of course, you’ll need to add the appropriate path to the file.

We also find that we live on the Index page most of the time, so that we can quickly find the section we want. The combination of the shortcut and the index is way faster than pulling the book off the shelf and finding the right page. We hope you find it as useful as we have.