Copyright: ® Roger Hadgraft, 1993


Release 5 Changes

This document describes changes in Doctor Help from release 4 to release 5. Similar documents exist as release3.hlp and release4.hlp for the historically inclined.

Table of Contents

Implemented Features

To be done

Glossary

Index


Table of Contents

Table of Contents

Implemented Features

Metafiles (Graphics) in Titles

Superscripts and Subscripts

Process Cross References

Ready For Printing macro

Run Matching Help File macro

Run Dialog Editor macro

Table of Contents

Index

Copy Topic menu item

MAP file

Check Jump and Check Popup macros

Jump to File macro

WinHelp support

Full Title as a Keyword

Hotspot Editor example

Glossary TABs

2000 topics now possible

View Normal

Side by Side Text and Graphics

New Examples file

Underlined End-of-line

RTF file in Options Dialog

Cancel Button in "Unresolved Cross References" dialog

Menu button

Optional Buttons

DEFAULT.HPJ

Add Menu Styles

Dr Help Options Button

Jumps Button

Keep with Next and Keep Lines Together

New Styles

Execute Programs DLL

Tutorial Format for DrHlpUsr.Hlp

Negative indents

Special Characters

Delete RTF and NEW files? prompt

Page Number in MAP File

To be done

Execute Programs DLL

Up Button

Project File Options Dialog

Popups

Separated Top Level

Keywords

Initial blank lines

Language Independence

Modify Win.Ini Options

Document Error Messages

Exact Match cross references

Yield Function

Glossary

Doctor Help

DRHELP.HLP

DRHELP.INI

Notepad

PATH

Index


Implemented Features

Metafiles (Graphics) in Titles

Superscripts and Subscripts

Process Cross References

Ready For Printing macro

Run Matching Help File macro

Run Dialog Editor macro

Table of Contents

Index

Copy Topic menu item

MAP file

Check Jump and Check Popup macros

Jump to File macro

WinHelp support

Full Title as a Keyword

Hotspot Editor example

Glossary TABs

2000 topics now possible

View Normal

Side by Side Text and Graphics

New Examples file

Underlined End-of-line

RTF file in Options Dialog

Cancel Button in "Unresolved Cross References" dialog

Menu button

Optional Buttons

DEFAULT.HPJ

Add Menu Styles

Dr Help Options Button

Jumps Button

Keep with Next and Keep Lines Together

New Styles

Execute Programs DLL

Tutorial Format for DrHlpUsr.Hlp

Negative indents

Special Characters

Delete RTF and NEW files? prompt

Page Number in MAP File


Metafiles (Graphics) in Titles

Dr Help now eliminates metafiles (eg. graphics or equations) from titles. It substitutes a space instead. In release 4, this caused unpredictable results from the help compiler.


Superscripts and Subscripts

WinHelp seems to mess up superscripts, by translating them into subscripts (even thought the RTF file seems correct). It is suggested that you use the equation editor instead. This is a little inconvenient, but does, at least, provide a solution.


Process Cross References

Removed a reference to dlgFmtChar.


Ready For Printing macro

A macro has been added to translate some of the Help specific things into a form more suitable for printing. For example, Double underlining is translated into bold italics, and Single underlining becomes just italics. This macro has been added to the print icon in the toolbar [image]. The macro prompts first to make sure that you want it to modify the Help specific items in the document. Otherwise, it just runs FilePrint as usual.

Bitmaps defined with {bm??? ...} instructions are imported. Hotspot files (.SHG) are handled by checking for either a .BMP or .WMF file. Files with other extensions are assumed to be correct. If Word cannot interpret a given file, then an Error! Cannot read or display file. message is inserted.

It also includes the insertion of all defined keywords as index entries to match the hypertext document. That is, the same words that are added to the hypertext document to work with the Search button, are added to the Index. UpdateFields is switched on for printing so that the index will be automatically updated.


Run Matching Help File macro

This macro calls up the matching help file. This is sometimes useful while working on a file.


Run Dialog Editor macro

This was mostly written for my benefit so I could call up Word's dialog editor when I needed it.


Table of Contents

