Copyright: ® Kenneth Liew 1993


First Page Contents

HYPERTRACK

The Windows Help File Tracker

plus

HYPERDOC

WinWord to WinHelp Document Conversion Macros

by

Kenneth LIEW

Release 3.2	November 1993

Overview of HyperTrack

Overview of HyperDoc

Installation and Getting Started

HyperTrack: revolutionising the WinHelp application

HyperDoc: the easy way to produce help files from existing documents

Detailed Description of HyperDoc Macros

Registration and Support


Overview of HyperTrack

1.	The WinHelp environment already has the capacity to display information in hypertext.  It comes standard with browse, topic jumps, history function and search on keywords.

2.	The HyperDoc.DLL is used because it is the only way for a help file to interface with any other application.  It contains routines that are only linked to a program at runtime.

3.	The HyperTrack.EXE application enhances the hypertext  capabilities of WinHelp by providing a dynamic Table of Contents for all the topics in the help file.  It provides a navigation feature, enabling a user to jump to any topic within the help file by double clicking on its heading title.  At the same time, it provides a visual tracking of the current help topic by highlighting its heading title on the application window.  It is dynamic in its display because a user can choose to only view up to a certain number of levels in the document hierarchy and hide the lower levels.  Another key feature of HyperTrack is the ability to list out all the topics that contain the occurrence of any word being searched for, so the user is not limited to just the list of keywords that is a part of the WinHelp search function.

Click here for more information on HyperTrack


Overview of HyperDoc

The macros that are contained in the file HYPERDOC.DOT facilitate the easy conversion of a linear document to a hypertext document, using the Windows Help application.  It takes advantage of the format in a document based on styles to come up with a hierarchical structure, eg. Chapter heading -> Section heading -> Paragraph -> Sub Paragraph, etc.  Based on these headings for every topic in the document, a macro will insert the necessary codes and menu items to allow the Help Compiler convert them to a Windows Help file (*.HLP).  Cross references to other topics can be inserted by calling on the appropriate macro, as well as creating a master listing of all topics.  The end user can then view the converted document by successively clicking on the selection choices (or hot spots) for each menu level until he reaches the topic desired.

Click here for more information on HyperDoc


Installation and Getting Started

Make sure you exit and get back into Word for Windows after the following steps.

1.	Copy the following files to your Word for Windows program directory (usually c:\winword) :-

•	V1TBAR.BMP, V2TBAR.BMP, V3TBAR.BMP, V4TBAR.BMP (for the customised toolbar to come out well)

2.	Copy the following files to the directory where WINWORD.INI exists (usually c:\winword) :-

