% teTeX main documentation file
% tetex by Thomas Esser
% this file maintained by Dirk Hillbrecht

\documentclass{article}

\newcommand{\teTeX}{{\rm te\TeX{}}}
\newcommand{\Linux}{{\rm Linu\sf X}}
\newcommand{\MF}{Metafont}
\newcommand{\smiley}{{\tt :-)}}

\title{The \teTeX{} Guide --- Installation and Maintenance}
\author{Thomas Esser, Dirk Hillbrecht}
\date{October 1994}

\begin{document}

\maketitle

\begin{abstract}

  This documentation describes the main features of the
  \teTeX{}-Distri\-bution, a \TeX{}/\LaTeX{}-distribution for \Linux{}
  that includes \TeX{}, \LaTeXe{}, \MF{} and many further
  programs as dvips, xdvi, bib\TeX{}, etc.

  \teTeX{} wants to make \TeX{}ing from within Unix as easy as
  possible, and takes full advantage of the efficient and highly
  customizable Kpathsea-library.

\end{abstract}

\tableofcontents

\newpage

\section{Introduction}
\label{sec:int}

Welcome to the documentation of
\teTeX{}, a \TeX{}-distribution for \Linux{} and --- as planned for
the future --- other Unix-variants.
\teTeX{} was mainly been written and assembled by Thomas Esser, {\tt
  te@informatik.uni-hannover.de}, whose work heavily bases on Karl
Berry's {\tt kpathsea}-library, his {\tt web2c}-package and the
associated packages as {\tt dvipsk} etc.

Furthermore, there is me. As Thomas had so much trouble with the
binaries, the fonts, the directory-organisation, and the additional
script files, not mentioning the fonts, the directory-organisation,
the binaries and of course all of those nifty little additional
scripts\dots Oh, it seems as if I repeat myself\dots As it is, I
offered him to write a little documentation and make some beta-testing
of his package.

So here we are now. If you find anything about the programs
themselves, Thomas is the right address to tell.  If you want to make
any remarks on the documentation, esp. this file, bother me: Dirk
Hillbrecht, {\tt dh@in\-for\-ma\-tik.uni-hannover.de}.

\subsection{Features}
\label{ssec:fea}

OK. What is it now, this remarkable new \TeX{}? What makes it so
different from other \TeX{}s? Well, in the first place, it is
assembled within approximately half a year, thinking about this topic
and that feature, testing this and that program, finding one and
another bug, heaving great ideas of a perfect directory tree --- and
throwing them away again\dots So you see, this \TeX{} has been done
with a lot of attention and passion. We really think it to be superiour
to most other \TeX{} implementations.

\medskip

Furthermore, there are the following highlights:

\begin{itemize}

\item Fully compile-time independent. \teTeX{} can be installed into
  any subdirectory of your filesystem you want. You even do not need to
  set any environment variables. It will find itself automatically
  once it is called. Of course, you can set environment variables to
  change or enlarge your search paths.

\item Installation and maintainance utilities for the whole package
  making these difficult topics much easier especially for unexperienced
  users (at least we hope so\dots \smiley{}).

\item Very fast file searching using all features of the {\tt
  kpathsea}-library v2.4 (even within the web2c package).

\item The {\tt kpsetools} as a run time interface to all the search
  paths of the \teTeX{} programs.

\item Ready-to-run font families: cm, dc, charter, oldgerman, ams,
  pandora, adobe and some special ones.

\item Ability to cope with the whole bunch of standard
  PostScript$^{\mathrm{TM}}$ fonts \emph{even usable with the normal
    {\tt xdvi}-viewer}.

\item Latest version of \LaTeXe{} (by now patchlevel 4), including the
  /emph{official} AMS\LaTeX{} for \LaTeXe.

\item Lots and lots of really useful documentation in {\tt texmf/doc},
  even made accessible through WWW-Browsers like Mosaic.

\end{itemize}

\subsection{Series and Locations}
\label{ssec:pac}

The \teTeX{}-distribution is splitted into three series: The
\emph{Base Series}, the \emph{Goodies Series} and the \emph{Source
  Series}. These series themselves are splitted up again into
several packages ({\tt .tgz}-files) that contain the files.

\smallskip

The \emph{Base Series} contains everything that is needed to handle
the common \TeX{}-stuff: compile a source, preview the document,
convert it into PostScript and print it. If you know how to embed this
into your favourite editor and can print PostScript files (e.g. via
GhostScript), you will not need more than this series.

