Rich Text Format

Rich text format (RTF) is a Microsoft word-processing format supported by several word processors, including Microsoft Word version 5.0 and later and Microsoft Word for Windows. RTF is an intermediate format that allows documents to be transferred between applications without loss of formatting. You can use RTF to simplify the transfer of help files from one format to another. Like QuickHelp files, RTF files can contain formatting attributes and links.

As with the other text formats, each topic in an RTF source file consists of one or more context strings followed by topic text. The Help delimiter (>>) at the beginning of any paragraph marks the beginning of a new Help entry. The text that follows on the same line is defined as a context for the topic. If the next paragraph also begins with the Help delimiter, it also defines a context string for the same topic. You can define any number of contexts for one topic. The topic text comprises all subsequent paragraphs up to the next paragraph that begins with the Help delimiter.

All QuickHelp dot commands, except .context and .length, can be used in RTF files. Each command must appear in a separate paragraph.

There are two ways to create an RTF file. The easiest way is to use a RTF word processor. RTF files usually contain additional information that is not visible to the user; HELPMAKE ignores this extra information.

You can also use an ordinary text editor to insert RTF codes manually. Utility programs exist that convert text files in other formats to RTF format. For more information on RTF, see the your Microsoft Word for Windows documentation.

Using a Word Processor

In an RTF-compatible word processor, enter the text and format it as you want it to appear: bold, underlined, hidden, and italic. You can also format paragraphs by selecting body and first-line indenting. Choose a monospace font and set the margin to the /W value you plan to encode the database with. The only item you need to insert into an RTF file manually is the Help delimiter (>>) followed by the context string that starts each entry. If you use dot commands, place each in its own paragraph.

When you have entered and formatted the text, save it in RTF format. In Microsoft Word version 5.5, for example, choose Save As from the File menu, then select RTF under Format.

You cannot see the RTF formatting codes when you load an RTF file into a compatible word processor. The word processor displays the text with the specified attributes. However, you can view these codes by loading an RTF file into a text editor or word processor.

Manually Inserting RTF Formatting Codes

RTF uses braces ({}) for nesting. Thus, the entire file is enclosed in braces, as is each specially formatted text item.

When you manually insert RTF codes, you must delimit each dot command with the \par code. (An RTF editor or word processor inserts “\par” at the beginning and end of a paragraph.) For example, to use the .popup command, write:

\par.popup\par

HELPMAKE recognizes the subset of RTF codes listed in Table 20.3.

Table 20.3 RTF Formatting Codes

RTF Code Action

\b Bold. The Help reader decides how to display this; often it is intensified text.
\fin Paragraph first-line indent, n twips.*
\i Italic. The application decides how to display this; often it is reverse video.
\lin Paragraph indent from left margin, n twips.*
\line New line (not new paragraph).
\par End of paragraph.
\pard Default paragraph formatting.
\plain Default attributes. On most screens, this is nonblinking normal intensity.
\tab Tab character.
\ul Underline. The application decides how to display this attribute; some adapters that do not support underlining display it as blue text.
\v Hidden text. Hidden text is used for explicit links; it is not displayed.

* A “twip” is 1/20 of a point or 1/1440 of an inch. One space is approximately 180 twips.

Encoding RTF with HELPMAKE

When HELPMAKE compresses an RTF file, it formats the text to the width given by the /W option and ignores the paragraph formats.

When HELPMAKE encodes RTF, any text between an RTF code and invisible text becomes an explicit link. This is illustrated in the following example:

{\b Formatting table}{\v prinf.ex}

The string Formatting table is displayed in bold and is part of an explicit link to printf.ex.

Example

The following example is in RTF format:

{\rtf1

\pard\plain >>Sample

\par >@Sample

\par .topic Sample Help Topic

\par .freeze 3

\par \pard \li8000 {\i }{\b Back}{\v !B}{\i }

\par \pard ----------------------------------------------------

\par

\par \pard \li360 Help can contain text with three attributes:

\par \pard

\par \pard \li360 {\b Attribute} {\b QuickHelp Code}

\par \pard

\par \pard \li360 {\i Italic} \\i

\par \pard \li360 {\b Bold} \\b

\par \pard \li360 {\ul Underline} \\u

\par \pard

\par \pard \li360\ri720 The visual appearance of each attribute

or combination of attributes is determined

by the application that displays the help.

\par \pard

\par \pard \li360 {\b See:}

\par \pard

\par \pard \li360 Coding, Expressions, Grammar, Keywords, Syntax

\par \pard \li360 {\i }{\b Flow Control}{\v @flow}{\i }

\par {\i }{\b Release Notes}{\v $DOC:README.DOC!}{\i }

\par \pard >@flow

\par .topic Sample Help: Flow Control

\par .freeze 3

\par \pard \li8000 {\i }{\b Back}{\v !B}{\i }

\par \pard ----------------------------------------------------

\par

\par \pard \li360 Here's another sample help screen.

\par

\par \pard \li360 This is an explicit link: {\i }{\b Sample}{\v @Sample}{\i }

\par \pard \li360 This is an implicit link: Sample

\par

}