##=============================================================================
## 
## This file is part of BibTool.
## It is distributed under the GNU General Public License.
## See the file COPYING for details.
## 
## (c) 1996-1999 Gerd Neugebauer
## 
## Net: gerd.neugebauer@sdm.de
##      gerd.neugebauer@gmx.de
## 
##*****************************************************************************

This file contains instructions and hints for the compilation of BibTool.

Table of Contents

	 0. Introduction
	 1. Prerequisites
	 2. Generic Installation Procedure
	 3. Installation on UNIX
	 4. Installation on MSDOS-like Computers
	 5. Installation on Amiga
	 6. Installation without make
	 7. Using the kpathsea library
	 8. Problems and Porting
         9. The C Interface
	10. The Tcl/Tk Interface



0. Introduction
===============

BibTool is known to work on the following operating systems/C compilers: (At
least an earlier version has been compiled successfully on them.)

	Sun4/SunOS4.1.*		cc, gcc
	SparcStation/Solaris2.4 gcc
	SparcStation/Solaris2.5 gcc
	Sun3/SunOS4.1.1		cc
	HP 9000/4??/HP UX ??	cc
	Atari ST/TOS 1.2	Laser C, Pure C

I   have been informed  that   BibTool has  been  compiled  on the following
machines/operating systems (and maybe some more that I have forgotten to add
to this list;-):

	AIX 3.2.5		gcc
	AIX 4.1.4
	Amiga			SAS/C
	DEC Alpha/OSF/1		
	HP 9000/778/HP-UX 10.20 gcc 2.7.2.3
	Linux			gcc
	MIPS/Ultrix4.4		gcc 2.4.5
	MIPS/RISCos 4.52	gcc
	MSDOS,OS/2,Win32,WinNT  emx, dj, Watcom C, MSC
	IBM PC 486DX2-66, OS/2 Merlin 4.0 FixPack #5. EMX v.0.9c+GCC+dmake 4.0
	OS/2
	NeXT			
	SGI Indigo2/IRIX 6.2	cc

If you compile  BibTool on other systems drop  me a mail. I'm  interested to
support a broad variety of systems/compilers.


	Gerd Neugebauer
	Mainzer Str. 8
	56321 Rhens (Germany)

	Net: gerd.neugebauer@sdm.de
	     gerd.neugebauer@gmx.de

You can also send me a mail if  you encounter problems in compiling BibTool,
or crashes, or shows  unexpected (contradicting the documentation)  behavior
of the final program.

Please enclose a  precise description what went  wrong.  Include the version
numbers  of  BibTool,  your computer,   your operating system,   and  your C
compiler.

If  you encounter unexpected   behavior  of  BibTool enclose  your  resource
file(s) and a  _SMALL_ BibTeX file  demonstrating the problem.  Describe how
you have invoked BibTool (arguments) and justify why you think that there is
a problem.

I know that this sounds like work.  But otherwise I will not be able to give
you proper advice or find a bug in the sources.


1. Prerequisites
================

To install BibTool you need:

-   A C compiler. ANSI-C is not required but highly recommended.
    Several library functions are expected. You will see if your linker
    complains.
-   A running version of make is recommended.


2. Generic Installation Procedure
=================================

See if there  is a special section for  your computer/C  compiler and follow
the instructions given there.  Most probably  you will be directed back into
this section after some initial actions.

See Section 7 and see if it applies to your setting.

