% teTeX main documentation file
% tetex by Thomas Esser
% this file maintained by Craig Bateman

\documentclass[12pt,a4paper]{article}
\usepackage{anysize,mflogo,xspace,texnames}

\newcommand{\teTeX}{\textrm{te}\TeX\xspace}
\newcommand{\Linux}{\textrm{Linu}\textsf{X}\xspace}
% \newcommand{\MF}{\textlogo{Metafont}\xspace}
\newcommand{\smiley}{\texttt{ :-)}\xspace}

\title{The \teTeX{} Guide --- Installation and Maintenance}
\author{Thomas Esser, Dirk Hillbrecht, Craig Bateman}
\date{June 1996}

\begin{document}

\maketitle

\begin{abstract}

  This documentation describes the main features of the
  \teTeX distribution, a \TeX{}/\LaTeX{} distribution
  that includes \TeX{}, \LaTeXe{}, \MF{} and many further
  programs as dvips, xdvi, \BibTeX{}, 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 from Karl Berry.

\end{abstract}

\tableofcontents

\newpage

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

Welcome to the documentation of
\teTeX{}, a \TeX{} distribution for UNIX-like platforms.
\teTeX{} was mainly set up 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 to mention 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 to write a little documentation and do 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@informatik.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 was
assembled within approximately half a year, thinking about this topic
and that feature, testing this and that program, finding one and
another bug, having 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 Multiplatform usability. \teTeX{} is known to run on the following
platforms: 

\begin{itemize}
\item Linux on Intel, Alpha and PowerPC platforms;
\item SGI Irix 5.3, 6.2
\item SunOS 4.1.3 on SPARC
\item Solaris 2.4, 2.5 on SPARC
\item FreeBSD 2.1.5 on Intel
\item NetBSD 1.2 on Intel
\item Ultrix 4.3, 4.4 on Mips
\item IBM RS6000 AIX 3.2.5, 4.1.4, 4.2.0
\item PowerPC AIX 3.2.5, 4.1.4
\item Digital Unix 3.2, 4.0
\item NEXTSTEP (NeXT,Intel,HP-PA,SPARC)
\item Convex C-110, C-210
\item HP-PA/HP-UX 9.xx, 10.xx
\item HP 400/HP-UX 9.xx
\end{itemize}

Other platforms are planned for the future.

\item Fully compile-time independent. \teTeX{} can be
  installed in any directory in your system. You even do not
  need to set any environment variables. The binaries will
  find themselves automatically once they are called.  Of
  course, you can set environment variables to change or
  enlarge your search paths.
  
\item Installation and maintenance utilities for the whole
  package make these difficult topics much easier,
  especially for inexperienced users.
  
\item Very fast file searching using all features of the
  {\tt Kpathsea}-library v2.6 (even within the web2c
  package).
  
\item The {\tt kpsetool} as a run time interface to all the
  search paths of the \teTeX{} programs.
  
\item Ready-to-use font families: cm, dc, charter,
  oldgerman, ams, pandora, adobe and some special ones.
  
\item Ability to cope with the whole bunch of standard
  PostScript$^{\textrm{TM}}$ fonts \emph{even usable with the
    normal {\tt xdvi}-viewer}.
  
\item Latest version of \LaTeXe{} (1995/06/01), including
  the \emph{official} {\tt amstex} package version 1.2 for
  \LaTeXe{} (formerly known as \AmSLaTeX{}).
  
\item Lots and lots of really useful documentation in {\tt
    texmf/doc}, even made accessible through WWW-Browsers
  like Netscape (or Mosaic).

\end{itemize}

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

The \teTeX distribution is split into two series: The
\emph{Base Series} and the \emph{Goodies Series}. These
series themselves are split up again into several
packages ({\tt .tgz}-files) that contain all the
system-independent 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,
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?

Having these two you can do --- nothing. As mentioned, these
series do not contain any system-dependent files, like e.g.
binaries.

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
  concerning 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 an 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 resolution of your printer
