Initial commit

4 files changed, 1193 insertions, 0 deletions

diff --git a/support/artex/README.artex b/support/artex/README.artex
new file mode 100644
index 0000000000..269e271753
--- /dev/null
+++ b/support/artex/README.artex
@@ -0,0 +1,29 @@
+ArTeX version 1.00b
+-------------------
+
+ArTeX is a Perl script which simplifies the exchange of LaTeX documents
+between collaborating authors or between author and publisher.
+
+ArTeX analyzes a LaTeX 2e document to determine whether it loads any
+non-standard files. If non-standard files are identified, ArTeX creates
+filecontents or filecontents* environments for them and adds these
+environments to the input document. The new document can be processed
+successfully on any system with a standard installation of LaTeX 2e.
+
+ArTeX has been tested in the following environments:
+
+    (1) Irix 5.2, Perl 4.036 and 5.000
+    (2) MS-DOS 6.2, Perl 4.036 (bigperl), emTeX
+
+The ArTeX distribution contains the following files:
+
+    README.artex   -  this file
+    artex          -  Perl script
+    artexman.html  -  HTML version of manual
+    artexman.tex   -  LaTeX 2e version of manual
+
+Note: this is a beta release. Bug reports, comments and suggestions for
+impovements should be directed to:
+
+    Nick Efford
+    nde@dcre.leeds.ac.uk
\ No newline at end of file
diff --git a/support/artex/artex b/support/artex/artex
new file mode 100644
index 0000000000..2e44e7a681
--- /dev/null
+++ b/support/artex/artex
@@ -0,0 +1,538 @@
+#!/usr/local/bin/perl
+
+# artex  -  bundles a LaTeX2e document with non-standard external files.
+#
+# Copyright (C) 1995 Nick Efford.
+#
+# This script analyzes a LaTeX2e document to determine whether it loads
+# any non-standard files. Any such files are bundled with the document by
+# means of filecontents or filecontents* environments. The resulting
+# document should be portable to any system with a standard installation
+# of LaTeX.
+#
+# Tested with:
+#
+#     Perl 4.036 and 5.000 under Irix 5.2
+#     Perl 4.036 (bigperl) under MS-DOS 6.2
+#
+# Direct bug reports, comments and suggestions to:
+#
+#     nde@dcre.leeds.ac.uk
+
+($PROG = $0) =~ s!.*/!!;
+$VER = '1.00b';
+$DATE = '18/2/95';
+
+# Configuration - uncomment/edit to suit your OS.
+
+# UNIX:
+$copy_cmd = 'cp';
+$copy_out = "";
+$to_null = '1> /dev/null 2>&1';
+($TEXINPUTS = $ENV{'TEXINPUTS'})
+    || die "$PROG: TEXINPUTS variable not defined\n";
+@texinputs = split(/:/, $TEXINPUTS);
+$BIBINPUTS = $ENV{'BIBINPUTS'} || '.';
+@bibinputs = split(/:/, $BIBINPUTS);
+$config_file = "~/.$PROG" . "rc";
+
+# DOS (MS-DOS 6.2 and emTeX):
+#$copy_cmd = 'copy/y';
+#$copy_out = '> nul';
+#$to_null = '> nul';
+#($TEXINPUTS = $ENV{'TEXINPUT'})
+#    || die "$PROG: TEXINPUT variable not defined\n";
+#@texinputs = split(/;/, $TEXINPUTS);
+#$BIBINPUTS = $ENV{'BIBINPUT'} || '.';
+#@bibinputs = split(/;/, $BIBINPUTS);
+#$config_file = $PROG . '.ini';
+
+$latex_cmd = 'latex';
+$bibtex_cmd = 'bibtex';
+
+# The assignments below specify standard bibliography styles
+# (styles which will never be bundled with the document).
+
+$stdbib{'plain'} = 1;
+$stdbib{'unsrt'} = 1;
+$stdbib{'abbrv'} = 1;
+$stdbib{'alpha'} = 1;
+
+# The assignments below determine whether a 'filecontents' or
+# 'filecontents*' environment is used for a particular filetype.
+# 0 or 1 can be used for files native to LaTeX; 1 should be
+# used for other files (e.g, PostScript).
+
+$star{'.tex'} = 0;
+$star{'.ltx'} = 0;
+$star{'.cls'} = 0;
+$star{'.dtx'} = 0;
+$star{'.sty'} = 0;
+$star{'.fd'}  = 0;
+$star{'.bib'} = 0;
+$star{'.bbl'} = 0;
+$star{'.ind'} = 0;
+
+$star{'.eps'} = 1;
+$star{'.ps'}  = 1;
+
+# Construct a UNIX & DOS-compatible basename for temporary files.
+
+$t = time;
+$tmpbase = 'ar' . substr($t, length($t)-6);
+
+# Define temporary filenames and extensions.
+
+$tmpdoc = $tmpbase . '.tex';
+$tmplog = $tmpbase . '.log';
+$tmpaux = $tmpbase . '.aux';
+$tmpbbl = $tmpbase . '.bbl';
+
+@tmpext = ('.tex', '.log', '.dvi', '.aux', '.lof', '.lot',
+	   '.toc', '.bbl', '.blg', '.idx', '.ilg');
+
+
+############# you shouldn't need to change anything below here ##############
+
+
+# Parse command line arguments.
+
+while ($_ = $ARGV[0], /^-/) {
+    shift;
+    last if /^--$/;
+    /^-f/ && ($fast = 1);
+    /^-c/ && ($confirm = 1);
+    /^-b/ && ($bibfiles = 1);
+    /^-q/ && ($tex_out = $to_null);
+    /^-v/ && do { &Version; exit(0) };
+    /^-h/ && do { &Help; exit(0) };
+    if (/^-i/ && $ARGV[0] !~ /^-/) {
+	$include_list = $ARGV[0];
+	shift;
+    }
+    if (/^-e/ && $ARGV[0] !~ /^-/) {
+	$exclude_list = $ARGV[0];
+	shift;
+    }
+}
+
+(@ARGV < 1) && die "usage: $PROG [options] input_file [output_file]\n";
+
+# Check input filename argument.
+# Valid filenames have a .tex or .ltx extension.
+
+if (index($ARGV[0], '.') == -1) {
+    $bbl = $ARGV[0] . '.bbl';
+    $ARGV[0] .= '.tex';
+}
+else {
+    die "$PROG: invalid filename (not *.tex or *.ltx)\n"
+	unless ($ARGV[0] =~ /(\w+)\.(tex|ltx)$/);
+    $bbl = $1 . '.bbl';
+}
+
+unless ($fast) {
+
+    # Read configuration file, if it exists.
+
+    if (open(CFG, $config_file)) {
+	@config = <CFG>; close(CFG);
+	eval(join(' ', @config));
+	if ($@) {
+	    chop($@); die "$PROG: config file error - $@\n";
+	}
+    }
+}
+
+# Override @include and @exclude definitions from configuration file,
+# if necessary, using what's been specified on the command line.
+
+if (length($include_list) > 0) {
+    @include = &StringToArray($include_list);
+}
+
+if (length($exclude_list) > 0) {
+    @exclude = &StringToArray($exclude_list);
+}
+
+# Test whether input file is a LaTeX2e document.
+# Test also for the presence of \nonstopmode or \listfiles
+# commands and any existing filecontents environments.
+
+open(DOC, $ARGV[0]) || die "$PROG: cannot open $ARGV[0]\n";
+while (<DOC>) {
+    /^\\nonstopmode\b/        && ($nonstop = 1);
+    /^\\listfiles\b/          && ($listfiles = 1);
+    /^\\documentclass(\[|\{)/ && ($latex2e = 1);
+    if (/\\begin\{filecontents.?\}\{(.*)\}/) {
+	$bundled{$1} = 1;
+    }
+}
+close(DOC);
+
+die "$PROG: $ARGV[0] not a LaTeX 2e document\n" unless $latex2e;
+
+# Create a temporary copy of the document, adding \nonstopmode
+# and \listfiles commands if necessary.
+
+open(DOC, $ARGV[0]) || die "$PROG: cannot reopen $ARGV[0]\n";
+open(TMP, ">$tmpdoc") || die "$PROG: cannot open $tmpdoc for output\n";
+print TMP "\\nonstopmode\n" unless $nonstop;
+print TMP "\\listfiles\n"   unless $listfiles;
+print TMP while <DOC>;
+close(TMP); close(DOC);
+
+# Run LaTeX on temporary copy and analyze logfile for dependencies.
+
+system "$latex_cmd $tmpdoc $tex_out";
+($error = $? >> 8) && die "$PROG: error running LaTeX, exit code $error\n";
+open(LOG, $tmplog) || die "$PROG: cannot open $tmplog for input\n";
+while (<LOG>) {
+    last if /^\s+\*File List\*/;
+}
+while (<LOG>) {
+    last if /^\s+\*{11}/;
+    next if /\bStandard LaTeX\b/;
+    if (/^\s*(\w+\.\w+)/ && ($file = &Pathname($1, @texinputs)) ne "") {
+	$dependency{$1} = $file;
+    }
+}
+close(LOG);
+
+# Bibliographies are detected by analyzing the .aux file.
+# If the '-b' option has been specified, the .bib and .bst files
+# become candidates for inclusion; otherwise, a .bbl file is
+# generated by running BibTeX and this becomes a candidate for
+# inclusion. The latter course is taken only if the .aux file
+# contains \citation commands.
+
+open(AUX, $tmpaux) || die "$PROG: cannot open $tmpaux\n";
+while (<AUX>) {
+    /\\citation/ && ($citations = 1);
+    /\\bibstyle\{(.*)\}/ && ($bibstyle = $1);
+    if (/\\bibdata\{(.*)\}/) {
+	$bibdata = 1;
+	@biblist = split(/,/, $1);
+    }
+}
+close(AUX);
+
+if ($bibdata) {
+    if ($bibfiles) {
+
+	# Make .bib and .bst files candidates for inclusion.
+
+	foreach (@biblist) {
+	    $_ .= '.bib';
+	    if (($file = &Pathname($_, @bibinputs)) ne "") {
+		$dependency{$_} = $file;
+	    }
+	}
+	if (! $stdbib{$bibstyle}) {
+	    $bibstyle .= '.bst';
+	    if (($file = &Pathname($bibstyle, @texinputs)) ne "") {
+		$dependency{$bibstyle} = $file;
+	    }
+	}
+
+    }
+    else {
+
+	# Generate a .bbl file and make it a candidate for inclusion.
+
+	if ($citations) {
+	    system $bibtex_cmd, $tmpbase, $tex_out;
+	    ($error = $? >> 8)
+		&& die "$PROG: error running BibTeX, exit code $error\n";
+	    $dependency{$bbl} = $tmpbbl;
+	}
+
+    }
+}
+
+# Add or remove dependencies defined in @include and @exclude
+# arrays (derived from configuration file/command line).
+
+foreach (@include) {
+    if (($file = &Pathname($_, @texinputs)) ne "") {
+	$dependency{$_} = $file;
+    }
+}
+
+foreach (@exclude) {
+    delete $dependency{$_};
+}
+
+if (($n = scalar(keys %dependency)) == 1) {
+    print '1 dependency';
+}
+else {
+    print "$n dependencies";
+}
+
+# Determine whether further processing is necessary.
+
+if ($n == 0) {
+    if ($ARGV[1] ne "") {
+	print ": $ARGV[1] not created.\n";
+    }
+    else {
+	print ": $ARGV[0] unchanged.\n";
+    }
+    &Housekeeping($tmpbase, @tmpext);
+    exit(0);
+}
+else {
+    print ".\n";
+}
+
+# Perform interactive editing of dependency list if required.
+
+if ($confirm) {
+    foreach $file (keys %dependency) {
+	&Confirm($file) || delete($dependency{$file});
+    }
+}
+
+# Open a file for output.
+
+if ($ARGV[1] ne "") {
+    open(DOC, ">$ARGV[1]")
+	|| die "$PROG: cannot open $ARGV[1] for output\n";
+}
+else {
+
+    # Create a backup copy of the original document
+    # (extension .te~ or .lt~ for DOS & UNIX compatibility)
+    # then open original file for overwriting.
+
+    ($backup = $ARGV[0]) =~ s/.$/~/;
+    system("$copy_cmd $ARGV[0] $backup $copy_out");
+    ($error = $? >> 8)
+	&& die "$PROG: failed to create backup file $backup\n";
+    open(DOC, ">$ARGV[0]")
+	|| die "$PROG: cannot open $ARGV[0] for output\n";
+
+}
+
+# Write a new version of the document containing filecontents
+# environments for all non-standard files that are loaded.
+
+@files = sort(keys %dependency);
+if (@files) {
+    print DOC &Header(@files);
+    foreach $file (@files) {
+	next if $bundled{$file};
+	$env = &EnvName(%star, $file);
+	print DOC "\n\\begin{$env}{$file}\n";
+	open(FILE, $dependency{$file})
+	    || die "$PROG: cannot open $dependency{$file} for input\n";
+	print DOC while <FILE>;
+	close(FILE);
+	print DOC "\\end{$env}\n";
+    }
+    print DOC "\n";
+}
+
+open(TMP, $tmpdoc) || die "$PROG: cannot open $tmpdoc for input\n";
+while (<TMP>) {
+    next if /^\\nonstopmode/;
+    next if /^\\listfiles/;
+    print DOC;
+}
+
+close(TMP);
+close(DOC);
+&Housekeeping($tmpbase, @tmpext);
+
+exit(0);
+
+
+#############################################################################
+
+# Version:
+# writes information on program version to stdout.
+
+sub Version
+{
+    print "$PROG version $VER, last revised $DATE\n";
+}
+
+
+#############################################################################
+
+# Help:
+# writes help on command line options to stdout.
+
+sub Help
+{
+    print "\n";
+    &Version;
+    print <<"END";
+
+Analyzes a LaTeX2e document to determine whether it loads any non-standard
+files. Such files, if they exist, are then bundled with the document by
+means of filecontents or filecontents* environments. The resulting document
+should be portable to any system with a standard installation of LaTeX.
+
+Usage: $PROG [options] input_file [output_file]
+
+input_file must have the extension .tex or .ltx (the extension can be
+omitted from the command line if it is .tex). Output replaces the original
+file if output_file is not specified (backup of original created, extension
+.te~ or .lt~).
+
+Command line options:
+
+    -f  fast startup (skip reading configuration file)
+    -c  prompt for confirmation before including a file
+    -b  include .bib files instead of creating a .bbl file
+    -q  quiet mode (no screen output from LaTeX)
+    -v  print program version and exit
+    -h  display this information and exit
+
+    -i file1[,file2,...]  files for which inclusion is guaranteed
+    -e file1[,file2,...]  files guaranteed to be excluded
+
+END
+}
+
+
+#############################################################################
+
+# StringToArray:
+# Converts a string of comma-separated names into an array of names,
+# or an empty array if the string is "none".
+
+sub StringToArray
+{
+    local($string) = @_;
+    local(@array);
+
+    if ($string =~ /^none$/i) {
+	@array = ();
+    }
+    else {
+	@array = split(/,/, $string);
+    }
+
+    @array;
+}
+
+
+#############################################################################
+
+# Pathname:
+# searches for a filename in a list of directories, returning the full
+# pathname of the file if found, an empty string otherwise.
+
+sub Pathname
+{
+    local($target, @dirlist) = @_;
+    local($file, $result);
+    $result = "";
+
+  DIR_LOOP:
+    foreach $dir (@dirlist) {
+	opendir(DIR, $dir) || die "$PROG: cannot access directory $dir\n";
+	while ($file = readdir(DIR)) {
+	    if ($file eq $target) {
+		$result = $dir . '/' . $target;
+		last DIR_LOOP;
+	    }
+	}
+    }
+
+    $result;
+}
+
+
+#############################################################################
+
+# Header:
+# constructs header text for the output document.
+
+sub Header
+{
+    local(@files) = @_;
+    local($n)     = $#files + 1;
+    local($hdr)   = "% Packaged by $PROG v$VER";
+    local(@mon)   = ('Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+		     'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec');
+    local(@h)     = ('00' .. '23');
+    local(@ms)    = ('00' .. '59');
+    local(@t)     = localtime;
+
+    $hdr .= " at $h[$t[2]]:$ms[$t[1]]:$ms[$t[0]], $t[3] $mon[$t[4]] $t[5].\n";
+
+    if ($n == 1) {
+	$hdr .= '% A new file';
+    }
+    else {
+	$hdr .= "% Up to $n new files";
+    }
+    $hdr .= " may be created when you first process this document:\n";
+    foreach (@files) {
+	$hdr .= "% $_\n";
+    }
+
+    $hdr;
+}
+
+
+#############################################################################
+
+# Confirm:
+# prompts for confirmation that a file is to be included in a
+# filecontents or filecontents* environment.
+
+sub Confirm
+{
+    local($file) = @_;
+    local($yes);
+
+    print "Include $file? (y/n) [y]: ";
+    chop($_ = <STDIN>);
+
+    $yes = (length == 0 || /^y/i);
+}
+
+
+#############################################################################
+
+# EnvName:
+# returns "filecontents*" if the specified file's extension has been
+# flagged as requiring a starred environment; otherwise returns
+# "filecontents".
+
+sub EnvName
+{
+    local(%star, $file) = @_;
+    local($name) = 'filecontents';
+    local($i);
+
+    if (($i = index($file, '.')) != -1 && $star{substr($file, $i)}) {
+	$name .= '*';
+    }
+
+    $name;
+}
+
+
+#############################################################################
+
+# Housekeeping:
+# removes a set of filenames given a basename and a list of extensions.
+
+sub Housekeeping
+{
+    local($base, @ext) = @_;
+    local($file);
+
+    foreach (@ext) {
+	$file = $base . $_;
+	if (-e $file) {
+	    unlink $file || die "$PROG: error removing $file\n";
+	}
+    }
+}
diff --git a/support/artex/artexman.html b/support/artex/artexman.html
new file mode 100644
index 0000000000..b47f16c28c
--- /dev/null
+++ b/support/artex/artexman.html
@@ -0,0 +1,323 @@
+<HTML>
+<HEAD>
+<TITLE>ArTeX User Manual</TITLE>
+</HEAD>
+<BODY>
+
+<H1>ArTeX User Manual</H1>
+<H2>N D Efford</H2>
+<H3>Version 1.00b, 18/2/95</H3>
+
+ArTeX is a Perl script which analyzes a LaTeX2e document to determine
+whether it loads any non-standard files. Any such files are bundled with
+the document by means of <EM>filecontents</EM> or <EM>filecontents</EM>*
+environments, as appropriate. The result should be portable to any system
+with a standard installation of LaTeX.
+
+<A NAME="contents"><H3>Contents</H3></A>
+<OL>
+<LI><A HREF="#intro">Introduction</A>
+<LI><A HREF="#config">Configuration</A>
+<LI><A HREF="#running">Running ArTeX</A>
+<LI><A HREF="#how">How it Works</A>
+<LI><A HREF="#custom">Customisation</A>
+<LI><A HREF="#bugs">Bugs and Limitations</A>
+</OL>
+
+<HR>
+
+<A NAME="intro"><H3>1 Introduction</H3></A>
+
+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.
+
+<P>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 <EM>archive</EM> 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 <EM>tar</EM>, <EM>gzip</EM> and
+<EM>uuencode</EM> cannot be unpacked on a normal PC system running MS-DOS.
+
+<P>Fortunately, LaTeX2e provides
+<OL>
+<LI>A method for identifying automatically the files on which a document
+depends;
+<LI>A built-in, platform-independent mechanism for combining a document
+with those files.
+</OL>
+ArTeX uses these two new features to automate the entire process of archive
+creation. Running ArTeX on a LaTeX document will create a new version
+suitable for distribution to anyone with a standard installation of LaTeX2e
+on their system.
+
+<P><EM>Aside: the name `ArTeX' 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, ArTeX archives a collection of
+related LaTeX files to make document distribution easier...</EM>
+
+<P><EM><A HREF="#contents">table of contents</A></EM>
+<P><HR>
+
+<A NAME="config"><H3>2 Configuration</H3></A>
+
+Before attempting to run ArTeX, 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 emTeX. Edit
+these definitions as necessary to suit the particular system you are
+using.
+
+<P>It is assumed that the commands <KBD>latex</KBD> and
+<KBD>bibtex</KBD> invoke LateX2e and BibTeX, respectively, on your
+system. If this is not the case, you will need to change
+<KBD>$latex_cmd</KBD> and/or <KBD>$bibtex_cmd</KBD>.
+
+<P>The <A HREF="#custom">configuration file</A> to be loaded at script
+startup is specified in the variable <KBD>$config_file</KBD>. On UNIX
+systems, the default name for this file is <KBD>~/.artexrc</KBD>; on DOS
+systems, the default file is <KBD>ARTEX.INI</KBD> 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.
+
+<P>The script defines an associative array, <KBD>%star</KBD>, which
+flags file types that are to be included using a <EM>filecontents</EM>*
+environment instead of the normal <EM>filecontents</EM> 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.
+
+<P><EM><A HREF="#contents">table of contents</A></EM>
+<P><HR>
+
+<A NAME="running"><H3>3 Running ArTeX</H3></A>
+
+<H4>3.1 Command Line Syntax</H4>
+
+On UNIX systems, the command line syntax for running ArTeX is
+<PRE>
+    % artex [options] input_file [output_file]
+</PRE>
+
+<P>Under DOS, which doesn't support the #! syntax for specifying a script
+interpreter, you can use
+<PRE>
+    C:\> perl artex [options] input_file [output_file]
+</PRE>
+The above can be placed in a batch file, ARTEX.BAT, to achieve the same
+effect as in UNIX; alternatively, you can put the following batch file
+wrapper around the script:
+<PRE>
+    @rem = '
+    @echo off
+    perl -S %0.bat %1 %2 %3 %4 %5 %6 %7 %8 %9 
+    goto endofperl
+    ';
+    # insert Perl code here
+    __END__
+   :endofperl
+</PRE>
+This avoids the need for two separate files.
+
+<P>Those who use 4DOS in place of COMMAND.COM have a further option.
+The script can be renamed ARTEX.PL and the following command can be
+added to the 4START.BAT file:
+<PRE>
+    set .pl=c:\path\to\perl.exe
+</PRE>
+where <KBD>c:\path\to\perl.exe</KBD> is the full pathname of the Perl
+interpreter.
+
+<H4>3.2 Command Line Options</H4>
+
+The following command line options can be specified before the input
+filename:
+<DL>
+<DT><KBD>-f</KBD>
+<DD>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.
+<DT><KBD>-i file1[,file2,...]</KBD>
+<DD>Specifies a list of files to be forcibly included in the archive.
+Overrides what was specified in the configuration file.
+<DT><KBD>-i none</KBD>
+<DD>Cancels forced inclusion that may have been requested via the
+configuration file.
+<DT><KBD>-e file1[,file2,...]</KBD>
+<DD>Specifies a list of files to be forcibly excluded from the archive.
+Overrides anything specified in the configuration file.
+<DT><KBD>-e none</KBD>
+<DD>Cancels forced exclusion that may have been requested via the
+configuration file.
+<DT><KBD>-c</KBD>
+<DD>Prompts the user to confirm the inclusion of each file.
+<DT><KBD>-b</KBD>
+<DD>Forces the script to use the <KBD>.bib</KBD> and <KBD>.bst</KBD> files
+if the document contains a <KBD>\bibliography</KBD> command. These files are
+candidates for inclusion regardless of whether any related citations occur
+within the document. The default behaviour is to include the <KBD>.bbl</KBD>
+file, generated by running BibTeX, instead - but this is done <EM>only</EM>
+if citations are found in the document.
+<DT><KBD>-q</KBD>
+<DD>Quiet mode. The screen output normally produced by LaTeX is
+suppressed.
+<DT><KBD>-v</KBD>
+<DD>Prints the program version and exits.
+<DT><KBD>-h</KBD>
+<DD>Prints help on command line options, then exits.
+</DL>
+
+<P><EM><A HREF="#contents">table of contents</A></EM>
+<P><HR>
+
+<A NAME="how"><H3>4 How it Works</H3></A>
+
+After parsing command line options and, if necessary, reading the <A
+HREF="#custom">configuration file</A>, the script checks the input document
+for LaTeX2e compliance. A temporary copy of the document is then created, to
+which <KBD>\nonstopmode</KBD> and <KBD>\listfiles</KBD> 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 <KBD>-q</KBD> option has been used) is echoed on the screen.
+
+<P>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
+`Standard LaTeX' are assumed to be part of the standard distribution
+of LaTeX2e and are ignored. For all remaining files in the dependency
+list, full pathnames are determined by searching the directories specified
+by the <KBD>TEXINPUTS</KBD> environment variable. The files and their full
+pathnames are stored in an associative array named <KBD>%dependency</KBD>.
+
+<P>Bibliographies are dealt with separately, by examining the auxiliary file
+(extension <KBD>.aux</KBD>). If the <KBD>-b</KBD> option (requesting the
+inclusion of <KBD>.bib</KBD> and <KBD>.bst</KBD> files only) has been
+specified and a <KBD>\bibdata</KBD> 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 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 <KBD>%stdbib</KBD> (by default the standard
+styles are <EM>plain</EM>, <EM>unsrt</EM>, <EM>abbrv</EM> and
+<EM>alpha</EM>). A full pathname for the <KBD>.bst</KBD> file is found by
+searching the <KBD>TEXINPUTS</KBD> directories.
+
+<P>By default, bibliographic data are bundled with a document in the form
+of a <KBD>.bbl</KBD> file, generated by running BibTeX. However, this
+is done <EM>only</EM> if <KBD>\citation</KBD> commands are found in the
+auxiliary file.
+
+<P>Next, dependencies are added or removed according to the contents of the
+<KBD>@include</KBD> and <KBD>@exclude</KBD> arrays. These are defined either
+in the runtime configuration file or via the command line (options
+<KBD>-i</KBD> and <KBD>-e</KBD>). Command line specifications override any
+in the configuration file. If the <KBD>-c</KBD> 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.
+
+<P>Finally, an expanded version of the original document, complete with
+<EM>filecontents</EM> and <EM>filecontents</EM>* 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 <KBD>.te~</KBD> or <KBD>.lt~</KBD>, depending on whether the
+input file extension is <KBD>.tex</KBD> or <KBD>.ltx</KBD>) and the original
+is overwritten by the new version.
+
+<P><EM><A HREF="#contents">table of contents</A></EM>
+<P><HR>
+
+<A NAME="custom"><H3>5 Customisation</H3></A>
+
+Runtime customisation of script behaviour is achieved through use of a
+<EM>configuration file</EM>. 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 <KBD>@include</KBD> and
+<KBD>@exclude</KBD>. A typical configuration file might contain the
+following:
+<PRE>
+    @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
+    );
+</PRE>
+
+<P>You can override definitions of <KBD>@include</KBD> and
+<KBD>@exclude</KBD> using the <KBD>-i</KBD> and <KBD>-e</KBD> 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
+<PRE>
+    artex -e none test.tex
+</PRE>
+was issued, the definition of <KBD>@exclude</KBD> would be ignored and
+the files <KBD>known.sty</KBD> and <KBD>odd.sty</KBD> <EM>would</EM> be
+included if the document depended on them.
+
+<P>The configuration file may also be used to change the definitions of the
+<KBD>%star</KBD> and <KBD>%stdbib</KBD> associative arrays.
+
+<P><EM><A HREF="#contents">table of contents</A></EM>
+<P><HR>
+
+<A NAME="bugs"><H3>6 Bugs and Limitations</H3></A>
+
+ArTeX 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 emTeX. 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 <KBD>TEXINPUTS</KBD> and <KBD>BIBINPUTS</KBD> to
+identify directories which will be searched for files. If this is not the
+case on your system, the script will need some alteration.
+
+<P>One known problem concerns the <KBD>-q</KBD> 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).
+
+<P>ArTeX relies on the LaTeX2e <KBD>\listfiles</KBD> 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 <KBD>\input</KBD> directive. 
+
+<P>The other main limitation is the mechanism used to determine
+whether files are part of the standard LaTeX distribution. ArTeX
+assumes that a file is a standard one if the words `Standard LaTeX'
+appear in the description printed by <KBD>\listfiles</KBD>. 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 <KBD>@include</KBD> or
+<KBD>@exclude</KBD> lists in the configuration file.
+
+<P>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 <KBD>$copy_cmd</KBD> or
+<KBD>@texinputs</KBD>.
+
+<P><EM><A HREF="#contents">table of contents</A></EM>
+<P><HR>
+
+<P>Nick Efford <BR>
+<EM>nde@dcre.leeds.ac.uk</EM>
+
+</BODY>
+</HTML>
+
diff --git a/support/artex/artexman.tex b/support/artex/artexman.tex
new file mode 100644
index 0000000000..818a6f195d
--- /dev/null
+++ b/support/artex/artexman.tex
@@ -0,0 +1,303 @@
+\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}