\documentclass[a4paper]{article}

\newcommand{\BibTeX}{\textrm{B\kern-.05em\textsc{i\kern-.025em b}\kern-.08em
    T\kern-.1677em\lower.7ex\hbox{E}\kern-.125emX}}

\setlength{\topmargin}{0mm}
\setlength{\headheight}{0mm}
\setlength{\headsep}{0mm}
\setlength{\oddsidemargin}{0mm}
\setlength{\textwidth}{160mm}
\addtolength{\textheight}{6\baselineskip}
\setlength{\parindent}{0pt}
\setlength{\parskip}{.5\baselineskip}

\begin{document}
\begin{center}
\LARGE\textbf{Ar\TeX\ User Manual} \\
\vspace{5mm}\large N D Efford \\
\small\verb|nde@dcre.leeds.ac.uk| \\
\vspace{5mm}\normalsize version 1.00b, 18/2/95
\end{center}

\begin{quotation}
  \noindent Ar\TeX\ is a Perl script which analyzes a \LaTeXe\ document to
  determine whether it loads any non-standard files. Any such files are
  bundled with the document by means of \emph{filecontents} or
  \emph{filecontents}$\ast$ environments, as appropriate. The result should
  be portable to any system with a standard installation of \LaTeX.
\end{quotation}

\vspace{.5\baselineskip}
\section{Introduction}

A number of situations can arise in which \LaTeX\ document portability is
important. Suppose, for instance, that you are writing a paper with a
colleague at another institution, and that you have chosen to exchange draft
versions back and forth via email. Clearly, either of you should be able to
process the document successfully, regardless of changes or additions made
by the other. When you come to submit the finished manuscript, you may have
the option to do this electronically---but this can work only if the
publisher, too, is able to process your document successfully.

Anyone wishing to process a \LaTeX\ document must also have on their system
all the files that are loaded by that document. Thus portability can only be
guaranteed by bundling a document with the files on which it depends and
then distributing this bundle or \emph{archive} to others. Unfortunately,
the business of identifying dependencies by hand is prone to error, and the
archives that are created are often OS-specific and inherently non-portable:
an archive created on a UNIX system with \emph{tar}, \emph{gzip} and
\emph{uuencode} cannot be unpacked on a normal PC system running
MS-DOS\footnote{Versions of these tools compiled for DOS systems are
  available, but acquiring them adds further unwanted complexity to the
  business of document exchange.}.

Fortunately, \LaTeXe\ provides
\begin{enumerate}
\item A method for identifying automatically the files on which a document
depends;
\item A built-in, platform-independent mechanism for combining a document
with those files.
\end{enumerate}
Ar\TeX\ uses these two new features to automate the entire process of archive
creation. Running Ar\TeX\ on a \LaTeX\ document will create a new version
suitable for distribution to anyone with a standard installation of \LaTeXe\
on their system.

