summaryrefslogtreecommitdiff
path: root/support/artex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/artex
Initial commit
Diffstat (limited to 'support/artex')
-rw-r--r--support/artex/README.artex29
-rw-r--r--support/artex/artex538
-rw-r--r--support/artex/artexman.html323
-rw-r--r--support/artex/artexman.tex303
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}