The purpose of this page is to help you get started in building your help and contents file.
I have spent many hours understanding and learning some of the tricks of this compiler. Please note the information provided here is for the Microsoft Help Workshop and could possibly be done other ways also. My particular version is 4.2 received on the Visual Basic 5.0 professional cd set. There should be an HWC (help workshop compiler) directory on your MS VB 5 cd. Of course MS doesn't tell you it is there.
Your help text should be housed in an .rtf file
You'll need to define a .Cnt file (content file of topics)
You'll need to set up a .Hpj file (help project file)
I also set up a .txt file to translate help topics in the word file to numerical help topic numbers for my visual basic programs to reference (if needed when pressing F1)
Sample RTF FILE
#$K General Ledger V1.0 summary Business results reporting Calculate net loss or profit Easy to determine business operations and results Interface with Billing software Monthly, quarterly, semi-annual, annual or any other period chosen Remembers past input and entry/offset accounts PURPOSE OF GENERAL LEDGER #$K Overview of purpose General ledger is a tool used to determine business financial results. Expenses, liabilities, assets, owner equity, revenue and sales are tracked to determine a companys financial results or condition. SYSTEM FEATURESEND OF SAMPLE RTF FILE
For the example above "General Ledger V1.0 summary" is topic #1 and "Overview of purpose" is topic #2, the #$K are inserted custom footnote markers that you do not type in these are inserted (see below).
Notes - Use insert footnote at the start of each topic and insert # $ and K into the text area of your rtf doc - do not do this in the footnote area they will be added after your insert is completed. The footnote # indicates the title of the topic follows. The footnote $ is a brief or long description of the topic used in help search. The footnote K holds all keywords for help search related to the topic. Key in topic name, description and keywords into the footnote area of your document not in the text area.
Sample footnotes - you must turn on footnotes (select view then footnotes) in your rtf file, also to insert a footnote your cursor should be positioned at the top of the topic. Choose "Insert / Footnote / Custom mark then key in the # or $ or K, each must be inserted separately.
Sample footnotes -
# GLSUMMARY
$ Statement features and highlights
K features; summary; highlights
You can program jumps to different topics by:
Typing in the topic to jump to
Double underlining the topic to jump to
Placing the # defined name in the .rtf directly after the double underlining (do not underline) and change the #defined name to Hidden by highlighting and selecting hidden with format.
You can program help pop ups (not a jump):
Typing in a description of the topic to pop up
Single underlining the topic to jump to
Placing the # defined name directly after the description of the topic and formating the # defined name as hidden text
Sample code within RTF file to display a graphic image in your help:
{bmlt Glshot.bmp}
Sample Map .txt file
GLSUMMARY=100
GLPURPOSE=200
Notes - help topic 100 invoked from xyz program starts up the glsummary topic defined in the rtf file.
Sample content .cnt file
Hopefully you can work through building each topic you have and linking to the name within the rtf file - its just a tedius puzzle!
Sample help project file
I've had some issues with the help compiler and certain options cause problems when attempting to compile. You might want to visit the Microsoft website to possibly find a resolution or just write me because I could probably help out without taxing my brain too much. Set your compile to directory, the location of the .cnt file, the location of the map file and run your compile. You should probably run the test content file to make sure your topics match up against your rtf file.
Well that was a quick overview of "how to". I hope that was not too confusing and hope is was enough detail to get you started! It is a nice utility to use but as with everything regarding documentation this process is time consuming. If you should need help or if you think I need to add more help here please let me know what I should add - write me.
____________________________________________________________________________
Below is a document from Microsoft, documentation for the help workshop is quite confusing... but here it is...
Creating a Keyword List
You can also enable users to find and view topics by assigning keywords to the
topics. You assign a keyword by using the \footnote statement and the letter K
as the footnote character. Windows Help collects all keywords in a help file
and displays them in its Index tab. Using this tab, a user can select a
keyword and view the help topics associated with it. The following example
assigns the keyword "Sample Topics" to the current topic:
#{\footnote topic1}
${\footnote My Topic}
K{\footnote Sample Topics}
This is my first topic.
\par
\page
If a keyword begins with the letter K, you must place an extra space before
the word. Multiple keywords for a topic are separated by semicolons.
A keyword can be assigned to any number of topics. When the user selects the
keyword in the Index tab, Windows Help displays all topics associated with the
keyword. The user then picks the one to view.
You can also create alternative keywords for a help file for use with the
WinHelp function.
Sample Project File
The following example is a sample project file for the Cardfile application.
Comments, marked by a beginning semicolon (;), indicate the purpose of each
section in the file:
; Options used to define the Help title bar and icon
[OPTIONS]
ROOT=C:\HELP
BMROOT=C:\HELP\ART
CONTENTS=cont_idx_card
TITLE=Cardfile Help
ICON=CARDHLP.ICO
COMPRESS=OFF
WARNING=3
REPORT=ON
ERRORLOG=CARD.BUG
; Files used to build Cardfile Help
[FILES]
RTFTXT\COMMANDS.RTF
RTFTXT\HOWTO.RTF
RTFTXT\KEYS.RTF
RTFTXT\GLOSSARY.RTF
; Button macros and Using help file
[CONFIG]
CreateButton("btn_up", "&Up", "JumpContents('HOME.HLP')")
BrowseButtons()
SetHelpOnFile("APPHELP.HLP")
; Secondary-window characteristics
[WINDOWS]
picture = "Samples", (123,123,256,256), 0, (0,255,255), (255,0,0)
Using Macros in Project Files
You can add macros to the [MACROS] section of a project file. These macros are
run whenever a user selects the specified keyword in the index.
You can create new menu items and buttons for Windows Help by using such
macros as CreateButton and InsertMenu. These macros define other help macros
and associate them with the menu items and buttons. Windows Help executes
these macros when the user chooses a corresponding menu item or button. Macros
that create help buttons, menus, or menu items remain in effect until the user
quits Windows Help or opens a new help file.
You can extend the capabilities of Windows Help by developing your own dynamic-
link libraries (DLLs) and defining help macros that call functions in the
libraries. To define help macros that call DLL functions, you must register
each function and its corresponding library by using the RegisterRoutine macro
in the [CONFIG] section of the project file.
Project File Sections
Every project file consists of one or more sections. Each section has a
section name, enclosed in brackets ([]), that defines the purpose and format
of statements and options in the section. Following are the sections used in
project files:
Section Description
[ALIAS] Assigns one or more context strings to the same topic.
[BAGGAGE] Lists files that are to be placed within the help file (which
contains its own file system).
[BITMAPS] Specifies bitmap files. This section is not required if the
project file lists a path for bitmap files by using the BMROOT or ROOT option.
[BUILDTAGS] Specifies valid build tags.
[CONFIG] Specifies help macros that define nonstandard menus and
buttons used in the help file. This section is required if the help file uses
any of these features.
[CONFIG:x] Contains one or more macros that Windows Help runs when
opening the corresponding window, x.
[FILES] Specifies topic files to be included in the build. This section is
required.
[MAP] Associates topic identifiers with context numbers.
[MACROS] Associates macros with keywords.
[OPTIONS] Specifies options that control the build process. If this
section is used, it should be the first section listed in the project file, so
that the options will apply during the entire build process.
[WINDOWS Defines the characteristics of the primary Help window and the
secondary-window types used in the help file. This section is required if the
help file uses secondary windows.
Every project file requires a [FILES] section. This section names the topic
files. Most project files also have an [OPTIONS] section that specifies how to
build the help file. A very useful option in the [OPTIONS] section is the
COMPRESS option, which specifies whether the help file should be compressed or
uncompressed. Compressing a help file reduces its size considerably and saves
valuable disk space. For more information, see the Help Author's Guide
(HCW.HLP) included with the Help Workshop.
The following example creates a compressed help file from two topic files,
MAIN.RTF and MENUS.RTF:
[OPTIONS]
COMPRESS=TRUE
[FILES]
MAIN.RTF
MENUS.RTF
Creating Browse Sequences
You can enable users to browse through a sequence of help topics by creating a
browse sequence and adding browse buttons to your help file. A browse sequence
typically consists of two or more related topics that are intended to be read
sequentially. You create a browse sequence by using the \footnote statement
and the plus-sign (+) footnote character to assign a sequence identifier. The
following example assigns a sequence identifier to the topic titled "A Topic":
#{\footnote topic5}
${\footnote A Topic}
+{\footnote shorttopics}
This is one topic in a browse sequence.
\par
\page
Windows Help adds topics with sequence identifiers to the browse sequence and
determines the order of topics in the sequence by sorting the identifiers
alphabetically. If two topics have the same identifier, Windows Help assumes
that the topic that was compiled first is to be displayed first.
Windows Help uses the sequence only if the browse buttons have been enabled.
You can enable the buttons by placing the following statements in the help
project file:
[CONFIG]
BrowseButtons()
For more information about the project file, see Creating Help Project Files.
You can create more than one browse sequence in a help file by using sequence
numbers with sequence identifiers. The sequence number consists of a colon (:)
followed by an integer. Windows Help combines all topics having the same
sequence identifier (but different sequence numbers) into a single browse
sequence and determines the order of the topics by sorting them
alphabetically. To ensure that numerals are sorted correctly, they should have
the same number of digits. For example, the numerals 1 through 10 should be 01
through 10.
#{\footnote topic10}
${\footnote Alpha Topic #3}
+{\footnote alpha:3}
This topic is part of the alpha browse sequence.
\par
\page
Creating Links and Pop-up Topics
Windows Help displays only one topic at a time. To enable users to view other
topics, you must create hot spots that link your topics to other topics. You
create a hot spot by using the \strike, \ul, or \uldb statement and a
corresponding \v statement. When you create a link, you provide the text for
the hot spot and the context string for the topic that is to be jumped to or
displayed. The following example creates a hot spot named Glossary and
establishes a link from the hot spot to the topic having the context
string "glo1":
You can find a list of terms used in this
help file in the {\uldb Glossary}{\v glo1}.
When Windows Help displays the topic with this hot spot, it places a line
under the word Glossary and colors the word green. The context string is not
shown, but if the user clicks on the hot spot, Windows Help jumps to and
displays the corresponding topic.
The \strike and \uldb statements are used to create jumps to other topics. The
\ul statement creates a link to a pop-up topic. Windows Help displays pop-up
topics in a pop-up window and leaves the current topic in the main window.
You can also associate a help macro with a hot spot in a topic. For example,
the following \uldb and \v statements create a hot spot for the ExecProgram
macro:
{\uldb Clock}{\v !ExecProgram("clock.exe", 1)}
Windows Help executes the macro whenever the user chooses the hot spot. Windows Help continues displaying the topic while it executes the macro,
unless the macro causes a jump to another topic.
Defining Individual Topics
Each topic starts with one or more \footnote statements and ends with a \page
statement. All text and graphics specified between these statements belong to
the topic.
Every topic must have a context string. Windows Help uses the context string
to locate the topic when the user requests to view it. You assign a context
string to a topic by using the \footnote statement and the number sign (#)
footnote character. Context strings can consist of letters, digits, and the
underscore character (_). To prevent conflicts, each context string in a help
file must be unique.
You can also assign a title to the topic by using the \footnote statement and
the dollar sign ($) footnote character. Windows Help uses the title to
identify the topic. You must provide a title if you assign keywords to the
topic.
The following example defines a small topic having the context string "topic1"
and the title "My Topic":
#{\footnote topic1}
${\footnote My Topic}
This is my first topic.
\par
\page
In general, you use the \par statement to mark the end of each paragraph. In
this example, the \par statement marks the end of the only paragraph in the
topic.
You can add a macro to a topic by using the \footnote statement and the
exclamation point (!) as the footnote character. For example, the following
\footnote statement adds the CopyTopic macro to the topic:
!{\footnote CopyTopic()}
Help Statement Syntax
Help statements are an extended subset of tokens defined by the rich-text-
format (RTF) standard. The statements specify character and paragraph
properties, such as font, color, spacing, and alignment for text in the help
file.
Help statements are contained in topic files, which are specified in the
[FILES] section of a project file. A topic file consists of statements,
groups, and unformatted text. Each statement consists of a backslash (\)
followed by a statement name. For example, the following line demonstrates
usage of the \tab statement:
left column\tab right column
Statements must be separated from subsequent text or statement parameters by a
delimiter. A delimiter can be one of the following:
� A space.
� A digit or minus sign, which indicates that a numeric parameter
follows. The subsequent digit sequence is then delimited by a space or
character other than a letter or digit.
� Any character other than a letter or digit.
When a space is used as a delimiter, the compiler discards it. If any other
character is used, the compiler processes it as text or the start of another
statement. For example, if a backslash is used as a delimiter, the compiler
interprets it as the beginning of the next statement.
A group consists of help statements and text enclosed in braces ({}). Formatting specified within a group affects only the text within that group.
Text within a group inherits any formatting of the text preceding the group.
Unformatted text consists of any combination of 7-bit ASCII characters.
Although characters whose values are greater than 127 are not permitted in
topic files, the \' statement can be used to insert them in the final help
file. The compiler treats spaces as part of the text, but it discards carriage
return and linefeed characters.
Although the compiler supports many RTF tokens, it does not support them all.
The compiler ignores any RTF statement that is not explicitly defined in the
Help Author's Guide (HCW.HLP). Furthermore, the compiler may interpret an RTF
token differently than it is specified by the standard. For example, the
standard specifies that the \uldb statement indicates a double underline, but
the compiler uses this statement to indicate a hot spot.
Help Macro Syntax
Help macros specify actions that Windows Help takes when it loads help or
displays a topic. A macro consists of a macro name and parameters enclosed in
parentheses.
Macro names specify the action to take, such as creating buttons or inserting
menu items. The names are not sensitive to case, so any combination of
uppercase and lowercase letters may be used.
Macro parameters specify the files, buttons, menus, or topics on which to
carry out the action. The parameters must be enclosed in parentheses and
separated by spaces. Parameters in many macros must also be enclosed in
quotation marks. This is especially true if the parameter contains space
characters. The valid quotation characters are the matching double quotation
marks (" ") and the opening and closing single quotation marks (' '). If a
quotation character is needed as part of a parameter rather than to enclose a
parameter, the parameter should be enclosed in single quotation marks. When
you use single quotation marks in this case, you can omit the backslash escape
character for the double quotation marks, as shown in the following:
'command "string as parameter"'
Macros can be used as parameters in other macros. In most cases, embedded
macros must be enclosed in quotation marks. If the embedded macro also has
quoted parameters, the quotation character that is used must be different than
the quotation characters enclosing the macro. The following example shows the
correct way to use nested quotation marks:
CreateButton("time_btn", "&Time", "ExecProgram('clock', 0)")
Help macros can be combined into macro strings by separating the macros with
semicolons (;). The compiler processes the macro string as a unit and executes
the individual macros sequentially.
____________________________________________________________________________
To contact me, please (Author of this website) E-mail me at:
jep1965@gmail.com
This page last updated July 6 2008