home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / rtfipf.zip / rtf2ipf.ipf < prev    next >
Text File  |  1994-05-19  |  12KB  |  331 lines
  1. :userdoc.
  2. .*--------------------------------------------------
  3. .*
  4. .* This IPF file was created with Rtf2Ipf v1.0
  5. .*
  6. .*--------------------------------------------------
  7. :title.RTF2IPF Reference
  8. :h1.RTF2IPF Overview
  9. :p.
  10. :font facename=default.This section describes some background information
  11. that may be useful when determining if RTF2IPF is the right utility for
  12. you&per.
  13. :p.
  14. :h2.Purpose of RTF2IPF
  15. :p.
  16. :font facename=default.This utility has been created as the result of my
  17. desire to maintain both printed and on-line documentation for an internally
  18. developed utility at work from a single document&per.  The general goal
  19. of the RTF2IPF&per.EXE program is to take a word processing document saved
  20. as Rich Text Format and re-tag the file with the IPFC compiler tags to
  21. allow the creation of an OS/2 &per.INF file&per.  RTF2IPF is currently
  22. a command line DOS program (sorry but I run DOS/Windows at home where this
  23. was developed) that should be able to integrate well to a development make
  24. file&per.  
  25. :p.
  26. :font facename=default.Although this utility is being distributed as 'Freeware'
  27. I would like to know what you think of it&per.  After trying it please
  28. send me a note to my CIS ID (74101,413) and let me know what you think&per.
  29.  I hope my efforts will be useful for you too&per.
  30. :p.
  31. :h2.What you need to use RTF2IPF
  32. :p.
  33. :font facename=default.All you need to use RTF2IPF is a word processor
  34. capable of saving its document (styles included) in Rich Text Format (RTF)&per.
  35.  All of my testing has been with Ami Pro v2&per.0 for Windows and Ami Pro
  36. v3&per.0 for OS/2&per.  The document you are receiving was created using
  37. Ami Pro v2&per.0 for Windows&per.  Any word processor that can save it's
  38. documents in RTF format should work&per.  If you use a different word processor
  39. and develop a style sheet that you find useful please send it to me (see
  40. the section Obtaining support for how to reach me) and I will include it
  41. in the next version to be uploaded&per.  To compile your on-line document
  42. you will need the OS/2 IPFC help compiler&per.
  43. :p.
  44. :h2.Disclaimers
  45. :p.
  46. :font facename=default.RTF2IPF is really still a work in process&per. 
  47. As you read through here you will see several places where I mention that
  48. a feature is planned or where I will even solicit your ideas about how
  49. a feature should be implemented&per.  As a result of this utility still
  50. evolving, the current version uploaded here still has some debug code compiled
  51. in&per.  As such it is possible that you may run into an assertion or other
  52. bugs&per.  Although I believe everything to be correct I cannot guarantee
  53. it&per.  If you do have a problem or a suggestion, please contact me and
  54. I will see what I can do to fix it&per.
  55. :p.
  56. :h1.Creating The Documentation in your Word Processor
  57. :p.
  58. :font facename=default.This section describes how to prepare you documentation
  59. in your favorite word processor&per.
  60. :p.
  61. :h2.Styles
  62. :p.
  63. :font facename=default.RTF2IPF is dependent upon your word processor correctly
  64. identifying style information in the RTF file when you save your document&per.
  65.  The styles are used to identify how the text in your document should be
  66. tagged for the IPFC compiler&per.  The most important use of styles is
  67. to identify which 'paragraphs' in your document are intended to be used
  68. as headings in the &per.INF file&per.  Since the IPFC compiler requires
  69. that you make an orderly progression through the heading levels it is imperative
  70. that you are very diligent in setting up a style sheet that mimics the
  71. progression of styles that the IPFC compiler will accept&per.  You must
  72. always keep in mind how the styles will affect your on-line document&per.
  73. :p.
  74. :font facename=default.For example, this document was created using the
  75. Ami Pro style sheet supplied with RTF2IPF&per.  Some of the styles present
  76. in the document and their uses are as follows&colon.
  77. :p.
  78. :font facename=default.:hp2.Heading 1
  79. :p.
  80. :ehp2.:font facename=default.The top level headings in the document&per.
  81.  The 'paragraph' Creating The Documentation in your Word Processor is a
  82. Heading 1 style&per.  That style always gets tagged with the IPFC tags
  83. '&colon.h1&per.'
  84. :p.
  85. :font facename=default.:hp2.Heading 2
  86. :p.
  87. :ehp2.:font facename=default.This is the second level heading in the document&per.
  88.  The 'paragraph' Styles is marked as a Heading 2 style&per.  That style
  89. always gets tagged with the IPFC tags '&colon.h2&per.'
  90. :p.
  91. :font facename=default.:hp2.Subhead
  92. :p.
  93. :ehp2.:font facename=default.The Subhead style is used how a style is traditionally
  94. used in a word processing document&per.  It is simply used to re-use common
  95. formatting attributes, in this case bold text and a larger point size&per.
  96.  The Subhead style was used for the Heading 1, Heading 2, and Subhead headings
  97. within the Styles heading&per.
  98. :p.
  99. :h2.Text attributes
  100. :p.
  101. :font facename=default.Where possible, RTF2IPF tries to emulate common
  102. text formatting characteristics within the constraints of IPFC&per.  Currently,
  103. the only attribute supported is :hp2.Bold:ehp2.&per.  In the near future I hope
  104. to have it supporting italics, underline, as well as all of the combinations
  105. of these attributes&per.  Please try not to use different colors for your
  106. text as my current thoughts are to use the RTF color tags in defining hyper-links
  107. to other topics&per.
  108. :p.
  109. :h2.Paragraph formatting
  110. :p.
  111. :font facename=default.The current version of RTF2IPF does not provide
  112. any paragraph formatting beyond the standard word wrap capabilities provided
  113. by IPFC&per.  Although IPFC does allow for some formatting it is beyond
  114. the scope of the current version of RTF2IPF&per.
  115. :p.
  116. :h2.Tables
  117. :p.
  118. :font facename=default.Tables are currently unsupported by RTF2IPF but
  119. are currently very high on the list for planned enhancements (I need them
  120. too!)&per.  The 'results are unpredictable' for what will happen if you
  121. give RTF2IPF a table to process&per.
  122. :p.
  123. :h1.RTF2IPF Project Files
  124. :p.
  125. :font facename=default.This section describes the RTF2IPF project files&per.
  126.  
  127. :p.
  128. :h2.Overview
  129. :p.
  130. :font facename=default.The RTF2IPF project files contain information for
  131. RTF2IPF to use when converting the RTF tagged file to an IPF tagged file&per.
  132.  The file is an ASCII text file that take the format of&colon.
  133. :p.
  134. :xmp.
  135. Keyword=Value
  136. Keyword=Value
  137.  
  138.  
  139. :exmp.
  140. :font facename=default.By convention the RTF2IPF project files have an
  141. &per.IPJ extension&per.
  142. :p.
  143. :h2.Keywords
  144. :p.
  145. :font facename=default.Each of the valid keywords are described in their
  146. own section below&per.  Although the keywords are shown in mixed case they
  147. are processed in a case insensitive manner&per.
  148. :p.
  149. :h3.ExampleStyle
  150. :p.
  151. :font facename=default.:hp2.Purpose
  152. :p.
  153. :ehp2.:font facename=default.The ExampleStyle keyword is used to define
  154. the style to be interpreted as example tagged information&per.  The ExampleStyle
  155. keyword is required if you need the '&colon.xmp&per.' tag to be created
  156. in the &per.IPF file&per.
  157. :p.
  158. :font facename=default.:hp2.Syntax
  159. :p.
  160. :ehp2.:xmp.
  161. ExampleStyle=<stylename>
  162.  
  163.  
  164. :exmp.
  165. :font facename=default.:hp2.Parameters
  166. :p.
  167. :ehp2.:font facename=default.:hp2.stylename:ehp2. - The name of the style to
  168. be tagged as '&colon.xmp&per.' in the IPF file&per.
  169. :p.
  170. :h3.HeadingNStyle
  171. :p.
  172. :font facename=default.:hp2.Purpose
  173. :p.
  174. :ehp2.:font facename=default.The HeadingNStyle keyword is used to define
  175. the style to be interpreted as heading level N&per.  Currently N can take
  176. the value of 1 - 3&per.  At least the Heading1Style keyword is required&per.
  177. :p.
  178. :font facename=default.:hp2.Syntax
  179. :p.
  180. :ehp2.:xmp.
  181. HeadingNStyle=<stylename>
  182.  
  183.  
  184. :exmp.
  185. :font facename=default.:hp2.Parameters
  186. :p.
  187. :ehp2.:font facename=default.:hp2.stylename:ehp2. - The name of the style to
  188. use for the heading level N in the &per.IPF file&per.
  189. :p.
  190. :h3.IpfFile
  191. :p.
  192. :font facename=default.:hp2.Purpose
  193. :p.
  194. :ehp2.:font facename=default.The IpfFile keyword is used to define the
  195. IPF output file to be created&per.  This keyword is required&per.
  196. :p.
  197. :font facename=default.:hp2.Syntax
  198. :p.
  199. :ehp2.:xmp.
  200. IpfFile=<filename>
  201.  
  202.  
  203. :exmp.
  204. :font facename=default.:hp2.Parameters
  205. :p.
  206. :ehp2.:font facename=default.:hp2.filename:ehp2. - The name of the file to be
  207. created containing the IPF tagged source for the help file&per.  The file
  208. name follows standard naming rules that allow the name to be a fully qualified
  209. or relative path name&per.
  210. :p.
  211. :h3.IpfTitle
  212. :p.
  213. :font facename=default.:hp2.Purpose
  214. :p.
  215. :ehp2.:font facename=default.The IpfTitle keyword is used to define the
  216. title for the &per.INF file to be created&per.  This keyword is required&per.
  217. :p.
  218. :font facename=default.:hp2.Syntax
  219. :p.
  220. :ehp2.:xmp.
  221. IpfTitle=<title>
  222.  
  223.  
  224. :exmp.
  225. :font facename=default.:hp2.Parameters
  226. :p.
  227. :ehp2.:font facename=default.:hp2.title:ehp2. - The title for the &per.INF file
  228. to be created&per.
  229. :p.
  230. :h3.RtfFile
  231. :p.
  232. :font facename=default.:hp2.Purpose
  233. :p.
  234. :ehp2.:font facename=default.The RtfFile keyword is used to define the
  235. RTF input file&per.  This keyword is required&per.
  236. :p.
  237. :font facename=default.:hp2.Syntax
  238. :p.
  239. :ehp2.:xmp.
  240. RtfFile<filename>
  241.  
  242.  
  243. :exmp.
  244. :font facename=default.:hp2.Parameters
  245. :p.
  246. :ehp2.:font facename=default.:hp2.filename:ehp2. - The name of the file containing
  247. the RTF source for the help file&per.  The file name follows standard naming
  248. rules that allow the name to be a fully qualified or relative path name&per.
  249. :p.
  250. :h2.Example &per.IPJ file
  251. :p.
  252. :font facename=default.The following is the &per.IPF file used to create
  253. this document&per.
  254. :p.
  255. :xmp.
  256. RtfFile=rtf2ipf&per.rtf
  257. IpfFile=rtf2ipf&per.ipf 
  258. IpfTitle=RTF2IPF Reference 
  259. Heading1Style=Heading 1 
  260. Heading2Style=Heading 2 
  261. Heading3Style=Heading 3 
  262. ExampleStyle=example
  263.  
  264. :exmp.
  265. :font facename=default.
  266. :p.
  267. :h1.Running RTF2IPF
  268. :p.
  269. :font facename=default.Running RTF2IPF is very simple&per.  The program
  270. is invoked from the DOS (or OS/2) command line as follows&colon.
  271. :p.
  272. :xmp.
  273. RTF2IPF <project file>
  274.  
  275.  
  276. :exmp.
  277. :font facename=default.There are no options just a project file on the
  278. command line&per.  RTF2IPF will print a banner line and print a progress
  279. '&per.' at approximately every 500 characters added to the &per.IPF file
  280. until complete&per.
  281. :p.
  282. :h1.Obtaining support
  283. :p.
  284. :font facename=default.If you have a suggestion or problem please send
  285. a description along with the &per.IPJ and &per.RTF files and the date on
  286. the RTF2IPF&per.EXE file to&colon.
  287. :p.
  288. :font facename=default.Mark Ault
  289. :p.
  290. :font facename=default.74101,413 (Comp-U-Serve)
  291. :p.
  292. :h1.Planned Enhancements
  293. :p.
  294. :font facename=default.:hp2.Character Formatting
  295. :p.
  296. :ehp2.:font facename=default.As mentioned earlier, one of the first enhancements
  297. on tap for this utility is the ability to use text properties other than
  298. normal and bold&per.  Italics and underline will be added along with the
  299. various combinations&per.
  300. :p.
  301. :font facename=default.:hp2.Tables
  302. :p.
  303. :ehp2.:font facename=default.Currently this utility is un-tested with tables&per.
  304.  Table support is planned for the next version I will post&per.
  305. :p.
  306. :font facename=default.:hp2.Hyper-Links
  307. :p.
  308. :ehp2.:font facename=default.The ability to create hyper-links from one
  309. of the &per.INF panels to another panel in the same document&per.  Currently
  310. I am planning on using a color tag to identify where the hyper-links occur&per.
  311.  If you have any suggestions of a different way to tag it in the word processor
  312. please let me know&per.
  313. :p.
  314. :font facename=default.:hp2.Multiple RTF input files
  315. :p.
  316. :ehp2.:font facename=default.As some documents get larger it can be convenient
  317. to break them into several smaller documents&per.  When this is done it
  318. requires you to combine the documents as one and save the one RTF file
  319. for Rtf2Ipf to process&per.  It would be more convenient to use several
  320. RTF files for each of the pieces of the original document&per.
  321. :p.
  322. :font facename=default.:hp2.Re-work the &per.IPJ project files
  323. :p.
  324. :ehp2.:font facename=default.Possible enhancements include adding comments,
  325. an include directive, getting file names from the command line instead,
  326. and getting the title from the document information section of the RTF
  327. file&per.
  328. :p.
  329.  
  330. :euserdoc.
  331.