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