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