% Technical.tex --- Technical details about armTeX
% This file is written in plain TeX to provide an example of TeX input.
% (And to show how terrible it is compared to LaTeX).
%
% Start a section
\def\section#1{\medbreak\leftline{\tenbf #1}\par\nobreak\noindent\ignorespaces}
% not quite like LaTeX's \verb|...|
\def\verb#1{{\tentt #1}}
% Indented code
\def\code#1{\par\smallskip{\narrower\ttraggedright#1}\smallskip\par\noindent\ignorespaces} % Macro for consistent logo
\def\armtex{arm\TeX}
\font\manfnt=manfnt
\def\MF{\hbox{\manfnt METAFONT}}
\vskip 1in
\hrule
\vskip .3in
\centerline{\tenbf Technical \armtex}
\centerline{8. June 1998}
\rightline{\tenit Jakob Stoklund Olesen}
\rightline{\tentt stoklund@usa.net}
\vskip .1in
\hrule
\vskip .5in
\noindent
This file explains some of the more complicated issues that you may need
to know about if you are trying to change the setup of \armtex. It is
very short at the moment; I hope to expand it based on questions from
users.

\section{Building new formats}
If you are updating La\TeX, if you want to use the Babel package or if
you want to make a Texinfo format, you need to rebuild the formats with
the INI\TeX\ program. The formats are kept in the directory
\verb{texmf:armtex.format}. The script \verb{!Build} will rebuild the
standard formats; it should also show you how to invoke INI\TeX.
To make a Texinfo format you say
\code{initex \&plain texinfo @dump}
The `\verb@' is special for Texinfo because it changes the escape
character which usually is `$\backslash$'. To use the new format say
\code{tex \&texinfo diff.texi}
If you are making new formats you may want to keep them separated from
the standard distribution formats. You can do this by creating the
directory \verb{!TeX.texmf.local.armtex.format} and putting them in there.

\section{Multiple TDS trees}
It is possible to have several TDS trees by adding entries to
\verb{texmf\$Path}. \TeX\ knows about path variables and it will find all
subdirectories in all paths. The search order given by path variables is
respected which means that it is possible to override files on a CD or
NFS mounted directory. Just place them in a TDS tree earlier on the
path. I would like to hear about experiences with using TDS trees
directly from CDROMs and networks as I have no way of testing this
myself.

\section{Local additions}
The multiple trees feature is used to allow you to keep your private
setup separate from the standard \armtex\ distribution. The directory
\verb{!TeX.texmf.local} is included in \verb{texmf\$path} so you can build
your own TDS tree there.

\section{Installing new La\TeX\ packages}
Extension packages for La\TeX\ usually come in \verb{.dtx} files which
are unpacked by the Docstrip processor. Let's take the package MFlogo as
an example.% to avoid a space after the period
\footnote*{The MFlogo package is already installed in this \armtex\
distribution.}
MFlogo comes as two files: \verb{mflogo.dtx} and \verb{mflogo.ins}.
Place them in the directory \verb{source.latex.mflogo}. Set the type of
\verb{mflogo.ins} to La\TeX\ and double-click it. This will unpack the
files \verb{mflogo.sty} and \verb{Ulogo.fd} from \verb{mflogo.dtx}.
These files are the input files needed by La\TeX\ and so should be put
in a directory read by \TeX\ which is somewhere under \verb{texmf:tex}.
The place to put La\TeX\ packages in \verb{texmf:tex.latex.misc} if
it is a single (or a few) \verb{.sty} file or
\verb{tex.latex.mflogo} if there is several files. Whether a package
should be installed under its name or under \verb{misc} is a matter of
taste and judgement.

You can typeset the documentation for a package by running La\TeX\ on
the \verb{.dtx} file directly. This usually has two parts: A general
description of how to use the package and a commented listing of all the
code that goes into the package. If you don't want the last part, you
can create a file called \verb{ltxdoc.cfg} which contains the line
\code{$\backslash$AtBeginDocument$\{\backslash$OnlyDescription$\}$}
This makes La\TeX\ stop when all the hairy macro definitions start.

You should now move the package documentation to a directory under
\verb{doc.latex} where you can find it easily later.

Some (old) packages don't have the \verb{.ins} file to do the unpacking.
In that case you should change directory to wherever you have put the
\verb{.dtx} file and say
\code{latex docstrip.tex}
in a task window. Docstrip will ask for the name of the \verb{.dtx}
file, the name of the output file and some options. Hopefully there is
a help file supplied with the package that tells you what to answer
here.

In summary, installing a package in the TDS tree involves splitting it
in three parts: Sources in \verb{source.latex}, Input files in
\verb{tex.latex} and documentation in \verb{doc.latex}. You may wish to
create these directories under \verb{!TeX.texmf.local} to keep your own
additions apart from the standard packages.

\section{Font files}
Most of the font files are kept in the \verb{!TeXFonts} directory but some
are put in their proper TDS location. They are the {\tentt.mf} files which
have no \verb{.tfm} equivalent. You can also put TFM files into the TDS if
you wish. Just add \verb{texmf:fonts.tfm..} to \verb{TeXFonts\$Path}. This
may cause some problems if you are using programs that expect to use
\verb{TeXFonts\$Path} like an ordinary RISC OS path.

\section{Open files limit}
\armtex\ currently has a problem with the number of open files allowed by
the Shared C Library. This is normally not a problem except when processing
Texinfo files and using the Docstrip processor. The version of
\verb{texinfo.tex} supplied solves the problem for most Texinfo files. It
closes the unused index files. Docstrip should not be a problem if the
supplied \verb{docstrip.cfg} file is used.

\section{Using dvips}
When dvips wants to make a font bitmap it calls \verb{virmf} directly.
This is the small variant of \MF\ which is not included in the standard
distribution (it's in \verb{lowmemory.zip}).

You can patch the file \verb{!DviPS.Library.MakeTeXPK} to call
\verb{bigvirmf} instead or put the line
\code{Set Alias\$virmf bigvirmf}
in \verb{!DviPS.!Boot}. You will need to increase the wimpslot in
\verb{!DviPS.desc} to 3200k at least.

\end

