1ARLATEX(1) User Commands ARLATEX(1)
2
6 arlatex - archive a number of ancillary LaTeX files into a master .tex
7 file
8
10 arlatex [--outfile=filename.tex] --document=filename.tex filename ...
11 arlatex --version
13 arlatex --help
15
17 arlatex is an archiving program like shar, tar, zip, etc. Unlike those
18 other archivers, however, arlatex is designed specifically for use with
19 LaTeX. arlatex takes the name of a master .tex file and a number of
20 ancillary files used by that master file (e.g., .tex, .sty, .cls, and
21 .eps files). From these, arlatex outputs a single file that, when it's
22 run through latex, both regenerates the ancillary files and compiles
23 the document into a .dvi file.
24 arlatex has a few advantages over other archiving programs:
26 • The .tex files produced by arlatex are in a plain-text format.
28 They are therefore perfectly portable and trivial to e-mail to
29 colleagues.
30 • arlatex needs only LaTeX to run. There is no dependence on any
32 external tools.
33 • There is no explicit extraction step. As the generated document is
35 run through latex, it extracts the ancillary files and builds the
36 document in the same step. The user running latex may not even
37 notice that additional files are being produced.
38 arlatex works by writing a number of "\begin{filecontents*}" ...
40 "\end{filecontents*}" blocks to the output file, followed by the
41 contents of the master file. (In fact, any LaTeX comments at the
42 beginning of the master file are hoisted to the top of the generated
43 file. This enables the author to draw attention, if so desired, to the
44 fact that ancillary files will be generated.) The "filecontents*"
45 environment, part of standard LaTeX2e, writes its contents verbatim to
46 a specified file.
47
49 --version
50 Output the arlatex script's version number.
51 --help
53 Output brief arlatex usage information.
54 --document=.tex file
56 Specify the master document. The output from arlatex is this file
57 with all of the other files named on the command line prepended to
58 it. Note that "--document" is a mandatory parameter; arlatex will
59 abort with an error message if "--document" is not specified.
60 --outfile=.tex file
62 Specify the output file. The output file looks just like the
63 master document, but with a number of "filecontents*" environments
64 preceding the "\documentclass" line. If "--outfile" is not
65 specified, output will be written to the standard output device.
66
68 Suppose you have a paper called paper.tex that loads a custom package
69 with "\usepackage{mypackage}". You want to submit the paper to a
70 conference, but you want to be absolutely certain that mypackage.sty
71 doesn't get lost as your paper is shuttled from person to person.
72 Here's how arlatex can be of use:
73 arlatex --document=paper.tex mypackage.sty --outfile=paper-submit.tex
75 When paper-submit.tex is processed with latex, it builds just like the
77 original paper.tex, except that it additionally creates a mypackage.sty
78 in the current directory:
79 This is TeX, Version 3.14159 (Web2C 7.3.1)
81 (paper-submit.tex
82 LaTeX2e <1999/12/01> patch level 1
83 Babel <v3.6Z> and hyphenation patterns for american, french, german,
84 ngerman, italian, nohyphenation, loaded.
85 LaTeX Warning: Writing file `./mypackage.sty'.
87 (/usr/share/texmf/tex/latex/base/article.cls
89 Document Class: article 1999/09/10 v1.4a Standard LaTeX document class
90 (/usr/share/texmf/tex/latex/base/size12.clo)) (mypackage.sty)
91 .
92 .
93 .
94 As another example, here's how you could bundle together all of the
96 files needed to build a large document for longevity:
97 arlatex --document=thesis.tex abstract.tex introduction.tex
99 background.tex approach.tex experiments.tex relatedwork.tex
100 conclusions.tex before.eps after.eps fast.eps slow.eps
101 podunkUthesis.cls --outfile=thesis-all.tex
102 As the number of files to archive together increases it becomes more
104 cumbersome to run arlatex manually. Fortunately, using arlatex with
105 bundledoc is straightforward. bundledoc finds all of the files needed
106 to build the document, and arlatex combines them into a single file.
107 The following are examples of the "bundle:" line you might use in a
108 bundledoc configuration file:
109 Unix:
111 bundle: (arlatex --document=$BDBASE.tex $BDINPUTS \
112 --outfile=$BDBASE-all.tex)
113 Windows:
115 bundle: arlatex --document=%BDBASE%.tex %BDINPUTS% \
116 --outfile=%BDBASE%-all.tex
117 See the bundledoc documentation for more information.
119
121 arlatex makes use of LaTeX's "filecontents*" environment. It passes
122 "filecontents*" the "overwrite" option to indicate that existing files
123 with the same name should be overwritten. Be forewarned that building
124 the generated file will overwrite the files used to create it.
125 It is best to avoid bundling binary files (e.g., included graphics)
127 with arlatex. These typically do not extract cleanly.
128
130 bundledoc(1), latex(1), shar(1), tar(1), zip(1)
131
133 Scott Pakin, scott+bdoc@pakin.org
134v1.1 2022-10-04 ARLATEX(1)