Initial commit

author: Norbert Preining <norbert@preining.info> 2019-09-02 13:46:59 +0900
committer: Norbert Preining <norbert@preining.info> 2019-09-02 13:46:59 +0900
commit: e0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree: 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/artex/artexman.html
1 files changed, 323 insertions, 0 deletions
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>
+
author	Norbert Preining <norbert@preining.info>	2019-09-02 13:46:59 +0900
committer	Norbert Preining <norbert@preining.info>	2019-09-02 13:46:59 +0900
commit	e0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree	60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/artex/artexman.html