Media Share 9/MEDIASHARE_09.ISO/utility/rtfgen.zip/RTFGEN

Text File | 1992-02-23 | 20KB | 693 lines

\docstart
\title Contents`
\topic contents`
\keyword contents`
\browse general:004`
\b
==========
\b Contents`

[Overview:overview]`
[General Editing Considerations:EditingConsiderations]`
[RTFGEN Defaults:Defaults]`
[Steps for Building a Help File:basicsteps]`
[ASCII Input File Layout:layout]`
[Commands:Commands]`
[References:References]`
[Copyright:Copyright]`
----------

\topic Commands`
\title Commands`
\keyword commands`
\browse general:030`
========
\b Commands`

[Command Syntax:CommandSyntax]`
RTFGEN Commands`
   [Topic Header Commands:TopicHeaderCommands]`
   [Cross Reference Commands:CrossReferences]`
   [Definitions:Definitions]`
   [Bitmap Commands:BitmapCommands]`
   [Block Formatting Commands:BlockFormatting]`
RTF Commands`
   [Font Commands:FontCommands]`
   [Paragraph Commands:ParagraphCommands]`
   [Tabbing Commands:TabbingCommands]`
------

\title Overview`
\topic overview`
\browse general:005`
===========
\b Overview`

Normally, to create a help file with the Windows help compiler,
you must first write a help topic file using a Rich Text Format (RTF)
word processor.  For many, there are two problems here:`

\blockstart \li500\fi-240`
  1. RTF word processors are expensive.`
  2. Learning to use a new word processor is a nuisance and not
     very productive.`
\blockend

RTFGEN solves both these problems by allowing you to use your favorite
ASCII text editor to produce RTF formatted files acceptable to the
help compiler.`
--------------

\title General Editing Considerations`
\topic EditingConsiderations`
\keyword special characters;tabs`
\keyword comments`
\browse general:010`
========
\b General Editing Considerations`

Almost any ASCII editor may be used.  I use Borland's TURBO or
TPW.  It's probably best to turn off options like 'optimal fill'
which can leave invisible and possibly unknown tab characters in the
document.`

The use of tabs is required to obtain column allignment with
proportional fonts.  Either the tab character or the RTF command,
[\\tab:TabbingCommands], may be used with the same effect.
The \\tab has the advantage
that it's visible in your ASCII file.`

