_RTFHELP FOR WINDOWS HELP FILES_
by Joseph Hlavaty

Listing One

* J. Hlavaty, RTFHelp sample file
* defaults for the file go here
  DEFFONT 0
  FONTSIZE 24
*   Justified text, with a 1/2" left and 1/2" right margin (1440 twips/inch)
  LEFTINDENT 720
  RIGHTINDENT 720
* Now begin the first topic
* The TITLE tag introduces a topic (page) of a help file.
  TITLE The first topic is usually the TABLE OF CONTENTS for the help file
*   The following statements select 12 point TmsRmn out of RTFHelp's default
*     font table.  What we'll actually get depends on the available fonts
*     in the session of Windows in which the help file is executing.
*   As noted in the text, measurements for tags like LEFTINDENT are in TWIPs
*      (an abbreviation for twentieths of a point). To convert inches to twips,
*      simply multiple inches by 1440 (72 points in an inch times twenty).
*      Other tags, like FONTSIZE are in 1/2 points so FONTSIZE 72 is 36 point
*      (meaning 1/2") type.  Note that LEFTINDENT (twips) tag arguments are
*      ten times the equivalent FONTSIZE argument
  KEYWORD Table of Contents

* note that if you wish your pop-up topics or links to be each on
*   an individual line, then you must use PARA tags to force the separation.
*   Don't forget the last PARA tag, or the text following these definitions
*   will begin on the same line as the last one
  BROWSESEQ rtfhelp:005
* Add 1\16th" (90 twips) of whitespace after each of the following
*   definitions for readability
  SA 90
  PARA
   PUTPOPUP rtfhbann.c
  XREFID PTR_RTFHBANN_C
  PARA
   PUTPOPUP rtfhcp85.c
  XREFID PTR_RTFHCP85_C
  PARA
   PUTPOPUP rtfhdata.c
  XREFID PTR_RTFHDATA_C
  PARA
   PUTPOPUP rtfhhelp.c
  XREFID PTR_RTFHHELP_C
   PUTPOPUP rtfhmain.c
  XREFID PTR_RTFHMAIN_C
  PARA
   PUTPOPUP rtfhpars.c
  XREFID PTR_RTFHPARS_C
* Without the following PARA, this text would be right next to RTFHHELP.C
*    PUTPOPUP
* Switch to a smaller font
FONTSIZE 16
PARA
   Please select one of the terms above by single-clicking on it with the left
 mouse button to view its definition, or go to a topic below by clicking on it.

PARA
FONTSIZE 24
* The PUTLINK tag tells the user where the link will go
  PUTLINK   Margins and spacing
* The XREFID tag must also be used to tell the help compiler what DEFINELINK
*   to go to
  XREFID LINKTO_MARGINSANDSPACING
  PARA
  PUTLINK   Special Effects
  XREFID LINKTO_SPECIALEFFECTS
  PARA
  PUTLINK   Bitmaps and graphics
  XREFID LINKTO_BITMAPSANDGRAPHICS
  PARA
  PUTLINK   WinHelp Terms
  XREFID LINKTO_WINHELPTERMS
  PARA
  PUTLINK   RTFHelp Terms
  XREFID LINKTO_RTFHELPTERMS

* Now explicitly start a new topic (PAGE) with the PAGE tag, which has no
*   arguments.  The PAGE tag ends the current page.
*   The help compiler will not like an extra \page tag on the first
*   page.  It will assume that the blank page is the table of contents
*   if you do not have a CONTENTS tag in your HPJ file
  PAGE
  TITLE Text formatting in a help file
  KEYWORD text formatting; left indent; right indent; hanging indent; 
                                                     default paragraph settings
  BROWSESEQ rtfhelp:010
  DEFINELINK LINKTO_MARGINSANDSPACING
* now reset the spacing after each PARA to the default
* 90= 1/16th inch glue following each PARA
  SA 90
  JUST
  LEFTINDENT 0
  RIGHTINDENT 2880
This is text with a two inch right margin. This is just done for some contrast 
with the paragraph below.

  PARA
* Produces a "hanging" indent for the first line only.  Note negative offset
*  The actual value used for the first line's offset is LEFTINDENT+FIRSTINDENT
  FIRSTINDENT -720
  LEFTINDENT 720
  RIGHTINDENT 720

this is text with a "hanging" indent, as you'll see the rest (lines after
 the first) of this paragraph is indented normally.
PARA
  SA 720
* Reset the firstindent/leftindent values to the default (720 ? )
  FIRSTINDENT
  LEFTINDENT
This paragraph has 1\2" "glue" (empty space) following.  Notice that
 the indent of the first and second lines are identical.
  PARA
  SA 0
This paragraph has no glue following
  PARA
  PARD
  This is a paragraph using default paragraph settings
  PARA

  PAGE
  TITLE Text formatting in a help file, continued
  KEYWORD text formatting; italic; smallcaps; bold
  BROWSESEQ rtfhelp:015
  DEFINELINK LINKTO_SPECIALEFFECTS
* now reset the spacing after each PARA to the default
  SA
  LEFTINDENT 720
  RIGHTINDENT 720
ITALIC This is italic text with half-inch left and right margins. Should 
ITALIC %also appear as Justified Text if JUST tag is supported by the HC.
* JUST
PARA
  LEFTINDENT 2880
  RIGHTINDENT 0
* note that RTFHelp considers the end of a line to end certain tags.  This is
*   intentional so that certain formatting properties (bold, italic and so
*   forth do not span lines)
JUST
LEFTINDENT 1440
SMALLCAPS This is text with a one inch left margin in small caps.
*   Note the use of the hard space character (%) to force a space.
SMALLCAPS %flexibility that you can put in your help file.  
  PARA