The \emph{Goodies Series} brings some useful things to you such as
some more dvi-drivers, the famous {\tt XTeXShell}, lots of
documentation, and many additional fonts. When having these both
series you have everything for a complete \TeX{}-Development-System.
Not bad, is it?

But some People want even more! The \emph{Source Series} brings you
all the sources needed to compile the \teTeX{}-binaries yourself.
Having this one, you may even try to convert \teTeX{} to another
platform --- as we do. \emph{You will not need the Source Series for
  normal \TeX{} work.}

\subsection{Related software and Requirements}
\label{ssec:req}

There are some programs not included in \teTeX{}, but which are quite
useful indeed:

\begin{itemize}

\item X11: Without the graphical environment you will not be able to
  preview your documents (as long as you do not install an SVGA-based
  dvi-previewer on your own). Fortunately, X11 is available on most UNIX
  platforms. The {\tt virtex} and {\tt xdvi} programs need dynamic X11
  libraries. As both XFree86-3.1 and XFree-2.X are in common use, these
  two binaries come in two versions: One is dynamically linked against
  the X11R6 libraries (from XFree86-3.1) and the other one against the
  old X11R5 libraries from XFree86-2.X.

\item GhostScript: \teTeX{} uses GhostScript for everything touching the
  Post\-Script fonts and for general printing (not using a special dvi
  driver) on a non-PostScript printer. This program is also part of
  every larger \Linux{}-distribution and should be available, too.

\end{itemize}

Of course you will need some disk space too. These are: approx. 10 MB
for the \emph{Base series}, approx. 15 MB for the full \emph{Goodies
  series} and 13 MB for the full \emph{Source series} (and additional 10
  MB if you actually want to compile them).

In addition, you will need approx. 5 - 20 MB for pk fonts, depending
on 
\begin{itemize}
\item the resulution of your printer
\item how much the fonts in your documents vary
\item how much you use te\TeX
\end{itemize}

Last not least, your printer(s) must be up and running.

With \teTeX{} you have several possibilities to print your {\tt
  dvi}-files:

\begin{itemize}
\item With {\tt dvips} directly to a PostScript printer. You need to
  know the logical name of your printer (= the name used by {\tt lpr})
  and the \MF{}-mode (the resolution will automatically be calculated
  during the configuration process).
\item With {\tt dvips} to a non-PostScript printer. This requires some
  configuration of your \verb|/etc/printcap|-file, because a so-called
  \emph{input filter} needs to convert the PostScript input into an
  output understood by your printer. For most printers, this can be
  done with GhostScript (type {\tt gs -help} to get a list of printers
  supported by your version of GhostScript). The setup of such an
  input filter (and even much more) can easily be done with the {\tt
    apsfilter}-program which is available at {\tt ftp.germany.eu.net}
  in the directory {\tt /pub/os/Linux/Local.EUnet/People/akl} (see the
  Linux-Software-Map for mirror sites).
\item With a specific printer driver such as {\tt dvilj4}. The driver
  knows what kind of output the printer understands. In general, you
  only need the logical name of the printer.
\end{itemize}


\subsection{te\TeX{} for em\TeX{}-Users}
\label{ssec:tet}

For many people working with \TeX{} on a PC \TeX{} is equal with
em\TeX{}, the best-known and widest spread \TeX{}-distribution. Its
binaries are OS/2 only indeed\footnote{It will run under DOS also, but
  it does not make any fun there\dots}, so it is not useable under
\Linux{}. But \teTeX{} might be kind of a replacement for it under
\Linux{}: As em\TeX{}, this should be an easy-to-use-\TeX{} that can
be installed by the average user and is fast and convenient. Below,
there are the most important changes between em\TeX{} and \teTeX{}:

\begin{itemize}

