If you're making a help file to support a software application, then the
project file will also contain

The name of the resource file (.hm) which identifies the
topic IDs that may be requested from inside the software.

It is not the purpose of this document to give a full introduction to
HCW, just to give a flavour of how it works, and how it can be used
with AscToRTF.

Essentially HCW acts as a compiler, that merges these files together so
that you end up with a Help file (.hlp) and a contents file (.cnt) that
go together, and which can then be distributed as a standalone Windows
Help file.

In order for HCW to know how to divide the help into topics, and how
to index and cross-reference these topics, the source RTF file has to
have special formatting applied and has to follow certain rules. For
more details see Formatting RTF files for use as WinHelp source documents

AscToRTF can turn your text file into an RTF file that obeys these rules,
and furthermore can create a good starting Help Project file and contents
list for you. With it's pre-processor, you can add links between topics
and even produce help files that can be invoked from inside application
software. Although the help files produced may be basic (they can't contain
images for example), there will be no easier way to turn your text document
into fully featured WinHelp files.

Formatting RTF files for use as WinHelp source documents

This section outlines just some of the special formatting rules AscToRTF
will apply when you elect to convert your text into a WinHelp source
document.

How to create topics

Each topic in the RTF file must begin on a new page. AscToRTF makes
each section heading in your source document a heading on a new page.

For long topics you can stop the title scrolling as you scroll down the
page by applying the "keep with next" attribute to the heading lines.
Because of this, you should avoid using "keep with next" anywhere else
as it confuses the compiler. For this reason AscToRTF doesn't apply this
property to tables and diagrams in the way that it does in normal RTF
production.

