summaryrefslogtreecommitdiff
path: root/Build/source/texk/kpathsea/INSTALL
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-17 21:41:51 +0000
committerKarl Berry <karl@freefriends.org>2006-01-17 21:41:51 +0000
commit487ca4806cc046076293cf6cc5fbba0db282bac7 (patch)
tree847b412ab5158dd7bdd7ed7e5a4cc3fbca94be32 /Build/source/texk/kpathsea/INSTALL
parenta3d3111bfe26b8e5f5bc6049dfb2a4ca2edc7881 (diff)
texk 1
git-svn-id: svn://tug.org/texlive/trunk@1485 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/texk/kpathsea/INSTALL')
-rw-r--r--Build/source/texk/kpathsea/INSTALL849
1 files changed, 849 insertions, 0 deletions
diff --git a/Build/source/texk/kpathsea/INSTALL b/Build/source/texk/kpathsea/INSTALL
new file mode 100644
index 00000000000..9b3e5621cb7
--- /dev/null
+++ b/Build/source/texk/kpathsea/INSTALL
@@ -0,0 +1,849 @@
+Contents:
+
+1 Installation
+ 1.1 Simple installation
+ 1.2 Custom installation
+ 1.2.1 Disk space
+ 1.2.2 Kpathsea application distributions
+ 1.2.3 Changing search paths
+ 1.2.3.1 Default path features
+ 1.2.3.2 Default path generation
+ 1.2.4 Running `configure'
+ 1.2.4.1 `configure' shells
+ 1.2.4.2 `configure' options
+ 1.2.4.3 `configure' environment
+ 1.2.4.4 `configure' scenarios
+ 1.2.4.5 Shared library
+ 1.2.5 Running `make'
+ 1.2.6 Installing files
+ 1.2.7 Cleaning up
+ 1.2.8 Filename database generation
+ 1.2.9 `mktex' scripts
+ 1.2.9.1 `mktex' configuration
+ 1.2.9.2 `mktex' script names
+ 1.2.9.3 `mktex' script arguments
+ 1.2.10 Installation testing
+ 1.3 Security
+
+
+1 Installation
+**************
+
+The procedure for Kpathsea (and Web2c, etc.) configuration and
+installation follows. If you encounter trouble, see *Note Common
+problems::, a copy of which is in the file `kpathsea/BUGS'.
+
+1.1 Simple installation
+=======================
+
+Installing TeX and friends for the first time can be a daunting
+experience. Thus, you may prefer to skip this whole thing and just get
+precompiled executables: see *Note unixtex.ftp::.
+
+ This section explains what to do if you wish to take the defaults for
+everything, and generally to install in the simplest possible way. Most
+steps here refer to corresponding subsection in the next section which
+explains how to override defaults and generally gives more details.
+
+ By default everything will be installed under `/usr/local' and the
+following discussion assumes this. However, if you already have TeX
+installed, its location is used to derive the directory under which
+everything is to be installed.
+
+ 1. Be sure you have enough disk space: approximately 8 megabytes for
+ the compressed archives, 15MB for sources, 50MB for compilation,
+ 40MB for the (initial) installed system (including library files).
+ *Note Disk space::.
+
+ 2. Retrieve these distribution archives:
+ `ftp://ftp.tug.org/tex/texk.tar.gz'
+ These are the sources, which you will be compiling.
+
+ `ftp://ftp.tug.org/tex/texklib.tar.gz'
+ This is a basic set of input files. You should unpack it in
+ the directory `/usr/local/share'; doing so will create a
+ `texmf' subdirectory there.
+
+ These archives are mirrored on the CTAN hosts, in the
+ `systems/web2c' directory.
+
+ *Note Kpathsea application distributions::.
+
+ 3. When using the default search paths, there is no need to edit any
+ distribution files. *Note Changing search paths::.
+
+ 4. At the top level of the distribution, run `sh configure'. (If you
+ have the GNU Bash shell installed, run `bash configure'.) *Note
+ Running configure::.
+
+ 5. `make'. *Note Running make::. If you are using a BSD 4.4 system
+ such as FreeBSD or NetBSD, you may have to use GNU make (often
+ installed in `/usr/local/bin'), not the BSD make.
+
+ 6. `make install'. *Note Installing files::.
+
+ 7. `make distclean'. *Note Cleaning up::.
+
+ 8. Set up a cron job to rebuild the filename database that makes
+ searching faster. This line will rebuild it every midnight:
+ 0 0 * * * cd /usr/local/share/texmf && /BINDIR/mktexlsr
+ *Note Filename database generation::, and *Note Filename
+ database::.
+
+ 9. If you're installing Dvips, you also need to set up configuration
+ files for your printers and make any additional PostScript fonts
+ available. *Note Installation: (dvips)Installation. If you have
+ any color printers, see *Note Color device configuration:
+ (dvips)Color device configuration.
+
+ 10. The first time you run a DVI driver, a bunch of PK fonts will be
+ built by Metafont via `mktexpk' (and added to the filename
+ database). This will take some time. Don't be alarmed; they will
+ created only this first time (unless something is wrong with your
+ path definitions).
+
+ By default, `mktexpk' will create these fonts in a hierarchy under
+ `/var/tmp/texfonts'; it simply assumes that `/var/tmp' exists and
+ is globally writable. If you need a different arrangement, see
+ *Note mktex configuration::.
+
+ *Note mktex scripts::.
+
+ 11. For some simple tests, try `tex story \\bye' and `latex sample2e'.
+ Then run `xdvi story' or `dvips sample2e' on the resulting DVI
+ files to preview/print the documents. *Note Installation
+ testing::.
+
+1.2 Custom installation
+=======================
+
+Most sites need to modify the default installation procedure in some
+way, perhaps merely changing the prefix from `/usr/local', perhaps
+adding extra compiler or loader options to work around `configure'
+bugs. This section explains how to override default choices. For
+additional distribution-specific information:
+ * `dviljk/INSTALL'.
+
+ * *Note Installation: (dvips)Installation.
+
+ * *Note Installation: (web2c)Installation.
+
+ * `xdvik/INSTALL'.
+
+ These instructions are for Unix systems. Other operating-system
+specific distributions have their own instructions. The code base
+itself supports Amiga, DOS, OS/2, and VMS.
+
+ Following are the same steps as in the previous section (which
+describes the simplest installation), but with much more detail.
+
+1.2.1 Disk space
+----------------
+
+Here is a table showing the disk space needed for each distribution
+(described in the next section). The `(totals)' line reflects the
+`texk' source distribution and `texklib'; the individual distributions
+don't enter into it. Sizes are in megabytes. All numbers are
+approximate.
+
+Distribution .tar.gz Unpacked Compiled Installed
+dviljk .9 3.8
+dvipsk .9 3.2
+xdvik .7 2.5
+web2c 1.3 5.0
+web 1.9 6.5 - -
+texk 7.5 32.1 95.3 33.5
+texklib 6.3 15.0 - 15.0
+(totals) 14.6 47.1 95.3 48.5
+
+1.2.2 Kpathsea application distributions
+----------------------------------------
+
+The archive `ftp://ftp.tug.org/tex/texk.tar.gz' contains all of the
+Kpathsea applications I maintain, and the library itself. For example,
+since NeXT does not generally support X11, you'd probably want to skip
+`xdvik' (or simply remove it after unpacking `texk.tar.gz'. If you are
+not interested in all of them, you can also retrieve them separately:
+
+`dviljk.tar.gz'
+ DVI to PCL, for LaserJet printers.
+
+`dvipsk.tar.gz'
+ DVI to PostScript, for previewers, printers, or PDF generation.
+
+`web2c.tar.gz'
+ The software needed to compile TeX and friends.
+
+`web.tar.gz'
+ The original WEB source files, also used in compilation.
+
+`xdvik.tar.gz'
+ DVI previewing under the X window system.
+
+
+ If you want to use the Babel LaTeX package for support of non-English
+typesetting, you may need to retrieve additional files. See the file
+`install.txt' in the Babel distribution.
+
+1.2.3 Changing search paths
+---------------------------
+
+If the search paths for your installation differ from the standard TeX
+directory structure (*note Introduction: (tds)Top.), edit the file
+`kpathsea/texmf.in' as desired, before running `configure'. For
+example, if you have all your fonts or macros in one big directory.
+
+ You may also wish to edit the file `mktex.cnf', either before or
+after installation, to control various aspects of `mktexpk' and
+friends. *Note mktex configuration::.
+
+ You do not need to edit `texmf.in' to change the default top-level or
+other installation _directories_ (only the paths). You can and should
+do that when you run `configure' (next step).
+
+ You also do not need to edit `texmf.in' if you are willing to rely on
+`texmf.cnf' at runtime to define the paths, and let the compile-time
+default paths be incorrect. Usually there is no harm in doing this.
+
+ The section below explains default generation in more detail.
+
+1.2.3.1 Default path features
+.............................
+
+The purpose of having all the different files described in the section
+above is to avoid having the same information in more than one place. If
+you change the installation directories or top-level prefix at
+`configure'-time, those changes will propagate through the whole
+sequence. And if you change the default paths in `texmf.in', those
+changes are propagated to the compile-time defaults.
+
+ The Make definitions are all repeated in several Makefile's; but
+changing the top-level `Makefile' should suffice, as it passes down all
+the variable definitions, thus overriding the submakes. (The
+definitions are repeated so you can run Make in the subdirectories, if
+you should have occasion to.)
+
+ By default, the bitmap font paths end with `/$MAKETEX_MODE', thus
+including the device name (usually a Metafont mode name such as
+`ljfour'). This distinguishes two different devices with the same
+resolution--a write/white from a write/black 300dpi printer, for
+example.
+
+ However, since most sites don't have this complication, Kpathsea
+(specifically, the `kpse_init_prog' function in `kpathsea/proginit.c')
+has a special case: if the mode has not been explicitly set by the user
+(or in a configuration file), it sets `MAKETEX_MODE' to `/'. This
+makes the default PK path, for example, expand into `.../pk//', so
+fonts will be found even if there is no subdirectory for the mode (if
+you arranged things that way because your site has only one printer,
+for example) or if the program is mode-independent (e.g., `pktype').
+
+ To make the paths independent of the mode, simply edit `texmf.in'
+before installation, or the installed `texmf.cnf', and remove the
+`$MAKETEX_MODE'.
+
+ *Note mktex script arguments::, for how this interacts with `mktexpk'.
+
+ *Note TeX directory structure: TeX directory structure, for a
+description of the default arrangement of the input files that comprise
+the TeX system. The file `kpathsea/HIER' is a copy of that section.
+
+1.2.3.2 Default path generation
+...............................
+
+This section describes how the default paths are constructed.
+
+ You may wish to ignore the whole mess and simply edit `texmf.cnf'
+after it is installed, perhaps even copying it into place beforehand so
+you can complete the installation, if it seems necessary.
+
+ To summarize the chain of events that go into defining the default
+paths:
+
+ 1. `configure' creates a `Makefile' from each `Makefile.in'.
+
+ 2. When Make runs in the `kpathsea' directory, it creates a file
+ `texmf.sed' that substitutes the Make value of `$(var)' for a
+ string `@var@'. The variables in question are the one that define
+ the installation directories.
+
+ 3. `texmf.sed' (together with a little extra magic--see
+ `kpathsea/Makefile') is applied to `texmf.in' to generate
+ `texmf.cnf'. This is the file that will eventually be installed
+ and used.
+
+ 4. The definitions in `texmf.cnf' are recast as C `#define''s in
+ `paths.h'. These values will be the compile-time defaults; they
+ are not used at runtime unless no `texmf.cnf' file can be found.
+
+ (That's a lie: the compile-time defaults are what any extra :'s in
+ `texmf.cnf' expand into; but the paths as distributed have no extra
+ :'s, and there's no particular reason for them to.)
+
+1.2.4 Running `configure'
+-------------------------
+
+Run `sh configure OPTIONS' (in the top-level directory, the one
+containing `kpathsea/'), possibly using a shell other than `sh' (*note
+configure shells::).
+
+ `configure' adapts the source distribution to the present system via
+`#define''s in `*/c-auto.h', which are created from the corresponding
+`c-auto.in'. It also creates a `Makefile' from the corresponding
+`Makefile.in', doing `@VAR@' and `ac_include' substitutions).
+
+ `configure' is the best place to control the configuration,
+compilation, and installed location of the software, either via
+command-line options, or by setting environment variables before
+invoking it. For example, you can disable `mktexpk' by default with
+the option `--disable-mktexpk'. *Note configure options::.
+
+1.2.4.1 `configure' shells
+..........................
+
+Considerable effort has gone into trying to ensure that the `configure'
+scripts can be run by most Bourne shell variants. If `sh' runs into
+trouble, your best bet is to use Bash, the GNU Bourne-again shell
+(*note Top: (bash)Top.).
+
+ Bourne shell variants for which problems have been reported in the
+past are:
+`ksh'
+ Old versions of the Korn shell may fail to handle the scripts.
+ The Korn shell may be installed as `/bin/sh' on AIX, in which case
+ `/bin/bsh' may serve instead.
+
+`ash'
+ Old versions of ash are unable to handle the scripts. Ash is
+ sometimes installed as `/bin/sh' on NetBSD, FreeBSD, and Linux
+ systems. `/bin/bash' should be available for those systems, but
+ might not be part of a default installation.
+
+`Ultrix /bin/sh'
+ `/bin/sh' under Ultrix is a DEC-grown shell that is notably
+ deficient in many ways. `/bin/sh5' may be necessary.
+
+1.2.4.2 `configure' options
+...........................
+
+For a complete list of all `configure' options, run `configure --help'
+or see *Note Running `configure' scripts: (autoconf)Invoking configure,
+(a copy is in the file `kpathsea/README.CONFIGURE'). The generic
+options are listed first in the `--help' output, and the
+package-specific options come last. The environment variables
+`configure' pays attention to are listed below.
+
+ Options particularly likely to be useful are `--prefix', `--datadir',
+and the like; see *Note configure scenarios::.
+
+ This section gives pointers to descriptions of the `--with' and
+`--enable' options to `configure' that Kpathsea-using programs accept.
+
+`--without-mktexmf-default'
+`--without-mktexpk-default'
+`--without-mktextfm-default'
+`--with-mktextex-default'
+ Enable or disable the dynamic generation programs. *Note mktex
+ configuration::.
+
+`--enable-shared'
+ Build Kpathsea as a shared library, and link against it. Also
+ build the usual static library. *Note Shared library::.
+
+`--disable-static'
+ Build only the shared library. Implies `--enable-shared'.
+
+`--enable-maintainer-mode'
+ Enables make targets that are useful for the maintainer and likely
+ to be a pain for anyone else; the makefiles created when this
+ option is enabled may not work at all for you. You have been
+ warned.
+
+1.2.4.3 `configure' environment
+...............................
+
+`configure' uses the value of the following environment variables in
+determining your system's characteristics, and substitutes for them in
+Makefile's:
+
+`CC'
+ The compiler to use: default is `gcc' if it's installed, otherwise
+ `cc'.
+
+`CFLAGS'
+ Options to give the compiler: default is `-g -O2' for `gcc', `-g'
+ otherwise. `CFLAGS' comes after any other options. You may need
+ to include `-w' here if your compilations commonly have useless
+ warnings (e.g., `NULL redefined'), or `configure' may fail to
+ detect the presence of header files (it takes the messages on
+ standard error to mean the header file doesn't exist).
+
+`CPPFLAGS'
+ Options to pass to the compiler preprocessor; this matters most for
+ configuration, not the actual source compilation. The `configure'
+ script often does only preprocessing (e.g., to check for the
+ existence of #include files), and `CFLAGS' is not used for this.
+ You may need to set this to something like
+ `-I/usr/local/include/wwwhatever' if you have the libwww library
+ installed for hyper-xdvik (see `xdvik/INSTALL').
+
+`DEFS'
+ Additional preprocessor options, but not used by `configure'.
+ Provided for enabling or disabling program features, as documented
+ in the various program-specific installation instructions. `DEFS'
+ comes before any compiler options included by the distribution
+ `Makefile's or by `configure'.
+
+`LDFLAGS'
+ Additional options to give to the loader. `LDFLAGS' comes before
+ any other linker options.
+
+`LIBS'
+ Additional libraries to link with.
+
+1.2.4.4 `configure' scenarios
+.............................
+
+Here are some common installation scenarios:
+
+ * Including X support in Metafont. This is disabled by default,
+ since many sites have no use for it, and it's a leading cause of
+ configuration problems.
+ configure --with-x
+
+ * Putting the binaries, TeX files, GNU info files, etc. into a single
+ TeX hierarchy, say `/here/texmf', requires overriding defaults in
+ `configure':
+ configure --prefix=/here/texmf --datadir=/here
+
+ * You can compile on multiple architectures simultaneously either by
+ building symbolic link trees with the `lndir' script from the X11
+ distribution, or with the `--srcdir' option:
+ configure --srcdir=SRCDIR
+
+ * If you are installing binaries for multiple architectures into a
+ single hierarchy, you will probably want to override the default
+ `bin' and `lib' directories, something like this:
+ configure --prefix=TEXMF --datadir=TEXMF \
+ --bindir=TEXMF/ARCH/bin --libdir=TEXMF/ARCH/lib
+ make texmf=TEXMF
+ (Unless you make provisions for architecture-specific files in
+ other ways, e.g., with Depot or an automounter.)
+
+ * To compile with optimization (to compile without debugging, remove
+ the `-g'):
+ env CFLAGS="-g -O" sh configure ...
+ For a potential problem if you optimize, see *Note TeX or Metafont
+ failing: TeX or Metafont failing.
+
+1.2.4.5 Shared library
+......................
+
+You can compile Kpathsea as a shared library on a few systems, by
+specifying the option `--enable-shared' when you run `configure'.
+
+ The main advantage in doing this is that the executables can then
+share the code, thus decreasing memory and disk space requirements.
+
+ On some systems, you can record the location of shared libraries in a
+binary, usually by giving certain options to the linker. Then
+individual users do not need to set their system's environment variable
+(e.g., `LD_LIBRARY_PATH') to find shared libraries. If you want to do
+this, you will need to add the necessary options to `LDFLAGS' yourself;
+for example, on Solaris, include something like `-R${prefix}/lib', on
+IRIX or Linux, use `-rpath${prefix}/lib'. (Unfortunately, making this
+happen by default is very difficult, because of interactions with an
+existing installed shared library.)
+
+ Currently, shared library support is implemented only on Linux, SunOS
+4 (Solaris 1), SunOS 5 (Solaris 2), IRIX 5, and IRIX 6. If you're
+interested and willing in adding support for other systems, please see
+the `configure' mode in the `klibtool' script, especially the
+host-specific case statement around line 250.
+
+1.2.5 Running `make'
+--------------------
+
+`make' (still in the top-level directory). This also creates the
+`texmf.cnf' and `paths.h' files that define the default search paths,
+and (by default) the `plain' and `latex' TeX formats.
+
+ You can override directory names and other values at `make'-time.
+`make/paths.make' lists the variables most commonly reset. For
+example, `make default_texsizes=600' changes the list of fallback
+resolutions.
+
+ You can also override each of `configure''s environment variables
+(*note configure environment::). The Make variables have the same
+names.
+
+ Finally, you can supply additional options via the following
+variables. (`configure' does not use these.)
+
+`XCPPFLAGS'
+`XDEFS'
+ Preprocessor options.
+
+`XCFLAGS'
+ Compiler options.
+
+`XLDFLAGS'
+ Loader options (included at beginning of link commands).
+
+`XLOADLIBES'
+ More loader options (included at end of link commands).
+
+`XMAKEARGS'
+ Additional Make arguments passed to all sub-`make''s. You may need
+ to include assignments to the other variables here via `XMAKEARGS';
+ for example: `make XMAKEARGS="CFLAGS=-O XDEFS=-DA4"'.
+
+ It's generally a bad idea to use a different compiler (`CC') or
+libraries (`LIBS') for compilation than you did for configuration,
+since the values `configure' determined may then be incorrect.
+
+ Adding compiler options to change the "universe" you are using
+(typically BSD vs. system V) is generally a cause of trouble. It's
+best to use the native environment, whatever that is; `configure' and
+the software usually adapt best to that. In particular, under Solaris
+2.x, you should not use the BSD-compatibility library (`libucb') or
+include files (`ucbinclude').
+
+ If you want to use the Babel LaTeX package for support of non-English
+typesetting, you need to modify some files before making the LaTeX
+format. See the file `install.txt' in the Babel distribution.
+
+1.2.6 Installing files
+----------------------
+
+The basic command is the usual `make install'. For security issues,
+*note Security::.
+
+ The first time you install any manual in the GNU Info system, you
+should add a line (you choose where) to the file `dir' in your
+`$(infodir)' directory. Sample text for this is given near the top of
+the Texinfo source files (`kpathsea/kpathsea.texi',
+`dvipsk/dvips.texi', and `web2c/doc/web2c.texi'). If you have a recent
+version of the GNU Texinfo distribution installed
+(`ftp://prep.ai.mit.edu/pub/gnu/texinfo-3.9.tar.gz' or later), this
+should happen automatically.
+
+ On the offchance that this is your first Info installation, the `dir'
+file I use is included in the distribution as `etc/dir-example'.
+
+ You may wish to use one of the following targets, especially if you
+are installing on multiple architectures:
+ * `make install-exec' to install in architecture-dependent
+ directories, i.e., ones that depend on the `$(exec_prefix)' Make
+ variable. This includes links to binaries, libraries, etc., not
+ just "executables".
+
+ * `make install-data' to install in architecture-independent
+ directories, such as documentation, configuration files, pool
+ files, etc.
+
+ If you use the Andrew File System, the normal path (e.g., PREFIX/bin)
+only gets you to a read-only copy of the files, and you must specify a
+different path for installation. The best way to do this is by setting
+the `prefix' variable on the `make' command line. The sequence becomes
+something like this:
+ configure --prefix=/whatever
+ make
+ make install prefix=/afs/.SYSTEM.NAME/system/1.3/@sys/whatever
+ With AFS, you will definitely want to use relative filenames in
+`ls-R' (*note Filename database::), not absolute filenames. This is
+done by default, but check anyway.
+
+1.2.7 Cleaning up
+-----------------
+
+The basic command is `make distclean'. This removes all files created
+by the build.
+
+ Alternatively,
+ * `make mostlyclean' if you intend to compile on another
+ architecture. For Web2C, since the generated C files are portable,
+ they are not removed. If the `lex' vs. `flex' situation is going
+ to be different on the next machine, `rm web2c/lex.yy.c'.
+
+ * `make clean' to remove files created by compiling, but leave
+ configuration files and Makefiles.
+
+ * `make maintainer-clean' to remove everything that the Makefiles can
+ rebuild. This is more than `distclean' removes, and you should
+ only use it if you are thoroughly conversant with (and have the
+ necessary versions of) Autoconf.
+
+ * `make extraclean' to remove other junk, e.g., core files, log
+ files, patch rejects. This is independent of the other `clean'
+ targets.
+
+1.2.8 Filename database generation
+----------------------------------
+
+You will probably want to set up a `cron' entry on the appropriate
+machine(s) to rebuild the filename database nightly or so, as in:
+ 0 0 * * * cd TEXMF && /BINDIR/mktexlsr
+ *Note Filename database::.
+
+ Although the `mktex...' scripts make every effort to add
+newly-created files on the fly, it can't hurt to make sure you get a
+fresh version every so often.
+
+1.2.9 `mktex' scripts
+---------------------
+
+If Kpathsea cannot otherwise find a file, for some file types it is
+configured by default to invoke an external program to create it
+dynamically (*note mktex configuration::). This is most useful for
+fonts (bitmaps, TFM's, and arbitrarily-sizable Metafont sources such as
+the Sauter and EC fonts), since any given document can use fonts never
+before referenced. Trying to build all fonts in advance is therefore
+impractical, if not impossible.
+
+ The script is passed the name of the file to create and possibly other
+arguments, as explained below. It must echo the full pathname of the
+file it created (and nothing else) to standard output; it can write
+diagnostics to standard error.
+
+1.2.9.1 `mktex' configuration
+.............................
+
+The following file types can run an external program to create missing
+files: `pk', `tfm', `mf', `tex'; the scripts are named `mktexpk',
+`mktextfm', `mktexmf', and `mktextex'.
+
+ In the absence of `configure' options specifying otherwise,
+everything but `mktextex' will be enabled by default. The `configure'
+options to change the defaults are:
+
+ --without-mktexmf-default
+ --without-mktexpk-default
+ --without-mktextfm-default
+ --with-mktextex-default
+
+ The `configure' setting is overridden if the environment variable or
+configuration file value named for the script is set; e.g., `MKTEXPK'
+(*note mktex script arguments::).
+
+ As distributed, all the scripts source a file `texmf/web2c/mktex.cnf'
+if it exists, so you can override various defaults. See `mktex.opt',
+for instance, which defines the default mode, resolution, some special
+directory names, etc. If you prefer not to change the distributed
+scripts, you can simply create `mktex.cnf' with the appropriate
+definitions (you do not need to create it if you have nothing to put in
+it). `mktex.cnf' has no special syntax; it's an arbitrary Bourne shell
+script. The distribution contains a sample `mktex.cnf' for you to copy
+and modify as you please (it is not installed anywhere).
+
+ In addition, you can configure a number of features with the
+`MT_FEATURES' variable, which you can define:
+ * in `mktex.opt', as just mentioned;
+
+ * by editing the file `mktex.opt', either before `make install' (in
+ the source hierarchy) or after (in the installed hierarchy);
+
+ * or in the environment.
+
+ If none of the options below are enabled, `mktexpk', `mktextfm', and
+`mktexmf' follow the following procedure to decide where fonts should
+be installed. Find the tree where the font's sources are, and test the
+permissions of the `fonts' directory of that tree to determine whether
+it is writable. If it is, put the files in the tree in appropriate
+locations. If it isn't writable, see whether the tree is a system tree
+(named in `SYSTEXMF'). If so, the `VARTEXFONTS' tree is used. In all
+other cases the working directory is used.
+
+ The `appendonlydir' option is enabled by default.
+
+`appendonlydir'
+ Tell `mktexdir' to create directories append-only, i.e., set their
+ sticky bit (*note Mode Structure: (coreutils)Mode Structure.).
+ This feature is silently ignored on non-Unix platforms (e.g.
+ Windows/NT and MS-DOS) which don't support similar functionality.
+ This feature is enabled by default.
+
+`dosnames'
+ Use 8.3 names; e.g., `dpi600/cmr10.pk' instead of `cmr10.600pk'.
+ Note that this feature only affects filenames that would otherwise
+ clash with other TeX-related filenames; `mktex' scripts do nothing
+ about filenames which exceed the 8+3 MS-DOS limits but remain
+ unique when truncated (by the OS) to these limits, and nether do
+ the scripts care about possible clashes with files which aren't
+ related with TeX. For example, `cmr10.600pk' would clash with
+ `cmr10.600gf' and is therefore changed when `dosnames' is in
+ effect, but `mf.pool' and `mp.base' don't clash with any
+ TeX-related files and are therefore unchanged.
+
+ This feature is turned on by default on MS-DOS. If you do not wish
+ `dosnames' to be set on an MS-DOS platform, you need to set the
+ `MT_FEATURES' environment variable to a value that doesn't include
+ `dosnames'. You can also change the default setting by editing
+ `mktex.opt', but only if you use the `mktex' shell scripts; the
+ emulation programs don't consult `mktex.opt'.
+
+`fontmaps'
+ Instead of deriving the location of a font in the destination tree
+ from the location of the sources, the aliases and directory names
+ from the Fontname distribution are used. (*note Introduction:
+ (fontname)Top.).
+
+`nomfdrivers'
+ Let mktexpk and mktextfm create metafont driver files in a
+ temporary directory. These will be used for just one metafont run
+ and not installed permanently.
+
+`nomode'
+ Omit the directory level for the mode name; this is fine as long as
+ you generate fonts for only one mode.
+
+`stripsupplier'
+ Omit the font supplier name directory level.
+
+`striptypeface'
+ Omit the font typeface name directory level.
+
+`strip'
+ Omit the font supplier and typeface name directory levels. This
+ feature is deprecated in favour of `stripsupplier' and
+ `striptypeface'.
+
+`varfonts'
+ When this option is enabled, fonts that would otherwise be written
+ in system texmf tree go to the `VARTEXFONTS' tree instead. The
+ default value in `kpathsea/Makefile.in' is `/var/tmp/texfonts'.
+ The `Linux File System Standard' recommends `/var/tex/fonts'.
+
+ The `varfonts' setting in `MT_FEATURES' is overridden by the
+ `USE_VARTEXFONTS' environment variable: if set to `1', the feature
+ is enabled, and if set to `0', the feature is disabled.
+
+`texmfvar'
+ Force generated files that would go into a system tree (as defined
+ by `SYSTEXMF') into `TEXMFVAR'. Starting with teTeX-3.0, the
+ variable `TEXMFVAR' is always set. The `varfonts' feature takes
+ precedence if also set.
+
+ The `texmfvar' setting in `MT_FEATURES' is overridden by the
+ `USE_TEXMFVAR' environment variable: if set to `1', the feature is
+ enabled, and if set to `0', the feature is disabled.
+
+1.2.9.2 `mktex' script names
+............................
+
+The following table shows the default name of the script for each
+possible file types. (The source is the variable `kpse_make_specs' in
+`kpathsea/tex-make.c'.)
+
+`mktexpk'
+ Glyph fonts.
+
+`mktextex'
+ TeX input files.
+
+`mktexmf'
+ Metafont input files.
+
+`mktextfm'
+ TFM files.
+
+These names are overridden by an environment variable specific to the
+program--for example, `DVIPSMAKEPK' for Dvipsk.
+
+ If a `mktex...' script fails, the invocation is appended to a file
+`missfont.log' (by default) in the current directory. You can then
+execute the log file to create the missing files after fixing the
+problem.
+
+ If the current directory is not writable and the environment variable
+or configuration file value `TEXMFOUTPUT' is set, its value is used.
+Otherwise, nothing is written. The name `missfont.log' is overridden
+by the `MISSFONT_LOG' environment variable or configuration file value.
+
+1.2.9.3 `mktex' script arguments
+................................
+
+The first argument to a `mktex' script is always the name of the file
+to be created.
+
+ In the default `mktexpk' implementation, additional arguments may
+also be passed:
+
+`--dpi NUM'
+ Sets the resolution of the generated font to NUM.
+
+`--mfmode NAME'
+ Sets the Metafont mode to NAME.
+
+`--bdpi NUM'
+ Sets the the "base dpi" for the font. This must match the mode
+ being used.
+
+`--mag STRING'
+ A "magstep" string suitable for the Metafont `mag' variable. This
+ must match the combination of BDPI and DPI being used.
+
+`--destdir STRING'
+ A directory name. If the directory is absolute, it is used as-is.
+ Otherwise, it is appended to the root destination directory set in
+ the script.
+
+1.2.10 Installation testing
+---------------------------
+
+Besides the tests listed in *Note Simple installation::, you can try
+running `make check'. This includes the torture tests (trip, trap, and
+mptrap) that come with Web2c (*note Triptrap: (web2c)Triptrap.).
+
+1.3 Security
+============
+
+None of the programs in the TeX system require any special system
+privileges, so there's no first-level security concern of people gaining
+illegitimate root access.
+
+ A TeX document, however, can write to arbitrary files, e.g.,
+`~/.rhosts', and thus an unwitting user who runs TeX on a random
+document is vulnerable to a trojan horse attack. This loophole is
+closed by default, but you can be permissive if you so desire in
+`texmf.cnf'. *Note tex invocation: (web2c)tex invocation. MetaPost has
+the same issue.
+
+ Dvips, Xdvi, and TeX can also execute shell commands under some
+circumstances. To disable this, see the `-R' option in *Note Option
+details: (dvips)Option details, the xdvi man page, and *Note tex
+invocation: (web2c)tex invocation, respectively.
+
+ Another security issue arises because it's very useful--almost
+necessary--to make arbitrary fonts on user demand with `mktexpk' and
+friends. Where do these files get installed? By default, the
+`mktexpk' distributed with Kpathsea assumes a world-writable `/var/tmp'
+directory; this is a simple and convenient approach, but it may not
+suit your situation because it means that a local cache of fonts is
+created on every machine.
+
+ To avoid this duplication, many people consider a shared, globally
+writable font tree desirable, in spite of the potential security
+problems. To do this you should change the value of `VARTEXFONTS' in
+`texmf.cnf' to refer to some globally known directory. *Note mktex
+configuration::.
+
+ The first restriction you can apply is to make newly-created
+directories under `texmf' be append-only with an option in `mktex.cnf'.
+*Note mktex configuration::.
+
+ Another approach is to establish a group (or user) for TeX files,
+make the `texmf' tree writable only to that group (or user), and make
+`mktexpk' et al. setgid to that group (or setuid to that user). Then
+users must invoke the scripts to install things. (If you're worried
+about the inevitable security holes in scripts, then you could write a
+C wrapper to exec the script.)
+
+ The `mktex...' scripts install files with the same read and write
+permissions as the directory they are installed in. The executable,
+sgid, suid, and sticky bits are always cleared.
+
+ Any directories created by the `mktex...' scripts have the same
+permissions as their parent directory, unless the `appendonlydir'
+feature is used, in which case the sticky bit is always set.
+