\item \teTeX{} does not need any environment variables to run as long
  as you keep the given directory structure (but you can use
  environment variables to make \teTeX{} search your private input
  directories, e.g. {\tt setenv TEXINPUTS \~/TeX//:} will make \TeX{}
  search your private macros below the {\tt TeX}-directory in your
  home directory and then the standard locations). 

  You can use the {\tt kpsepath}-program to display the run-time
  paths.

\item \teTeX{} is much more actual than the current
  em\TeX{}-distribution (which is --- apart from the {\tt
    betatest}-directory --- from 1992). It comes with \LaTeXe{},
  \TeX{} 3.1415 etc.

\item \teTeX{} comes with only one previewer ({\tt xdvi}) and has only
  one printer driver in the base series ({\tt dvips}). Nevertheless,
  you do not need more under \Linux{}.

\item You can obtain all the sources --- there are no secrets.
\end{itemize}

\section{Installation}
\label{sec:ins}

There are two ways to install \teTeX{} depending on the source media
you have.

If you have the \teTeX{} in a mounted directory in your filesystem
(but \emph{not} on a mounted floppy!), then you can start the
installation process simply by calling {\tt install.sh}:

\begin{verbatim}
# cd /path/to/tetex
# ./install.sh
\end{verbatim}

For a installation from floppies, do the following: Copy {\tt
  install.sh} to any location in your file system (e.g. {\tt /tmp})
and execute it from there. A typical installation could be done like this:

\begin{verbatim}
# cd /tmp
# mcopy a:install.sh .
# sh ./install.sh
\end{verbatim}

{\tt install.sh} provides on-line-help describing the remaining
installation process.

\subsection{{\tt texconfig}}
\label{ssec:tex}

After the installation program has copied all files to their final
locations it calls a program called {\tt texconfig} that allows you to
configure \teTeX{} to fit your local needs.

\section{Using and maintaining te\TeX}
\label{sec:using}

\subsection{The directory structure --- Where are my files?}
\label{ssec:locs}

\teTeX{} comes with a very clearly structured directory tree which is
described in the following:

In the first order, \teTeX{} differs between site-dependent programs
such as {\tt xdvi}, {\tt dvips} or {\tt dvicopy}, which all have their
own directory subtree directly below {\tt \$TETEXDIR}. All of these
trees have the same structure: They contain at least a {\tt bin} and a
{\tt man/man1}-subdirectory that are for the binaries and the
man-pages of the appropriate program.

The site-independent \TeX -files reside below \verb|$TEXMF| which can
be chosen during the installation process.
\verb|texmf| stands for "\TeX{} and more" and is often spoken as
"\TeX and friends". 

Here we find inputs for \TeX{}, \MF{}, Bib\TeX{} and all the sources
and metrics of the fonts.

\subsection{The input file database}
\label{ssec:the}

As you perhaps have already remarked, \teTeX{} is fast. Very fast.
Quite extraordinary fast. This is due to a fantastic feature of the
latest {\tt kpathsea}-libraries: The \emph{input file database}. This is
not much more than the output of a simple {\tt ls -LR}-command, running
over the \verb|$TEXMF|-directory tree. The \TeX{} programs can read this
database once at the beginning of their run (which is a fast
operation), store it in a hash table and then look up any needed file in
this database rather than searching the whole directory tree
on the disk (which is --- due to the so-called {\tt stat}-operation
--- very time-consuming).

The database can be found in the \verb|$TEXMF|-directory and is called
almost like the command to produce it: {\tt ls-R} and it can be
maintained through three different programs:

\begin{enumerate}
\item {\tt texhash}. The {\tt texhash} program builds the database
  from scratch by scanning the whole {\tt texmf}-directory-tree and
  putting the output of the {\tt ls}-command into the (newly created)
  {\tt ls-R}-file.

\item {\tt append\_db}. This little shell-script is especially for the case
  that a new font has been created and therefore should be entered into
  the database. {\tt append\_db} gets the font's file name and its
  location and creates then an {\tt ls -LR}-like entry for this one
  font at the end of the {\tt ls-R}-file.
\end{enumerate}

What can one do with these scripts now and where are the
pitfalls in their use?

For the following, assume a system, where are two users, {\tt adm} and
{\tt foo}. Both are non-priviledged, but {\tt adm} installed \teTeX{}
and {\tt foo} uses it.

While the installation, {\tt adm} ran {\tt texhash} (automatically
through the installation script). So the {\tt ls-R}-file is his. Now
{\tt foo} comes, compiles a file and previews it. Therefore one or
more fonts are created and stored --- and have to be appended to {\tt
  ls-R}. This is done by {\tt foo} and therefore with his privileges
--- and these include assurently not to write into {\tt adm}'s
files!

So, we have a problem. There are new files on the disk that are not
listed in the database. Each lookup of one of these files will cause 
time-consuming search operations on the disk, or -- if disk searching
is disabled (i.e. when the path component is prefixed by !!)  -- it
might happen that those files are not found or that MakeTeXPK or
MakeTeXTFM are accidently called.

In the following we give some hints how to avoid such problems:

\begin{enumerate}

\item Make {\tt ls-R} world-writeable. This is the easiest solution, and
  should be safe enough for most sites. \teTeX{} is installed this
  way when it comes out of the box.

\item Create a new group {\tt tex} and make {\tt ls-R} writable for
  this group. Then, rename {\tt append\_db} to {\tt append\_db.sh}
  and call the renamed shell-script from a small set-GID programm 
  (written in C) with the name {\tt append\_db}.

  This will give you some more security (sa ls-R no longer needs to be
  world-writable), but it requires some more administration whilst the
  installation (esp. {\tt root}'s privileges to make the {\tt
    tex}-group), so \teTeX{} does \emph{not} install itself like this
  in the first place.