* Reset leftindent to default
LEFTINDENT
BOLD  This text is displayed in bold type. 
BOLD  %text (similar to underlining). Underlining is not supported by
BOLD  %RTFHelp as the HC gives a specific meaning to the RTF underline
BOLD  %command in help files.
PARA
  PAGE
  TITLE Bitmaps and graphics
  KEYWORD bitmap; graphics
  BROWSESEQ rtfhelp:020
  DEFINELINK LINKTO_BITMAPSANDGRAPHICS
*
* You will need to copy pyramid.bmp from your \windows directory to the
*   directory containing your HDC file for the bitmap to be found
*
  BMC pyramid.bmp
  This is a sample bitmap caption

SA 180
* begin a new paragraph and draw a box around it
PARA
  BOX
  DEFTAB 2880
  TAB
1
  TAB
This is one
  LINE
  TAB
2
  TAB
This is two
PARA
PARD

 PAGE
  TITLE WinHelp Terminology
  BROWSESEQ rtfhelp:025
* note that a ; separates multiple keywords (as multiword keywords are 
* permitted) you can also have multiple KEYWORDs in the same topic
  KEYWORD     WinHelp terminology
  KEYWORD     topic file; topic; title; link; pop-up topic
  DEFINELINK LINKTO_WINHELPTERMS
  SA 90
The document containing the Rich Text Format (hereafter abbreviated RTF) text
 input to the help compiler will be called the TOPIC FILE.  One or more topic
 files are used to generate a help file (a binary file with the .HLP
 extension). Every topic file is made up of a series of "pages" or "screens"
 of related information known as TOPICS.
PARA
Each topic can contain a variety of constructs, such as titles,
 links and pop-up topics.  A TITLE is not visible in the topic itself, but is
 used in the Search and other WinHelp dialog boxes to allow the user to
 distinguish this topic from others in the help file.
PARA
 A LINK hooks one topic
 to another so that when the user clicks on the link's hot spot, the topic
 that the link references will become the current topic displayed to the user.
PARA
Finally, a POP-UP TOPIC when clicked on will create a child window on top of
 the help  window which contains information for the user.  These pop-up topics
 are often used for definitions of terms.

 PAGE
  TITLE RTF Terminology
  BROWSESEQ rtfhelp:030
 * note that a ; separates multiple keywords (as multiword keywords are 
 * permitted) you can also have multiple KEYWORDs in the same topic
  KEYWORD     RTFHelp terminology
  KEYWORD     control words; control symbols; groups
  DEFINELINK LINKTO_RTFHELPTERMS
The topic file is a collection of RTF tags and raw text.  These tags
 are known as CONTROL WORDS and all contain a backslash as their first
 character and consist of entirely lower case letters (RTF is case-sensitive).
 One such tag is \\par to end a paragraph.
PARA
There is a small set of non-alphabetic control words known as CONTROL
 SYMBOLS, such as \\~ which signifies a hard (non-breaking) space.
PARA
Control words and control symbols together with the text making up the
 topic file are collected in GROUPS.  A group begins with an open curly brace
 and continues until an equally-nested closing curly brace.  Any formatting
 properties that are found within a group apply to all and only elements of
 that group. Some groups can even inherit specific formatting properties from
 the group preceding them.  For details on exactly when and how this occurs,
 refer to the RTF specification listed in the reference section.
PARA
RTFHelp uses the tagged file passed in by the user to generate an
 RTF topic file containing a mixture of control words, control symbols and
 groups.

  PAGE
* Here are the definitions for our (what's the term) definitions

* A few warnings are in order.  The DEFINEPOPUP generates a new page, so I
*   generally put my DEFINEPOPUPs at the end of my help file.
* Note that the context ID (such as PTR_RTFHMAIN_C below) cannot have any
*   text following it.  This is because RTF assumes that any text following
*   the context ID is actually a part of the context ID and includes it in
*   the #{\footnote} tag that it builds.  The help compiler will complain
*   about this mixture of text and context ID. Because of this, there is a
*   a restriction that text that is the definition of a DEFINEPOPUP must begin
*   on the line following the DEFINEPOPUP tag and ID
  DEFINEPOPUP PTR_RTFHMAIN_C
    RTFHMain.c is the main module for RTFHelp. It reads the tagged input file, 
 and writes the formatted RTF text to the output file.
  DEFINEPOPUP PTR_RTFHCP85_C
    RTFHCP85.c is the module containing the translation table from CP850 
 (the so-called Latin 1 code page). This code page roughly corresponds to those
 characters needed to display Western European languages. It converts to the 
 Windows default (ANSI) code page.
  DEFINEPOPUP PTR_RTFHDATA_C
    RTFHData.c is the module containing global data.
  DEFINEPOPUP PTR_RTFHBANN_C
    RTFHBann.c is the module containing the banner (logo) information
 that is displayed when using the RTFHelp compiler.
  DEFINEPOPUP PTR_RTFHHELP_C
    RTFHHelp is the module that processes RTFHelp's command line arguments.
  Named because it also displays help for the user.
  DEFINEPOPUP PTR_RTFHPARS_C
    RTFHHelp is the module that contains the RTFHelp parser.


Example 1:

;   J. Hlavaty, 1994
[OPTIONS]
TITLE = RTFHelp Sample Help File
COPYRIGHT = Help file content copyright (C) J. Hlavaty, 1994

[FILES]
sample.rtf

[BITMAPS]
pyramid.bmp

[CONFIG]
BrowseButtons()