diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /indexing/makeindex/src/README |
Initial commit
Diffstat (limited to 'indexing/makeindex/src/README')
-rw-r--r-- | indexing/makeindex/src/README | 263 |
1 files changed, 263 insertions, 0 deletions
diff --git a/indexing/makeindex/src/README b/indexing/makeindex/src/README new file mode 100644 index 0000000000..4b3413ec93 --- /dev/null +++ b/indexing/makeindex/src/README @@ -0,0 +1,263 @@ +% /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++ + +------------------------------------------------------------------------ |