summaryrefslogtreecommitdiff
path: root/indexing/makeindex/src/README
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /indexing/makeindex/src/README
Initial commit
Diffstat (limited to 'indexing/makeindex/src/README')
-rw-r--r--indexing/makeindex/src/README263
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++
+
+------------------------------------------------------------------------