\begin{slshape}
Aside: the name `Ar\TeX' comes from a (rather loose) analogy with the
UNIX ar tool. The latter typically archives files of related object code to
make program linking easier; in the same way, Ar\TeX\ archives a collection
of related \LaTeX\ files to make document distribution easier\ldots
\end{slshape}

\section{Configuration}

Before attempting to run Ar\TeX, you must configure it for your operating
system by editing the script and uncommenting the appropriate set of
variable definitions. Two sets are provided in the script; one for a typical
UNIX system, the other for an MS-DOS system with em\TeX. Edit these
definitions as necessary to suit the particular system you are using.

It is assumed that the commands \verb|latex| and \verb|bibtex| invoke
\LaTeXe\ and \BibTeX, respectively, on your system. If this is not the
case, you will need to change \verb|$latex_cmd| and/or \verb|$bibtex_cmd|.

The \emph{configuration file} to be loaded at script startup is specified in
the variable \verb|$config_file|. On UNIX systems, the default name for this
file is \verb|~/.artexrc|; on DOS systems, the default file is
\verb|ARTEX.INI| in the current working directory. In the latter case, you
might wish to give an absolute pathname so that there is only one global
configuration file.

The script defines an associative array, \verb|%star|, which
flags file types that are to be included using a \emph{filecontents}$\ast$
environment instead of the normal \emph{filecontents} environment. The
default settings will cause PostScript files to be included using the
former, with all other files included by means of the latter. You can
change this permanently by editing the array definition, or
temporarily by redefining array elements in the configuration file.

\section{Running Ar\TeX}
\subsection{Command Line Syntax}

On UNIX systems, the command line syntax for running Ar\TeX\ is
\begin{verbatim}
    % artex [options] input_file [output_file]
\end{verbatim}

Under DOS, which doesn't support the \verb|#!| syntax for specifying a
script interpreter, you can use
\begin{verbatim}
    C:\> perl artex [options] input_file [output_file]
\end{verbatim}
The above can be placed in a batch file, \verb|ARTEX.BAT|, to achieve
the same effect as in UNIX; alternatively, you can put the following
batch file wrapper around the script:
\begin{verbatim}
    @rem = '
    @echo off
    perl -S %0.bat %1 %2 %3 %4 %5 %6 %7 %8 %9 
    goto endofperl
    ';
    # insert Perl code here
    __END__
   :endofperl
\end{verbatim}
This avoids the need for two separate files.

Those who use \textsf{4DOS} in place of \verb|COMMAND.COM| have a further
option.  The script can be renamed \verb|ARTEX.PL| and the following command
can be added to the \verb|4START.BAT| file:
\begin{verbatim}
    set .pl=c:\path\to\perl.exe
\end{verbatim}
where \verb|c:\path\to\perl.exe| is the full pathname of the Perl
interpreter.

\subsection{Command Line Options}

The following command line options can be specified before the input
filename:
\begin{description}
\item[\texttt{-f}]
Ensures fast startup of the script, i.e., the configuration
file is not accessed. Variables will have their default values and
there will be no forced inclusion/exclusion of files.
\item[\texttt{-i file1[,file2,...]}]
Specifies a list of files to be forcibly included in the archive.
Overrides what was specified in the configuration file.
\item[\texttt{-i none}]
Cancels forced inclusion that may have been requested via the
configuration file.
\item[\texttt{-e file1[,file2,...]}]
Specifies a list of files to be forcibly excluded from the archive.
Overrides anything specified in the configuration file.
\item[\texttt{-e none}]
Cancels forced exclusion that may have been requested via the
configuration file.
\item[\texttt{-c}]
Prompts the user to confirm the inclusion of each file.
\item[\texttt{-b}]
Forces the script to use the \verb|.bib| and \verb|.bst| files
if the document contains a \verb|\bibliography| command. These files are
candidates for inclusion regardless of whether any related citations occur
within the document. The default behaviour is to include the \verb|.bbl|
file, generated by running \BibTeX, instead---but this is done \emph{only}
if citations are found in the document.
\item[\texttt{-q}]
Quiet mode. The screen output normally produced by \LaTeX\ is suppressed.
\item[\texttt{-v}]
Prints the program version and exits.
\item[\texttt{-h}]
Prints help on command line options, then exits.
\end{description}

\section{How it Works}

After parsing command line options and, if necessary, reading the
configuration file, the script checks the input document for \LaTeXe\
compliance. A temporary copy of the document is then created, to which
\verb|\nonstopmode| and \verb|\listfiles| commands are added (if not already
present). \LaTeX\ is run on this file, thereby generating a list of
dependencies for the document. This is stored in the logfile and (unless the
\verb|-q| option has been used) is echoed on the screen.

An initial list of candidates for inclusion in the archive is generated by
extracting filenames from the list of dependencies in the logfile. For each
file in this list, the associated description, if any, is examined. Files
with descriptions containing the words \texttt{Standard LaTeX} are assumed
to be part of the standard distribution of \LaTeXe\ and are ignored. For all
remaining files in the dependency list, full pathnames are determined by
searching the directories specified by the \verb|TEXINPUTS| environment
variable. The files and their full pathnames are stored in an associative
array named \verb|%dependency|.

Bibliographies are dealt with separately, by examining the auxiliary file
(extension \verb|.aux|). If the \verb|-b| option (requesting the inclusion
of \verb|.bib| and \verb|.bst| files only) has been specified and a
\verb|\bibdata| command is found in the auxiliary file, then the
bibliographies that are arguments to this command become candidates for
inclusion. A list of directories obtained from the \verb|BIBINPUTS|
environment variable is searched to identify the full pathnames of each
bibliography file and this information is stored in the dependencies
array. The bibliography style becomes a candidate for inclusion unless it is
flagged as a `standard style' in array \verb|%stdbib| (by default the
standard styles are \emph{plain}, \emph{unsrt}, \emph{abbrv} and
\emph{alpha}). A full pathname for the \verb|.bst| file is found by
searching the \verb|TEXINPUTS| directories.

