README for libkpathsea-perl: a Perl interface to the Kpathsea library
and Perl alternatives to the mktex{mf,tfm,pk} scripts
=====================================================================

Current version: 3.3.1.1 (3.030101) - ALPHA release
Based on the Kpathsea library, version 3.3.1.

This is an alpha release of my Perl modules to interface to the
Kpathsea library and to provide the functionality of the kpsewhich
program.  Also included is a set of Perl scripts which can be used as
alternatives to the mktex{mf,tfm,pk} shell scripts.

        *** PLEASE SEE THE WARNING BELOW BEFORE ***
        *** YOU TRY INSTALLING THIS SOFTWARE    ***

I want to make absolutely clear that these Perl scripts are *NOT*
intended to replace the shell scripts in the distribution, but rather
to be an alternative.  As has been discussed on the tex-k list, it is
not practical to expect everyone to have a Perl distribution in order
to use the teTeX/texk/web2c TeX distribution.

What there is so far
--------------------

The TeX::Kpathsea module, which provides a relatively low-level
interface to the Kpathsea[rch] library.

The TeX::Kpsewhich module, which provides an object-oriented interface
to the TeX::Kpathsea library, with functionality similar to that of
the kpsewhich program.

Three Perl scripts, mktexmf, mktextfm, mktexpk, which together with
the TeX::Mktex module provide alternatives to the shell script
versions of these programs.  These are almost identical in
functionality to their shell script equivalents, and differ in only
very small ways.  For example, the decision about whether to use the
system tree or alternative tree for storing newly created fonts is
based on the writeability of the directory into which the font would
be placed rather than on the root of the font tree.

Full documentation of the TeX::Kpathsea and TeX::Kpsewhich modules.

A piece of simple test code.

Two makefiles: Makefile.PL for building and installing the Perl code,
and Makefile.swig for recreating the wrappers using SWIG.

What is missing
---------------

The current versions of the mktex* scripts are basically the same as
the shell script versions.  The intention is to have improved security
provisions: the main Perl scripts will be able to be made setuid tex
(where tex owns the font tree) and will decide whether to execute as
tex (after making appropriate security checks) and to place the newly
created font in the system tree, or as the user, placing the fonts in
the user's current or home directory as appropriate, so that the tree
can be read-only to normal users

How to install this
-------------------

You will require a working Perl 5.x installation, and a working teTeX
(or equivalent) installation.  The Kpathsea version must be at least
3.3 (you can run kpsewhich --version to find the version number);
teTeX 1.0.X will work, as will TeX Live 4.  You will also need to have
compiled and installed the Kpathsea headers and libkpathsea.so shared
library or libkpathsea.a static library (respectively achieved using
the --enable-shared and --enable-static configure options).

If you wish to rebuild the C wrapper file source using SWIG, you can
use the Makefile.swig file to achieve this.  There is no need to do
this, however.

To install the rest of the package:
  perl Makefile.PL
  make
  make install

You may wish to give these three commands additional options to
influence the compilation (using, for example, INSTALLDIRS=perl for
the "perl Makefile.PL" command, OPTIMIZE='-g -Wall' for the "make"
command, or PREFIX=/usr/local for the "make install" command).  Please
see Makefile.PL and ExtUtils::MakeMaker(3pm) for more details.

If your kpathsea header files or library are in non-standard
locations, you can run something like
  make INC=-I/usr/local/teTeX/include OTHERLDFLAGS=-L/usr/local/teTeX/lib
to search the correct directories during compilation.  (Unfortunately,
there does not appear to be a simple way to specify the library path
during the perl Makefile.PL step without losing the values of these
variables from Also, you will
need to set the environment variable LD_LIBRARY_PATH to a sensible
value if you have linked against a shared libkpathsea.so which is not
in the standard library search path (as defined by /etc/ld.so.conf).

*** WARNING: This package will, by default, install the three mktex*
*** scripts in the $(PREFIX)/bin directory, which may well have the
*** effect of overwriting your existing mktex* programs.  If you do
*** not wish to overwrite them, you should either choose an
*** appropriate PREFIX setting, or you can set EXE_FILES='' to prevent
*** the mktex* files from even being considered.


Author etc.
-----------

This code is copyright by Julian Gilbey <jdg@debian.org>, 1999, and is
released under the GNU Public License, version 2 or later.  No
warranty is implied.  See the copyright file for more details.

Any feedback is more than welcome.

