home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #30 / NN_1992_30.iso / spool / comp / os / mswindo / programm / misc / 4367 < prev    next >
Encoding:
Text File  |  1992-12-21  |  4.8 KB  |  137 lines
  1. Newsgroups: comp.os.ms-windows.programmer.misc
  2. Path: sparky!uunet!elroy.jpl.nasa.gov!usc!cs.utexas.edu!torn!nott!emr1!jagrant
  3. From: jagrant@emr1.emr.ca (John Grant)
  4. Subject: i'm stupid and can't create an RTF file!
  5. Message-ID: <1992Dec19.205009.850@emr1.emr.ca>
  6. Organization: Energy, Mines, and Resources, Ottawa
  7. Date: Sat, 19 Dec 1992 20:50:09 GMT
  8. Lines: 127
  9.  
  10. I'm trying to understand how to create help files for my application
  11. and I am getting overwhelmed by the complexity.  As far as I am
  12. concerned, the use of RTF files is the most awkward format to 
  13. read/write/maintain that they could have possibly used.
  14.  
  15. I have looked at WFWHLP, XANTIPPE and various other things including
  16. suggestions to use Perl, awk, etc etc etc.  Someone sent me a sample
  17. RTF file generated by a machine which is so full of crap that I can't
  18. understand it (sorry Bill).  I am still hopelessly confused and
  19. frustrated.  I'm a programmer - documentation and word processing
  20. is somewhat foreign to me.
  21.  
  22. Here is what I have
  23.   1. various text editors
  24.   2. WordPerfect 5.1 (DOS)
  25.   3. BC++ 3.1
  26.   4. Windows 3.1
  27.  
  28. Here is what I have read:
  29.   1. Borland's on-line help for creating help files
  30.   2. Borland's documentation on creating help files
  31.   3. MicroSoft's RTF specification
  32.  
  33. Here is what I understand:
  34.   1. {\rtf\ansi
  35.  
  36. What I Don't Need
  37.   1. help on maintaining a complete help subsystem 
  38.      (Xantippe,Perl,awk,various shareware/freeware etc etc)
  39.   2. help on using Word (I don't have it)
  40.   3. help on bitmaps        \
  41.   4. help on macros          \
  42.   5. help on fonts           >  maybe later
  43.   6. help on colours          /
  44.   7. help on browse sequences   /
  45.   8. help on context-sensitive help (F1)
  46.  
  47. What I Need
  48.   A sample RTF file that has no font table, no colour table,
  49.   no style table - none of that crap - default everything!
  50.   that demonstrates:
  51.      1. a couple of help topics
  52.      2. a couple of jumps to other topics
  53.      3. a couple of glossary items
  54.      4. use of keywords for help's 'search button'
  55.      5. use of #define in program AND help so I only have to
  56.         define things once (NOT context-sensitive help!)
  57.  
  58. In particular, I have the following questions:
  59.   1. I just want simple stuff, default everything - just text.  
  60.      Am I a fool to want to create an RTF file with a plain-text 
  61.      editor?  I'll be damned if I am going to go out and spend
  62.      $500 on MS Word for Windows!
  63.  
  64.   2. all of the examples I see don't seem to know about CR/LF - they
  65.      just go on forever without line breaks and/or whitespace.  They
  66.      are impossible to read.  It is the most unstructured pile of
  67.      trash I have ever seen and having lots of embedded {} doesn't
  68.      make it any easier.  I want to use lots of white space in the
  69.      RTF file.  Can I do this?
  70.         {\rtf\ansi
  71.  
  72.         {@!&^%&^%^&@#$%^&Topic 1
  73.           blah... blah... blah...
  74.         }
  75.  
  76.         {^%$%^$#%^$#^%$#Topic 2
  77.           blah blah blah
  78.         }
  79.  
  80.         {*&^%^&$%^$Topic 3
  81.           blah blah blah
  82.         }
  83.  
  84.         }       <------is this the thing that finally closes {\rtf\ansi?
  85.  
  86.   3. In the on-line help "Creating Topic Files" on the second page
  87.      under "Defining Individual Topics", I see $(DOLLAR_BRACE) etc
  88.      What the heck is that all about?  Do I need to say that?  What
  89.      does it mean?  Stupid...
  90.  
  91.   3. Is there any way to put comments in an RTF file (so I can put blank
  92.      lines, white space etc in it?  There should be something like:
  93.         {!@#$%^&*...
  94.               blah blah blah
  95.         }
  96.         !
  97.         !
  98.         ! this is the topic that shows up when ....
  99.         !
  100.         !@#!#@$&^*&^&
  101.         {
  102.                 ...
  103.         }
  104.  
  105.   4. I thought about just creating a help document in WordPerfect,
  106.      formatting it as if I was going to print it out as a manual,
  107.      and then saving it as a text file and then editing the text
  108.      file to insert all of the rtf formatting garbage.  But then
  109.      that will be difficult to maintain, since I will have to do
  110.      it all over again when I rewrite the main WP document.
  111.  
  112.   5. What will the help compiler do when it finds blank lines and
  113.      line breaks in the RTF file - does it ignore them entirely
  114.      until it sees \... directives for paragraphs and line breaks?
  115.      In other words, do the following appear the same after compiling
  116.      with HC to make a *.HLP file:
  117.     This is a paragraph of text to describe how to use
  118.     various stuff in my fancy program.
  119.      and:
  120.     This is a paragraph
  121.             of text to describe
  122.     how
  123.     to
  124.     use various stuff in my fancy program.
  125.  
  126. As you can tell I'm frustrated, dazed and confused.  I can't wait
  127. to get this documentation stuff over and done with so I can get back
  128. to real programming in a real language that has logical structured
  129. syntax and real diagnostics.  And yes, I can still smile :) (barely)
  130.  
  131. Thanks in advance.
  132.  
  133. -- 
  134. John A. Grant                        jagrant@emr1.emr.ca
  135. Airborne Geophysics
  136. Geological Survey of Canada, Ottawa
  137.