By default, bibliographic data are bundled with a document in the form
of a \verb|.bbl| file, generated by running \BibTeX. However, this
is done \emph{only} if \verb|\citation| commands are found in the
auxiliary file.

Next, dependencies are added or removed according to the contents of the
\verb|@include| and \verb|@exclude| arrays. These are defined either
in the runtime configuration file or via the command line (options
\verb|-i| and \verb|-e|). Command line specifications override any
in the configuration file. If the \verb|-c| option has been selected,
the user is prompted to confirm the inclusion of each candidate.  If no
confirmation is given, the candidate is removed from the list of
dependencies.

Finally, an expanded version of the original document, complete with
\emph{filecontents} and \emph{filecontents}$\ast$ environments, is written
to a file. The name of this file can be specified on the command line. If no
name is supplied, a backup copy of the original document is created
(extension \verb|.te~| or \verb|.lt~|, depending on whether the input file
extension is \verb|.tex| or \verb|.ltx|) and the original is overwritten by
the new version.

\section{Customisation}

Runtime customisation of script behaviour is achieved through use of a
\emph{configuration file}. The main purpose of this file is to allow
specification of files that will always be included in or excluded from the
archive. Such files should be listed in arrays named \verb|@include| and
\verb|@exclude|. A typical configuration file might contain the
following:
\begin{verbatim}
    @include = (
      'mystuff.sty'  # I always use this in documents
    );

    @exclude = (
      'known.sty',   # I know that recipients have this package
      'odd.sty'      # standard package that doesn't announce itself as such
    );
\end{verbatim}

You can override definitions of \verb|@include| and \verb|@exclude| using
the \verb|-i| and \verb|-e| options on the command line. These options are
normally followed by comma-separated lists of filenames, or by the word
`none'. If `none' is specified, any definition of the corresponding array in
the configuration file is ignored. Thus if the configuration file was as
given above and the command
\begin{verbatim}
    artex -e none test.tex
\end{verbatim}
was issued, the definition of \verb|@exclude| would be ignored and the
files \verb|known.sty| and \verb|odd.sty| \emph{would} be included if the
document depended on them.

The configuration file may also be used to change the definitions of the
\verb|%star| and \verb|%stdbib| associative arrays.

\section{Bugs and Limitations}

Ar\TeX\ was hacked together fairly quickly, and hasn't been tested as
thoroughly as I would like. I'd appreciate being notified of any bugs
that you find. If you feel moved to fix any of them, please send me your
patches. I developed the script for Perl 4.036 in two environments: a
Silicon Graphics workstation running Irix 5.2 and a 486 PC with MS-DOS
6.2 and em\TeX. If your system resembles either of these then you should
not have any difficulties. I've assumed that \TeX\ and \LaTeX\ use the
environment variables \verb|TEXINPUTS| and \verb|BIBINPUTS| to
identify directories which will be searched for files. If this is not the
case on your system, the script will need some alteration.

One known problem concerns the \verb|-q| option (quiet mode), which
doesn't seem to work under MS-DOS (I've not tried it with any other
DOS---feedback on this would be welcome).

Ar\TeX\ relies on the \LaTeXe\ \verb|\listfiles| command for the
detection of dependencies and hence is subject to the limitations of
that command. In particular, it cannot cope with files that are loaded
via the low-level \TeX\ \verb|\input| directive. 

The other main limitation is the mechanism used to determine
whether files are part of the standard \LaTeX\ distribution. Ar\TeX\
assumes that a file is a standard one if the words \texttt{Standard LaTeX}
appear in the description printed by \verb|\listfiles|. A standard
file which doesn't use this wording will be accidentally bundled with
the document, and a non-standard file which happens to use this
wording will be wrongly omitted. Mistakes that occur regularly can be
rectified by adding the offending files to the \verb|@include| or
\verb|@exclude| lists in the configuration file.

Syntax errors in the configuration file are trapped, but note that
it is still possible for Perl code in this file to break the script---e.g.,
by incorrectly redefining \verb|$copy_cmd| or \verb|@texinputs|.

\end{document}