•	HYPERDOC.DOT	(if there's an entry for DOT-path in the WIN.INI file then make sure that this template file is put there instead)

•	HYPERDOC.ICO	(for the help file's icon when it gets minimised) -- feel free to modify the icon if you want to.

3.	Copy the following files to a directory that is somewhere in the system's path, eg. \WINDOWS or \WINWORD :-

•	HYPERDOC.DLL	(contains subroutines needed by the HyperDoc macros as well as by HyperTrack)

•	HYPERTRK.EXE	(the HyperTrack application -- tracker for WinHelp)

•	HYPERDOC.HLP	(help file for the above modules)

•	HYPERDOC.HPJ	(help project file for HYPERDOC.HLP)

•	HYPERDOC.KEY	(keywords file for HYPERDOC.HLP)

•	HC.PIF	(PIF for the help compiler to work well)

•	HC31.BAT	(batch file for the help compiler)

•	HC31.EXE	(the help compiler for Windows 3.1)

•	HC31.ERR	(error message file for HC31.EXE)

The last two files HC31.EXE and HC31.ERR are not part of the zipped package. You can get them from Windows 3.1 SDK or Borland C++ Application Frameworks or from the WHAT.ZIP package available from most windows ftp sites.  If you cannot get a hold of them, just email me and I'll be glad to mail you a copy.

If you want to make use the WinGIF application to display graphics interactively within you help file, you should also make sure that WINGIF.EXE is somewhere in the system path.

4.	The rest of the files (the .DOC files and the .TXT files) you can copy them to any working directory you want.

5.	Edit the WIN.INI file and ensure the following line is found under the Microsoft Word 2.0 section:

LoadToolbarBitmaps=1

If its not there, you'll find a few character based toolbar buttons instead when you first open this HYPERDOC.DOC file, but the macro Process Topic Outlines will ensure the line is inserted after it is run.

When opening a help file, ensure that the project file (*.HPJ) and keywords file (*.KEY) is found in the same location in order for HyperTrack and the keyword search facility to work.

Disclaimer


Disclaimer

The author (Kenneth Liew) will not be held responsible for any undesirable effects that may occur  from running any of the macros contained in the HYPERDOC document template.  Though it should never cause any terrible side-effects, you are still using it at your own risk.  The same goes for the HYPERTRACK application.


HYPERTRACK: revolutionising the WinHelp application

Overview

How to use HyperTrack

Summary of HyperTrack features

List of Short-Cut Keys in HyperTrack

Short-Cut Keys added for WinHelp

Performing Word Searches

Anticipated Improvements for Future Releases

Things to watch out for when using HyperTrack:

•	Notice which window is having the keyboard input focus (usually that window's caption colour will be highlighted).  Press the SpaceBar to toggle between focusing on the help file or Tracker.

•	To quickly find out which file it is tracking, observe the Tracker's caption -- it shows the file name.  To find out the complete path, press I or select the File-Information menu.

•	Get to know the Short-Cut Keys!

Click the Contents toolbar button to jump to the very first topic in this help document.


Summary of HYPERTRACK features

•	Master listing of all topics in a help file, suitably indented and/or colour coded to reflect hierarchy in the document.

•	Can choose to display only topics up to a certain level -- helpful if there are too many topics to choose from.

•	Highlights exactly which topic the help file is currently displaying (no more being lost in hyper-space, wondering where in the document you are).

•	Ability to perform search on every word in the document, with some boolean searching capabilities. (new for Release 2)

•	Ability to print multiple help file topics at one go by selecting Print... from the File menu. (new for Release 3)

•	Supports two help windows: allows you to view any topic on the main window by double clicking the left mouse button, while right clicking displays the topic on the secondary help window -- no longer having to keep switching between two topics especially if both are closely related!

•	Fully customable display -- how much to indent each level, line separation, colours for each topic level.

•	Automatic resizing according to size of current help windows -- the entire screen is well used up.

•	Ability to search on strings in a topic, rather than just keywords -- eg. by just specifying doc the search window will display all topic titles that contain the string doc, like ..document.., ..documentation..., ..doctor..., etc.

•	True Up One Level handling of topics -- you can always jump to the next upper level in the document hierarchy.

•	Lots of very useful short-cut keys -- can navigate through an entire help file without bothering with the mouse.

See also

List of Short-cut keys

Overview of HyperTrack

How to use HyperTrack


How to use HYPERTRACK

Move the mouse to the area you want help on and click on it:

If you screen resolution is less than 800x600, some of the menu items will appear abbreviated: S=Search, ?=Help

See also

How to use the Search window

List of Short-cut keys

Overview of HyperTrack

Summary of HyperTrack features


How to use the Search window

Move the mouse to the area you want help on and click on it:

See also

List of Short-cut keys

Overview of HyperTrack

Summary of HyperTrack features


List of Short-Cut Keys in HYPERTRACK

Notice that it is optional to press the Ctrl key for those functions that use the alphabet set.

Function  (and where in the menu)	Key
Alternates between setting the focus on the HyperTrack main window and the Search Results window.	Tab
Alternates between setting the focus on the main help window and HyperTrack main window.	SpaceBar
Collapse the number of levels to display.  (Display menu as well as <= symbol)	Ctrl-C  C
Display the HYPERTRACK help file topic.	Ctrl-H H  or  ?  or F1
Displays the selected topic on the main help window.	Enter
Displays the selected topic on the secondary help window.	Ctrl-Enter
Expand by one the number of levels to display  (Display menu, as well as => character)	Ctrl-X  X
Jump to last topic.	End
Minimise the HyperTrack application.	ESC key
Move Down to Next Level.	Ctrl-Right
Move the selected topic Up 1 Level.  (Display menu, as well as U character)	Ctrl-U  U
Move Up to Previous Level.	Ctrl-Left
Move down one topic.	Down Arrow
Move up one topic.	Up Arrow
Move up or down the topics according to screen size.	Page Up   Page Down
Move up or down topics of the same level.	Ctrl-Up  Ctrl-Down
Print help topics.  (File menu)	Ctrl-P  P
Quit the HyperTrack application.  If help wasn't called before by another application, it'll also close the help window.  (File menu)	Ctrl-Q  Q
Reposition the HyperTrack window so that it fits nicely to the left of the main help window and below the secondary window.  (Display menu)	Ctrl-R  R
Scroll screen to left.	Left Arrow
Scroll screen to right.	Right Arrow
Scroll up or down the topic window.	Ctrl-PageUp   Ctrl-PageDown
Search for a string among all topic titles.  (Display menu)	Ctrl-T  T
Search for a word anywhere in the document.  (Display menu)	Ctrl-S  S
Sets the display options.  (Display menu)	Ctrl-O  O
Sets the input focus on the main help window.	M
Sets the input focus on the secondary help window.	N
Show all the levels in document.  (Display menu)	Ctrl-A   A
Show the help file's information. (File menu)	Ctrl-I  I
Show up to 1,2 or 3 heading levels in document.	1, 2, 3
Toggle between showing the context strings all the topics.  (Display menu)	Ctrl-E  E
Toggle to Keeps Focus, ie. the HyperTrack application doesn't lose the input focus even after you press Enter to display a topic on the Help window -- useful for quickly browsing through the help file.  (Display menu)	Ctrl-F  F
Toggles between setting the application window as the Top-most Window (Display menu)	Ctrl-W  W


Short-Cut Keys added for WinHelp

Besides the normal key assignments in the WinHelp application (those that are underlined in the toolbar buttons -- remember that you don't need to press Alt for them, eg. U shows Up 1 Level, O displays the current topic on the Secondary Window, R focuses on HyperTrack, etc...) there are also a few others added on:

These only apply if your help file was created with the Load HyperTrack option.

Function	Key
Alternate between setting the focus on the main help window and HyperTrack main window.	SpaceBar
Close the current window (whether the secondary or the main help window).	Q
Display the current topic on the secondary window.	O
Display help on using HYPERTRACK.	H
Display the previous or next topic on the secondary window.	Ctrl-Left  Ctrl-Right
Display the Up 1 Level topic on the secondary window.	Ctrl-U
Select multiple topics for printing.	P
Search for a word anywhere in the document.	W Ctrl-S
Set the input focus on the main help window.	M
Set the input focus on the secondary help window.	N
You can modify these key assignments or add in your own by adapting the help project file (.HPJ) before running the Help Compiler.  Have a look in the macro Initialise Files, which first creates the HPJ files....


Performing Word Searches

To search for all the topics that contain a certain word, select Search Words from the HYPERTRACK display menu or press S.  Here are the options for the Word Search Dialog box:

Word to Search for:	This is the word that you are searching for.  As you type, you'll see the list-box below it highlight the nearest matching word.

Add to Criteria:	To add the word being searched for to the list-box that contains the Search Criteria.

Remove from Criteria:	To remove the current word selected in the Search Criteria list-box .

OR / AND Conditions:	These option buttons allow you to select whether the words listed in the Search Criteria will be combined using either boolean OR (which will list all topics that contain at least one of those words) or boolean AND (which will list only topics that contain all the words listed).

Show Results:	To show the Search Result window that will display all the topics that fulfil the Search Criteria.  Notice that the Search Dialog stays as the top most window all the time even if you display help topics from the Search Result window.

Clear Previous Search Results:	This option button causes the next query made to clear the topics already displayed on the Search Result window.

Reset:	This button will clear both the Search Criteria list-box as well as the Search Result window.

Search on Title Headings:	To perform searches on strings within the title headings instead.

Close:	To close this Search Dialog box.

Keep this Dialog Box Visible:	This button when selected causes the Dialog Box to remain as the top-most window even when it is not having the input focus.


Anticipated Improvements for Future Releases

•	History function that will be preserved even after quitting WinHelp, hence even allowing some sort of analysis on document usage, ie. what topics were encountered and how often, in what sequence -- enabling document author to fine-tune the structure of the hypertext document.

•	Any other suggestions that you may give -- the more registrations there are coming in, the more motivated I'll be to implement them.


HYPERDOC: the easy way to produce help files from existing documents

Overview

Summary of HyperDoc Features

Document Preparation

Tips for Creating Help Files with HyperDoc

Steps for creating a basic help file with HyperDoc

Acknowledgments

See also

Detailed Description of HyperDoc Macros

Toolbar buttons for HyperDoc

Click the Contents toolbar button to jump to the very first topic in this help document.


Summary of HYPERDOC Features

•	Automatically assigns context strings, topic titles, keywords and browse sequences for the help file.

•	Able to use heading styles other than the standard heading 1, heading 2, etc... for describing the heirachical structure of the document; hence you can use styles like Chapter, Section, etc.

•	Automatically splits up the words in a title heading to individual keywords, optionally leaving out certain common occurring words like where, about, etc..

•	Generation of a Master Listing for all topics in the file, with context string, title, keywords and browse sequence numbering.

•	Extremely easy to jump to any topic in the file with the HyperTrack application, and then either edit any items or insert a phrase as keywords for that topic.

•	A Help Project File (HPJ) will be automatically created, with various customable options including title, compression and window size.

•	Cross References to other topics can be generated painlessly and quickly, with the help of HyperTrack, with automatic searching for matching titles, matching phrases throughout the document as well as comments for the cross references.

•	Graphics can be inserted with various options, saving file size with external references and auto insertion of full bitmap path names in project file.

•	Map section generated automatically, allowing the help file to be called from any Windows application.

•	Bullets and other symbol characters are supported (converted to corresponding characters).

•	Ability to run macro minimised (so that you can do something else in the meantime) or with screen echo off (to increase execution speed).

•	A whole bundle of extremely useful macros provided to increase productivity and joy in using Word for Windows, coupled with customised toolbar buttons and short-cut keys.  See Other Useful Macros.

•	Convenient way to pre-process FAQ files by automatically assigning styles to them.  See Pre-Process FAQ files.

See also Overview of HyperDoc and Detailed Description.


Document Preparation

First and foremost, these macros are designed for use under Microsoft Word for Windows™(or Winword for short) Version 2.x only.  Therefore it should be obvious that the input document (ie. the existing linear document) must be in Winword 2 format, which fortunately Winword has the ability to convert from with its powerful file conversion functions.  Once that is done the document must be attached to the template HYPERDOC.DOT.

In order to use the macros, the document must first employ the use of Styles as the heading for every topic (ie. the sections in the document).  For example in this document, "HYPERDOC: THE EASY WAY TO PRODUCE HELP FILES..." is set to the style "Heading 1", and so is "DETAILED DESCRIPTION...", while "Overview of Hyperdoc", "Document Preparation" and "Process Topic Outlines" are set to "Heading 2".  Titles with Heading 1 are known as having a document hierarchy level of 1.

Remember that if your document contains styles that are not part of the standard heading styles and you want to consider them as part of the document hierarchy, de-select the Use Default Heading Styles option in the Setup Options dialog box.

Following are common pitfalls to watch out for:

Heading styles must only be on one line

First line of document should not be part of document hierarchy

Inconsistent Styles or Heading levels


Heading styles must only be on one line

The length for each heading / title must be for one line only.  That means that the heading lines with the same style name:

Chapter 2

FIELD AND BASE REPAIR

must be converted (by yourself -- you can't expect a macro to do it reliably for all cases...) to something like:

Chapter 2	FIELD AND BASE REPAIR

with the line ending with just one paragraph mark and the appropriate style applied to it (eg. Chapter Heading).  If not, the macro will think that the two (or more) lines represent more than one topic heading and will really screw things up.


First line of document should not be part of document hierarchy

The very first line of the document (usually some sort of document title) should not have a style that is to be part of the document hierarchy.  This is because the processing macros will need as its first section a place to insert the top level menu or in other words the first page contents.  Hence in this document, the text that appear before the paragraph "INTRODUCTION" are of the Normal style, instead of being in any of the heading styles.

However, if you do have the first line in a style that is part of the document hierarchy, then you'll be prompted whether to abort or simply insert a blank line above it.  For the latter case, it'll be necessary for you then to insert some text to make the final help file look meaning full for its startup topic.


Inconsistent Styles or Heading levels

By default, the when processing the document, HyperDoc will check that the document has heading levels that are consistent, ie. progress from one level to the next without jumps.  However, if heading levels like

heading 1 	(or any other style that represents the level)

heading 2

heading 4

are found, then a warning message will be shown if you selected the Warn If Inconsistent Style Found  option during the setup dialog.  If the warning is not shown or if you select OK to continue even if that inconsistent style was found, then the heading 4 title will simply be assumed to be of level 3 in the document hierarchy instead, ie. the macro will adjust its level number to be appropriate for that location.

This means that for all documents, there must be titles with styles in the first heading level, or else the help file will come out quite awkward.


Tips for Creating Help Files with HYPERDOC

What you see in Winword vs. what appears finally

Use the proper HyperTrack Loading option

Remove the Keep With Next paragraph attribute for Popup Windows

Use Cross Reference macro to create new topic groups

Consider using Undo Process macro to preserve Cross References

Remember to distribute Project and Keyword Files with Help File

More Customisation?


What you see in Winword vs. what appears finally

Remember that WinHelp displays the document in 100% zoom mode, so if you want to check whether the font size is big enough or not, click on the [image] toolbar button.  To bring back to Page Width zoom, just press CTRL-SHIFT-V.

The tab stops in WinHelp are different from Winword, and so is its right margin.  In fact its right margin depends on the width of the help window, unless you have a table in it.  Try using hanging indents as in this document for listing of bulleted items.


Use the proper HyperTrack Loading option

If your help file is intended to be called by an application ie. using the WinHelp function to load up specific topics, make sure you select the Load Minimised option under the Set Run + HyperTrack Options Dialog when running the Process Topic Outlines macro.  This will prevent the HYPERTRACK application from automatically initialising the help topic to the first page contents.

If you are creating a small help file (like say under 10 topics), then it may be unnecessary to have the HyperTrack application loaded up.  This will enable the help file to be distributed alone but none of the added functions of HyperTrack will be available, like the Up 1 Level button or the search on every word feature.


Remove the Keep With Next paragraph attribute for Popup Windows

Due to a bug in WinHelp, topics with the title defined using the Keep With Next attribute (found under the Format-Paragraph menu) will not display properly when used for popup windows.  All the heading titles are automatically set with this attribute when the Process Topic Outlines macro is run so if you want to use any topics as a popup window, you'll have to remove that attribute from that topic's  heading line.


Use Cross Reference macro to create new topic groups

If you want to create useful topic groups, for example in this case create a group of topics all related to Cross References, you can call the Cross Reference macro after selecting a phrase.  The new topic created at the end of the document can then be used like a new topic but references to it must be done manually since the Tracker would not know about it.  The only way the Tracker could know about it is if you insert the proper title headings to it and then run the Process Topic Outlines macro on the document again.  The context string for it will usually begin with topic4popup1, meaning topic for popup and a counter as to how many of them are around.


Consider using Undo Process macro to preserve Cross References

If you've performed a lot of Cross References and then find that you need to run the Process Topic Outlines macro again, you may want to consider using the Undo Process macro to remove all the footnote characters before running it.  However, if you add in new topics or rearrange the document structure, you may find that some of the cross references may be invalid and hence require the context string attached to it to be changed (either manually or you can call the Cross Reference macro again).  You can use the table listing of topic titles and context strings from the Master Topic Listing macro as a guide to help you find the right references.


Remember to distribute Project and Keyword Files with Help File

If you want to use the HYPERTRACK application with your help file, remember to keep the project file created (*.HPJ) in the same location as your help (*.HLP) file.  Also if you want to have the feature to search for all words, you'll need to run the Scan Keywords macro on the processed file and distribute the resultant (*.KEY) file.


More Customisation?

If you want to further customise your help files, feel free to modify the help project (*.HPJ) files, eg. to add or remove some of the buttons, add in extra short cut keys, etc.  Since most of the macros in the HyperDoc template are not read-only, you can adapt them to your own situations.  For example to change the default color headings, you can modify the Run Help Compiler macro.  There is also an entry added to the WIN.INI file called [HYPERDOC] that contains some of the options for HyperDoc and HyperTrack.

If you require further customisation both of the macros or the HyperTrack application, feel free to contact me and I will do my best to help.  If you need any assistance or have any comments, please feel free to contact me on the address listed under Registration and Support.


Steps for creating a basic help file with HyperDoc

Listed below are the minimum steps required to create a help file with the HyperDoc macros from an existing Winword document:

Any other macros that you want to execute, they should be done between steps 3 and 4.

If you want to have cross-linkages between different topics, you can run the Cross Rerefence macro.  To create a listing of all the topics in the help files together with their context strings, browse sequences and keywords, use the Master Topic Listing macro.  To insert new topics, eg. for pop-up windows, use the Insert Help Topic macro.


Acknowledgments

Much credit would go to Roger Hadcraft of Monash University (author of Dr Help) who first showed it was possible to automate the creation of help files from Winword files.  The Microsoft Windows Help Authoring Template (WHAT) files also provided a great deal of assistance; in fact the macros InsertMacroHotspot, EditMacroHotspot, InsetTopic, EditTopic and StartOfTopic are taken directly from there.


Detailed Description of HyperDoc Macros

The following are the macros used.  They are all found under the Help section of the Microsoft Word screen title (located at the right end of the title bar). Most of them can also be accessed by clicking on the toolbar buttons.

Process Topic Outlines

Jump To Topic

Edit Topic

Scan Keywords

Master Contents And Listings

Cross References

Insert Helpfile Graphic

Undo Process

Insert Macro Hotspot

Insert Topic Keywords

Insert Help Topic

Run Help Compiler

Open Help File

Other Useful Macros

List of all Key Assignments under HyperDoc

See also Overview of HyperDoc


Process Topic Outlines

This macro can be run by clicking on the [image] toolbar button, by pressing the keys (CTRL-SHIFT-P) or selecting the option under the Help sub-title.  Please ensure that you've read the "Document Preparation" section first before running this macro.  After that, this macro should be run, before most of the others, because it performs the necessary formatting on the document.

After the macro has completed, you will find all sorts of funny characters added (most of them are actually footnote markers) as well as a hard page break inserted at the start of each topic.  These are needed for the Help Compiler afterwards.  If everything went well, then you should find the file saved under a name which you specified under the setup options.

ProcessTopicOutlines Setup Options

Customise Keywords Dialog Box

Set Run + HyperTrack Options Dialog Box


ProcessTopicOutlines Setup Options

Name of File to Save As:	Allows you to specify the name to save the processed file as -- if you don't want the extension BAK, use something else and it should be automatically set for the next time.

Don't Save Now:	Select this if you do not want to save the original file yet.  However it will still be saved under another name as specified on the above field, unless it was deliberately blanked out.

Use Default Heading Styles:	With this option selected, the macro will assume that the document hierarchy is determined by the styles heading 1, heading 2, and so forth.  If your document has other styles that you want to consider as part of the document hierarchy (eg. Chapter, Section, etc..) then make sure that you de-select this option.

Warn If Inconsistent Style Found:	With this option selected, the macro will prompt if it comes across a style that does not conform to the standard document hierarchy (eg. from a heading 1 topic, it comes across a heading 3 topic, instead of a heading 2 topic first).

Name of Default Heading Style:	Used to define the default name of heading levels in the document, eg. heading 1, heading 2, etc..(relevant if you're using a different language)  This section is only applicable if the Use Default Heading Styles option is set.

Customise Menu Style:	Select this button to change the default style for topic menus (ie. the titles that will be listed as choices for the user when navigating through the help file).

Title for First Topic:	This field defines the title of the very first topic in the help file, and by default it is First Page Contents.

Customise Words to Exclude as Keywords:

This button allows customisation of words that will be included as keywords in the help file. Refer also to Customise Keywords Dialog.

Set Run + HyperTrack Options:	Select this button to control how the macro will be run as well as options to load up HyperTrack.  Refer also to Set Run + HyperTrack Options Dialog.


Customise Keywords Dialog Box

The main combo box contains the list of words that will not be included as keywords (ie. words that appear in the Search dialog) of the help file.  Usually will contain common occurring words like those in the default list.  Feel free to add or delete any words from the list by selecting the appropriate push button and when satisfied, select OK.  If you select Cancel, the macro will terminate.

Don't Split Keywords: 	If you decide that you do not want to split up the topic titles into individual words, then select this button.

Minimum Length of Keywords:	This edit box determines the minimum length of words that will be considered to be split up as keywords.  Eg. if its set to 5, then common words like "that, are, more" will be excluded.  Note that if its set to less than 5, you may have to add more to the list of words to be excluded.


Set Run + HyperTrack Options Dialog Box

Run Minimised:	This will cause the Microsoft Word application to be reduced to an icon as the macro is run -- able to speed things up (less need for screen redraw) as well as allows you to do something while it hums along.  It will be restored back to normal size when the macro finishes.

Lock Screen Updates:	This option freezes the application screen window in order to speed things up, and makes sure that it is not in maximised position, also giving you an opportunity to do something else while it is silently at work.

Note that for the two above options, while the macro is running, the mouse pointer will be as an hourglass, but you should still be able to click on other applications (depending how fast is your machine).  However, they are NOT very reliable and may cause the computer to hangup.... so be warned!!

Show Elapsed Time:	If you want to know how long the macro took to complete, you can select this option.

Save after <num> topics:	Determines how often the macro will perform a save to disk file for the document being processed (usually to prevent running out of memory for large files).

HyperTrack Options:

Load Automatically:	Select this if you want the Helpfile Tracker (HyperTrack) to be loaded up every time the help file is run.  This would be the default option for help files that are intended as a hypertext viewing environment.

Load Minimised:	Select this if your helpfile will be called by an application ie. for context-sensitive help (as in the case for this help file).  If you select this option, you may find that when you terminate HyperTrack, the help window is still around.

Don't Load at all:	Select this if you do not want your help files to rely on the HyperTrack application.  This will enable your help files to be distributed without the Hyperdoc.dll and Hypertrk.exe files as well as its HPJ files.  The Process Topic Outlines will work faster with this option since it will not insert the !DisplayText() macro for each topic.


Jump To Topic

Called by CTRL-SHIFT-J, clicking the [image] toolbar button, or by selecting it under the Help sub-menu.

This macro enables you to jump to the start of any topic within the processed file.  It calls up the HyperTrack application to do so.


Edit Topic

Called by CTRL-SHIFT-E, clicking the [image] toolbar button, or by selecting under the Help sub-menu.

This macro, taken directly from Windows Help Authoring Template, allows you to edit any aspect of the topic you are currently at.  However, you should not modify the context string, which has already been set by the ProcessTopicOutline macro when it was first run.  Use it to modify the topics that you've created manually (eg. with the Insert Help Topic macro).


Scan Keywords

Accessed by clicking on the [image] toolbar button, pressing CTRL-SHIFT-K, or selecting it under the Help sub-menu.  It can only be called after running Process Topic Outlines.

This macro scans through the entire document line by line and processes every word in it, excluding those that are less than a certain length and some common occuring ones.  You have the option to set those words to exclude when the macro fires up.  After it has completed successfully, it creates a file with the extension .KEY that is used by the HYPERTRACK application.


Master Contents And Listings

Accessed by clicking on the [image] toolbar button, pressing CTRL-SHIFT-T, or selecting it under the Help sub-menu.  It can only be called after running Process Topic Outlines.

This macro enables you create a complete listing of ALL the topics in your document, ie. those that have a heading style that is part of the document hierarchy.  If lists the number, title, context string, keywords, and browse sequence of all topics. After the macro has finished you'll be prompted to save it under the name with default extension IDX.  This will then be useful if printed out and kept for reference when establishing cross-linkages/references to other topics, especially in producing hot-spots within bitmaps, since the context-strings there will have to be entered in manually.


Cross References

Once the Process Topic Outlines macro has successfully completed you can insert Cross References to other topics within the document.  If you want a word or phrase to be linked to another topic, just Double-Underline it (simple way is by selecting the phrase and then press CTRL-D), as in Process Topic Outlines.  You should consider using the Select Word macro (F2 key) to select only the current word without trailing spaces.  Once they have been double underlined, call up the Cross Reference macro using either the [image] toolbar button, key strokes CTRL-SHIFT-X or select under the Help sub-menu.  After the macro has finished, its a good idea to save the file again.

If you only want to process one phrase and make it a hypertext link to other topics, just select that phrase (no need to underline it) and immediately call the macro.  This macro can be run as often as you want.  When multiple targets are selected, topics that refer to itself are automatically left out, so you won't get cases when you're in a topic and you find yourself selecting a jump back to the same place.

You can still run this macro even on a clean, unprocessed document if it was processed at least once by the Process Topic Outlines macro, ie. a HPJ file has already been created for it.

Using the Tracker for Cross References


Using the Tracker for Cross References

When you select the Cross Reference macro, the HyperTrack program will be called up to assist you in select the topic you want quickly and effectively.  When first started, it will try to search for the currently selected phrase among the list of all topic headings.

•	To add in other topics to be part of the links by double-clicking the selected topic or press the Ins key from the keyboard.

•	To remove/delete a topic from the list on the Search Results window, right-click the selected topic or press the Del key.

•	To insert comments for that topic (text that will appear next to a menu item in the help file, usually to provide some initial summary of what that topic is about), left-click on the selected topic or press Enter from the keyboard.


Insert Helpfile Graphic

If you have any graphic images you want to insert into or reference to the document, call this macro.  It can be accessed through the [image] toolbar button or  under Insert sub-menu or CTRL-SHIFT-G.  The following options apply:

Use WinGIF application:	Allows the graphic file to be accessed indirectly using the WinGIF application (which is a shareware product).  This will save a disk space since the graphic will not be inserted into the help file but will be accessed only when WinGIF calls it.  Formats allowed are BMP, PCX or GIF.

Insert Bitmap indirectly:	This will cause the bitmap to be inserted into the help file at compile time, so you won't be able to see the graphic in Winword but only in the help file.  This is the only way to insert bitmaps with hotspots (SHG files).

Insert into Document:	This simply inserts the graphic directly into the Winword document.  Though this is useful for small pictures, it may cause some memory problems during compilation if the graphic files are too big.


Undo Process

Attempts to remove all the changes made to the original document by the Process Topic Outlines macro.  Use this if you want to restore the processed file to its original state, eg. after adding in many Cross References you decide you want to insert new topics and have to call the Process Topic Outlines macro again.  Press CTRL-SHIFT-U or select it under the Help sub-menu.


Insert Macro Hotspot

Called by CTRL-SHIFT-I or by selecting it under the Help sub-menu.

This allows you to insert Help-Macro hotspots within the document.  Acknowledgments go to the Windows Help Authoring Template (WHAT) authors for the macros.


Insert Topic Keywords

This macro splits a selected phrase into individual words and inserts them as keywords for the current topic.  You'll have the option to control the words that are actually included by selecting the Excluded Certain Words check box and selecting the button Set Exclude Words.   This enables you to leave out certain common occurring or non-specific words from being listed under the Search window in the final Help file.


Insert Help Topic

This macro is also taken directly from Windows Help Authoring Template.  It allows you to insert a new help topic at the end of the file.  You should only use this macro to insert additional topics eg. for popup windows that you cannot include in your original document.  See also the Edit Topic macro.


Run Help Compiler

Once you made the necessary processing on the help file, you can run this macro using the [image] toolbar button, or under the Help sub-menu.

This macro will save the file in Rich Text Format (RTF), allow you to set certain options, and then calls the Help Compiler, which takes the current document and churns out a Windows Help (.HLP) file.  The following describes the options that you can set before calling the help compiler:

Main Window Title:	This is the text that will appear in the caption of the main help window, which by default will be the name of the current document's title as what appears in the summary information.

Secondary Window Title:	Text for the caption of the secondary help window.  This secondary window will appear on the top right of the screen while the main window will take up most of the left screen.

Main Window Size:	The two fields (Width and Height) describe the sizing of the main help window in units of screen pixels out of 1023, ie. the maximum width and height of the screen is assumed to be 1023 irregardless of the actual screen resolution.  The WinHelp system automatically scales it to the real screen resolution so that if you specified 1023, it will take up the full width or height of the screen irregardless of the display resolution.

File Compression:	This option list box allows you to select what type of compression will be applied when compiling the help file; High can result in up to 50% compression but creates a *.PH file in the process which stores commonly occurring phrases; Medium compresses up to around 40% or less but doesn't create a *.PH file (the default method); while None obviously creates the largest help file, with no compression applied.

Use Colours for Tracker Headings:	This check box sets up the HyperTrack program to display different colours for different topic heading levels, eg. all Level 1 headings will be in red, etc..

Do not worry about the warning message while compiling which says "section [HYPERDOC] unrecognised..."


Open Help File

Accessed by pressing CTRL-SHIFT-L or clicking the [image] toolbar button or selecting it under the Help sub-menu.

This macro will display the Help file that is produced after it has been compiled, eg. if this document is called HYPERDOC.DOC, then after running the above macros, you will get the file HYPERDOC.HLP created.  Since this macro is not write-protected, you can modify it to display the Help file using the WinHelp windows function call instead.  This is useful if the file has the option to run HyperTrack minimised when loaded.


Other Useful Macros

The HYPERDOC.DOT template comes with a whole lot of other useful macros that will make life much easier not only for creating help files but also for every use of Word for Windows. Feel free to explore all the other macros listed under ToolsMacros (by pressing CTRL-SHIFT-M).... I'm only listing out a few of them here:-

Change Directory (as well as Open and Delete files)

Toggle View Style Name Area

Toggle View Hidden

Jump To Page (the dynamic way)

Dynamic Zoom (the easiest way to change view)

Dos Shell

Copy Macro

Select Word

Pre-Process FAQ files


Change Directory (as well as Open and Delete files)

This allows you select a directory to change to as well as what default extension to open file as.  Even allows you to delete files.

Called under the File sub-menu or the [image] toolbar button.


Toggle View Style Name Area

Toggles between seeing the style names on the left of the document or not -- no more hassles about having to switch to outline mode, though that is still useful when checking the consistency of your document styles.  Accessed through CTRL-SHIFT-N keystrokes, under View sub-menu or [image] toolbar button.


Toggle View Hidden

Toggles between seeing hidden text in the document.  Accessed through View sub-menu or CTRL-SHIFT-H.


Jump To Page (the dynamic way)

Allows you to easily jump to any page in the document with the help of a scroll bar.  Also allows jumping to any bookmarks or to the previous location.  Accessed with the F5 key or [image] toolbar button.  Note that selecting the Sample button will bring you to the specified page but the status bar in the bottom will not be updated.


Dynamic Zoom (the easiest way to change view)

Allows you to easily control the View Zoom percentage of the document -- must see it to believe it.... accessed with CTRL-SHIFT-Z key or [image] toolbar button.  Note that selecting the Sample button will bring about the specified zoom value but the status bar in the bottom will not be updated.


Dos Shell

Allows you to start a MS-DOS shell session.... accessed under File sub-menu.  It assumes that you've got the file DOSPRMPT.PIF somewhere in the path.  Feel free to modify it to any Operating System shell you want.


Copy Macro

Allows you to copy a macro from one template to another..... accessed with CTRL-SHIFT-Y or use ToolsMacros to select manually.


Select Word

Allows you to select only the word where the insertion point is at, without the spaces at the end.  Very useful if you want to underline only that word but can't stand the ugly extension of it to the next word.... use the F2 function key.


Pre-Process FAQ files

Pre-process Frequently Asked Questions (FAQ) text files by putting in the appropriate heading styles on it.  A convenient way to use it would be to select the table of contents, and the macro will automatically set the styles for the matching title, based on the number of periods there are (eg: "1. Title..." would mean level one, "1.2. Another title..." would mean level two, etc.)  Make sure you check out the actual macro code itself to get it customised for the particular FAQ file..... access by selecting the ToolsMacro list box.


List of all Key Assignments under HyperDoc

To find out all the key assignments under the HyperDoc template, just run the FilePrint command and under the Print: field, instead of Document select Key Assignments and then print it out.

Most of them are listed next to the macro names under the View and Help menu titles, eg. Ctrl-Shift-H toggles between viewing hidden chars, Ctrl-Shift-Y calls up the help, etc.


Registration and Support

If you are having an evaluation copy, you need to register if you use it for more than 10 days.  The unregistered version of HYPERDOC is limited to handling up to 30 topics while the registered version should be able to handle up to 900 topics, unless you run out of memory first.

To register, please print the following section or the file REGISTER.TXT and send the  payment to me at my home address.

REGISTRATION FORM

For HyperDoc and HyperTrack

Release 3.2	November 1993

Name:	_________________________________________

Company:	_________________________________________

Address:	_________________________________________

_________________________________________

_________________________________________

Phone No:	________________

E-mail address:	_________________________________________

Transmission:	___ email	___ 3.5" disk	___5.25" disk

Payment enclosed:	$_______	(remember to include extra for disks and also if you want the source code as well)

Cost:

The HyperDoc macros and the HyperTrack application are not freeware programs -- they are shareware.  The author has spent more than 300 hours in research, design, coding, debugging and documentation.  Hence in return all I'm asking for is a meagre sum for me to keep developing this powerful hypertext system.  For basic registration, the cost will be

either 	US	$25

or 	AUD	$35 	in bank cheque or money order.

If you are sending cash, it'll only cost you US$20, since it's less of a hassle for me.

Delivery:

If you have an email address, I would prefer to send you the registered version via e-mail.  However, if you can only manage diskettes, then you'll need to pay an extra $5 for postage and handling.

Contact:

The most convenient way for me to keep in touch with you will be through e-mail, until 10th December 1993.  The following is my email address in Melbourne, Australia:

s892831@minyos.xx.rmit.oz.au   or   s892831@yallara.cs.rmit.oz.au

Home address: (normal mail)

13 Stawell St.

Coburg

VIC 3058

AUSTRALIA.

Tel: (03) 354-2490

After 10th December 1993,  I can be contacted via normal mail at

220, Jalan Raja Kam,

Canning Garden,

31400 Ipoh, Perak,

MALAYSIA.

Tel: (6-05) 573-304

If after registering you have any queries about building help files or even programming in Windows, feel free to ask me and I'll try my best to assist in any way possible.

Special Offer for Source Code


Special Offer for Source Code

If you are interested in how all the HyperDoc macros work or want to customise them yourself, I'll be willing to send it to you at the cost of US$70 (or AUD$100).

If you want the source code for the HyperTrack program and the DLL module (which was written in Borland C++), it'll cost you US$120 (or AUD$150).

As a special offer for both the source codes (WordBasic and C++), I'm offering it at US$150 (or AUD$200).  With both these source codes, you can not only customise it to your heart's content but probably even adapt it to other word processing environments (like WordPerfect or AmiPro) and you can then make even more $$ out of it.......  Developers of other WinHelp authoring systems may want to use adapt the HyperTrack concept into their help files so having the source code will be quite essential.

Thank you for you support.

Kenneth Liew

October 1993


Short-Cut Keys

List of Short-Cut Keys in HyperTrack

Short-Cut Keys added for WinHelp


Overview of HyperDoc

HyperDoc: the easy way to produce help files from existing documents


Cross Reference

Use Cross Reference macro to create new topic groups

Consider using Undo Process macro to preserve Cross References

Cross References	Description of the macro

Using the Tracker for Cross References


Cross Reference

Use Cross Reference macro to create new topic groups

Consider using Undo Process macro to preserve Cross References

Using the Tracker for Cross References


These menu items act as toolbar buttons and they perform the task of collapsing the displayed levels [<=] or expanding the displayed levels [>=] by one.

Alternatively, you may choose to use the numbers on the keyboard 1, 2 or 3 to show only up to those heading levels, or click on the [I] item.


The caption bar shows the help file that it is currently tracking.  Press the I key for more detailed information about the help file.


(Only listing some of the menu items here...)

File-- Print:  Prompts for a range of topics to print and then spools them to the printer.  To view the topic numbers, select the Show Context Strings option under the Display menu.

Display-- Reposition Window: Reposition and resize the Tracker according to the current help windows active.


This is the main work space for HyperTrack.  It displays the list of topics in the help file and is usually color coded to distinguish between the heading levels.

When used in viewing help files, you left double click the topic to view on the main help window, while right clicking will show it on the secondary window.

The current topic displayed is highlighted in light blue.

•	To customise the screen, select Set Display Options from the Display menu.

•	To print out help topics, select Print... from the File menu.


Display:	This menu item allows you to customise the way the search results appear.

Show Context Info will show the topic context string as well as how many hits for the current search criteria.


Sort:	This menu item allows you to choose in what order the topics will be displayed.  To show how many hits for each search criteria, select the Show Context Info under the Display menu.


Print:	This menu item will spool out to the printed the help topics currently listed on this Search Results window.


This area shows the results of the last search option.  It shows the same colors as the main Tracker window but may or may not be indented.  If you double click on a line, it'll show the help topic for that title.  See also the display and sort menu items.


The main HyperDoc macros:

Other useful macros:


A windows application that attaches itself to the WinHelp engine, providing various features not present in normal help files.  Its main window shows a dynamic table of contents of the document being displayed, which would have been processed by the HyperDoc document template.


A Word for Windows document template that automates the creation of windows help files.  The help files generated can then be viewed either by themselves or together with HyperTrack.


HyperTrack and HyperDoc are the two components that make up a comprehensive development system for creating Microsoft Windows help files.