RTFGEN and/or the RTF language have special use for the following
characters:`

\blockstart \li1200\tx1200\fi-840`
  {\b\`}    (grave accent) Used to mark end of paragraphs.`
  {\b\[}, {\b\]}    Used to mark jumps and definitions.`
  {\b\{}, {\b\}}    Used to mark areas where font characteristics will change.`
  {\b\\}    Used as a command start character.`
\blockend

When these characters are to be used in the text, they should be
preceded by a '\\'.  Thus, '\\\[' will cause the left bracket to be
inserted in text and '\\\\' will result in a single backslash being
inserted in text.`

( * . . . * ) may be used to insert comments within the text.`
--------

\title RTFGEN Defaults`
\topic Defaults`
\keyword defaults`
\browse general:015`
=======
\b RTFGEN Defaults`

   Helv, 10 point font.`

   Paragraphs are left justified.  The first line is not
   indented.`

   Paragraph indentation is set by indentation of the first
   line of the paragraph.`

   Tabs are spaced every 720 [[twips:twipdef]] (about 6 default
   characters).`

Any of these defaults may be changed globally for the whole
document, or locally at the topic, paragraph, or even character level.`
---------

\title Steps for Building a Help File`
\topic basicsteps`
\keyword steps for building a help file;building a help file`
\browse general:020`
=========
\b Steps for Building a Help File`

The steps required to create a Windows help file using RTFGEN
are:`

\blockstart \li600\fi-240`
     1. Using an ASCII editor, create one or more input text files.
    [See input file layout:layout]`
     2. Use RTFGEN to convert these files to RTF files.`
     3. Create a Help Project File (.HPJ) for input to the help
    compiler.  This file should reference the RTF files.`
     4. Run the help compiler to make the help file.`
\blockend

Steps 3 and 4 are described in the help compiler documentation.
This documentation deals with the first two steps only.`

Once the ASCII files have been written,  RTFGEN is used to
convert them to suitable RTF format.  The file, [[HEADING:headingDef]],
must be present on the default drive.  From the DOS prompt:`

  RTFGEN  \[Infile \[Outfile\]\]`

The optional filenames specify the names of the ASCII input file
and the RTF file to be generated.  If no extensions are given,
.RTF is used by default for the output file.  If the output
filename is missing from the command line, an RTF file will be
created using the same name as the source file.  When neither
filename is specified, names will be requested once execution
starts.`

  RTFGEN MYHELP`

will cause RTFGEN to look for a source file, MYHELP and create an
object file, MYHELP.RTF.`
-----------

\title HEADING File`
\topic headingDef`
\keyword HEADING`
========
The file, HEADING, is copied to the start of each RTF file generated.
Along with some boilerplate RTF commands, it contains the font table
defining fonts by number.`
--------

\title ASCII Input File Layout`
\topic layout`
\keyword layout;ASCII input file layout;input file layout`
\browse general:025`
\li600\brdrl\brdrr\ri600\sb-50\sa-50  (*general paragraph stuff for whole topic*)
==========
\pard\b RTFGEN ASCII Input File Layout`

\brdrt\qc {\fs16 [document header:doc_header]}  `
\b[[\\docstart:docstartDef]]{\fs30  }` (*space of larger font gives more height *)
\qc  {\fs16 [topic header:topicHeader]} `
 ===========[[==:EqualDef]]`
    `
\qc\fs16 [topic text:TopicText]`
    `
 - - - - - - - - - - - [[- -:HyphenDef]]`
  \blockstart \li600`
  . . . . . .`
  \blockend
\qc \fs16 [topic header:TopicHeader]`
 ===========[[==:EqualDef]]`
    `
\qc\fs16 [topic text:TopicText]`
    `
 - - - - - - - - - - - [[- -:HyphenDef]]`
\brdrb\b [[\\docend:DocendDef]]`
------------
\topic TwipDef`
======
TWIP: A 20th of a point.  For our purposes, 1440 twips per inch.
One 10 point character is about 120 twips wide.`
------
\topic EndofParaDef`
======
A grave accent, '{\b\`}', is used to mark paragraph  ends.`
-----
\topic DocstartDef`
=========
The command, \\docstart, marks the end of the document header and the
start of the topics.`
-----------
\topic DocendDef`
========
The command, \\docend, marks the end of the document.`
----------
\topic EqualDef`
\title Start of Topic Text Marker`
\keyword ========`
=========
\b Start of Topic Text Marker`

A row of 5 or more '='s starting in column 1 marks the end of a topic header
and the start of the topic text.`
-------
\topic HyphenDef`
\title End of Topic Marker`
\keyword - - - - - - -;formfeed`
======
\b End of Topic Marker`

A row of 5 or more hyphens starting in column 1 marks the end of a topic.`

An optional formfeed or several blank lines may follow the row of hyphens
to better format your ASCII file.`
--------
\title Document Header`
\topic Doc_Header`
\keyword document header;\\docstart`
============
\b Document Header`

The optional document header may contain commands to overide the
[[RTFGEN defaults:defaults]].  Commands
changing the font, font size, or paragraph first line indent might be
appropriate here.`

The \\docstart command follows the document header to mark the start of
the topics.`

Example:`

\\f0 \\fs24   ( * Times Roman font, 12 pitch for entire help file * )`
\\docstart`
------------
\title Topic Header`
\topic TopicHeader`
\keyword topic header`
===========
\b Topic Header`

The topic header contains commands defining build tags, context
strings, title, keywords, and browse sequence number as appropriate for the
topic.  Topic global formatting commands may also be included.
The topic header section is terminated with a row of 5 or more
'='s.`

   Example:`

   \\title Table of Contents\``
   \\topic contents\``
   \\keyword contents\``
   \\f0 \\fs24   ( * Times Roman font, 12 pitch for this topic * )`
   ============  ( * end of topic header * )`

\b See also : [Topic Header Commands:topicHeaderCommands]`
------------

\title Topic Text`
\topic TopicText`
\keyword topic text;text entry rules;indenting`
==========
\b Topic Text`

Text for the topic is entered here.  Rules for text entry are:`

  Paragraph ends are marked with a grave accent, '\`'`

  Blank lines will appear as blank lines.`

  By default, paragraphs are left justified.  The indenting of
  the paragraph is set by the indenting of the first line of
  the paragraph.  Indenting of lines after the first is
  ignored.`

  Carriage returns and linefeeds within the paragraph are
  ignored as far as the final results are concerned.`

  Commands may be interspersed within the text for special
  effects.  The commands themselves won't appear in the final
  result.`

\b Examples:`
ASCII`
   Here is a typical paragraph.  It will appear in the font`
   and pitch specified in the topic header or document`
   header.  It is left justified and indented by 360 [[twips:twipdef]]`
   because the first line is so indented.  The paragraph`
   is terminated with a grave accent character.\``

Result`
   Here is a typical paragraph.  It will appear in the font
   and pitch specified in the topic header or document
   header.  It is left justified and indented by 360 twips
   because the first line is so indented.  The paragraph
   is terminated with a grave accent character.`

ASCII`
   \\b\\fi480 Here is another paragraph.  It will appear in`
   bold font because of the \\b command.  It will also be`
   be indented by 360 [[twips:twipdef]] and left justified.  The`
   \\fi480 will cause the first line of the paragraph`
   to be indented an additional 480 twips.\``

Result`
   \b\fi480 Here is another paragraph.  It will appear in
   bold font because of the \\b command.  It will also be
   be indented by 360 twips and left justified.  The
   \\fi480 will cause the first line of the paragraph
   to be indented an additional 480 twips.`
-----------

\title Command Syntax`
\topic CommandSyntax`
\keyword syntax;command syntax;commands`
\browse commands:005`
=======
\b Command Syntax`

Commands for RTFGEN and RTF commands passed thru to the help compiler
have a similar syntax.  Commands start with a
backslash followed by a {\ul lowercase} alpha symbol.  Some RTF
commands have a numerical value attached.  Some RTFGEN commands
have an additional parameter string.`

  Examples:`

  \\box`
  \\topic <topic name>`
  \\fs24          RTF command with number`
  \\fi-720        minus sign may be used if appropriate`

When commands are mixed with text, a trailing space may be
required as a delimiter.  The first space following a command is
considered part of the command--{\ul additional spaces are
part of the text}.`
----------

\title Topic Header Commands`
\topic TopicHeaderCommands`
\keyword topic header commands;footnotes;commands`
\browse commands:010`
========
\b Topic Header Commands`

  \\buildtag <parameter string>\``
  \\topic <parameter string>\``
  \\title <parameter string>\``
  \\keyword <parameter string>\``
  \\browse <parameter string>\``

These commands correspond to the *, #, $, K, and + footnotes
described in the help compiler documentation.  Each
topic header will contains one or more of these commands
as appropriate (ordering is unimportant).`

The parameter string should--`

  have format and contents exactly as described in the help compiler
  documentation for the equivalent footnote.`

  be entirely on one line.`

  be terminated by an [[end of paragraph mark:EndofParaDef]].`

More than one \\keyword command may be used if the number of keywords
would exceed the allowable editor line length.`


  Examples:`

  \\topic proc_deleting_text\``
  \\title Deleting Text\``
  \\browse procedures:020\``
  \\keyword delete;clipboard\``
---------

\title Cross Reference Commands`
\topic CrossReferences`
\keyword cross references`
\browse commands:015`
========
\b Cross References`

Cross references may be included in the topic text using the
format:`

  \[<green text>:<context>\]`

where the brackets indicate a cross reference, <green text> will
appear highlighted, and <context> is the topic context string for
the jump destination.`

  Example:`

  To change the color of an existing object, the object is first
  \[selected:selecting\].  Its color may then be changed.\``
------------

\title Definitions`
\topic Definitions`
\keyword definitions`
\browse commands:020`
=========
\b Definitions`

Definitions may also be included in topic text by enclosing them
in {\ul double} brackets:`

  \[\[<green text>:<context>\]\]`

  Example:`

  Each space is equivalent to 120 \[\[twips:twip_def\]\].\``
---------

\title Bitmap Commands`
\topic BitmapCommands`
\keyword bitmaps;commands`
\browse commands:025`
=========
\b Bitmap Commands`

  \\bml <filename>`
  \\bmr <filename>`
  \\bmc <filename>`

These commands are used to insert bitmaps within the topic text.`

  Example:`

ASCII`
  A bitmap may be placed in a sentence \\bmc glass.bmp just like
  any character.\``

Result`
  A bitmap may be placed in a sentence \bmc glass.bmp just like
  any character.`

It's also possible to use a bitmap to cause a jump or bring up a
definition as:`

ASCII`

   \[\[\\bml tryme.bmp:bmpPop\]\]\``

Result`

   [[\bml tryme.bmp:bmpPop]]`
---------

\topic bmpPop`
======
Illustrates a bitmap popup.`
------

\title Block Formatting Commands`
\topic BlockFormatting`
\keyword block formating command;commands;\\blockstart;\\blockend`
\browse commands:030`
=========
\b Block Formatting Commands`

  \\blockstart <commands>\``
  \\blockend`

The blockstart,  blockend commands define a block over which a set
of RTF commands will apply.  These commands are used mainly when
laying out tables where formatting is somewhat complex.  An
example of their use is given in the
[tabbing commands section:TabbingCommands].`

The block commands may be nested to a level of 4.`
--------

\title Font Commands`
\topic FontCommands`
\keyword font commands;commands;font table`
\browse commands:035`
=======
\b Font Commands`

Fonts are refered to by number.  Number vs font is set by the
font table in the [[HEADING:headingDef]] file.  For the HEADING file supplied:`

  0  Times Roman`
  1  Symbol`
  2  Helv (default)`
  3  Courier`

You can add fonts or change the order by editing the HEADING
file.`

\blockstart \li1500\fi-1100\tx1500`
  \\f000    change to font 000`
  \\fs000    set font size in half points`
  \\plain    plain text (as opposed to bold, italic)`
  \\b    bold`
  \\i    italic`
  \\ul    underline`
  \\uldb    double underline`
  \\uld    dotted underline`
  \\strike    strikethru text`
\blockend

The scope of font commands may be document global (placed in
document header), topic global (placed in topic header),
paragraph global (placed at start of paragraph), or character or
word global (scope defined with \{ . . \}).`

Examples:`
ASCII`
  \\b This paragraph will appear in bold text.\``

Result`
  \b This paragraph will appear in bold text.`

ASCII`
  This paragraph is \{\\ul mostly\} in plain text with a \{\\b bold\}
  and an \{\\i italicized\} word.  \{\\f0 Fonts and \\fs30 pitch\} can be
  temporarily changed.\``

Result`
  This paragraph is {\ul mostly} in plain text with a {\b bold}
  and an {\i italicized} word.  {\f0 Fonts and \fs30 pitch} can be
  temporarily changed.`
---------

\title Paragraph Commands`
\topic ParagraphCommands`
\keyword paragraph commands;commands;indenting;justifying;boxed paragraphs`
\browse commands:040`
=========
\b Paragraph Commands`

\blockstart \li1500\fi-1100\tx1500`
  \\par    end of paragraph.  RTFGEN handles this.`
  \\pard    reset to paragraph defaults.  RTFGEN handles this.`
  \\li000    left paragraph indent in [[twips:twipdef]].  RTFGEN handles this.`
  \\fi000    first line indent.  May be negative.`
  \\ri000    right paragraph indent.`
  \\sb000    space below paragraph.`
  \\sa000    space above paragraph.`

  \\ql    left justified (default)`
  \\qc    paragraph is centered`
  \\qr    right justified`

  \\box    paragraph is surrounded by a box`
  \\brdrl    left border`
  \\brdrb    bottom border`
  \\brdrr    right border`
  \\brdrt    top border`
\blockend

The scope of paragraph commands may be document global (placed in
document header), topic global (placed in topic header), or
paragraph global (placed at start of paragraph).`

Examples:`
ASCII`
\\box\\qc This paragraph is surrounded by a box and is centered.\``

Result`
\box\qc This paragraph is surrounded by a box and is centered.`

ASCII`
      \\fi-360 The first line of this paragraph overhangs by
      about 3 characters.  Note that RTFGEN has already
      indented the paragraph 720 [[twips:twipdef]] because of its
      interpretation of
      the 6 character indentation on the first line.\``

Result`
      \fi-360 The first line of this paragraph overhangs by
      about 3 characters.  Note that RTFGEN has already
      indented the paragraph 720 twips because of its
      interpretation of
      the 6 character indentation on the first line.`
----------

\title Tabbing Commands`
\topic TabbingCommands`
\keyword tabs;tabbing commands;tab stops`
\browse commands:045`
==========
\b Tabbing Commands`

In RTFGEN, either the tab character or the RTF command, \\tab, may
be used to produce a tab in the help file.  By default, tabs are
every 720 [[twips:twipdef]] (about 6 characters).  If neat columns are
desired with proportional fonts, tabs are a must.`

\blockstart \li1500\fi-1100\tx1500`
  \\tab    causes tab`
  \\tx0000    defines tab position in [[twips:twipdef]].  May be used
                   multiply and should be used prior to using
           tabs.`
\blockend

The following should be used just prior to the \\tx000 command to
which they are to apply:`

\blockstart \li1500\fi-1100\tx1500`
  \\tqr    tab is right justified`
  \\tqc    tab is centered`
\blockend

The \\blockstart..\\blockend commands may be used to prepare the
format for a table.`

Example:`
ASCII`
\\blockstart \\li1000\\tqr\\tx2700\\tqc\\tx4000\` ( * tab setup * )`
  \\ul Left\\tab Right\\tab Centered\`  ( * underlined table heading * )`
  Data1\\tab 1234\\tab 12345\``
  ABC \\tab 12\\tab 3333444\``
  XYZdef\\tab 45678\\tab 9\``
\\blockend`

Result`
  \blockstart \li1000\tqr\tx2700\tqc\tx4000` (* tab setup *)
  \ul Left\tab Right\tab Centered`  (* underlined table heading *)
  Data1\tab 1234\tab 12345`
  ABC \tab 12\tab 3333444`
  XYZdef\tab 45678\tab 9`
  \blockend
--------

\title References`
\topic References`
\keyword references`
\browse general:035`
=========
\b References`

The following files may be found on CompuServe in several locations.
To locate them, use the IBM File Finder (GO IBMFF).`

\blockstart \li1700\fi-1500\tx1700`
  RTF.TXT    Info on the RTF syntax.  Many more commands
                   are listed than given here.`
  QDHELP.LZH    Another system to produce help files using an
           ASCII editor.`
\blockend
--------

\title Copyright`
\topic Copyright`
\keyword copyright`
\browse general:040`
=========
\b\qc (C) Copyright 1992 by L. David Baldwin.`
\qc All Rights Reserved`

RTFGEN may be copied and distributed freely providing that no fee
is charged and it is not part of a package for which a charge is
made.`

Please report all bugs, suggestions, and problems to Dave
Baldwin, CompuServe ID #76327,53.`

     22 Fox Den Rd., (Summer)`
     Hollis, NH 03049`
     [phone]`

     144 13th St. East,  (Winter)`
     Tierra Verde, FL 33715`
     [phone]`
-------
\docend