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