home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / texipf22.zip / texi2ipf / readme < prev    next >
Text File  |  1997-07-17  |  7KB  |  177 lines

  1. texi2ipf - Texinfo to OS/2 IPFC source file converter
  2. -----------------------------------------------------
  3.  
  4.         This program is a modified version of texi2roff.
  5.         texi2roff is  Copyright  1988, 1989, 1990 by  Beverly A. Erlebacher
  6.  
  7.         texi2ipf was written by Marcus Groeber 1992/93
  8.         and modified by Martin "Herbert" Dietze 1996 and 1997
  9.  
  10.  
  11. Some remarks concerning my changes (Herbert):
  12. ---------------------------------------------
  13.  
  14. As the program was not exactly what I wanted (especially all that @def*
  15. stuff got out rather scrambled) I changed a few things. I have documented
  16. all of that in a seperate manual in Texinfo and inf format "texi2ipf.texi"
  17. and "texi2ipf.inf". I may add more features in the future (and make them 
  18. public) if necessary and time allows. 
  19.  
  20.  Herbert
  21.  
  22. herbert@wiloyee.shnet.org
  23. 2:240/5210.18 fidonet
  24.  
  25. Below follows the original readme text by Beverly A. Erlenbacher 
  26. and Marcus Groeber:
  27.  
  28.  
  29. >-------------------------------------------------------------------------<
  30.  
  31.  
  32. Very soon after the first GNU ports for OS/2 2.0 were out, some
  33. people asked for a simple way to make use of the texinfo manuals,
  34. especially those included with the various GCC ports.
  35.  
  36. Having seen some examples of OS/2's excellent Information
  37. Presentation Facility (some would call it a help system) I had the
  38. idea that porting the GNU manuals to a graphical viewer would be
  39. much more aedequate for a graphical user interface than a text based
  40. reader.
  41.  
  42. The texi2roff translator provided me with the basics of reading and
  43. interpreting texinfo files. But the original texi2roff manual was 
  44. right in saying that "texinfo remained a moving target" - since the
  45. completion of the 1990 release of texi2roff (which was the lastet
  46. I could find), a number of new additions the the texinfo package
  47. had been made [such as conditional compiling].
  48.  
  49. Also, porting texinfo to a viewing system capable of "hypertext"
  50. functions (i.e. cross references) meant having to add extended
  51. support for those commands that were specific to the "info" version
  52. of a texinfo file (as opposed to the "TeX" version).
  53.  
  54. Therefore, the source code to this program is a complete mixture of
  55. original and modified routines down to expression level, which is
  56. why I did not create a seperate diff file.
  57.  
  58.  
  59. As the IPFC compiler from the Toolkit is absolutely required for
  60. creating INF files, most end users won't be able to convert
  61. texinfo files to INF themselves. Therefore, people doing GNU ports
  62. for OS/2 should probably best do the conversion themselves and
  63. include INF version manuals in their distribution.
  64.  
  65. It should be stressed that this program is *not* a general
  66. TeX-to-something converter; even certain texinfo styles will not
  67. be recognized properly, even though they might produce correct
  68. TeX output. Especially questions like font changes inside other
  69. statements (document titles, index entries etc.) are not even
  70. handled consistently by texinfo authors.
  71.  
  72.  
  73. What you need
  74. -------------
  75. To use this program, you should have the IPFC program from the
  76. OS/2 2.0 development toolkit installed. As far as I know, this
  77. program is not available separately, but it is included on the
  78. public beta versions of the Toolkit as well.
  79.  
  80. I tested the included source files with the emx/gcc 0.8f port of the
  81. Gnu C compiler. The other port ("GCC/2") should work also, but
  82. you might have to change the make files. See below for further notes
  83. on recompiling the program.
  84.  
  85.  
  86. Usage
  87. -----
  88. There are no tricky options, just type 
  89.  
  90.     texi2ipf texinfo_file >IPF_file
  91.  
  92. to convert a given texinfo file to an IPF source file that can then
  93. be compiled with the IPFC compiler. If the texinfo file includes
  94. other files (as the GCC manual does), these should be in the current
  95. directory. Output will always be in one big file. IPF filenames
  96. should usually end in .IPF.
  97.  
  98. To compile the IPF file to a viewable INF database, type:
  99.  
  100.     ipfc /INF IPF_file
  101.  
  102. This creates a file with the same name as the IPF file, but with a
  103. .INF extension.
  104.  
  105. Both commands can produce a number of warnings. With text based
  106. formats that are as flexible as texinfo and IPF, complete
  107. transformation is very hard to achieve. Anyway, most warnings
  108. will only point at local problems in the data (such as unrecognized
  109. commands) - the resulting database will still be usable in most
  110. cases.
  111.  
  112. After compiling you can have a look at the database by typing
  113.  
  114.     view INF_file
  115.  
  116. If the database appears correct, you can delete the IPF source file.
  117. If not, you can still try to patch out any problems reported.
  118.  
  119. To facilitate the translation process, a CMD file has been included
  120. that automatically calls texi2ipf and ipfc. It is called texi2i
  121. and should not be renamed. To use it, it must reside in the same
  122. directory as texi2ipf, and ipfc must be on the PATH.
  123.  
  124. Typing
  125.  
  126.     texi2i texinfo_file
  127.  
  128. [texinfo_file must be specified without extension; names ending in
  129. .tex .texi .texinfo are automatically found] converts and compiles
  130. the texinfo file to an INF database and deletes the temporary
  131. IPF source code. If you add a "!" as second parameter, the IPF
  132. source file is preserved.
  133.  
  134.  
  135. Texinfo support
  136. ---------------
  137. The program has been tested with a number of texinfo files,
  138. especially those that come with the gcc distribution, and most
  139. compile with little or no errors and warnings [some of which
  140. result from real problems in the original info files]. If you
  141. come across a file which does not compile with texi2ipf, I'd
  142. appreciate a short note to my Fidonet adress [see below].
  143.  
  144. The latest Texinfo version at the time of this release was 2.16
  145. from October 1992.
  146.  
  147.  
  148. Making changes to the source
  149. ----------------------------
  150. The program was compiled using emx/gcc 0.8f with the Toolkit nmake
  151. program [together with the toolkit headers, but these should not
  152. make any difference as this is a commandline-only application that
  153. uses no OS/2 specific features]. To compile the executable with the
  154. included makefile, you'll have to build the omf libraries for
  155. emx/gcc first, or you can omit the "-Zomf" parameter in the
  156. compiler flags.
  157.  
  158. The source has not been completely "brushed over" to remove all
  159. lines the have become obsolete with the changes from texi2roff,
  160. and it may not be fully "bullet-proof" in extreme circumstances
  161. (recursive include files, excessive nesting etc.) either, but as
  162. this is not a program for everyday use, this seemed
  163. appropriate to me.
  164.  
  165.  
  166. Portability
  167. -----------
  168. None. :-) I haven't used any OS/2 specific functions, but as the
  169. destination format is OS/2 specific, I did not take any precautions
  170. to ensure portability to other environments.
  171.  
  172.  
  173. Please adress comments, suggestions etc. to:
  174. Marcus Groeber, Fido 2:2402/61.1
  175.  
  176.  
  177.