home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / prog / c / mi_1_49b.lha / readme.amiga < prev    next >
Text File  |  1992-11-25  |  11KB  |  222 lines
  1.  
  2.  
  3.  
  4.  
  5.                                makeinfo 1.49
  6.  
  7.  
  8.       A modified GNU makeinfo by Reinhard Spisser and Sebastiano Vigna
  9.  
  10.  
  11.                                November 1992
  12.  
  13.  
  14. This program is distributed under the GNU General Public License. Please
  15. refer to the COPYING file for details.
  16.  
  17. If you want to write your own Texinfo documentation (and not just converting
  18. pre-existing Texinfo docs), you will need the GNU Texinfo distribution,
  19. available on many ftp sites (e.g., prep.ai.mit.edu). This distribution
  20. archive contains also an executable version of texindex, so that you don't
  21. need any other file in order to fully exploit Texinfo. Should this
  22. distribution archive not contain the full sources of texindex and makeinfo,
  23. you can get them by sending a self-addressed, stamped envelope and a disk to
  24. either one of the authors, or by searching for the complete distribution on
  25. an ftp site.
  26.  
  27.  
  28. (Note that from this release makeinfo is a Release 2 only program, but you
  29. won't need the ixemul.library, because makeinfo has been compiled under the
  30. GNU 2.2 port by Davide Pasetto of Agemo [available at the ftp site
  31. amiga.physik.unizh.ch]; for the same reason, you can stop at any time the
  32. program via CTRL-C, or suspend it in wait state via CTRL-D; in the latter
  33. case, you can resume via CTRL-E).
  34.  
  35.  
  36. This project started with the idea of bringing to the Amiga community a set
  37. of tools which would have greatly simplified the handling of on-line help as
  38. opposed to a printed manual. Currently, the Amiga programmer has to keep two
  39. separate files which have to be updated in parallel. If also some hypertext
  40. feature is desired, the document writer has to keep a third version of the
  41. file (since AmigaGuide® is still not enough spread that one can assume the
  42. user will have it somehow).
  43.  
  44. This is unbearable. And indeed, the GNU people have found a great way of
  45. working around this problem. It's called Texinfo.
  46.  
  47. A Texinfo document is written in a very simple dialect of TeX that is easy
  48. to learn and use, and it's specifically tailored for the creation of
  49. technical manuals. Texinfo focuses on logical aspects---so the @t{} command,
  50. which typeset in fixed width font whatever is in the braces, should be never
  51. used, and rather replaced with @code{}, @file{} or @key{}, depending on the
  52. semantics of the text involved. This also ensures that each user can
  53. customized its Texinfo macros in such a way to spot out specific parts of a
  54. Texinfo file, or to set a different page size, text formatting etc.
  55.  
  56. Of course, the format has to be rich enough to express all the needs of a
  57. technical manual, and small enough to allow a decent translation of all the
  58. available constructs to plain ASCII (for an hypotetical hypertext viewer).
  59. Also in this respect Texinfo is an excellent balance.
  60.  
  61. Full documentation is available on how to write a Texinfo document. It is
  62. written, of course, in Texinfo, and is very clear. You should be able to
  63. start authoring a Texinfo document in an hour or so. If you're used to TeX,
  64. ten minutes will suffice. This documentation can be found on most ftp sites
  65. which have GNU stuff. The latest version of Texinfo we know of is 2.16. It's
  66. a final, very stable version.
  67.  
  68. Once a Texinfo document is ready, it can be converted in one of the
  69. following ways:
  70.  
  71. 1) It can be passed through TeX using the set of macros texinfo.tex. You
  72. will get a beautiful printed manual.
  73.  
  74. 2) It can be passed through the standard makeinfo in its Info mode; it will
  75. generate an Info document (Info is the GNU hypertext reader). This is not
  76. much of interest for you.
  77.  
  78. 3) It can be passed through makeinfo with the --no-headers option; it will
  79. generate an almost plain ASCII text file (cross references and indices will
  80. still be in Info style).
  81.  
  82. But with our version of makeinfo,
  83.  
  84. 4) It can be passed through makeinfo with the new --amiga option; it will
  85. generate an AmigaGuide® document; cross references, menus and indices will
  86. become buttons.
  87.  
  88. 5) It can be passed through makeinfo with the --amiga --no-headers options;
  89. it will generate a plain ASCII text file.
  90.  
  91. Thus, you have to maintain just a document in order to produce a printed
  92. manual, on-line hypertext documentation and plain ASCII documentation.
  93. Texinfo of course relies on a series of information you specify, like menus,
  94. cross references, etc., but the amount of work you'll need to do this will
  95. be very small. It also makes a great job in converting to ASCII---for
  96. instance, @emph{} text, which comes out slanted in the manual, is shown with
  97. two asterisk around. We would like to urge all of the Amiga community
  98. programmers, in particular the people distributing documentation as a file,
  99. to start using Texinfo. It will be an enormous quantum leap.
  100.  
  101. While we were working on the project, it became clear that much more was
  102. possible with this new tool. For instance, all of the GNU software comes
  103. with Texinfo documentation. It was a matter of a couple of minutes to make
  104. the Texinfo manual (500K!) into an AmigaGuide® file that we could browse at
  105. will, in full AmigaGuide® hypertext.
  106.  
  107.  
  108. Every port of this kind has of course some kind of tradeoff. Info and
  109. AmigaGuide® have a rather vaste intersection of features, but both have
  110. specific features that can't be mimicked on the other side.
  111.  
  112. The main design choice at the specification level was that *every* Texinfo
  113. should have been convertible to an AmigaGuide® file. And that *every*
  114. Texinfo file prepared for AmigaGuide® should have been convertible to Info
  115. format (this is essential, e.g., for people doing cross-development).
  116.  
  117. Fortunately, we were enough lucky: all Info features are translatable in
  118. AmigaGuide® features, excepted for file splitting; but AmigaGuide® doesn't
  119. load a file entirely---just loads a part of it. So even a 1 megabyte
  120. document is not a problem for it. Info instead relies on a splitting
  121. mechanism which is in makeinfo: this mechanism is disabled by the option
  122. --amiga.
  123.  
  124. There are also a couple of problem with the representation of buttons; Info
  125. does not have "real" buttons---it just put in the text something of the form
  126. "*Note Nodename::". Thus, the aspect of a line in Info or AmigaGuide® is
  127. very different. We chose to put in the button name only the "real title" of
  128. the button, i.e., the destination node name if nothing else is specified, or
  129. the second argument of a @ref, @xref or @pxref command if available.
  130. Moreover, we noted that the absence of "*Note"'s had made the text a bit
  131. unpleasant to read; so we inserted "see" and "See" whenever Texinfo would
  132. have done it in the printed text.
  133.  
  134. For menus, Texinfo relies on the visualisation of *both* the button name
  135. *and* the destination node name when building indices. Cutting away the
  136. destination node name would have resulted in a horribly looking index. So we
  137. decided to preserve the visualization of the destination node name after a
  138. menu button when building an index. A normal menu will instead show just a
  139. button.
  140.  
  141. Also, we slightly improved an aspect of @pxref. Since no ending point was
  142. needed before the closing parenthesis, we stripped it off.
  143.  
  144. All the features of Info which maps to AmigaGuide® have been implemented.
  145. Thus, the Top node of a Texinfo document will become the Main node of the
  146. AmigaGuide® file, the @master command will be set to the name of the Texinfo
  147. file, and the @width command will be set to the value makeinfo is using for
  148. formatting text.
  149.  
  150. The --no-headers option has now a better behaviour when also --amiga is
  151. selected. "*Note"'s are replaced by "see", etc.. The result is a completely
  152. human readable ASCII file.
  153.  
  154. It should also be noted that unfortunately Texinfo doesn't have any way of
  155. specifying a *line* in a node. So this feature of AmigaGuide® is not
  156. representable in a Texinfo file. This is indeed the biggest drawback of
  157. using Texinfo for writing AmigaGuide® documents. But we feel that the
  158. advantages are definitely overwhelming.
  159.  
  160. Due to the fact that AmigaGuide® is rather picky about the characters it
  161. allows in a button name or in a node name, at least for the time being
  162. makeinfo has to replace in a node name every slash or backslash with a dash
  163. and every quotes with a single open quote. Still, names with curly braces in
  164. them will behave incorrectly. But this is an AmigaGuide® problem.
  165.  
  166. Note that Texinfo doesn't support officially extended or accented
  167. characters. The workaround, for the time being, is to use ASCII extended
  168. characters like à, etc. in the text (in place of the various \`, etc.
  169. commands). Makeinfo will process the document flawlessly, and by including
  170. the amigatexinfo.tex file supplied in this distribution archive *before*
  171. texinfo.tex into your document, Texinfo will typeset correctly the accented
  172. characters (this should work on any TeX system which supports TeX 3.0; we
  173. tried successfully AmigaTeX and PasTeX). We would like to thank Tom Rokicki
  174. for allowing us to distribute the amigatexinfo.tex file, which is based on
  175. the amiga.tex file supplied in the distribution of Radical Eye's AmigaTeX,
  176. and for his invaluable assistance in adapting amiga.tex to Texinfo. Note
  177. also that the first (October) release of makeinfo 1.49 had an incorrect
  178. amiga.tex file, which did not work with many foreign characters.
  179.  
  180. Finally, we want to describe some bugs we found both in Texinfo and
  181. AmigaGuide®, whose knowledge can be helpful.
  182.  
  183. AmigaGuide® 33.1369 doesn't work properly if the name of a button contains
  184. an apostrophe ("'"). So you shouldn't use button names containing @code{},
  185. @samp{}, etc. (they are always forbidden in node names, but you can specify
  186. a button name different from the node name in an external reference
  187. command). The workaround is to not use apostrophes in button names
  188. (AmigaGuide® V34 and V39 doesn't suffer from this problem).
  189.  
  190. Texinfo 2.16 will insert an unnamed TOC entry for the Top node when the
  191. automatic pointer generation feature of makeinfo is used (that is, your Top
  192. node is defined via @node Top followed by @top). You should include the
  193. whole Top node in a @ifinfo/@end ifinfo pair for the time being.
  194.  
  195. Texinfo 2.16 will print an extra '*' while underlining chapters (when
  196. --no-headers is activated). In particular, a stand-alone asterisk will
  197. appear at the top of the document if you use the @top command.
  198.  
  199. (These bugs have been reported to GNU, of course).
  200.  
  201. Good Texinfoing! Please send any bug report or enhancement request to
  202.  
  203.  
  204.     Reinhard Spisser
  205.     Via Bonghi 15
  206.     I-20141 Milano MI
  207.  
  208.     BIX: reinhards
  209.     INTERNET: rein@bliss.st.dsi.unimi.it
  210.  
  211.  
  212.     Sebastiano Vigna
  213.     Via California 22
  214.     I-20144 Milano MI
  215.  
  216.     BIX: svigna
  217.     INTERNET: vigna@imiucca.csi.unimi.it
  218.               vigna@ghost.sm.dsi.unimi.it
  219.     UUCP:cbmehq!cbmita!sebamiga!seba@cbmvax.cbm.commodore.com
  220.          ...{uunet|pyramid|rutgers}!cbmvax!cbmehq!cbmita!sebamiga!seba
  221.     FIDO: 2:332/607.28
  222.