home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fonts 1 / freshfonts1.bin / bbs / programs / amiga / makeindex.lha / makeindex-2.12 / src / README < prev    next >
Text File  |  1993-06-04  |  10KB  |  264 lines
  1. % /u/sy/beebe/tex/makeindex/2-12/makeindex/src/README, Wed May 26 11:25:46 1993
  2. % Edit by Nelson H. F. Beebe <beebe@plot79.math.utah.edu>
  3. =================================================================
  4. = As of the release of MakeIndex version 2.9, the original
  5. = author, Pehong Chen, is no longer able to maintain it, and is
  6. = inaccessible via electronic mail.  The maintenance job has been
  7. = taken over for the TeX User's Group by
  8. =
  9. =      Nelson H. F. Beebe
  10. =      Center for Scientific Computing
  11. =      Department of Mathematics
  12. =      University of Utah
  13. =      Salt Lake City, UT 84112
  14. =      USA
  15. =      Tel: +1 801 581 5254
  16. =      FAX: +1 801 581 4148
  17. =      Email: <beebe@math.utah.edu>
  18. =
  19. = to whom reports of problems, ports to new environments, and
  20. = general correspondence about MakeIndex, should be addressed.
  21. =================================================================
  22.  
  23.  
  24. ==================
  25. Building MakeIndex
  26. ==================
  27.  
  28. Makefiles for numerous systems are provided in the distribution
  29. as the files makefile.*; select the appropriate one, and copy it
  30. to Makefile.  For systems that lack a suitable make
  31. implementation, command files (*.bat and *.com) are provided.
  32.  
  33. In many cases, once the makefile has been selected, you should be
  34. able to do
  35.  
  36.     make
  37.     (cd ../test; make)
  38.  
  39. and if the acceptance tests in that second step all pass (there
  40. should be no output from any of the files differences, except on
  41. VAX VMS, where a couple of lines differing only in letter case,
  42. are expected), then on many UNIX systems, you may be able to do
  43.  
  44.     make install
  45.  
  46. to install the executable and manual pages on your system.
  47.  
  48. For version 2.12, the code has been updated to support compilation
  49. with numerous C++ compilers.  No features of the C++ language are used
  50. that do not also exist in C, but the stricter compile-time checking
  51. provided by C++ compilers provides additional confidence in the code.
  52. Thanks go to P. J. Plauger for his efforts in the ANSI/ISO Standard C
  53. and C++ environments, and for promoting the idea of using C++
  54. compilers for C code development.
  55.  
  56. If you have a C++ compiler, please try a build of MakeIndex with a
  57. command like (select the one that corresponds to the name of your C++
  58. compiler)
  59.  
  60.     make CC=CC
  61.     make CC=xlC
  62.     make CC=g++
  63.  
  64. Any problems with C++ compilations should be reported back to the
  65. address above.
  66.  
  67. Before doing so however, check that BINDIR and MANDIR are set to
  68. your local conventions (you can override the values in the
  69. Makefile by setting them on the command-line), and also verify
  70. that you do not have a brain-damaged install implementation that
  71. either requires root privileges to run (e.g. IBM AIX), or moves
  72. (instead of copies) files (e.g. Stardent or DEC ULTRIX).  In the
  73. latter case, you might be able to instead do
  74.  
  75.     make cp-install
  76.  
  77. If you want to undo the installation,
  78.  
  79.     make uninstall
  80.  
  81. should work.
  82.  
  83. There are additional documentation files in ../doc that you may
  84. want to install manually (Emacs info, local help systems, VAX VMS
  85. help).
  86.  
  87.  
  88. ====================
  89. Compilation Problems
  90. ====================
  91.  
  92. The standardization of the C language by ANSI X3.159-1989
  93. Programming Language--C (December 15, 1989), and ISO C 1990, has
  94. resulted in C implementations gradually being adapted to conform
  95. to the requirements of the Standard, but released for use before
  96. Standard conformance has been reached.  For a lot of C code, this
  97. affects several main areas:
  98.  
  99.     (1) system header files, and what symbols they define
  100.     (2) function prototype declarations
  101.     (3) new preprocessor statements, and more
  102.         precisely-defined preprocessor behavior
  103.     (4) new features introduced by Standard C (const,
  104.         adjacent string concatenation, new style function
  105.         definitions, new string escape sequences, trigraphs,
  106.         new data types)
  107.  
  108. MakeIndex has successfully compiled and run on many different
  109. operating systems and C implementations, but until Standard C
  110. becomes uniformly implemented, the first two above are the most
  111. troublesome.
  112.  
  113. The code in MakeIndex is written to conform to Standard C, which
  114. is distinguished by the preprocessor symbol __STDC__ being
  115. permanently defined to a non-zero value.  Unfortunately, some
  116. implementations define this symbol without having
  117. Standard-conforming header files, or without accepting some of
  118. the new language features.
  119.  
  120. In MakeIndex, function definitions are done in the old Kernighan and
  121. Ritchie style in a pre-Standard C environment, but in Standard C and
  122. C++ style if __STDC__ or __cplusplus are defined.
  123.  
  124. All functions referenced are declared by function prototype
  125. declarations of the form
  126.  
  127. static    void    check_idx ARGS((char *fn,int open_fn));
  128.  
  129. where ARGS is defined in mkind.h to expand such a declaration to
  130.  
  131. static    void    check_idx (char *fn,int open_fn);
  132.  
  133. or
  134.  
  135. static    void    check_idx ();
  136.  
  137. depending on whether the compiler supports function prototype
  138. declarations or not.  If you get syntax errors from the new
  139. style, you may need to revert to the old style by introducing a
  140.  
  141. #define STDC_PROTOTYPES 0
  142.  
  143. statement in the appropriate section of mkind.h.  Some compilers
  144. partly support the function prototypes, but without variable
  145. names; use the old-style for them, and complain to your compiler
  146. supplier.
  147.  
  148. When STDC_PROTOTYPES is non-zero, it is assumed that the Standard
  149. C type modifier "const" is recognized; if your compiler complains
  150. about it, add a
  151.  
  152. #define const
  153.  
  154. definition in mkind.h, or use a compile-time option -Dconst=;
  155. either of these make it expand to an empty string, so the
  156. compiler doesn't see it.
  157.  
  158. Standard C specifies the data types of all library functions and
  159. their arguments, and the system header files are required to
  160. declare them appropriately.  Nevertheless, some implementations
  161. have a few erroneous declarations in the header files and still
  162. claim to be Standard conforming (by defining the symbol __STDC__
  163. to a non-zero value).  On such systems, the extra compile-time
  164. type checking provided by function prototype declarations may
  165. raise compilation errors, and it may be necessary to adjust
  166. declarations in any of the files that use the ARGS macro
  167. (genind.c, mkind.c, mkind.h, qsort.c, scanid.c, scanst.c, and
  168. sortid.c) to make the code conform to the local implementation's
  169. erroneous declarations.
  170.  
  171. Numerous external variables and functions in MakeIndex require
  172. long names (at least 12 unique characters). For older systems
  173. that do not support long names, make sure the symbol SHORTNAMES
  174. is defined to a non-zero value in mkind.h; this is already done
  175. for supported systems that need it.  Standard C requires
  176. uniqueness in the first 6 characters of external names, WITHOUT
  177. distinction between upper- and lower-case letters, so
  178. implementations that do not allow long external names are NOT in
  179. violation of the Standard.
  180.  
  181. If you get compiler warnings about conversion of integers to
  182. pointers, or find that rindex() or index() cannot be unresolved
  183. by the linker, then check the settings in mkind.h.  The default
  184. is to use the Standard C functions strchr() and strrchr(), but on
  185. a few non-conforming systems, to remap these names to index() and
  186. rindex() instead.  Any other integer-to-pointer conversion
  187. warnings are likely to be traced to missing function prototype
  188. declarations, which is either because of an omission in system
  189. header files, or because the MakeIndex declaration in one of its
  190. source files was not selected during the preprocessing step.
  191. When the MakeIndex source code is compiled correctly, EVERY
  192. function used by MakeIndex will have been declared in a function
  193. prototype prior to its first use.
  194.  
  195.  
  196. ======================
  197. VAX VMS Considerations
  198. ======================
  199.  
  200. Different versions of VAX VMS C have used different
  201. interpretations of the arguments to return() and exit()
  202. statements.  The convention on UNIX and many other systems is
  203. that a 0 value denotes success, and a non-zero value, failure.
  204. The EXIT() macro in mkind.h hides the remapping of this value for
  205. VAX VMS; for other systems, it calls exit() directly.
  206.  
  207. For VAX VMS, MakeIndex should be declared to be a foreign command
  208. symbol in a system-wide, or user, startup file that is executed
  209. at each login.  Here is an example:
  210.  
  211. $ makeindex :== $public$disk:[beebe.MakeIndex.src]makeindex.exe
  212.  
  213. The leading dollar sign identifies