To install BibTool you can try to apply the following instructions:

 A  Copy one of the  prepared makefiles to makefile  and adjust it according
    to your C compiler.   The following makefiles  should be present  in the
    distribution:

    makefile.unx
	This is the generic makefile. Especially it  is for all UN*X systems
	and may provide  a basis for  compilation on systems not  explicitly
	mentioned here.
    makefile.dos
	This is the makefile for MSDOS based machines.
    makefile.ata
	This is the makefile for Atari ST/TT computers.
    makefile.ami
	This is the makefile for Amiga computers (with SAS/C).

    Edit the makefile  and adjust the settings  in the configuration section
    according to your needs.

    Maybe you have to adapt the name and  options for your C compiler. (Most
    of the time I prefer the GNU C compiler)

    Maybe you want to change the location  for the installation target, even
    though reasonable defaults are provided.

 B  Look  into  the file  include/bibtool/config.h to  see   if it fits your
    operating  system  and C  compiler.   Adjust  things  as required.  Most
    probably you do not have to change anything in  this file.  This file is
    mainly for those with an old C compiler (non-ANSI).

 C  If you want to configure some of the internals of BibTool you can have a
    look   into   include/bibtool/bibtool.h.    It  contains   the  internal
    configuration   options which used to  be  in  config.h prior to release
    2.39.  Most  probably there is   no need to   change the defaults  given
    there.  One exception is the  support for another language by specifying
    additional words to  be ignored.  (Maybe I could  include them into  the
    distribution; thus drop me a mail if you do so)

 D  If you have a working makedepend command run

	make depend 

    Otherwise just skip this step. It is only helpful if you compile BibTool
    more than once.

    This might cause  problems if the makedepend  command does not fit the C
    compiler used  (e.g.  proprietary  makedpend  together  with gcc).  This
    results in unknown files to  show up.  In  this case also skip this step
    and revert to the original makefile.

 E  Afterwards run

	make

    Most probably   this    should produce   the  executable    bibtool  (or
    bibtool.exe, or bibtool.ttp, or ...) in the current directory.

 F  If you have tried the command bibtool in the current directory
    you can install it with

	make install

    to install the executable and the libraries and

	make install.man

    to install the UN*X  man pages. This is only  useful if you can make use
    of them, i.e. on a UN*X-like system.

 G  To get rid of all intermediate files run

	make clean

 H  To prepare the documentation contained  in the subdirectory Doc  go into
    the Doc subdirectory and run

	latex   bibtool
	latex   bibtool
	bibtex  bibtool
	makeidx bibtool
	latex   bibtool
	latex   bibtool

    The makeidx program  may be named differently on  your system or missing
    at all. In this case you can omit this step and do without the index.

    On UN*X you can try

	make doc

    which tries to perform the steps given above.

    The documentation is written in a way that either LaTeX or LaTeX2.09 can
    be used to compile it. I had a bug report about a real ancient LaTeX2.09
    and  I am not sure  I have completely fixed it.  Thus the best is to use
    an up-to-date LaTeX.

    There might be problems when files produced by  LaTeX2.09 should be read
    by  LaTeX2e  and vice versa.   In  this case  you can try  to remove the
    intermediate files

	bibtool.toc
	bibtool.ind

    and follow   the  instruction for making    the  documentation from  the
    beginning.



3. Installation on UNIX
=======================

Some special preparations have been made for UNIX systems.  autoconf scripts
are  provided which  try  to find  out the   characteristics  of  the system
automatically.

General instructions:

 A  Run the configure script with the command:

	./configure

    The following options are useful for configure:

    --with-kpathsea	    try  to find the kpathsea  library either in the
			    current  directory     or  in    the    previous
			    directory.  Thus  you  can  place  the   BibTool
			    directory   in  the same    directory  where the
			    directory kpathsea  resides  or you can put  the
			    kpathsea directory in in the BibTool directory.
			    (default) (See also section 7)
    --without-kpathsea	    disable the search for the kpathsea library.
    --prefix=PREFIX         install architecture-independent files in PREFIX
			    [/usr/local]
    --exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
                            [same as prefix]
    --bindir=DIR            the bibtool executable is stored in DIR
			    [EPREFIX/bin]
    --libdir=DIR            the BibTool directory containing certain
			    resource files are stored in DIR [EPREFIX/lib]
    --mandir=DIR	    the manual pages bibtool.1 is stored in DIR
			    [PREFIX/man]

 B  Continue with the item C in section 2.


4. Installation on MSDOS-like Computers
=======================================

This  section some hints on  the compilation of  BibTool on MSDOS computers.
These adaptions   are  mainly  due   to  the   efforts  of   Josef  Spangler
(JS@rphnw3.ngate.uni-regensburg.de). All credits  go to him.  Any  remaining
problems should be blamed on my ignorance.

General instructions:

 A  Copy   makefile.dos   to makefile  and adjust  it   according  to your C
    compiler.

 B  Edit include/bibtool/config.h and include/bibtool/bibtool.h to adjust it
    to your needs.  Normally you should be interested only in the support of
    emTeX at the end of include/bibtool/bibtool.h.

 C  Copy  MSDOS\link.*  to the source directory.

 D  Depending on the C compiler do the following:

    - dj  (GNU C port)

	make dj

    - emx (GNU C port)

	make emx

      Maybe you have to set the environment variable EMX to point to the 
      installed EMX directory.

    - Watcom C 386 (32 Bit Compiler for Dos, OS/2 2.x, Win32 and WinNT)

	make wat

    - Microsoft C 6.00A (16 Bit Dos and OS/2 1.x)

	make msc

    - Borland C++ 3.1 (16 Bit Dos)
	Go and get another compiler. 
	Or, even better do the port and send me the diffs :-)

 E  If you have tried the command bibtool in the current directory
    you can install it with

	make install

 F  Make the documentation according to step H in section 2.


5. Installation on Amiga
========================