\end{enumerate}

In any case, you need to run {\tt texhash} after installing new styles
or fonts below \verb|$TEXMF|.

For additional information about the library and file searching in
\teTeX{}, see the documentation in the {\tt Kpathsea}-package.

\subsection{Adding new fonts}
\label{ssec:adf}

\teTeX comes with many fonts included. But perhaps you need more
fonts, e.g. your firm specific name font. The question is: Where to
put it?

The following table shows where to put the font related files,
depending on their type. In general, this type is given by the
extension of the filename:

\begin{tabular}{|c|c|}
\hline
{\rmfamily file} & to \\ \hline
.fd & \$TEXMF/tex/latex/{\it package}\\
.mf & \$TEXMF/fonts/{\it source}/{\it typeface}/src \\
.tfm & \$TEXMF/fonts/{\it source}/{\it typeface}/tfm \\
.afm, .vf, \dots & \$TEXMF/fonts/{\it source}/{\it typeface}/\{afm,vf,...\}\\
.pfa, .pfb & \$TEXMF/fonts/{\it source}/{\it typeface}/type1 \\
.*pk & \$TEXMF/fonts/{\it source}/{\it typeface}/pk/{\it mf-mode} \\
\hline
\end{tabular}

{\tt \$TEXMF} is the directory given in the installation process to
put the site-independent stuff. To get the run-time value of {\tt
  \$TEXMF} you can run {\tt kpsexpand '\$TEXMF'}.

{\it source} is the name of the font distributor, such as AMS,
Bitstream, Adobe, or {\tt public} for freely distributable fonts.
{\it typeface} is the name of the font family, e.g. Computer Modern
{\tt cm}.

\subsection{Adding new system-wide styles}
\label{ssec:ads}

A new style should be put below {\ttfamily
  \$TEXMF/tex/{\it format}/{\it package}} for all formats (e.g. plain, latex,
eplain).

To avoid {\it package} directories containing only a single style
file, use {\tt misc} directory for these instead.

Examples:

\begin{verbatim}
$TEXMF/tex/ams/amssym.tex
$TEXMF/latex/graphics/epsfig.sty
$TEXMF/latex/misc/anysize.sty
\end{verbatim}

The documentation for a style is held seperately in the directories below
{\ttfamily \$TEXMF/doc}.

\subsection{User-dependent configuration}
\label{ssec:use}

On a site with lots of users, all these users may have their own
 style files that are not to be copied into the common
\teTeX{} tree. There are several possibilities to make these files
visible for the \TeX{} programs:

\begin{itemize}
\item The {\ttfamily .sty}-file can be copied into the current
  directory.  This directory is always searched for. Of course, this
  is only senseful if the style is very proprietary and for just a
  single \TeX{} source.

\item Every user can change the {\ttfamily TEXINPUTS} environment
  variable. Anyway, he should 
  ensure that \teTeX 's own paths are seached, too. This can be done
  by putting a colon in the beginning or at the end of the path or a
  doubled colon in the middle. Such an empty path component will be
  replaced by the default path.

A typical settings for \emph{csh} and \emph{tcsh} could be

\verb|setenv TEXINPUTS :~/TeX/mystyles|

or for \emph{bash} or \emph{sh}:

\verb|export TEXINPUTS=~/TeX/mystyles:|.

\item At least, the \TeX -Administrator himself can take care of the
  user's style files by putting something like \verb|...:~/TeX//| into
  the {\ttfamily TEXINPUTS}-statement in the {\ttfamily texmf.cnf}
  file in \teTeX{}'s base directory. The two slashes mean "this
  directory and any below it".
\end{itemize}


%\subsection{Conforming the Linux Filesystem Standard}

