home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / ipf10b.zip / rtf2ipf.ipf < prev    next >
Text File  |  1994-07-04  |  15KB  |  382 lines
  1. :userdoc.
  2. .*--------------------------------------------------
  3. .*
  4. .* This IPF file was created with Rtf2Ipf v1.0b
  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&slash.2 &per.INF file&per.  RTF2IPF is currently
  22. a command line DOS program &lpar.sorry but I run DOS&slash.Windows at home
  23. where this was developed&rpar. that should be able to integrate well to
  24. a development make file&per.  
  25. :p.
  26. :font facename=default.Although this utility is being distributed as &apos.Freeware&apos.
  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 &lpar.74101,413&rpar. and let me know what
  29. you think&per.  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 &lpar.styles included&rpar. in Rich Text
  35. Format &lpar.RTF&rpar.&per.  All of my testing has been with Ami Pro v2&per.0
  36. for Windows and Ami Pro v3&per.0 for OS&slash.2&per.  The document you
  37. are receiving was created using Ami Pro v2&per.0 for Windows&per.  Any
  38. word processor that can save it&apos.s documents in RTF format should work&per.
  39.  If you use a different word processor and develop a style sheet that you
  40. find useful please send it to me &lpar.see the section Obtaining support
  41. for how to reach me&rpar. and I will include it in the next version to
  42. be uploaded&per.  To compile your on-line document you will need the OS&slash.2
  43. IPFC help compiler&per.
  44. :p.
  45. :h2.Disclaimers
  46. :p.
  47. :font facename=default.RTF2IPF is really still a work in process&per. 
  48. As you read through here you will see several places where I mention that
  49. a feature is planned or where I will even solicit your ideas about how
  50. a feature should be implemented&per.  As a result of this utility still
  51. evolving, the current version uploaded here still has some debug code compiled
  52. in&per.  As such it is possible that you may run into an assertion or other
  53. bugs&per.  Although I believe everything to be correct I cannot guarantee
  54. it&per.  If you do have a problem or a suggestion, please contact me and
  55. I will see what I can do to fix it&per.
  56. :p.
  57. :h1.Creating The Documentation in your Word Processor
  58. :p.
  59. :font facename=default.This section describes how to prepare you documentation
  60. in your favorite word processor&per.
  61. :p.
  62. :h2.Styles
  63. :p.
  64. :font facename=default.RTF2IPF is dependent upon your word processor correctly
  65. identifying style information in the RTF file when you save your document&per.
  66.  The styles are used to identify how the text in your document should be
  67. tagged for the IPFC compiler&per.  The most important use of styles is
  68. to identify which &apos.paragraphs&apos. in your document are intended
  69. to be used as headings in the &per.INF file&per.  Since the IPFC compiler
  70. requires that you make an orderly progression through the heading levels
  71. it is imperative that you are very diligent in setting up a style sheet
  72. that mimics the progression of styles that the IPFC compiler will accept&per.
  73.  You must always keep in mind how the styles will affect your on-line document&per.
  74. :p.
  75. :font facename=default.For example, this document was created using the
  76. Ami Pro style sheet supplied with RTF2IPF&per.  Some of the styles present
  77. in the document and their uses are as follows&colon.
  78. :p.
  79. :font facename=default.:hp2.Heading 1
  80. :p.
  81. :ehp2.:font facename=default.The top level headings in the document&per.
  82.  The &apos.paragraph&apos. Creating The Documentation in your Word Processor
  83. is a Heading 1 style&per.  That style always gets tagged with the IPFC
  84. tags &apos.&colon.h1&per.&apos.
  85. :p.
  86. :font facename=default.:hp2.Heading 2
  87. :p.
  88. :ehp2.:font facename=default.This is the second level heading in the document&per.
  89.  The &apos.paragraph&apos. Styles is marked as a Heading 2 style&per. 
  90. That style always gets tagged with the IPFC tags &apos.&colon.h2&per.&apos.
  91. :p.
  92. :font facename=default.:hp2.Subhead
  93. :p.
  94. :ehp2.:font facename=default.The Subhead style is used how a style is traditionally
  95. used in a word processing document&per.  It is simply used to re-use common
  96. formatting attributes, in this case bold text and a larger point size&per.
  97.  The Subhead style was used for the Heading 1, Heading 2, and Subhead headings
  98. within the Styles heading&per.
  99. :p.
  100. :h2.Text attributes
  101. :p.
  102. :font facename=default.Where possible, RTF2IPF tries to emulate common
  103. text formatting characteristics within the constraints of IPFC&per.  Currently,
  104. the only attribute supported is :hp2.Bold:ehp2.&per.  In the near future I hope
  105. to have it supporting italics, underline, as well as all of the combinations
  106. of these attributes&per.  Please try not to use different colors for your
  107. text as my current thoughts are to use the RTF color tags in defining hyper-links
  108. to other topics &lpar.although this is still the subject of some debate&rpar.&per.
  109. :p.
  110. :h2.Paragraph formatting
  111. :p.
  112. :font facename=default.The current version of RTF2IPF does not provide
  113. any paragraph formatting beyond the standard word wrap capabilities provided
  114. by IPFC&per.  Although IPFC does allow for some formatting it is beyond
  115. the scope of the current version of RTF2IPF&per.
  116. :p.
  117. :h2.Tables
  118. :p.
  119. :font facename=default.Tables are currently unsupported by RTF2IPF but
  120. are currently very high on the list for planned enhancements &lpar.I need
  121. them too&xclm.&rpar.&per.  The &apos.results are unpredictable&apos. for
  122. what will happen if you give RTF2IPF a table to process&per.
  123. :p.
  124. :h1.RTF2IPF Project Files
  125. :p.
  126. :font facename=default.This section describes the RTF2IPF project files&per.
  127.  
  128. :p.
  129. :h2.Overview
  130. :p.
  131. :font facename=default.The RTF2IPF project files contain information for
  132. RTF2IPF to use when converting the RTF tagged file to an IPF tagged file&per.
  133.  The file is an ASCII text file that take the format of&colon.
  134. :p.
  135. :xmp.
  136. Keyword&eq.Value
  137. Keyword&eq.Value
  138.  
  139.  
  140. :exmp.
  141. :font facename=default.By convention the RTF2IPF project files have an
  142. &per.IPJ extension&per.
  143. :p.
  144. :h2.Keywords
  145. :p.
  146. :font facename=default.Each of the valid keywords are described in their
  147. own section below&per.  Although the keywords are shown in mixed case they
  148. are processed in a case insensitive manner&per.
  149. :p.
  150. :h3.ExampleStyle
  151. :p.
  152. :font facename=default.:hp2.Purpose
  153. :p.
  154. :ehp2.:font facename=default.The ExampleStyle keyword is used to define
  155. the style to be interpreted as example tagged information&per.  The ExampleStyle
  156. keyword is required if you need the &apos.&colon.xmp&per.&apos. tag to
  157. be created in the &per.IPF file&per.
  158. :p.
  159. :font facename=default.:hp2.Syntax
  160. :p.
  161. :ehp2.:xmp.
  162. ExampleStyle&eq.<stylename>.
  163.  
  164.  
  165. :exmp.
  166. :font facename=default.:hp2.Parameters
  167. :p.
  168. :ehp2.:font facename=default.:hp2.stylename:ehp2. - The name of the style to
  169. be tagged as &apos.&colon.xmp&per.&apos. in the IPF file&per.
  170. :p.
  171. :h3.HeadingNStyle
  172. :p.
  173. :font facename=default.:hp2.Purpose
  174. :p.
  175. :ehp2.:font facename=default.The HeadingNStyle keyword is used to define
  176. the style to be interpreted as heading level N&per.  Currently N can take
  177. the value of 1 - 9&per.  At least the Heading1Style keyword is required&per.
  178. :p.
  179. :font facename=default.:hp2.Syntax
  180. :p.
  181. :ehp2.:xmp.
  182. HeadingNStyle&eq.<stylename>.
  183.  
  184.  
  185. :exmp.
  186. :font facename=default.:hp2.Parameters
  187. :p.
  188. :ehp2.:font facename=default.:hp2.stylename:ehp2. - The name of the style to
  189. use for the heading level N in the &per.IPF file&per.
  190. :p.
  191. :h3.IpfFile
  192. :p.
  193. :font facename=default.:hp2.Purpose
  194. :p.
  195. :ehp2.:font facename=default.The IpfFile keyword is used to define the
  196. IPF output file to be created&per.  This keyword is required&per.
  197. :p.
  198. :font facename=default.:hp2.Syntax
  199. :p.
  200. :ehp2.:xmp.
  201. IpfFile&eq.<filename>.
  202.  
  203.  
  204. :exmp.
  205. :font facename=default.:hp2.Parameters
  206. :p.
  207. :ehp2.:font facename=default.:hp2.filename:ehp2. - The name of the file to be
  208. created containing the IPF tagged source for the help file&per.  The file
  209. name follows standard naming rules that allow the name to be a fully qualified
  210. or relative path name&per.
  211. :p.
  212. :h3.IpfTitle
  213. :p.
  214. :font facename=default.:hp2.Purpose
  215. :p.
  216. :ehp2.:font facename=default.The IpfTitle keyword is used to define the
  217. title for the &per.INF file to be created&per.  This keyword is required&per.
  218. :p.
  219. :font facename=default.:hp2.Syntax
  220. :p.
  221. :ehp2.:xmp.
  222. IpfTitle&eq.<title>.
  223.  
  224.  
  225. :exmp.
  226. :font facename=default.:hp2.Parameters
  227. :p.
  228. :ehp2.:font facename=default.:hp2.title:ehp2. - The title for the &per.INF file
  229. to be created&per.
  230. :p.
  231. :h3.RtfFile
  232. :p.
  233. :font facename=default.:hp2.Purpose
  234. :p.
  235. :ehp2.:font facename=default.The RtfFile keyword is used to define the
  236. RTF input file&per.  This keyword is required&per.
  237. :p.
  238. :font facename=default.:hp2.Syntax
  239. :p.
  240. :ehp2.:xmp.
  241. RtfFile&eq.<filename>.
  242.  
  243.  
  244. :exmp.
  245. :font facename=default.:hp2.Parameters
  246. :p.
  247. :ehp2.:font facename=default.:hp2.filename:ehp2. - The name of the file containing
  248. the RTF source for the help file&per.  The file name follows standard naming
  249. rules that allow the name to be a fully qualified or relative path name&per.
  250. :p.
  251. :h2.Example &per.IPJ file
  252. :p.
  253. :font facename=default.The following is the &per.IPF file used to create
  254. this document&per.
  255. :p.
  256. :xmp.
  257. RtfFile&eq.rtf2ipf&per.rtf
  258. IpfFile&eq.rtf2ipf&per.ipf 
  259. IpfTitle&eq.RTF2IPF Reference 
  260. Heading1Style&eq.Heading 1 
  261. Heading2Style&eq.Heading 2 
  262. Heading3Style&eq.Heading 3 
  263. ExampleStyle&eq.example
  264.  
  265. :exmp.
  266. :font facename=default.
  267. :p.
  268. :h1.Running RTF2IPF
  269. :p.
  270. :font facename=default.Running RTF2IPF is very simple&per.  The program
  271. is invoked from the DOS &lpar.or OS&slash.2&rpar. command line as follows&colon.
  272. :p.
  273. :xmp.
  274. RTF2IPF <project file>.
  275.  
  276.  
  277. :exmp.
  278. :font facename=default.There are no options just a project file on the
  279. command line&per.  RTF2IPF will print a banner line and print a progress
  280. &apos.&per.&apos. at approximately every 500 characters added to the &per.IPF
  281. file until complete&per.
  282. :p.
  283. :h1.Obtaining support
  284. :p.
  285. :font facename=default.If you have a suggestion or problem please send
  286. a description along with the &per.IPJ and &per.RTF files and the date on
  287. the RTF2IPF&per.EXE file to&colon.
  288. :p.
  289. :font facename=default.Mark Ault
  290. :p.
  291. :font facename=default.74101,413 &lpar.Comp-U-Serve&rpar.
  292. :p.
  293. :h1.Planned Enhancements
  294. :p.
  295. :font facename=default.This section contains a list of possible enhancement
  296. I am currently considering for RTF2IPF&per.  They are listed in no particular
  297. order&per.  If you have some favorites or additional ideas please let me
  298. know and I will see what I can do&per.  Currently they are being prioritized
  299. base on how badly I need the feature and how long it would take to implement&per.
  300. :p.
  301. :h2.Character formatting
  302. :p.
  303. :font facename=default.As mentioned earlier, one of the first enhancements
  304. on tap for this utility is the ability to use text properties other than
  305. normal and bold&per.  Italics and underline will be added along with the
  306. various combinations&per.
  307. :p.
  308. :h2.Tables
  309. :p.
  310. :font facename=default.Currently this utility is un-tested with tables&per.
  311.  Table support is planned for the next version I will post&per.
  312. :p.
  313. :h2.Margins
  314. :p.
  315. :font facename=default.One of the things that can make a help files contents
  316. more attractive is to control the margins&per.  These will most likely
  317. be controlled through style modifiers in the &per.IPJ files&per.
  318. :p.
  319. :h2.Lists
  320. :p.
  321. :font facename=default.The IPFC compilers supports several flavors of lists&per.
  322.  The intention is to support at least the basic list type such as ordered
  323. lists, simple lists, and unordered lists&per.  Once again, the various
  324. list types will be indicated through the use of styles&per.
  325. :p.
  326. :h2.Hyper-links
  327. :p.
  328. :font facename=default.The ability to create hyper-links from one of the
  329. &per.INF panels to another panel in the same document&per.  Currently I
  330. am planning on using a color or footnote tag to identify where the hyper-links
  331. occur &lpar.although this is still the subject of some debate&rpar.&per.
  332.  If you have any suggestions of a different way to tag it in the word processor
  333. please let me know&per.
  334. :p.
  335. :h2.Multiple RTF input files
  336. :p.
  337. :font facename=default.As some documents get larger it can be convenient
  338. to break them into several smaller documents&per.  When this is done it
  339. requires you to combine the documents as one and save the one RTF file
  340. for Rtf2Ipf to process&per.  It would be more convenient to use several
  341. RTF files for each of the pieces of the original document&per.
  342. :p.
  343. :h2.Re-work the &per.IPJ project files
  344. :p.
  345. :font facename=default.Possible enhancements include adding comments, an
  346. include directive, getting file names from the command line instead, and
  347. getting the title from the document information section of the RTF file&per.
  348. :p.
  349. :h2.Add a user interface shell
  350. :p.
  351. :font facename=default.At the very least the shell would be useful for
  352. creating the &per.IPJ files&per.  However, the ultimate goal of the shell
  353. would be to act as an integrated &apos.workbench&apos. for all of the tools
  354. you would use to create your on-line documentation&per.  From the workbench
  355. you would start you word processor to create the initial source for the
  356. on-line book, run RTF2IPF and view the output, run the IPFC compiler to
  357. create the &per.HLP or &per.INF file, and even start VIEW&per.EXE to view
  358. the newly created &per.INF file&per.  Obviously this is the most ambitious
  359. of the enhancements listed here and the time to design&slash.create this
  360. tool will dictate when&slash.if it appears&per.  Doing this may be mutually
  361. exclusive with the previous &apos.Re-work the &per.IPF project files&apos.
  362. enhancement&per.
  363. :p.
  364. :h2.Create panel resource ID&apos.s and &numsign.defines
  365. :p.
  366. :font facename=default.The resource ID is required for creating a &per.HLP
  367. file that is accessed from a Presentation Manager application&per.  This
  368. is another of the features that I will be needing within the next few months
  369. so look for it to be available relatively quickly &lpar.I&apos.m hoping
  370. by Sep&slash.Oct 1994 but make no promises&xclm.&rpar.&per.
  371. :p.
  372. :h2.Window help file support
  373. :p.
  374. :font facename=default.As I learn more about the MS Window help compiler
  375. I will be adding support for maintaining a MS Window help file in the same
  376. way you can use RTF2IPF to maintain an OS&slash.2 help file&per.
  377. :p.
  378. :h2.
  379. :p.
  380.  
  381. :euserdoc.
  382.