Added a macro to create a Table of Contents to replace Word's Table of Contents. Each item is a hotspot for the relevant topic. This can help a user to browse through the entire file's contents, rather than just levels of it.

The format of this contents page is determined by your own setting of the toc styles, which are now predefined in HELPFILE.DOT.


Index

If an Index is found in a document, an instruction is inserted suggesting that the reader use the Search facility in its place. This required an extra item in DRHELP.INI and the Win.Ini Options macro was updated accordingly.


Copy Topic menu item

DEFAULT.HPJ now includes a macro to insert a Copy Topic item in the Edit menu.


MAP file

Dr Help now produces a .MAP file which contains a mapping of the context names to integers. This is useful when calling WinHelp from within applications via a

WinHelp( hWnd, lpHelpFile, HELP_CONTEXT, dwData )

call or from a dialog box in Microsoft Excel. However, beware that the numbers assigned to topics will change if you change the file. A better way to go is to use a HELP_KEY call, and if necessary, define a unique keyword. You can also define your own context names (see Defining context names)


Check Jump and Check Popup macros

This macro scans the matching .MAP file to see how many matches exist for a given defined jump. Just click before the defined (underlined) hotspot, and CheckJump will locate the next underlined term. It opens the .MAP file (which you must confirm is a Text file - I really wish Microsoft would fix that), and starts scanning for the phrase given. If you keep clicking on OK, it will keep scanning. Press Cancel to stop. The number of matches (if more than 1) is reported. After each search, you have the option to redefine the search string.


Jump to File macro

Jump to File is a new way to define links to other .HLP files. It accesses the .MAP file for that .HLP file, allowing you to browse through the topics until you find the one you want, and includes a Help button to show this information. Click on Cancel to abort the process.

You are required to define 3 parameters:

Button text is text which will be underlined, and which the reader will click on. If you have already entered the button, simply leave blank.

Filename is the file containing the topic required. Click on the Choose button to bring up a dialog box to find the file. The .HLP file must exist, and there must be a corresponding MAP file to match.

Destination is the required topic. Click on Choose to search the .MAP file for the file you chose at the last step. It will prompt for a string to search for if you have not entered something for the button text. (You usually have some idea of what the topic is called). You can search up and down through the .MAP file. When you've identified the topic you want, click on OK. (Check Jump is used to do the searching).