%The Linux Filesystem Standard claims, that {\tt /usr} should be
%mountable read-only. This does not work with the standard \teTeX{}
%installation since \teTeX{} writes its fonts below {\tt
%  /usr/.../tex/\$TEXMF/fonts}. This behaviour can be changed indeed, so
%that the fonts are stored below e.g. {\tt /var/tex/fonts} Do the
%following for this:

%\begin{itemize}
%\item change the {\tt MTPK\_DESTROOT} variable in {\tt texmf.cnf} to {\tt /var/tex/fonts}.

%\item Create the directories {\tt \${}MTPK\_DESTROOT/public/cm/pk}, {\tt \${}MKPK\_DESTROOT/public/dc/pk} and so on
%  (in fact, copy the whole directory structure below {\tt \${}TETEXDIR/\$TEXMF/fonts} that has something to do
%  with the {\tt .pk}-files) and make a {\tt chmod 1777} on all these directories.

%\item Enlarge the following search paths in {\tt texmf.cnf} as follows

%\verb|setenv PKFONTS ':$MTPK_DESTROOT//pk/$MAKETEX_MODE'|

%\verb|setenv TFMFONTS ':$MTPK_DESTROOT//tfm'|
%\end{itemize}

\subsection{Fonts again: Creation on suspect, import, export}
\label{ssec:fon}

When you start working with \teTeX{}, you have no {\tt .pk}-files.
This is due to the fact, that every resolution needs its own {\tt
  .pk}-files (they contain the pixel information about the letters).
So it would not of any use for you if \teTeX{} came with precalculated
fonts for an Epson Stylus (360 dpi) whilst you have a HP Laserjet IV
(and need therefore fonts with 600 dpi resolution). \teTeX{}
calculates these files "on demand", that means if and only if they are
needed.

Nevertheless it is quite annoying to wait for the first documents
created with the \teTeX -series several minutes, because of \MF{}
calculating the needed fonts. Fortunately, there are some possible
ways to shorten this time (perhaps down to 0):

\begin{enumerate}

\item Calculate a large bunch of fonts just on suspicion. This is e.g.
  the method, em\TeX{} works when installed in the stock '92 version.
  You just start {\tt cmall -m {\it mode}} or {\tt dcall -m {\it mode}}
    --- and go away. Depending on the power of your computer these
    programs will work several minutes, hours or days to calculate all
    fonts \LaTeX will need of the Computer Modern or DC-fonts for the
    given {\tt mode}.  On the one
    hand this might be an overkill, filling lots of your disk space
    with useless fonts (useless for you, because none of your
    documents use them), but on the other hand it is sure
    that there are no fonts missing to show almost any document
    immideately.

%\item Calculate all the fonts needed to show the documents existing on
%  your system. This may be of interest for you if you have a large
%  number of documents and bought a new printer with a different
%  resolution. Just run "???". This script will search the whole disk
%  for {\tt .dvi}-files and run them through {\tt dvips} and {\tt
%    dvired} (with the output sent to {\tt /dev/null} \smiley). The
%  nice sideeffect of this operation is that the dvi-driver will call
%  {\tt MakeTeXPK} to create the needed fonts, and the result of this
%  is, that all the {\tt .dvi}-files on your system are processible
%  without delay --- as long as you do not produce new ones that use
%  different fonts, of course \smiley .

\item Import font files from a different \TeX -Installation. This can
  be done through the program {\tt fontimport}. We even provide a
  possibility to exchange fonts between \teTeX{} and \TeX{}
  implementations using the 8.3-naming convention ({\tt
    dpi300/cmr10.pk} instead of {\tt cmr10.300pk}), just
  call {\tt fontimport} or {\tt fontexport -d}. For details, refer to
  {\it fontimport(1)} and {\tt fontexport(1)}.
\end{enumerate}

%\section{Usage}
%\label{sec:use}

%So, it's done! When you are here reading, you have installed \teTeX{} properly and want to know what to do now, won't you? The 

%\subsection{Common \TeX{}-runs}
%\label{ssec:com}

%\subsection{Using the {\tt kpsetools}}
%\label{ssec:kps}

%\section{Embedding in other programs}
%\label{sec:emb}

%\subsection{emacs \& auctex --- The Dynamic Duo}
%\label{ssec:ema}

%\subsection{ispell}

%\subsection{Useful aliases}

\end{document}
% Ende des Quelltextes geschrieben von Dirk Hillbrecht, 09/94