This section contains  some  hints on the  compilation  of BibTool  on Amiga
computers. These adaptions are mainly due to the  efforts of Andreas Scherer
(SCHERER@genesis.informatik.rwth-aachen.de).   All  credits go  to him.  Any
remaining problems should be blamed on my ignorance.

This section describes the installation procedure if you are using the SAS/C
compiler on Amiga.

General instructions:

 A  Copy  makefile.ami  to  SMakefile
    and adjust it accordingly.

 B  Edit the file include/bibtool/config.h and include/bibtool/bibtool.h and
    adjust it to your needs.  There should not be much for you to change.

 C  	make

 E  If you have tried the command bibtool in the current directory
    you can install it with

	make install

 D  Make the documentation according to step H in section 2.


6. Installation without make
============================

 A  Adjust   the   settings  in   the   files  include/bibtool/config.h  and
    include/bibtool/bibtool.h to fit your C compiler and operating system.

 B  Compile all .c files in  the base directory.  The macros REGEX and maybe
    MSDOS should be defined.  The subdirectory regex-0.12 should be included
    in the include search path.  A typical compile command looks like

	cc main.c -c -o main.o -DREGEX -DMSDOS -Iregex-0.12 -I.

 C  Compile regex.c in the regex-0.12 subdirectory  and move the object file
    into the base directory (The one containing this file).

 D  Link together all object files to get the executable bibtool.
    (maybe include the kpathsea library; see section 6)

 E  Run  LaTeX  on  bibtool.tex  in  the  Doc  subdirectory  to  produce the
    documentation.  (see step H in section 2 for details)


7. Using the kpathsea library
=============================

The kpathsea library provides a very flexible way to specify the search path
for files.  This  library is already used by  the web2c distribution of Karl
Berry  and the teTeX distribution.   To achieve compatibility with those TeX
systems you can try to make BibTool use the same library.


The kpathsea library is  currently  NOT  CONTAINED  in the  distribution  of
BibTool since this is  an experimental feature.  You  can get  kpathsea from
the same location where you  got BibTool.  Fetch  the file kpse2-6.tar.gz or
kpse2-6.zip.

Unpack   this file.   Enter  the  directory kpse2-6   and  use the  commands
`./configure' and `make' to create the library. This works  at least on Unix
platforms. For porting to other platforms I would like to get some feedback.

ATTENTION: The kpathsea library has to exists before BibTool is made!

If  you are  using  configure then the  option  --with-kpathsea  enables the
inclusion of the kpathsea routines if the library is found.

To use  the library you can just  provide three definitions in the makefile.
See the section about kpathsea in  makefile for explanations.  Alternatively
you have to provide the appropriate options to the C compiler yourself.

Note: the searching for BibTeX files  with the kpathsea library is different
from the BibTool built-in searching. Some resources are no longer taken into
account when this library is used.

Note: kpathsea is only used to search for BibTeX files.  All other files are
still searched with the traditional BibTool searching mechanism.  This might
change soon.


8. Problems and Porting
=======================

Well, if the procedures described above don't work I have some hints.  These
hints may also  be  useful if you plan to port  BibTool  to other  operating
systems or C compilers.

First of all a small list of assumptions that I use.

 -  On ANSI systems there should be no problem at all. There is some support
    for non-ANSI  systems.  This support  can be improved.  (I don't know if
    it's worthwhile to do so).

 -  BibTool  has  been  developed  on  UN*X  (SunOS)  and  UN*X-like systems
    (Atari).  Such file/directory naming  conventions  found their way  into
    the code.  Single character delimiters between directories and files can
    be modified in a resource file.

 -  ASCII encoding is assumed.
    I  role  my  own type.h  instead  of  using  ctypes.h.  This  has mainly
    historical reasons. Maybe this code should be rewritten to be adapted at
    make time.

    If you  port BibTool  to a  non-ASCII  machine the  table of  characters
    (allowed[]) in type.h has to  be adapted -- at least (please send me the
    diffs).

 -  Maybe some BSD-isms found their way into the code even if I am not aware
    of it.


9. The C Interface
==================

The C interface to  BibTool is described in the  document Doc/c_lib.dvi.  To
create this  document run LaTeX and makeindex  on the  file c_lib.tex in the
Doc subdirectory:

	latex c_lib
	makeindex c_lib
	latex c_lib
	latex c_lib

Read this document. I would like some kind of feedback for this attempt.

Attention: This documentation is experimental.  Some things are likely to be
	   changed soon.


10. The Tcl/Tk Interface
========================

The  Tcl/Tk interface  is  called  BibTcl.  It is  contained  in  the BibTcl
subdirectory. See the file README in this directory for details.