| Back to Contents List |
|
Documentation for the AscToRTF conversion utility |
The latest version of these files is available online at http://www.jafsoft.com/doco/docindex.html
New in version 2.0
From version 2.0 onwards, AscToRTF now has the ability to create RTF files that are suitable for use as source documents when creating WinHelp files (.hlp)
Of course, the current flavour of Microsoft help files is the compiled HTML format (.chm), but many authors still prefer the .hlp format.
Contents of this section
Some background on WinHelp files
Formatting RTF files for use as WinHelp source documents
How to create topicsRunning Microsoft Help Compiler Workshop (HCW)
How to create links to topics
Browse sequences
How to create hyperlinks to URLs
Help project file (.hpj)Tips on how to write text files for AscToRTF
Source file (.rtf)
Contents file (.cnt)
Resource file (.hm)
Creating headingsUsing the pre-processor HELP commands
Avoid "empty topics"
HELP_CHAPTER commandIntegrating the help file with your software application
HELP_SUBJECT command
HELP_TOPIC_ID command
The MAKINGRTFHELP section name
Matching Topic IDsCreating HTML versions of your WinHelp files
Setting the help file name
Create "missing" topics to get a clean compile
WinHelp files can be created using the free Microsoft Help Workshop tool HCW. If you don't already have this installed, you can easily download this from the Microsoft web site.
The HCW file allows you to define help projects, the details of which are saved in a help project file (.hpj). This file contains the details of your project which will include, among other things
If you're making a help file to support a software application, then the project file will also contain
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.
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.
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
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
- [[GOTO how to create topics]]
- [[POPUP how to create topics]]
becomes
- how to create topics (GOTO link)
- how to create topics (POPUP link)
WinHelp allows you to link topics in a "browse sequence" so that by pressing the "<<" and ">>" buttons you can move from one topic to the next and previous logical topics.
This is configured through use of footnotes on the plus sign (+)
AscToRTF adds footnotes so that your entire help file can be browsed as a single sequence.
AscToRTF can convert URLs into working hyperlinks in the RTF it creates. These links will also work inside the WinHelp file created from the RTF source file.
The Help Compiler Workshop (HCW) will probably be installed on your system if you have already installed some programming tools such as visual studio. Otherwise you can download it from
http://download.microsoft.com/download/win95/MSPRESS/1.0/W9X/EN-US/hcwsetup.EXE
or goto http://download.microsoft.com/ and search for "Help Compiler Workshop" It is a free download.
In HCW you will be prompted to open a 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.
Amongst other things, the project file identifies
The main input into the Help Compiler is one or more RTF files. These have to be formatted in a particular way to achieve all the particular effects required of a Help Manual.
When you select a conversion type of "Making Windows Help source file", AscToRTF does all this formatting for you.
See Formatting RTF files for use as WinHelp source documents
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.
This relies on AscToRTF correctly detecting all the headings in your source file. To achieve this see the topic creating headings in the section called Tips on how to write text files for AscToRTF
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
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).
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
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.
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.
See the SECTION command and The MAKINGRTFHELP section name
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 HELP_SUBJECT command HELP_TOPIC_ID command |
Adds new chapter titles to your generated Contents file Adds a new subject title to you generated Contents file Associates a help topic with a named resource from your software application |
| The MAKINGRTFHELP section name | Allows you to add help file-only test to your source document |
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..."
See also the 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.
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
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.
e.g.
$_$_HELP_SECTION "Introduction to WinHelp files"
Introduction
------------
WinHelp files are ...
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.
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
See Avoid "empty topics for a discussion of why you might want to do this.
This section gives a brief overview of how to use AscToRTF to create a WinHelp file that will provide context-sensitive help for your software application.
By default when you press F1 on an application, Windows does the following
- identifies the control that had focus and gets its ID
- locates the help file for this application. By default this will have the same name as the .exe file, but with a .hlp extension
- launches the help file, staring at the topic that matches the ID (if such a topic exists).
See matching topic IDs
See setting the help file name
See Create "missing" topics to get a clean compile
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.
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.
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.
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.
For example:
This document has been converted from text to :-
$_$_SECTION MAKINGHTML
HTML format
$_$_SECTION MAKINGRTF
RTF format
$_$_SECTION MAKINGRTFHELP
WinHelp RTF source file
$_$_SECTION_ALL
...and this text appears in all formats.
 |
Converted from
a single text file by
AscToHTM © 1997-2004 John A Fotheringham |  |