Both title and context name are copied back into the Jump dialog box. You can choose which one you will use for the jump. If the context name has been defined by you (ie. it's not created by Doctor Help to look like card35), then use the context. Use the title when you know that it's unique. Simply click on the appropriate option button, then on OK.

You don't have to use the Choose buttons. They just make it easier for you. You can just type in the name of the file, and/or the context or title names.


WinHelp support

Doctor Help now has access to the standard WinHelp call in Windows. This has allowed me to build Help buttons into its dialog boxes, such as the Project File Options Dialog and Win.Ini Options.


Full Title as a Keyword

In the last revision, it became possible to fragment titles as separate keywords. In this revision, the full title is added as well as the separate keywords. This allows unambiguous jumps via keyword by using the full title. (It is still possible to have only full titles, by choosing the appropriate option in the OptionsDialog).


Hotspot Editor example

DRHLPUSR.HLP now includes a graphic which has defined hotspots using the hotspot editor.


Glossary TABs

Thanks to Hajo ??-Schmitt, included are 2 .SHG files for glossaries, TABS.SHG and BUTTONS.SHG. Each is constructed to expect topics named like glossaryABC, glossary DEF, ... glossary YZ. Include one at the start of your glossary and divide your glossary items into sub-sections. An example file is included (GLOSSARY.HLP and .DOC).


2000 topics now possible

Since one of the users of the macro has run into the 1,000 limit, I have increased the limit to 2,000 topics.


View Normal

Dr Help now switches page view to Normal mode. It was found that it sometimes got confused if the document was in Page Layout mode.


Side by Side Text and Graphics

I have created a small example (SIDESIDE.*) to show how text and graphics can be positioned side by side on a page by using a 2 cell table.


New Examples file

The several examples from release 4 have been rolled into one example file (EXAMPLES.HLP).


Underlined End-of-line

Be careful not to press the <Enter> key if you are typing in an underlined cross reference or popup. It may be myterious why this cross reference is not matched with its corresponding destination.


RTF file in Options Dialog

The Options Dialog now contains the RTF filename, just in case it needs to be changed. Unfortunately, this means opening the .HPJ file, which means that you have to tell Word that it's a text file. This is a bit of a pain. Perhaps I will look at changing this.


Cancel Button in "Unresolved Cross References" dialog

A Cancel button has been added to this dialog box so a user can quit out of the compilation process. It also optionally reloads the DOC file. The change was made to the generic ErrorMsg routine, so all error messages inherit the Cancel option.


Menu button

A Menu button now allows a reader to browse up through the hierarchy. This is a little like the Up button, except that Up always backtracks along the route that you have taken, while Menu follows the hierarchy strictly. It was necessary to add an extra line to DEFAULT.HPJ, so you will need to update your old .HPJ files if you wish to provide the Menu button.


Optional Buttons

With the addition of the Menu button it was necessary to preserve compatibility with old files, and also allow extra control over which buttons would be inserted in the Help file's button bar. A check box for each of the three buttons (Up, Menu, Annotate) have been added to the Project Files options dialog. This macro writes the relevant macro strings into the project file. All of this takes a bit of time, (5 to 10 seconds), so be patient.


DEFAULT.HPJ

DEFAULT.HPJ has been modified to include the new Menu button, and to make it a HELPFILE type file. This was necessary so that it has access to all the macros attached to HELPFILE.DOT. If you have your own version of this file, make sure you update this version, rather than vice versa.


Add Menu Styles

The Add Menu Styles macro has been removed from the menu bar and moved to the Project Options dialog. It now correctly adds the Dr Help styles to a document, including creating a project file if necessary. This is particularly useful when you are about to convert an existing .DOC file.

See also Assign Help File Template, which differs by allowing you to add all the Dr Help styles, and not just those peculiar to Dr Help. This is useful if you want to have a large number of documents with uniform appearance.


Dr Help Options Button

The options button on the Toolbar [image] that previously only accessed the Project File options dialog now has an intermediate dialog (shown below) which allows access to several options:

•	Project File options dialog

•	Notepad to edit the project file directly. Most of the time, this will not be necessary, but occasionally it is useful. You must have Notepad in your PATH. This is the case if you have done a normal installation of Windows. This option is useful in particular for editing the [FILES] and [CONFIG] sections of the project file (if you know what you're doing!).

•	the Win.Ini options dialog (previously in the Help menu)

•	Add Template Styles (useful for standardising attributes across a range of help files)

•	Add Menu Styles adds just the specific Dr help styles, which is handy whehn you want to change a normal .DOC file into a Help file, without changing all the other styles.

•	a Help button that gives options-oriented help from DRHELP.HLP.


Jumps Button

The third button from the left in the Toolbar [image] is now used for:

•	jumps to other files

•	executing programs, and for

•	checking the next popup or jump in this file (see Check Jump and Check Popup)

An intermediate dialog box allows you to choose between them. Context sensitive Help is available.


Keep with Next and Keep Lines Together

Keep With Next ensures that the title of a topic does not scroll. This is very useful for most topics except for popups.

Keep Lines Together makes for non-wrapping text, so for long titles, do not use Keep Lines Together. HELPFILE.DOT has now been modified to remove Keep Lines Together from the heading styles.


New Styles

HELPFILE.DOT now contains default styles for Tables of Contents and Indexes. You can add the default styles to existing documents using Add Template Styles from the Dr Help options button.


Execute Programs DLL

I have built a DLL (DRHELP.DLL) to execute programs in the Windows style, ie. you only need to give the document name, and it will look in WIN.INI for the application. This is particularly useful if you are using the same help file on many different systems (with applications installed in different directories). A RegisterRoutine command has been added to DEFAULT.HPJ. For old Project files, you will need to add this line manually to the [CONFIG] section:

RegisterRoutine("drhelp.dll", "ExecProg", "v=Si")

The name of the routine is ExecProg (as opposed to the built-in function which is ExecProgram - I tried using the same name but it didn't work):

!ExecProg(drhelp.hlp,1)

The values for the integer parameter are as follows:

0	hide

1	normal

2	minimise

3	maximise

These match the parameters used by Windows in its ShowWindow function, but are not the same as WinHelp's ExecProgram (where 0 indicates a normal window).

I expect other routines will be added to this DLL in due course. It must be in a directory on your PATH, eg. the Windows or Windows System directory.

The DLL will also handle full pathnames, and will change to the correct directory before executing the application, eg.

ExecProg("c:\\infosys\\ar-r\\winhelp\\chapters.hlp", 1)

In this case, chapters.hlp will be opened, and its default directory will be c:\infosys\arr\winhelp, which is handy when that help file points to other help files which it expectsa to find in the current directory. This is useful for launching another application and making sure that its home directory is appropriate. Note that you must double all the backslashes. Sorry about that, but it seems unavoidable.


Tutorial Format for DrHlpUsr.Hlp

DRHLPUSR.DOC has been restructured into a tutorial format. This relies on drawing the reader into browsing through it. At the end is a diagram that allows the reader to click on various items to refresh his/her memory about it.


Negative indents

Negative indents are removed from headings as they are processed on the first pass.


Special Characters

Some characters with ANSI codes between 128 and 255 are not translated correctly into the Help file. These are now replaced with their ASCII equivalents. The ones processed at the moment are ' ' " " .


Delete RTF and NEW files? prompt

This prompt only comes up if you set debug mode in the Win.ini Options.


Page Number in MAP File

I have recently discovered that if a page number is set in the template file (as it is in HELPFILE.DOT), then it is written out if such a file is saved in text mode. One example is the MAP file. Although this does not cause any errors, it has been fxied in the WriteMapFile procedure.


To be done

Execute Programs DLL

Up Button

Project File Options Dialog

Popups

Separated Top Level

Keywords

Initial blank lines

Language Independence

Modify Win.Ini Options

Document Error Messages

Exact Match cross references

Yield Function


Execute Programs DLL

Add capabilities of StartUp (ie. handling of different PATHs for different applications) to DrHelp.dll.


Up Button

It might be possible to add a refinement to the existing Up macro to define the level above the current one if it doesn't exist.


Project File Options Dialog

Add a picture of the dialog box that a user can click on to see the required help. The bitmap already exists as OPTIONS.BMP which needs to go to the hotspot editor.


Popups

Use glossary entries to resolve popups.

Translate annotations into popups.


Separated Top Level

Implement a scheme to allow a set of separated topics at the top level. This might be possible using the existing Table of Contents feature.


Keywords

Enable searching of user-defined keywords.


Initial blank lines

Macro should remove initial blank lines in a file, and replace them with "lines before" for the first paragraph.


Language Independence

It would be useful to move all strings into a resource file which could be translated into different languages. So far, this has been done only for essential strings that are a part of Word.

I have made a start on this by adding the UseSearch string to DRHELP.INI. This is the string that is inserted into a help file if an Index is found. It reminds the reader to use the Search button.


Modify Win.Ini Options

I need to modify various macros that expect to read items from WIN.INI. I will keep only the bare minimum in WIN.INI in future, namely, copyright, language and home directory. This flows on from changes made to ensure enhanced language independence.


Document Error Messages

The various error messages and other messages need to be documented in DRHELP.DOC.


Exact Match cross references

Use the third type of underlining to provide an exact match style of cross reference.


Yield Function

The macro needs access to the Windows Yield function so other things can co-exist with it while it's running.

I've defined the function, and tested it with Ready For Printing, but it doesn't seem to work.


Glossary

Doctor Help

DRHELP.HLP

DRHELP.INI

Notepad

PATH


Doctor Help


DRHELP.HLP


DRHELP.INI


Notepad


PATH


Index

Use the [Search] button to find words in this document.


MAP file

Implemented Features / MAP file

Implemented Features / Page Number in MAP File


Table of Contents

Release 5 Changes / Table of Contents

Implemented Features / Table of Contents