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