home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / texipf22.zip / texi2ipf / texi2ipf.ipf < prev    next >
Text File  |  1997-07-17  |  18KB  |  289 lines
  1. :userdoc.
  2. :docprof toc=1234.
  3.  
  4. :title.Texi2ipf
  5. :h1.Title page
  6. :lines align=center.
  7. Texi2ipf 2&per.2 -- a Texinfo to IPF converter
  8. :elines.
  9. :lines align=center.
  10. Based on work by M&per. Groeber and B&per. A&per. Erlenbacher
  11. :elines.
  12. :lines align=center.
  13.  Martin "Herbert" Dietze
  14. :elines.
  15. :p.:p.:p.
  16. :p.Copyright (C) 1996, 1997 by Herbert&per.
  17. :p.Permission is granted to make and distribute verbatim or modified copies
  18. of this manual in terms of the Copyright notice below&per.
  19. :p.Permission is granted to copy and distribute translations of this manual
  20. into another language, under the above conditions&per.
  21. :h1 id='Top'.Top
  22. :p.This manual provides some information about using texi2ipf, a Texinfo to
  23. IPF converter&per. It can also be used as test file for texi2ipf's output&per.
  24. :p.:parml tsize=40 break=none compact.
  25. :pt.:link reftype=hd refid='Introduction'.Introduction:elink.:pd.Historical notes etc&per.
  26. :pt.:link reftype=hd refid='Using it'.Using it:elink.:pd.Usage and basic features&per.
  27. :pt.:link reftype=hd refid='Change log'.Change log:elink.:pd.What I did to it and when&per.
  28. :eparml.
  29. :p.
  30. :h1 id='Introduction'.Introduction
  31. :p.:parml tsize=40 break=none compact.
  32. :pt.:link reftype=hd refid='Historical notice'.Historical notice:elink.:pd.Its roots&per.
  33. :pt.:link reftype=hd refid='Further notices'.Further notices:elink.:pd.What you might like to know&per.
  34. :eparml.
  35. :p.
  36. :h2 id='Historical notice'.Historical notice
  37. :p.The :hp1.texi2ipf:ehp1. program is mainly Beverly A&per. Eschenbacher's work
  38. from 1988, 1989 and 1990 as his :hp1.texi2roff:ehp1. was the base for Marcus
  39. Groebner making a Texinfo to IPF converter out of it in 1992/93&per.
  40. :p.As I needed a tool to convert my master's thesis written in Texinfo to
  41. IPF I tried it but found it not suitable for my needs -- it did not
  42. treat :hp1.@def*:ehp1. templates correctly and produced blank pages where I
  43. had menus in my sources&per. So I decided to take a closer look at the
  44. sources and add the features I found missing and fix a few bugs I
  45. found&per.
  46. :p.I don't claim to have done much on the program, it is still mainly
  47. Beverly's and Marcus' work but as nobody else seems to have maintained
  48. it any more I have decided to make my modifications public, they have
  49. made the program a bit more usable for me after all&per.
  50. :p.The result works -- let's say -- not too bad, the sources look like what
  51. they are&colon. the result of at least three people doing this or that &colon.-)
  52. :p.
  53. :h2 id='Further notices'.Further notices
  54. :p.The program comes shipping as an OS/2 executable (compiled and linked
  55. using IBM's VisualAge C++ tools) with Texinfo documentation (you are
  56. just reading it!) and the C sources&per.
  57. :p.Asking me for license stuff I can only say "no idea!" as it is not only
  58. my work&per. As far as I'm concerned my stuff can be considered as GPL'ed,
  59. nobody pays nobody nothing&per. You may also want to take a look at the
  60. original license shipped with :hp1.texi2roff:ehp1. in the file
  61. :hp1.copyright:ehp1. for all that was written by Beverly&per.
  62. :p.If anybody of you out there adds some useful feature or fixes a bug
  63. (there :hp1.should:ehp1. be some more) please feel free to send me a mail, I
  64. am always interested in further enhancements&per. My email address is&colon.
  65. :xmp.
  66.   herbert@wiloyee&per.shnet&per.org
  67. :exmp.
  68. :font facename=default size=0x0.
  69. :p.I will try to release all future versions to at least those two ftp
  70. sites / directories&colon.
  71. :ol.
  72. :li.:font facename=Courier size=16x8.ftp&per.cdrom&per.com/pub/os2/:font facename=default size=0x0.
  73. :li.:font facename=Courier size=16x8.ftp&per.leo&per.org/pub/comp/os/os2/leo/:font facename=default size=0x0.
  74. :eol.
  75. :p.By the way&colon. You may find this manual a bit too verbose for such a small
  76. utility, it is indeed, but this also makes it a good demo file for the
  77. program's capabilities&per.&per.&per.
  78. :p.
  79. :h1 id='Using it'.Using it
  80. :p.:parml tsize=40 break=none compact.
  81. :pt.:link reftype=hd refid='Usage'.Usage:elink.:pd.How to invoke it&per.
  82. :pt.:link reftype=hd refid='Features'.Features:elink.:pd.What it can do&per.
  83. :pt.:link reftype=hd refid='Limitations'.Limitations:elink.:pd.What it cannot do&per.
  84. :pt.:link reftype=hd refid='Compiling it'.Compiling it:elink.:pd.Compatibility etc&per.
  85. :eparml.
  86. :p.
  87. :h2 id='Usage'.Usage
  88. :p.The program reads the Texinfo source, translates it and writes the
  89. result to stdout&per. It has no further options&per. A sample invocation looks
  90. like&colon.
  91. :xmp.
  92. texi2ipf texi2ipf&per.texi >texi2ipf&per.ipf
  93. :exmp.
  94. :font facename=default size=0x0.
  95. :p.Redirecting the standard output to a file via ">" creates us an ipf
  96. source that can be compiled via&colon.
  97. :xmp.
  98. ipfc -inf texi2ipf&per.ipf
  99. :exmp.
  100. :font facename=default size=0x0.
  101. :p.If encountering a Texinfo command it does not recognize (there are still
  102. some) it will ignore it and emit a warning message&per. If the Texinfo
  103. commands ignored is not important for the ipf output the warnings can be
  104. ignored&per. Only if the program runs into a situation it cannot recover
  105. from it will abort with an error message&per. This is only very rarely the
  106. case (e&per.g&per. not correctly nested :font facename=Courier size=16x8.@:font facename=default size=0x0.&per.&per. :font facename=Courier size=16x8.@end &per.&per.:font facename=default size=0x0.
  107. environments)&per.
  108. :p.The program can, of course, only handle standard Texinfo commands&per. It
  109. will parse all :font facename=Courier size=16x8.@ifinfo:font facename=default size=0x0. &per.&per. :font facename=Courier size=16x8.@end:font facename=default size=0x0. ifinfo environments and
  110. ignore all :font facename=Courier size=16x8.@tex:font facename=default size=0x0. &per.&per. :font facename=Courier size=16x8.@end tex:font facename=default size=0x0. environments&per. How it treats
  111. some special Texinfo features will be described in the next section
  112. (see :link reftype=hd  refid='Features'.Features:elink.)&per.
  113. :p.
  114. :h2 id='Features'.Features
  115. :p.:hp5.Overall features:ehp5.
  116. :p.Like mentioned in the previous section (see :link reftype=hd  refid='Usage'.Usage:elink.) the program parses
  117. only :font facename=Courier size=16x8.@iftex:font facename=default size=0x0. &per.&per. :font facename=Courier size=16x8.@end iftex:font facename=default size=0x0. environments&per. As :hp1.info:ehp1. is
  118. a hypertext format like :hp1.inf:ehp1. is there is only a small subset of
  119. features not covered by both formats&per. One of them is the missing
  120. handling of bitmaps in info, for this I use the pseudo-ipf tag
  121. :font facename=Courier size=16x8.@ipfline{}:font facename=default size=0x0. described more below&per. Here's a list of further
  122. features&colon.
  123. :ul.
  124. :li.:font facename=Courier size=16x8.@def*:font facename=default size=0x0. templates produce an entry in the main index&per. Using the
  125. :font facename=Courier size=16x8.@cindex:font facename=default size=0x0. command will do this, too&per. Texinfo-like indices
  126. (:font facename=Courier size=16x8.@printindex:font facename=default size=0x0.) are not (yet) supported&per. See :link reftype=hd  refid='Limitations'.Limitations:elink.
  127. for more information&per.
  128. :li.Texinfo menus are simulated&per. This is not really necessary but looks
  129. better than blank pages&per. Please, note that menu descriptions continueing
  130. in the line(s) after the menu entry will only be handled correctly if
  131. indented more than 25 columns&per.
  132. :li.The program will create a node for every document structuring command
  133. except the :font facename=Courier size=16x8.@*heading:font facename=default size=0x0. commands (You see two of them in this
  134. section!)&per.
  135. :li.For being able to enter plain ipf code into the Texinfo document I
  136. provide a pseudo-tag :font facename=Courier size=16x8.@ipfline{}:font facename=default size=0x0.&per. Its handling will be
  137. described more verbosely below&per.
  138. :eul.
  139. :p.:hp5.Entering plain ipf:ehp5.
  140. :p.As info knows no images inside info documents we may want to enter plain
  141. ipf code into our Texinfo documents still being able to process them via
  142. :hp1.makeinfo:ehp1., :hp1.texi2dvi:ehp1. etc&per. For this task :hp1.texi2ipf:ehp1.
  143. recognizes a pseudo-tag :font facename=Courier size=16x8.@ipfline{}:font facename=default size=0x0. containing plain ipf code
  144. as argument&per. To avoid conflicts with other formatting tools you should
  145. use it the following way&colon.
  146. :xmp.
  147.  
  148. @c Define this macro somewhere near the beginning of your document&per.
  149. @c It expands to nothing for "makeinfo" and is necessary to avoid
  150. @c errors when creating an Info file&per.
  151. @c The "@ifinfo" block is necessary because the "@macro" command is
  152. @c only known to "makeinfo"&per. Please, note that older versions of
  153. @c "makeinfo" do not recognize the "@macro" command either&per.
  154.  
  155. @ifinfo
  156. @macro ipfline{line}
  157. @end macro
  158. @end ifinfo
  159.  
  160. @c [&per.&per.&per.]
  161.  
  162. @c Now somewhere inside the document enter the ipf commands as
  163. @c arguments to "@ipfline{}"&per. In this example we use plain
  164. @c ipf to include a bitmap and some explaining text only into
  165. @c the ipf output&per. Like the macro above we put in into a "@ifinfo"
  166. @c block because the (empty) macro "@ipfline{}" would cause
  167. @c errors to any formatter but "makeinfo" or "texi2ipf"&per.
  168.  
  169. @ifinfo
  170. @ipfline{The following example shows a simple LAN consisting of}
  171. @ipfline{three machines connected by a ring&.colon&per.}
  172. @ipfline{&colon.p&per.&colon.artwork name='lan&per.bmp' align=center&per.}
  173. @end ifinfo
  174. :exmp.
  175. :font facename=default size=0x0.
  176. :p.This will enter the text and the bitmap into the ipf output just the
  177. way it is inside of the :font facename=Courier size=16x8.@ipfline{}:font facename=default size=0x0. arguments&per.
  178. :p.
  179. :h2 id='Limitations'.Limitations
  180. :p.Disregarding the fact that the program is still pretty buggy <g> there
  181. are a few features I would like it to have but yet it has not&colon.
  182. :ul.
  183. :li.The program does not yet recognize all Texinfo commands&per. This is not so
  184. bad as most of them are not of interest for producing ipf output&per. But
  185. this still leads to unnecessary warning messages&per.
  186. :li.There is no support for the :font facename=Courier size=16x8.@defindex:font facename=default size=0x0. and :font facename=Courier size=16x8.@printindex:font facename=default size=0x0.
  187. commands&per. This results in almost empty pages only containing "Sorry, no
  188. &per.&per. index!"&per. I plan to add this but I have no idea when&per.
  189. :eul.
  190. :p.
  191. :h2 id='Compiling it'.Compiling it
  192. :p.First thing I did when starting working on it was changing the code from
  193. K&.R C to ANSI C&per. So it will not compile on a pre-ANSI C compiler any
  194. more&per. It should not make any problems with non-Unix compilers any more
  195. (emx/gcc offers all the Unix functions not available with other PC
  196. compilers)&per.
  197. :p.I have compiled the program using the following compilers / operating
  198. systems&colon.
  199. :ul.
  200. :li.GNU CC under AIX and OS/2&per.
  201. :li.IBM's xlC compiler under AIX&per.
  202. :li.IBM's CSet++ 2&per.1 and VisualAge C++ 3&per.0 under OS/2&per.
  203. :eul.
  204. :p.The makefile contains predefined sections for those compilers that only
  205. need to be uncommented&per.
  206. :p.By the way&colon. Yes I know the code :hp1.is:ehp1. ugly&per. This is partially my
  207. fault as I did not get into the way it works too much when I first
  208. started modifying it&per. It also was quite unreadable when I took my first
  209. look at it&per.&per.&per.
  210. :p.
  211. :h1 id='Change log'.Change log
  212. :p.:parml tsize=40 break=none compact.
  213. :pt.:link reftype=hd refid='Release 2&per.2'.Release 2&per.2:elink.:pd.The third public release&per.
  214. :pt.:link reftype=hd refid='Release 2&per.1'.Release 2&per.1:elink.:pd.The second public release&per.
  215. :pt.:link reftype=hd refid='Release 2&per.0'.Release 2&per.0:elink.:pd.The first public release&per.
  216. :eparml.
  217. :p.
  218. :h2 id='Release 2&per.2'.Release 2&per.2, July 1997
  219. :ul.
  220. :li.Fixed a minor bug with templates&per. As the template tags are parsed separately
  221. things like '&.' inside e&per.g&per. a :font facename=Courier size=16x8.@defun:font facename=default size=0x0. tag slipped through our fingers&per.
  222. :li.Fixed a not so minor bug with menus&per. Sometimes the end of menu environments
  223. were not recognized correctly&per. This lead to plenty of handywork (try the
  224. Texinfo documentation with the old version and you will know what I mean)&per.
  225. :li.Added a Rexx file written by Hans-Michael Stahl for those who do not like
  226. typing more than necessary &colon.-)
  227. :eul.
  228. :p.
  229. :h2 id='Release 2&per.1'.Release 2&per.1, February 1997
  230. :ul.
  231. :li.Added this documentation&per.
  232. :li.Added enhanced support for footnotes&per. Produces real IPF footnotes now instead of
  233. Text in brackets&per.
  234. :li.Changed the handling of all :font facename=Courier size=16x8.@*heading:font facename=default size=0x0. commands and added the missing
  235. :font facename=Courier size=16x8.@chapheading:font facename=default size=0x0. command&per. They will no longer produce nodes but rather
  236. produce real headings like in the Info file&per.
  237. :p.This makes it more consistent to the commands' definition saying they
  238. do not generate Table-Of-Contents entries&per. Note, that all the other
  239. :font facename=Courier size=16x8.@chapter:font facename=default size=0x0., :font facename=Courier size=16x8.@*section:font facename=default size=0x0., :font facename=Courier size=16x8.@unnumbered*:font facename=default size=0x0. commands do
  240. :hp1.not:ehp1. generate headings inside the text window as these lines
  241. appear in the title of the frame anyway&per.
  242. :li.Upped stack size under OS/2 to 0x30000 Bytes&per.
  243. :li.Changed the :font facename=Courier size=16x8.setclear():font facename=default size=0x0. and :font facename=Courier size=16x8.findtag():font facename=default size=0x0. routine&per. The program
  244. now no longer crashes with large :font facename=Courier size=16x8.@set:font facename=default size=0x0. names&per.
  245. :li.:font facename=Courier size=16x8.@ignore:font facename=default size=0x0. will now be handled like real comments&per.
  246. :li.Fixed a bug in :font facename=Courier size=16x8.eat_first_word():font facename=default size=0x0. that made the program crash
  247. sometimes&per.
  248. :li.Fixed the handling of a few :font facename=Courier size=16x8.@def*:font facename=default size=0x0. commands (index entry)&per.
  249. :li.Added routine :font facename=Courier size=16x8.remove_texicmds():font facename=default size=0x0. for better formatting of
  250. automatically created index entries from :font facename=Courier size=16x8.@def*:font facename=default size=0x0. commands&per.
  251. :li.Menu entry descriptions can now be continued in the next line(s) if
  252. indented more than 25 columns&per. Also use :font facename=Courier size=16x8.remove_texicmds():font facename=default size=0x0. when
  253. processing menu entries&per.
  254. :li.Added support for the :font facename=Courier size=16x8.@bye:font facename=default size=0x0. tag for leaving the document before
  255. the physical end of file&per.
  256. :eul.
  257. :p.
  258. :h2 id='Release 2&per.0'.Release 2&per.0, December 1996
  259. :ul.
  260. :li.Converted any K&.R stuff to ANSI C (prototypes etc&per.)&per. Still the code
  261. looks rather shrouded &colon.-)
  262. :li.Changed the table&per.h for a better handling of all the :font facename=Courier size=16x8.@def*:font facename=default size=0x0. stuff&per. Now
  263. any definition will start with a new paragraph&per. The leading "--" will
  264. not appear anymore&per. I also added the :font facename=Courier size=16x8.@deftp:font facename=default size=0x0. command and the pseudo-
  265. Texinfo command :font facename=Courier size=16x8.@ifhtml:font facename=default size=0x0. (ignored, no error message) that may be used
  266. by users of texi2html and the :font facename=Courier size=16x8.@macro:font facename=default size=0x0. command (ignored, no error mes-
  267. sage)&per.
  268. :li.Added my name to the banner &colon.-)
  269. :li.Removed the :font facename=Courier size=16x8.#include <string&per.h>:font facename=default size=0x0. from texi2ipf&per.h and added it to those
  270. &per.c files that needed it&per.
  271. :li.Texinfo menus will now be simulated in the output &per.ipf file&per. This
  272. is not really necessary but it looks better than blank pages&per.
  273. :li.:font facename=Courier size=16x8.@include:font facename=default size=0x0. statements inside of menus will no longer crash the program&per.
  274. :li.All Texinfo :font facename=Courier size=16x8.@def*:font facename=default size=0x0. commands will now produce an index entry in
  275. the main index&per. Support for seperate indices like "Concept index",
  276. "Types index" etc&per. may be possible in future but has not yet been
  277. added&per. The :font facename=Courier size=16x8.@printindex:font facename=default size=0x0. command still produces the "Sorry, no
  278. &per.&per.&per. index" entry in the resulting &per.IPF file&per. Commands dealing with
  279. custom indices will now produce a more verbose error (ignore) message&per.
  280. :li.Changed the makefile&per. Compiles well under Unix systems (AIX and
  281. LINUX) and with IBM's VisualAge C++ for OS/2&per.
  282. :li.Added support for pseudo-Texinfo command @ipfline{} (my invention)
  283. for entering IPF commands into the Texinfo source file&per. The syntax
  284. is&colon. "@ipfline{<Sequence of IPF code not longer than one line>}" and
  285. it should be put into :font facename=Courier size=16x8.@ifinfo:font facename=default size=0x0. / :font facename=Courier size=16x8.@end ifinfo:font facename=default size=0x0. blocks to
  286. avoid trouble with e&per.g&per. texi2dvi or texi2html&per.
  287. :eul.
  288. :euserdoc.
  289.