1BUNDLEDOC(1) User Commands BUNDLEDOC(1)
2
6 bundledoc - bundle all the files needed by a LaTeX document
7
9 bundledoc [--version] [--help] [--[no]verbose] [--texfile=file.tex]
10 [--directory=directory] [--[no]localonly] [--exclude=string]
11 [--include=filespec] [--manifest=file]
12 [--listdeps=[yes|no|only|rel]...] [--[no]keepdirs] [--config=file.cfg]
13 file.dep
14
16 bundledoc is a post-processor for the snapshot package that bundles
17 together all the classes, packages, and files needed to build a given
18 LaTeX document. It reads the .dep file that snapshot produces, finds
19 each of the files mentioned therein, and packages them into a single
20 archive file (e.g., a .tar.gz file), suitable for moving across
21 systems, transmitting to a colleague, etc.
22 As the simplest example possible, consider a LaTeX file called, say,
24 hello.tex:
25 \RequirePackage{snapshot} % Needed by bundledoc
27 \documentclass[11pt]{article}
28 \begin{document}
30 Hello, world!
31 \end{document}
32 The "\RequirePackage{snapshot}" causes a hello.dep file to be produced.
34 When bundledoc is then given "hello.dep" as an argument, it locates the
35 dependent files -- snapshot.sty, article.cls, and size11.clo -- and
36 bundles them into a single archive file, along with hello.tex and a
37 MANIFEST file (described in "OPTIONS", below).
38
40 In the following descriptions, somefile refers to the name of your main
41 LaTeX document (no extension).
42 bundledoc requires the name of the dependency file produced by
44 snapshot, normally somefile.dep). (For convenience, the file can be
45 specified without its .dep extension.) The following options may also
46 be given:
47 --version
49 Output the bundledoc script's version number. This overrides all
50 of the remaining options.
51 --help
53 Give a brief usage message. This overrides all of the remaining
54 options.
55 --[no]verbose (default: "noverbose")
57 bundledoc normally does not output anything except error messages.
58 With "--verbose", it outputs copious status messages.
59 --texfile=main .tex file (default: somefile.tex)
61 snapshot's dependency file does not list the main LaTeX file (the
62 one that gets passed to latex). In order for bundledoc to find and
63 bundle that file, bundledoc assumes it has the same name as the
64 snapshot dependency file but with a .tex extension. If this is not
65 the case, then use "--texfile" to specify the correct filename.
66 --directory=archive directory (default: somefile)
68 When bundledoc creates an archive (e.g., a .tar or .zip file)
69 containing the document's files, it puts all of them in a directory
70 to avoid cluttering the current directory with files. If the given
71 dependency file is called somefile.dep then the resulting archive
72 will, by default, store all the dependent files in a somefile
73 directory. To change the directory name use the "--directory"
74 option.
75 --[no]localonly (default: "nolocalonly")
77 Although bundledoc normally archives all of the files named in the
78 .dep file, the "--localonly" option tells bundledoc to exclude all
79 files located in a directory other than the .tex file's directory
80 or one of its subdirectories.
81 --exclude=string (default: none)
83 While "--localonly" causes files outside of the .tex file's
84 directory tree to be omitted from the archive, "--exclude" provides
85 finer-grained control over files to omit from the archive. The
86 "--exclude" option, which can be specified repeatedly on the
87 command line, causes all files whose name contains string to be
88 omitted from the archive.
89 --include=filespec (default: none)
91 The "--include" option, which can be specified repeatedly on the
92 command line, instructs bundledoc to include in the archive all of
93 the files matching filespec, even if they're not referenced in the
94 .dep file.
95 --manifest=manifest file (default: MANIFEST)
97 In addition to the dependent files, bundledoc includes in the
98 archive file one extra file called, by default, ``MANIFEST''.
99 MANIFEST is a text file that lists the original filenames of all
100 the dependencies. To change the filename from ``MANIFEST'' to
101 something else, use the "--manifest" option. As a special case,
102 "--manifest=""" tells bundledoc not to include a manifest file at
103 all.
104 --listdeps=[yes|no|only|rel]...] (default: "no")
106 "--listdeps" accepts one or more of "yes", "no", "only", or "rel"
107 as a comma-separated list. As long as "no" does not appear in this
108 list, bundledoc outputs all of the main LaTeX file's dependencies.
109 If the list contains "rel", then bundledoc outputs the list of
110 dependencies with relative pathnames. If the list contains "only",
111 then bundledoc exits after displaying the list, without producing
112 an archive.
113 --[no]keepdirs (default: "nokeepdirs")
115 Normally, the archive file that bundledoc produces contains a
116 single directory -- and subdirectories, if the document refers
117 explicitly to them -- in which all the dependent files lie. If
118 "--keepdirs" is specified, all the dependent files are stored with
119 their original pathnames. For example, if somefile.tex depends on
120 figures/somefigure.eps, article.cls, and snapshot.sty, then the
121 somefile archive will normally contain the following files:
122 · somefile/somefile.tex
124 · somefile/figures/somefigure.eps
126 · somefile/article.cls
128 · somefile/snapshot.sty
130 · somefile/MANIFEST
132 However, "--keepdirs" will cause the somefile archive to contain
134 the following sorts of filenames instead:
135 · home/me/mydocs/somefile.tex
137 · home/me/mydocs/figures/somefigure.eps
139 · usr/share/texmf/tex/latex/base/article.cls
141 · usr/share/texmf/tex/latex/snapshot/snapshot.sty
143 "--directory" is not used when "--keepdirs" is in effect. In
145 addition, no manifest file is written to the archive file as it
146 contains redundant information.
147 --config=configuration file (default: <none>)
149 The "--config" option is used to point bundledoc to the appropriate
150 configuration (.cfg) file for your TeX distribution and operating
151 system. bundledoc comes with a few configuration files and it's
152 easy to write more. See "CONFIGURATION FILES" (below) for a
153 description of the configuration file format. For convenience, the
154 file can be specified without its .cfg extension.
155
157 Format
158 Configuration files follow a fairly simple format. Lines beginning
159 with "#" are comments. Blank lines are ignored. All other lines are
160 of the form:
161 variable: value
163 The current version of bundledoc recognizes the following variables:
165 bundle
167 The command to use to bundle a set of files into a single archive
168 file
169 sink
171 The affix to a command to discard its output
172 find
174 The command to find a file within the TeX tree(s).
175 Values that are too long for one line can be split across multiple
177 lines by using "\" as the line-continuation symbol.
178 There are two environment variables that bundledoc makes available for
180 use by configuration-file commands: "BDBASE", which is set to somefile
181 (as in "OPTIONS"), and "BDINPUTS", which is set to a space-separated
182 list of files that a command is to operate upon. That is, when the
183 command associated with "bundle" is running, "BDINPUTS" contains the
184 list of all the files that are to be archived. In contrast, when the
185 command associated with "find" is running, "BDINPUTS" contains the name
186 of the file to search for.
187 Examples
189 The following configuration file parallels bundledoc's default values
190 of the various configuration-file variables, which represents a
191 kpathsea-based TeX distribution running on a generic Unix system, which
192 doesn't necessarily have any of the GNU tools, such as gzip or GNU tar:
193 # "Default" configuration file
195 # By Scott Pakin <scott+bdoc@pakin.org>
196 bundle: (tar -cvf - $BDINPUTS | compress > $BDBASE.tar.Z)
198 sink: > /dev/null 2>&1
199 find: kpsewhich -progname=latex $BDINPUTS
200 The parentheses in the "bundle:" line tell the Unix shell to run the
202 command in a subshell. This is to make the "sink:" affix work properly
203 (i.e., so there aren't two ">"'s in the same command).
204 Notice how the commands treat "BDBASE" and "BDINPUTS" like any other
206 environment variables in a Unix shell, using "$" to take their value.
207 Other operating systems use different conventions for referring to
208 environment variables. For instance, a configuration file for a
209 Windows-based TeX distribution would use "%BDBASE%" and "%BDINPUTS%"
210 instead.
211 The value for "sink:" is specific to an operating system. The value
213 for "find:" is specific to a TeX distribution. "bundle:" is where the
214 most opportunity for customization lies. You can use "bundle:" to
215 specify your favorite archive format. For example, you can produce a
216 shar file on Unix with something like:
217 bundle: (shar --archive-name="$BDBASE" $BDINPUTS > $BDBASE.sh)
219 or a CAB file on Microsoft Windows with something like:
221 bundle: cabarc -r -p N %BDBASE%.cab %BDINPUTS%
223
225 Assume that myfile.dep was produced from myfile.tex by following the
226 instructions in the Description section. The following command
227 produces a .zip file with the MikTeX TeX distribution running on
228 Microsoft Windows:
229 bundledoc --config=miktex.cfg myfile.dep
231 This can be abbreviated to
233 bundledoc --config=miktex myfile
235 The following builds a .tar.gz archive with the TeX Live distribution
237 running on a Unix-like operating system. bundledoc will produce
238 verbose output describing its operations. All files not in the same
239 directory tree as myfile.tex and all files containing ".fd" or ".sty"
240 in their names are omitted. However, all .bib files in the current
241 directory will be included in the archive even though none of them are
242 referenced by myfile.dep. Finally, no MANIFEST file will be produced.
243 bundledoc --config=texlive-unix.cfg --verbose --localonly \
245 --exclude=.fd --exclude=.cfg --include="*.bib" --manifest="" \
246 myfile.dep
247
249 The user must have previously installed snapshot.sty and used it to
250 produce a dependency file for his document. Besides that, the set of
251 external files needed by bundledoc is system-specific and depends on
252 the configuration file used. (See "CONFIGURATION FILES", above.)
253 bundledoc currently comes with two configuration files:
255 texlive-unix.cfg
257 Configuration file for TeX Live installations on Unix or Linux.
258 TeX Live is a kpathsea-based TeX distribution that runs on various
259 flavors of Unix and Microsoft Windows. texlive-unix.cfg assumes
260 you have gzip and uses it to produce a .tar.gz archive file. The
261 configuration file has bundledoc use kpsewhich to find LaTeX files.
262 miktex.cfg
264 Configuration file for MikTeX installations. MikTeX is a popular
265 TeX distribution for Microsoft Windows. miktex.cfg assumes you
266 have zip and uses it to produce a .zip archive file. The
267 configuration file now has bundledoc use kpsewhich to find LaTeX
268 files; older version of MikTeX required the rather nonstandard
269 initexmf for this purpose.
270 texlive-unix-arlatex.cfg
272 This is a variant of texlive-unix.cfg that uses arlatex instead of
273 gzip to archive files. arlatex is a script included in the
274 bundledoc distribution that generates a self-extracting .tex file
275 based on LaTeX's "filecontents" environment.
276
278 Including and excluding files
279 The "--localonly", "--exclude", and "--include" options provide control
280 over the archive's contents. "--exclude" and "--include" can be
281 specified repeatedly on the command line. The order in which these
282 options are specified is immaterial; bundledoc processes file
283 inclusions and exclusions in the following order:
284 1. All files referenced by the .dep file are added to the list of
286 files to archive.
287 2. If "--localonly" is specified, all files not found in the .tex
289 file's directory are removed from the list.
290 3. For each "--exclude" string specified, all files containing that
292 string are removed from the list.
293 4. For each "--include" file specification, the set of files
295 designated by its expansion are added to the list.
296 Issues When Running Under Microsoft Windows
298 First, because bundledoc is a Perl script, you should do one of the
299 following to run it under Windows:
300 · "perl bundledoc"
302 · Rename bundledoc to bundledoc.pl and run "bundledoc.pl". (This is
304 assuming you have a file association set up for .pl.)
305 · Run the pl2bat script (if you have it) to convert bundledoc to
307 bundledoc.bat, then run "bundledoc".
308 Second, Windows uses a multi-rooted filesystem (i.e., multiple drive
310 letters). I wouldn't be surprised if bad things were to happen if the
311 files to be bundled are scattered across drives. In addition, Windows
312 supports ``UNC'' filenames, which have no drive letter at all, just a
313 machine and share name. UNC filenames are also untested waters for
314 bundledoc. Be careful!
315 Testing Status
317 I have tested bundledoc only with Perl v5.6.0 and later and only on the
318 following platforms:
319 · Linux + TeX Live
321 · Linux + teTeX
323 · Windows NT + MiKTeX
325 · Solaris + ??? (something kpathsea-based)
327 It is my hope that bundledoc works on many more platforms than those.
329 I tried to make the program itself fairly independent of the operating
330 system; only the configuration files should have to change to run
331 bundledoc on a different system.
332 Future Work
334 I'd like bundledoc to work on as wide a variety of TeX distributions as
335 possible. If your platform is significantly different from the ones
336 listed in "Testing Status" (e.g., if you're running OS X) and you need
337 to create a substantially different configuration file from
338 texlive-unix.cfg and miktex.cfg, please send it to me at the address
339 listed in "AUTHOR" so I can include it in a future version of
340 bundledoc. (I make no promises, though).
341 Once bundledoc works on all the major operating systems and TeX
343 distributions it would be really convenient if I could get bundledoc to
344 detect the platform it's running on and automatically select an
345 appropriate configuration file.
346 Finally, it would be handy for bundledoc to include fonts in the
348 archive file. At a minimum, it should include .tfm files, but it would
349 be even better if it included .mf, .pfb, .ttf, and other common font
350 formats, as well.
351 Acknowledgments
353 Thanks to Fabien Vignes-Tourneret for suggesting what became the
354 "--localonly" option and for a discussion that led to the "--exclude"
355 and "--include" options; to Marius Kleiner for updating bundledoc to
356 properly handle document subdirectories; and to Frank Mittelbach for
357 suggesting using Kpathsea to help find .cfg files and to automatically
358 append .cfg and .dep extensions if necessary.
359
361 arlatex(1), gzip(1), kpsewhich(1), latex(1), perl(1), zip(1), the
362 snapshot documentation
363
365 Scott Pakin, scott+bdoc@pakin.org
366v3.4 2019-09-08 BUNDLEDOC(1)