Directory indexing/makeindex/src
README
% /u/sy/beebe/tex/makeindex/2-12/makeindex/src/README, Wed May 26 11:25:46 1993 % Edit by Nelson H. F. Beebe <beebe@plot79.math.utah.edu> ================================================================= = As of the release of MakeIndex version 2.9, the original = author, Pehong Chen, is no longer able to maintain it, and is = inaccessible via electronic mail. The maintenance job has been = taken over for the TeX User's Group by = = Nelson H. F. Beebe = Center for Scientific Computing = Department of Mathematics = University of Utah = Salt Lake City, UT 84112 = USA = Tel: +1 801 581 5254 = FAX: +1 801 581 4148 = Email: <beebe@math.utah.edu> = = to whom reports of problems, ports to new environments, and = general correspondence about MakeIndex, should be addressed. ================================================================= ================== Building MakeIndex ================== Makefiles for numerous systems are provided in the distribution as the files makefile.*; select the appropriate one, and copy it to Makefile. For systems that lack a suitable make implementation, command files (*.bat and *.com) are provided. In many cases, once the makefile has been selected, you should be able to do make (cd ../test; make) and if the acceptance tests in that second step all pass (there should be no output from any of the files differences, except on VAX VMS, where a couple of lines differing only in letter case, are expected), then on many UNIX systems, you may be able to do make install to install the executable and manual pages on your system. For version 2.12, the code has been updated to support compilation with numerous C++ compilers. No features of the C++ language are used that do not also exist in C, but the stricter compile-time checking provided by C++ compilers provides additional confidence in the code. Thanks go to P. J. Plauger for his efforts in the ANSI/ISO Standard C and C++ environments, and for promoting the idea of using C++ compilers for C code development. If you have a C++ compiler, please try a build of MakeIndex with a command like (select the one that corresponds to the name of your C++ compiler) make CC=CC make CC=xlC make CC=g++ Any problems with C++ compilations should be reported back to the address above. Before doing so however, check that BINDIR and MANDIR are set to your local conventions (you can override the values in the Makefile by setting them on the command-line), and also verify that you do not have a brain-damaged install implementation that either requires root privileges to run (e.g. IBM AIX), or moves (instead of copies) files (e.g. Stardent or DEC ULTRIX). In the latter case, you might be able to instead do make cp-install If you want to undo the installation, make uninstall should work. There are additional documentation files in ../doc that you may want to install manually (Emacs info, local help systems, VAX VMS help). ==================== Compilation Problems ==================== The standardization of the C language by ANSI X3.159-1989 Programming Language--C (December 15, 1989), and ISO C 1990, has resulted in C implementations gradually being adapted to conform to the requirements of the Standard, but released for use before Standard conformance has been reached. For a lot of C code, this affects several main areas: (1) system header files, and what symbols they define (2) function prototype declarations (3) new preprocessor statements, and more precisely-defined preprocessor behavior (4) new features introduced by Standard C (const, adjacent string concatenation, new style function definitions, new string escape sequences, trigraphs, new data types) MakeIndex has successfully compiled and run on many different operating systems and C implementations, but until Standard C becomes uniformly implemented, the first two above are the most troublesome. The code in MakeIndex is written to conform to Standard C, which is distinguished by the preprocessor symbol __STDC__ being permanently defined to a non-zero value. Unfortunately, some implementations define this symbol without having Standard-conforming header files, or without accepting some of the new language features. In MakeIndex, function definitions are done in the old Kernighan and Ritchie style in a pre-Standard C environment, but in Standard C and C++ style if __STDC__ or __cplusplus are defined. All functions referenced are declared by function prototype declarations of the form static void check_idx ARGS((char *fn,int open_fn)); where ARGS is defined in mkind.h to expand such a declaration to static void check_idx (char *fn,int open_fn); or static void check_idx (); depending on whether the compiler supports function prototype declarations or not. If you get syntax errors from the new style, you may need to revert to the old style by introducing a #define STDC_PROTOTYPES 0 statement in the appropriate section of mkind.h. Some compilers partly support the function prototypes, but without variable names; use the old-style for them, and complain to your compiler supplier. When STDC_PROTOTYPES is non-zero, it is assumed that the Standard C type modifier "const" is recognized; if your compiler complains about it, add a #define const definition in mkind.h, or use a compile-time option -Dconst=; either of these make it expand to an empty string, so the compiler doesn't see it. Standard C specifies the data types of all library functions and their arguments, and the system header files are required to declare them appropriately. Nevertheless, some implementations have a few erroneous declarations in the header files and still claim to be Standard conforming (by defining the symbol __STDC__ to a non-zero value). On such systems, the extra compile-time type checking provided by function prototype declarations may raise compilation errors, and it may be necessary to adjust declarations in any of the files that use the ARGS macro (genind.c, mkind.c, mkind.h, qsort.c, scanid.c, scanst.c, and sortid.c) to make the code conform to the local implementation's erroneous declarations. Numerous external variables and functions in MakeIndex require long names (at least 12 unique characters). For older systems that do not support long names, make sure the symbol SHORTNAMES is defined to a non-zero value in mkind.h; this is already done for supported systems that need it. Standard C requires uniqueness in the first 6 characters of external names, WITHOUT distinction between upper- and lower-case letters, so implementations that do not allow long external names are NOT in violation of the Standard. If you get compiler warnings about conversion of integers to pointers, or find that rindex() or index() cannot be unresolved by the linker, then check the settings in mkind.h. The default is to use the Standard C functions strchr() and strrchr(), but on a few non-conforming systems, to remap these names to index() and rindex() instead. Any other integer-to-pointer conversion warnings are likely to be traced to missing function prototype declarations, which is either because of an omission in system header files, or because the MakeIndex declaration in one of its source files was not selected during the preprocessing step. When the MakeIndex source code is compiled correctly, EVERY function used by MakeIndex will have been declared in a function prototype prior to its first use. ====================== VAX VMS Considerations ====================== Different versions of VAX VMS C have used different interpretations of the arguments to return() and exit() statements. The convention on UNIX and many other systems is that a 0 value denotes success, and a non-zero value, failure. The EXIT() macro in mkind.h hides the remapping of this value for VAX VMS; for other systems, it calls exit() directly. For VAX VMS, MakeIndex should be declared to be a foreign command symbol in a system-wide, or user, startup file that is executed at each login. Here is an example: $ makeindex :== $public$disk:[beebe.MakeIndex.src]makeindex.exe The leading dollar sign identifies this as a foreign command symbol, and must be followed by an ABSOLUTE file specification for the executable program; this regrettably makes it site dependent, and the definitions in ../test/vmsdiff.com and elsewhere must be adjusted accordingly. The symbol SW_PREFIX in mkind.h can be redefined from '-' to '/' for those VAX VMS sites that prefer to retain VMS-style command-line options; the default value is '-' on all systems. This redefinition can be done on the command line, or by changing the setting in mkind.h. =============== Machines Tested =============== Here is a list of machines, operating systems, and compilers under which MakeIndex 2.12 has been successfully tested. Convenience targets in the Makefile provide support for them on UNIX. Command files are provided for MS DOS and VAX VMS. ------------------------------------------------------------------------ Machine O/S Compiler(s) ------------------------------------------------------------------------ DEC Alpha 3000/500X OSF 1.2 cc, c89, cxx DECstation 3100 ULTRIX 4.2 and 4.3 cc, gcc, g++, lcc DEC VAX VMS 5.4-2 cc HP 9000/735 HP-UX 9.01 cc, c89, CC, gcc, g++ HP 9000/850 HP-UX 9.0 cc, c89 IBM 3090/600S-VF AIX 2.1 cc (Metaware High C 2.1t), CC IBM PS/2 AIX 2.1 cc (Metaware High C 2.2g), CC IBM RS/6000 AIX 3.2 cc, xlC MIPS R6000 RISC/os 5.0 cc NeXT Mach 3.0 cc, Objective C, gcc Sun SPARCstation SunOS 4.1.3 apcc, cc, CC, gcc, g++ ------------------------------------------------------------------------
