1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
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>
|