\item how much the fonts in your documents vary
\item how much you use \teTeX
\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} or {\tt lp} or whatever your printer
  access program is) 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 from the German site {\tt
    ftp-i2.informatik.rwth-aachen.de} in the directory {\tt
    /pub/Linux/pak/APSfilter} (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{\teTeX{} 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 is not any fun
  there\dots}, so it is not usable under \Linux{}. But
\teTeX{} might be kind of a replacement for it under
\Linux{}: Like 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 Although both \teTeX and em\TeX{} are fast (em\TeX{} is
  only fast when you can use the protected mode binaries on
  a 386 or higher), it is a major advantage of \teTeX to run
  in a real multitasking environment: you can continue
  editing your text while the previewer is running and your
  document is being processed by \TeX{}.

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

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

The way you install \teTeX depends on what version and
source media you have. If you get \teTeX as part of a \Linux
distribution, just install it the same way you do for other
packages of your distribution.

If you get \teTeX as a stand-alone package, there are two ways to
install: from sources or using precompiled binaries. See the file 
{\tt INSTALL.src} or {\tt INSTALL.bin}, respectively, for
instructions. The binary installation is nothing more than unpacking
the archives and running texconfig. The compilation of the sources can
be done with a {\tt make world} from the top-level directory. But, you
will need recent versions of {\tt gcc}, {\tt flex} and {\tt GNU make}
for the compilation.

\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, we distinguish between site-dependent
programs such as {\tt xdvi}, {\tt dvips} or {\tt dvicopy},
which have their files in {\tt bin, man, info} subdirectories of 
{\tt \$TETEXDIR}.

The site independent \TeX files are installed below the directory
\verb|$TEXMF|, which defaults to {\tt \$TETEXDIR/texmf}.  \verb|texmf|
stands for ``\TeX{} and more'' and is often spoken as ``\TeX{} and
friends''.

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

The organisation follows the ``TeX Directory Standard'' (TDS) to a
large extent. See file {\tt \$TEXMF/doc/help/tds.dvi} for more
information about the TDS.

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

As you perhaps have already noticed, \teTeX{} is fast. Very
fast.  Quite extraordinarily fast. This is due to a fantastic
feature of the {\tt Kpathsea}-library: The
\emph{input file database}. This is not much more than the
output of a simple {\tt ls -LAR}-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
during installation). 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:\medskip

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

{\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{A note on X support for \MF}

If \MF{} does not support seem to support the X window
system, your virmf binary is compiled without support for
the X window system. If there exists a virmf.X binary, that
one has the missing X support you need. The easiest way to
use it is to change the symbolic link \texttt{mf $\to$
  virmf}. Example:
\begin{verbatim}
cd /usr/local/teTeX/bin/i386-linux
rm mf
ln -s virmf.X mf
\end{verbatim}

\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 styles is held separately 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 searched by default.
  Of course, this is only sensible if the style is very
  proprietary and for just a single \TeX{} source.
  
\item Every user can change the {\ttfamily TEXINPUTS}
  environment variable. Anyway, they should ensure that \teTeX
  's own paths are searched, 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.
  
  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 to search
  recursively in all subdirectories.
\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 suspicion, 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 be of
any use to 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.
  You just start {\tt allcm -m {\it
      mode}} or {\tt allec -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 ec-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 immediately.
  
\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 the {\tt
    allneeded} script. This script will search the given
  directories for {\tt .dvi}-files and run them through {\tt
    dvips} and (optionally) {\tt dvired} (with the
  PostScript output sent to {\tt /dev/null} \smiley). The
  nice side-effect of this operation is that the {\tt dvips}
  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 processable 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 short filenames ({\tt dpi300/cmr10.pk} instead
  of {\tt cmr10.300pk}), just call {\tt fontimport} or {\tt fontexport
    -d}. For details, refer to {\tt 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