Debian Codegraph @

texmf-dist/doc/man/man1/arlatex.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "ARLATEX 1"
58 .TH ARLATEX 1 2026-05-16 v1.1 "User Commands"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 arlatex \- archive a number of ancillary LaTeX files into a master
65 \&.tex file
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 arlatex
69 [\fB\-\-outfile\fR=\fIfilename\fR\fI.tex\fR]
70 \&\fB\-\-document\fR=\fIfilename\fR\fI.tex\fR
71 \&\fIfilename\fR
72 \&...
73 .PP
74 arlatex
75 \&\fB\-\-version\fR
76 .PP
77 arlatex
78 \&\fB\-\-help\fR
79 .SH DESCRIPTION
80 .IX Header "DESCRIPTION"
81 \&\fBarlatex\fR is an archiving program like \fBshar\fR, \fBtar\fR, \fBzip\fR, etc.
82 Unlike those other archivers, however, \fBarlatex\fR is designed
83 specifically for use with LaTeX. \fBarlatex\fR takes the name of a
84 master \fI.tex\fR file and a number of ancillary files used by that
85 master file (e.g., \fI.tex\fR, \fI.sty\fR, \fI.cls\fR, and \fI.eps\fR files).
86 From these, \fBarlatex\fR outputs a single file that, when it's run
87 through \fBlatex\fR, both regenerates the ancillary files and compiles
88 the document into a \fI.dvi\fR file.
89 .PP
90 \&\fBarlatex\fR has a few advantages over other archiving programs:
91 .IP \(bu 4
92 The \fI.tex\fR files produced by \fBarlatex\fR are in a plain-text format.
93 They are therefore perfectly portable and trivial to e\-mail to
94 colleagues.
95 .IP \(bu 4
96 \&\fBarlatex\fR needs only LaTeX to run. There is no dependence on any
97 external tools.
98 .IP \(bu 4
99 There is no explicit extraction step. As the generated document is
100 run through \fBlatex\fR, it extracts the ancillary files and builds the
101 document in the same step. The user running \fBlatex\fR may not even
102 notice that additional files are being produced.
103 .PP
104 \&\fBarlatex\fR works by writing a number of \f(CW\*(C`\ebegin{filecontents*}\*(C'\fR\ ...
105 \&\f(CW\*(C`\eend{filecontents*}\*(C'\fR blocks to the output file, followed by the
106 contents of the master file. (In fact, any LaTeX comments at the
107 beginning of the master file are hoisted to the top of the generated
108 file. This enables the author to draw attention, if so desired, to
109 the fact that ancillary files will be generated.) The
110 \&\f(CW\*(C`filecontents*\*(C'\fR environment, part of standard LaTeX2e, writes its
111 contents verbatim to a specified file.
112 .SH OPTIONS
113 .IX Header "OPTIONS"
114 .IP \fB\-\-version\fR 4
115 .IX Item "--version"
116 Output the \fBarlatex\fR script's version number.
117 .IP \fB\-\-help\fR 4
118 .IX Item "--help"
119 Output brief \fBarlatex\fR usage information.
120 .IP "\fB\-\-document\fR=\fI.tex file\fR" 4
121 .IX Item "--document=.tex file"
122 Specify the master document. The output from \fBarlatex\fR is this file
123 with all of the other files named on the command line prepended to it.
124 Note that \f(CW\*(C`\-\-document\*(C'\fR is a \fImandatory\fR parameter; \fBarlatex\fR will
125 abort with an error message if \f(CW\*(C`\-\-document\*(C'\fR is not specified.
126 .IP "\fB\-\-outfile\fR=\fI.tex file\fR" 4
127 .IX Item "--outfile=.tex file"
128 Specify the output file. The output file looks just like the master
129 document, but with a number of \f(CW\*(C`filecontents*\*(C'\fR environments preceding
130 the \f(CW\*(C`\edocumentclass\*(C'\fR line. If \f(CW\*(C`\-\-outfile\*(C'\fR is not specified, output
131 will be written to the standard output device.
132 .SH EXAMPLES
133 .IX Header "EXAMPLES"
134 Suppose you have a paper called \fIpaper.tex\fR that loads a custom
135 package with \f(CW\*(C`\eusepackage{mypackage}\*(C'\fR. You want to submit the paper
136 to a conference, but you want to be absolutely certain that
137 \&\fImypackage.sty\fR doesn't get lost as your paper is shuttled from
138 person to person. Here's how \fBarlatex\fR can be of use:
139 .PP
140 .Vb 1
141 \& arlatex \-\-document=paper.tex mypackage.sty \-\-outfile=paper\-submit.tex
142 .Ve
143 .PP
144 When \fIpaper\-submit.tex\fR is processed with \fBlatex\fR, it builds just
145 like the original \fIpaper.tex\fR, except that it additionally creates a
146 \&\fImypackage.sty\fR in the current directory:
147 .PP
148 .Vb 5
149 \& This is TeX, Version 3.14159 (Web2C 7.3.1)
150 \& (paper\-submit.tex
151 \& LaTeX2e <1999/12/01> patch level 1
152 \& Babel <v3.6Z> and hyphenation patterns for american, french, german,
153 \& ngerman, italian, nohyphenation, loaded.
154 \&
155 \& LaTeX Warning: Writing file \`./mypackage.sty\*(Aq.
156 \&
157 \& (/usr/share/texmf/tex/latex/base/article.cls
158 \& Document Class: article 1999/09/10 v1.4a Standard LaTeX document class
159 \& (/usr/share/texmf/tex/latex/base/size12.clo)) (mypackage.sty)
160 \& .
161 \& .
162 \& .
163 .Ve
164 .PP
165 As another example, here's how you could bundle together all of the
166 files needed to build a large document for longevity:
167 .PP
168 .Vb 4
169 \& arlatex \-\-document=thesis.tex abstract.tex introduction.tex
170 \& background.tex approach.tex experiments.tex relatedwork.tex
171 \& conclusions.tex before.eps after.eps fast.eps slow.eps
172 \& podunkUthesis.cls \-\-outfile=thesis\-all.tex
173 .Ve
174 .PP
175 As the number of files to archive together increases it becomes more
176 cumbersome to run \fBarlatex\fR manually. Fortunately, using \fBarlatex\fR
177 with \fBbundledoc\fR is straightforward. \fBbundledoc\fR finds all of the
178 files needed to build the document, and \fBarlatex\fR combines them into
179 a single file. The following are examples of the \f(CW\*(C`bundle:\*(C'\fR line you
180 might use in a \fBbundledoc\fR configuration file:
181 .IP Unix: 1
182 .IX Item "Unix:"
183 .Vb 2
184 \& bundle: (arlatex \-\-document=$BDBASE.tex $BDINPUTS \e
185 \& \-\-outfile=$BDBASE\-all.tex)
186 .Ve
187 .IP Windows: 1
188 .IX Item "Windows:"
189 .Vb 2
190 \& bundle: arlatex \-\-document=%BDBASE%.tex %BDINPUTS% \e
191 \& \-\-outfile=%BDBASE%\-all.tex
192 .Ve
193 .PP
194 See the \fBbundledoc\fR documentation for more information.
195 .SH CAVEATS
196 .IX Header "CAVEATS"
197 \&\fBarlatex\fR makes use of LaTeX's \f(CW\*(C`filecontents*\*(C'\fR environment. It
198 passes \f(CW\*(C`filecontents*\*(C'\fR the \f(CW\*(C`overwrite\*(C'\fR option to indicate that
199 existing files with the same name should be overwritten. Be
200 forewarned that building the generated file will overwrite the files
201 used to create it.
202 .PP
203 It is best to avoid bundling binary files (e.g., included graphics)
204 with \fBarlatex\fR. These typically do not extract cleanly.
205 .SH "SEE ALSO"
206 .IX Header "SEE ALSO"
207 \&\fBbundledoc\fR\|(1), \fBlatex\fR\|(1), \fBshar\fR\|(1), \fBtar\fR\|(1), \fBzip\fR\|(1)
208 .SH AUTHOR
209 .IX Header "AUTHOR"
210 Scott Pakin, \[email protected]\fR