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