🚀 go-pugleaf

I'm trying to understand how to create help files for my application
and I am getting overwhelmed by the complexity.  As far as I am
concerned, the use of RTF files is the most awkward format to 
read/write/maintain that they could have possibly used.

I have looked at WFWHLP, XANTIPPE and various other things including
suggestions to use Perl, awk, etc etc etc.  Someone sent me a sample
RTF file generated by a machine which is so full of crap that I can't
understand it (sorry Bill).  I am still hopelessly confused and
frustrated.  I'm a programmer - documentation and word processing
is somewhat foreign to me.

Here is what I have
  1. various text editors
  2. WordPerfect 5.1 (DOS)
  3. BC++ 3.1
  4. Windows 3.1

Here is what I have read:
  1. Borland's on-line help for creating help files
  2. Borland's documentation on creating help files
  3. MicroSoft's RTF specification

Here is what I understand:
  1. {\rtf\ansi

What I Don't Need
  1. help on maintaining a complete help subsystem 
     (Xantippe,Perl,awk,various shareware/freeware etc etc)
  2. help on using Word (I don't have it)
  3. help on bitmaps		\
  4. help on macros		  \
  5. help on fonts		   >  maybe later
  6. help on colours		  /
  7. help on browse sequences   /
  8. help on context-sensitive help (F1)

What I Need
  A sample RTF file that has no font table, no colour table,
  no style table - none of that crap - default everything!
  that demonstrates:
     1. a couple of help topics
     2. a couple of jumps to other topics
     3. a couple of glossary items
     4. use of keywords for help's 'search button'
     5. use of #define in program AND help so I only have to
        define things once (NOT context-sensitive help!)

In particular, I have the following questions:
  1. I just want simple stuff, default everything - just text.  
     Am I a fool to want to create an RTF file with a plain-text 
     editor?  I'll be damned if I am going to go out and spend
     $500 on MS Word for Windows!

  2. all of the examples I see don't seem to know about CR/LF - they
     just go on forever without line breaks and/or whitespace.  They
     are impossible to read.  It is the most unstructured pile of
     trash I have ever seen and having lots of embedded {} doesn't
     make it any easier.  I want to use lots of white space in the
     RTF file.  Can I do this?
        {\rtf\ansi

        {@!&^%&^%^&@#$%^&Topic 1
          blah... blah... blah...
        }

        {^%$%^$#%^$#^%$#Topic 2
          blah blah blah
        }

        {*&^%^&$%^$Topic 3
          blah blah blah
        }

        }       <------is this the thing that finally closes {\rtf\ansi?

  3. In the on-line help "Creating Topic Files" on the second page
     under "Defining Individual Topics", I see $(DOLLAR_BRACE) etc
     What the heck is that all about?  Do I need to say that?  What
     does it mean?  Stupid...

  3. Is there any way to put comments in an RTF file (so I can put blank
     lines, white space etc in it?  There should be something like:
        {!@#$%^&*...
              blah blah blah
        }
        !
        !
        ! this is the topic that shows up when ....
        !
        !@#!#@$&^*&^&
        {
                ...
        }

  4. I thought about just creating a help document in WordPerfect,
     formatting it as if I was going to print it out as a manual,
     and then saving it as a text file and then editing the text
     file to insert all of the rtf formatting garbage.  But then
     that will be difficult to maintain, since I will have to do
     it all over again when I rewrite the main WP document.

  5. What will the help compiler do when it finds blank lines and
     line breaks in the RTF file - does it ignore them entirely
     until it sees \... directives for paragraphs and line breaks?
     In other words, do the following appear the same after compiling
     with HC to make a *.HLP file:
	This is a paragraph of text to describe how to use
	various stuff in my fancy program.
     and:
	This is a paragraph
			of text to describe
	how
	to
	use various stuff in my fancy program.

As you can tell I'm frustrated, dazed and confused.  I can't wait
to get this documentation stuff over and done with so I can get back
to real programming in a real language that has logical structured
syntax and real diagnostics.  And yes, I can still smile :) (barely)

Thanks in advance.

-- 
John A. Grant						jagrant@emr1.emr.ca
Airborne Geophysics
Geological Survey of Canada, Ottawa