To allow linking to a topic, each topic is given a topic ID. The topic
ID is identified by adding a footnote to the heading on the hash character
(#). The text in this footnote is the topic ID, which is best kept as a
single string without spaces in it.

To allow a topic to appear in the Help index, you need to add a second
footnote on the dollar character ($). The text in this footnote should be
a single line description for the index.

To allow a topic to be located by keywords, you need to add a third
footnote on the character 'K'. The text in this footnote should list the
keywords for this topic.

AscToRTF will create all these footnotes for you. It will invent an
ID for you, or - if you supply a HELP_TOPIC_ID pre-processor command, use
that instead. See the HELP_TOPIC_ID command

How to create links to topics

Links to topic are done as follows

The Display text for the link is underlined

this is immediately followed (i.e. no white space) by the topic
ID, which must be placed in hidden text.

For the linked topic to appear in a popup box, use a single underline.
For the linked topic to fill the main window, use a double underline.

For reasons not immediately clear, topics with a heading level of 1
can't be invoked in popup windows.

Manually editing such strings is tiresome beyond belief. Happily the
AscToRTF pre-processor makes this much easier by providing the GOTO and
POPUP tags, which are used to generate full and popup links as follows

Help project file (.hpj)

This file identifies the RTF file(s) to be converted, the Help file title,
resources etc. You can edit the settings using HCW's options, and it is
recommended that you study HCW's own help file for more details on this.

AscToRTF can create a project file for you, with some of these details
filled in. It is recommended you do this the first time you convert
the text file to RTF, but be aware that if you repeat this any existing
.hpj file will be overwritten, and any changes made since the last time
the file was created will be lost.

Contents file (.cnt)

WinHelp files can have their own contents files. By convention these have
the same name as the .hlp file, but with a .cnt extension. When you
convert your text file into a WinHelp source file and elect for AscToRTF
to create a project file, AscToRTF will also create a .cnt file for you
with all the chapter and section headings listed in it.

Resource file (.hm)

Software developers can use AscToRTF to create context-sensitive help for
their applications. This allows users to press F1 anywhere in the program
and be taken to the corresponding topic in the Help file. Indeed exactly
this approach has been used in the AscToRTF help file itself.

To achieve this it is necessary for the Help Compiler to be aware of the
IDs allocated to key controls within the application, and for topics in the
RTF file to be associated with a named control.

The first of these steps is achieved by telling the compiler where the
resource file from your software project is. This is usually a .hm file
created automatically by your software development tool each time you build
your application.

If you tell AscToRTF where this file is located, then when it creates the
Help project file, it will add an entry identifying this file. Alternatively
you can add it manually to the project file yourself using HCW.

To link particular topics to named controls within your software you need to
add HELP_TOPIC_ID commands to your text file just before the heading of
the topic. See the HELP_TOPIC_ID command

Tips on how to write text files for AscToRTF

AscToRTF should be capable of converting files into good looking WinHelp
files just as well as it converts text files into good-looking RTF. However
in WinHelp soured files each new topic should begin on a new page, and
ideally has a topic heading at the top of that page.

To that end AscToRTF treats each "heading" as the start of a new topic.
Thus each "heading" gets a new page, special codes and an entry in any
generated contents file (.cnt).

Creating headings

For that reason it is important that your document has clearly marked
headings that can be unambiguously understood. There are two main ways
to do this

Use numbered headings. If your document uses a clear numbering
system such as 1, 1.1, 1.2, 2, 2.1 etc, this will normally work
well. However AscToRTF can occasionally get confused, e.g. by
a numbered list at the same indentation as the expected headings,
so care has to be taken to eliminate any such ambiguities

Use underlined headings. AscToRTF will recognize any line that
is "underlined" as being a heading. That is, if the following
line is all "underline" characters ("*","=","-",) and of the same
length as the previous line, then this is an underlined heading.

In my experience using underlined headings works best. The possibilities
for error are less, and you don't need to renumber sections if you start
to move things around. For more details on how AscToRTF interprets
underlined headings see Expect underlined headings

This document has been created in exactly this way. If you locate the file
AscToRTF.txt you'll see exactly how this file was created.

Avoid "empty topics"

In a structured document, it may happen that you have a title sequence
as follows

MAJOR TITLE
***********
Section Title
=============
First topic
-----------
The first text only starts here

While that works okay as a document, when creating a WinHelp source file,
each of these headings becomes a Help topic, and in the above example the
first two would be "empty" topics.

To get round this, you can add text to your document that will only get included
when making the RTF help file by using the SECTION command together with the
reserved section name MAKINGRTFHELP. For example

MAJOR TITLE
***********
$_$_SECTION MAKINGRTFHELP
This chapter contains the following sections:-
[[goto section title]]
$_$_SECTION_ALL
Section Title
=============
$_$_SECTION MAKINGRTFHELP
This Section contains the following topics:-
[[goto first topic]]
$_$_SECTION ALL
First topic
-----------
The first text only starts here

When this is converted to normal RTF, the output looks like the original,
but when converted to WinHelp RTF you get three topics, with the first
two containing links to the next topic, allowing the user to navigate
properly to the first topic.

Using the pre-processor HELP commands

Although you can use AscToRTF to turn your text files into WinHelp
files without further editing, if you want to exercise a bit more
control over the results, or if you want to create context sensitive
help for your software applications, then you will want to add the
following commands to your source file.

HELP_CHAPTER command

The HELP_CHAPTER command creates a new "chapter" in the generated contents
file. A Chapter appears as a book that you can click on to go down
a level, but isn't a topic you can read in it's own right.

The syntax is

$_$_HELP_CHAPTER <level>,"Chapter title"

Where <level> is 1,2,3... according to how many levels deep the chapter
should be in the contents list, and "Chapter title" is the title to appear
in the contents file.

You should place the HELP_CHAPTER command just before the heading that
starts the new chapter in the source document. If you want this new section
to also be a topic in its own right, you will need to add a HELP_SUBJECT
command as well.

For example

$_$_HELP_CHAPTER 1,"Using AscToRTF to make Help files"
$_$_HELP_SUBJECT "Overview of creating help files"
Creating WinHelp files
**********************
This is my topic text....

This will create a help chapter called "Using AscToRTF to make Help files"
in the contents list. If you click on that, the first topic will be
called "Overview of creating help files", and if you click on that, you
will be taken to the topic headed "Creating WinHelp files"
which starts "This is my topic..."

HELP_SUBJECT command

The HELP_SUBJECT command creates a new "subject" in the current chapter
of the generated contents file. This will appear as a small text icon,
in the contents list, and if you click on this you will be taken into
the matching topic in the help file.

The syntax is

$_$_HELP_SUBJECT "Subject text"

The default behaviour of AscToRTF is to treat each new section as a new
subject, so by default each new heading creates a new topic in the current
chapter of the contents file. As such a HELP_SUBJECT command is not required
for every new heading. However there are two situations in which the
HELP_SUBJECT is required:-

You should place the HELP_SUBJECT command just before the heading that
starts the new topic in the source document.

Adding a topic after a change in heading level

Whenever the next heading is at a different level to the
preceding one, a new Help "chapter" is created. A new "subject"
is not created by default, and so you need to explicitly add
a HELP_SUBJECT command there if you want the new level heading
to be a selectable topic. See the example given in the
discussion of the HELP_CHAPTER command

Changing the text in the contents file

By default the text shown in the contents is that of the heading title
itself. However this isn't always useful. For example the first
topic in a new section may be called just "Introduction". In a large
document that is fine, but in a Help File you soon end up with
a dozen "Introduction" sections in the index, and this is unhelpful.

In this case you can add a HELP_SECTION command to make the entry in
the Help file index more useful.

HELP_TOPIC_ID command

The HELP_TOPIC_ID identifies the ID that should be allocated to
a given topic. By default each topic will be allocated a unique
ID derived from the heading text.

The syntax is

$_$_HELP_TOPIC_ID <ID_NAME>

Where <ID_NAME> is a unique name that shouldn't contain any
spaces or punctuation characters. The HELP_TOPIC_COMMAND should
be placed just after the heading of the topic it relates to (see
example below)

Normally you won't need to add the HELP_TOPIC_ID command, as the
software will generate an ID and keep track of this when creating any
links to this topic.

However if you are trying to create a context-sensitive help file
for your software application you need to make the topic IDs match the
resource names in your Resource file (.hm).

For example if your .hm file contains a line like

HIDD_SETTINGS_DOCO 0x200B3

For a dialogue used to access the documentation, then your source
file would look like this :-

Documentation settings
......................
$_$_HELP_TOPIC_ID HIDD_SETTINGS_DOCO
These options allow you to specify the location of the program's

If this is done, and the .hm file is added to your help project file (.hpj)
then pressing F1 on the documentation dialogue will launch the help
file at the "Documentation Settings" topic.

The MAKINGRTFHELP section name

If you want to add text that gets included in the WinHelp RTF file,
but not in a normal RTF file, then you can use the SCETION command
with the reserved section name MAKINGRTFHELP.

For example:-

This text will appear in all RTF files
$_$_SECTION MAKINGRTFHELP
(but this text will only appear in the Help RTF file)
$_$_SECTION ALL
This text will also appear in all RTF files

Matching Topic IDs

The IDs used by your application are normally listed in a resource file (.hm)
generated by your software IDE. You need to add this to your help project file (.hpj),
or tell AscToRTF to add it for you when it generates the project file.

Inside your source text file you then need to add a HELP_TOPIC_ID command
to each topic to link it to the control names. Typically you will link
Dialog screens to major topics within your help file.

Setting the help file name

By default Windows expects your help file to have the same name as your application.
The easiest way to achieve this is to call your text file application.txt, so that
when it is converted it becomes application.rtf, and creates an application.hpj that
in turn will make an application.hlp.

You can make these files named whatever you want by editing the
project file,
but it's easier to go with the flow.

Create "missing" topics to get a clean compile

The Help Compiler Workshop will report as "missing" any ID in the resource
file for which it doesn't find a matching topic. To get round this I
recommend adding a HELP_TOPIC_ID command for each unused ID at
the top of the file. That way the compiler won't complain, and any dialogue
without a help topic will open up at the first topic in the help file.

Creating HTML versions of your WinHelp files

As well as being able to make normal RTF and WinHelp files from the
same source file with AscToRTF, you could also use AscToHTM to
convert the same source file into HTML. Users who purchase AscToRTF
can get a discount on AscToHTM (and vice versa). Details will
be provided when you register your first product.

If you want to have different text in the three output formats
you can use the SECTION command with the reserved section
names MAKINGRTF, MAKINGRTFHELP and MAKINGHTML.