From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- support/artex/README.artex | 29 +++ support/artex/artex | 538 ++++++++++++++++++++++++++++++++++++++++++++ support/artex/artexman.html | 323 ++++++++++++++++++++++++++ support/artex/artexman.tex | 303 +++++++++++++++++++++++++ 4 files changed, 1193 insertions(+) create mode 100644 support/artex/README.artex create mode 100644 support/artex/artex create mode 100644 support/artex/artexman.html create mode 100644 support/artex/artexman.tex (limited to 'support/artex') 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 = ; 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 () { + /^\\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 ; +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 () { + last if /^\s+\*File List\*/; +} +while () { + 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 () { + /\\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 ; + close(FILE); + print DOC "\\end{$env}\n"; + } + print DOC "\n"; +} + +open(TMP, $tmpdoc) || die "$PROG: cannot open $tmpdoc for input\n"; +while () { + 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($_ = ); + + $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 @@ + + +ArTeX User Manual + + + +

ArTeX User Manual

+

N D Efford

+

Version 1.00b, 18/2/95

+ +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 filecontents or filecontents* +environments, as appropriate. The result should be portable to any system +with a standard installation of LaTeX. + +

Contents

+
    +
  1. Introduction +
  2. Configuration +
  3. Running ArTeX +
  4. How it Works +
  5. Customisation +
  6. Bugs and Limitations +
+ +
+ +

1 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 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 tar, gzip and +uuencode cannot be unpacked on a normal PC system running MS-DOS. + +

Fortunately, LaTeX2e provides +

    +
  1. A method for identifying automatically the files on which a document +depends; +
  2. A built-in, platform-independent mechanism for combining a document +with those files. +
+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. + +

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... + +

table of contents +


+ +

2 Configuration

+ +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. + +

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

The configuration file to be loaded at script +startup is specified in the variable $config_file. On UNIX +systems, the default name for this file is ~/.artexrc; on DOS +systems, the default file is 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, %star, which +flags file types that are to be included using a filecontents* +environment instead of the normal 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. + +

table of contents +


+ +

3 Running ArTeX

+ +

3.1 Command Line Syntax

+ +On UNIX systems, the command line syntax for running ArTeX is +
+    % artex [options] input_file [output_file]
+
+ +

Under DOS, which doesn't support the #! syntax for specifying a script +interpreter, you can use +

+    C:\> perl artex [options] input_file [output_file]
+
+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: +
+    @rem = '
+    @echo off
+    perl -S %0.bat %1 %2 %3 %4 %5 %6 %7 %8 %9 
+    goto endofperl
+    ';
+    # insert Perl code here
+    __END__
+   :endofperl
+
+This avoids the need for two separate files. + +

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: +

+    set .pl=c:\path\to\perl.exe
+
+where c:\path\to\perl.exe is the full pathname of the Perl +interpreter. + +

3.2 Command Line Options

+ +The following command line options can be specified before the input +filename: +
+
-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. +
-i file1[,file2,...] +
Specifies a list of files to be forcibly included in the archive. +Overrides what was specified in the configuration file. +
-i none +
Cancels forced inclusion that may have been requested via the +configuration file. +
-e file1[,file2,...] +
Specifies a list of files to be forcibly excluded from the archive. +Overrides anything specified in the configuration file. +
-e none +
Cancels forced exclusion that may have been requested via the +configuration file. +
-c +
Prompts the user to confirm the inclusion of each file. +
-b +
Forces the script to use the .bib and .bst files +if the document contains a \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 .bbl +file, generated by running BibTeX, instead - but this is done only +if citations are found in the document. +
-q +
Quiet mode. The screen output normally produced by LaTeX is +suppressed. +
-v +
Prints the program version and exits. +
-h +
Prints help on command line options, then exits. +
+ +

table of contents +


+ +

4 How it Works

+ +After parsing command line options and, if necessary, reading the configuration file, the script checks the input document +for LaTeX2e compliance. A temporary copy of the document is then created, to +which \nonstopmode and \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 -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 +`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 TEXINPUTS environment variable. The files and their full +pathnames are stored in an associative array named %dependency. + +

Bibliographies are dealt with separately, by examining the auxiliary file +(extension .aux). If the -b option (requesting the +inclusion of .bib and .bst files only) has been +specified and a \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 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 %stdbib (by default the standard +styles are plain, unsrt, abbrv and +alpha). A full pathname for the .bst file is found by +searching the TEXINPUTS directories. + +

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

Next, dependencies are added or removed according to the contents of the +@include and @exclude arrays. These are defined either +in the runtime configuration file or via the command line (options +-i and -e). Command line specifications override any +in the configuration file. If the -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 +filecontents and filecontents* 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 .te~ or .lt~, depending on whether the +input file extension is .tex or .ltx) and the original +is overwritten by the new version. + +

table of contents +


+ +

5 Customisation

+ +Runtime customisation of script behaviour is achieved through use of a +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 @include and +@exclude. A typical configuration file might contain the +following: +
+    @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
+    );
+
+ +

You can override definitions of @include and +@exclude using the -i and -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 +

+    artex -e none test.tex
+
+was issued, the definition of @exclude would be ignored and +the files known.sty and odd.sty would be +included if the document depended on them. + +

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

table of contents +


+ +

6 Bugs and Limitations

+ +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 TEXINPUTS and 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 -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). + +

ArTeX relies on the LaTeX2e \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 \input directive. + +

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 \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 @include or +@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 $copy_cmd or +@texinputs. + +

table of contents +


+ +

Nick Efford
+nde@dcre.leeds.ac.uk + + + + 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} -- cgit v1.2.3