summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/scripts/bundledoc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-04-10 22:08:00 +0000
committerKarl Berry <karl@freefriends.org>2010-04-10 22:08:00 +0000
commit963b665a04c33ddcfe04234426c8bca1942589bf (patch)
tree2416c1045ecd8aaa916a512cf7a05cd4055661f9 /Master/texmf-dist/scripts/bundledoc
parent5406b8e0ea1d596600f773e766975256e4087c51 (diff)
add bundledoc 3.0 (10apr10)
git-svn-id: svn://tug.org/texlive/trunk@17794 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/scripts/bundledoc')
-rwxr-xr-xMaster/texmf-dist/scripts/bundledoc/arlatex283
-rwxr-xr-xMaster/texmf-dist/scripts/bundledoc/bundledoc806
2 files changed, 1089 insertions, 0 deletions
diff --git a/Master/texmf-dist/scripts/bundledoc/arlatex b/Master/texmf-dist/scripts/bundledoc/arlatex
new file mode 100755
index 00000000000..3b94dcaff52
--- /dev/null
+++ b/Master/texmf-dist/scripts/bundledoc/arlatex
@@ -0,0 +1,283 @@
+#! /usr/bin/env perl
+
+###################################################
+# Combine a bunch of ancillary files into a LaTeX #
+# document using the filecontents* environment. #
+# #
+# By Scott Pakin <scott+bdoc@pakin.org> #
+###################################################
+
+########################################################################
+# arlatex #
+# Copyright (C) 2010 Scott Pakin #
+# #
+# This program may be distributed and/or modified under the conditions #
+# of the LaTeX Project Public License, either version 1.3c of this #
+# license or (at your option) any later version. #
+# #
+# The latest version of this license is in: #
+# #
+# http://www.latex-project.org/lppl.txt #
+# #
+# and version 1.3c or later is part of all distributions of LaTeX #
+# version 2008/05/04 or later. #
+# #
+# This program consists of the file bundledoc and all the files listed #
+# in the Files section of the associated README file. #
+########################################################################
+
+use 5.006; # Fail gracefully if we're not using Perl v5.6.0.
+our $VERSION = "1.02"; # Specify the version of arlatex.
+use Getopt::Long;
+use Pod::Usage;
+use File::Basename;
+use File::Find;
+require File::Spec;
+use strict;
+
+my $progname = basename($0); # Name of this program
+my $latexfile; # Main LaTeX document
+my $outfile = "-"; # Output file (default is standard output)
+
+######################################################################
+
+# Include a file using the filecontents* environment.
+sub includefile ($)
+{
+ my $filename = $_[0];
+ my $basefilename = basename $filename;
+ open (SOMEFILE, "<$filename") || die "${progname}: $! ($filename)\n";
+ print OUTFILE "\\begin{filecontents*}{$basefilename}\n";
+ print OUTFILE <SOMEFILE>;
+ print OUTFILE "\\end{filecontents*}\n";
+ close SOMEFILE;
+}
+
+######################################################################
+
+# Parse the command line.
+GetOptions ('version' => sub { print "arlatex $VERSION\n"; exit -1 },
+ 'help'=> sub {pod2usage (-exitval => 0, -verbose => 1)},
+ 'document=s' => \$latexfile,
+ 'outfile=s' => \$outfile) ||
+ pod2usage (-exitval => -1, -verbose => 0);
+pod2usage (-exitval => -1, -verbose => 0) if !defined $latexfile;
+if (!-e $latexfile) {
+ my $newlatexfile = "$latexfile.tex";
+ if (!-e $newlatexfile) {
+ die "${progname}: File $latexfile does not exist\n";
+ }
+ else {
+ $latexfile = $newlatexfile;
+ }
+}
+
+# Read the entire input file.
+open (LATEXFILE, "<$latexfile") || die "${progname}: $! ($latexfile)\n";
+my @entirefile = <LATEXFILE>;
+close LATEXFILE;
+
+# Open the output file, write any initial comments, and then include
+# all of the files specified on the command line using the filecontents*
+# environment. Finally, include the rest of the input file.
+open (OUTFILE, ">$outfile") || die "${progname}: $! ($outfile)\n";
+while ($entirefile[0] =~ /^\s*(\%.*)?$/) {
+ print OUTFILE (shift @entirefile);
+}
+my @expandedARGV;
+foreach my $filename (@ARGV) {
+ if (-f $filename) {
+ push @expandedARGV, $filename;
+ }
+ else {
+ find ({wanted => sub {push @expandedARGV, File::Spec->rel2abs($_) if -f $_},
+ follow => 1},
+ $filename);
+ }
+}
+foreach my $filename (@expandedARGV) {
+ includefile ($filename);
+ print OUTFILE "\n";
+}
+print OUTFILE @entirefile;
+close OUTFILE;
+exit 0;
+
+######################################################################
+
+=head1 NAME
+
+arlatex - archive a number of ancillary LaTeX files into a master
+F<.tex> file
+
+
+=head1 SYNOPSIS
+
+arlatex
+[B<--outfile>=I<filename>F<.tex>]
+B<--document>=I<filename>F<.tex>
+I<filename>
+...
+
+arlatex
+B<--version>
+
+arlatex
+B<--help>
+
+
+=head1 DESCRIPTION
+
+B<arlatex> is an archiving program like B<shar>, B<tar>, B<zip>, etc.
+Unlike those other archivers, however, B<arlatex> is designed
+specifically for use with LaTeX. B<arlatex> takes the name of a
+master F<.tex> file and a number of ancillary files used by that
+master file (e.g., F<.tex>, F<.sty>, F<.cls>, and F<.eps> files).
+From these, B<arlatex> outputs a single file that, when it's run
+through B<latex>, both regenerates the ancillary files and compiles
+the document into a F<.dvi> file.
+
+B<arlatex> has a few advantages over other archiving programs:
+
+=over 4
+
+=item *
+
+The F<.tex> files produced by B<arlatex> are in a plain-text format.
+They are therefore perfectly portable and trivial to e-mail to
+colleagues.
+
+=item *
+
+B<arlatex> needs only LaTeX to run. There is no dependence on any
+external tools.
+
+=item *
+
+There is no explicit extraction step. As the generated document is
+run through B<latex>, it extracts the ancillary files and builds the
+document in the same step. The user running B<latex> may not even
+notice that additional files are being produced.
+
+=back
+
+B<arlatex> works by writing a number of S<C<\begin{filecontents*}> ...>
+C<\end{filecontents*}> blocks to the output file, followed by the
+contents of the master file. (In fact, any LaTeX comments at the
+beginning of the master file are hoisted to the top of the generated
+file. This enables the author to draw attention, if so desired, to
+the fact that ancillary files will be generated.) The
+C<filecontents*> environment, part of standard LaTeX2e, writes its
+contents verbatim to a specified file.
+
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<--version>
+
+Output the B<arlatex> script's version number.
+
+=item B<--help>
+
+Output brief B<arlatex> usage information.
+
+=item B<--document>=I<.tex file>
+
+Specify the master document. The output from B<arlatex> is this file
+with all of the other files named on the command line prepended to it.
+Note that C<--document> is a I<mandatory> parameter; B<arlatex> will
+abort with an error message if C<--document> is not specified.
+
+=item B<--outfile>=I<.tex file>
+
+Specify the output file. The output file looks just like the master
+document, but with a number of C<filecontents*> environments preceding
+the C<\documentclass> line. If C<--outfile> is not specified, output
+will be written to the standard output device.
+
+=back
+
+
+=head1 EXAMPLES
+
+Suppose you have a paper called F<paper.tex> that loads a custom
+package with C<\usepackage{mypackage}>. You want to submit the paper
+to a conference, but you want to be absolutely certain that
+F<mypackage.sty> doesn't get lost as your paper is shuttled from
+person to person. Here's how B<arlatex> can be of use:
+
+ arlatex --document=paper.tex mypackage.sty --outfile=paper-submit.tex
+
+When F<paper-submit.tex> is processed with B<latex>, it builds just
+like the original F<paper.tex>, except that it additionally creates a
+F<mypackage.sty> in the current directory:
+
+ This is TeX, Version 3.14159 (Web2C 7.3.1)
+ (paper-submit.tex
+ LaTeX2e <1999/12/01> patch level 1
+ Babel <v3.6Z> and hyphenation patterns for american, french, german,
+ ngerman, italian, nohyphenation, loaded.
+
+ LaTeX Warning: Writing file `./mypackage.sty'.
+
+ (/usr/share/texmf/tex/latex/base/article.cls
+ Document Class: article 1999/09/10 v1.4a Standard LaTeX document class
+ (/usr/share/texmf/tex/latex/base/size12.clo)) (mypackage.sty)
+ .
+ .
+ .
+
+As another example, here's how you could bundle together all of the
+files needed to build a large document for longevity:
+
+ arlatex --document=thesis.tex abstract.tex introduction.tex
+ background.tex approach.tex experiments.tex relatedwork.tex
+ conclusions.tex before.eps after.eps fast.eps slow.eps
+ podunkUthesis.cls --outfile=thesis-all.tex
+
+As the number of files to archive together increases it becomes more
+cumbersome to run B<arlatex> manually. Fortunately, using B<arlatex>
+with B<bundledoc> is straightforward. B<bundledoc> finds all of the
+files needed to build the document, and B<arlatex> combines them into
+a single file. The following are examples of the C<bundle:> line you
+might use in a B<bundledoc> configuration file:
+
+=over 1
+
+=item Unix:
+
+ bundle: (arlatex --document=$BDBASE.tex $BDINPUTS \
+ --outfile=$BDBASE-all.tex)
+
+=item Windows:
+
+ bundle: arlatex --document=%BDBASE%.tex %BDINPUTS% \
+ --outfile=%BDBASE%-all.tex
+
+=back
+
+See the B<bundledoc> documentation for more information.
+
+
+=head1 CAVEATS
+
+B<arlatex> makes use of LaTeX2e's C<filecontents*> environment.
+C<filecontents*> refuses to overwrite an existing file. However, it
+also refuses to create a file that exists I<anywhere> that LaTeX can
+find it. That is, if the user running B<latex> on an
+B<arlatex>-generated F<.tex> file already has a
+F</usr/share/texmf/tex/latex/whatever/whatever.sty> file then
+C<filecontents*> will refuse to create a F<whatever.sty> file, even in
+a different directory.
+
+
+=head1 SEE ALSO
+
+bundledoc(1), latex(1), shar(1), tar(1), zip(1)
+
+
+=head1 AUTHOR
+
+Scott Pakin, I<scott+bdoc@pakin.org>
diff --git a/Master/texmf-dist/scripts/bundledoc/bundledoc b/Master/texmf-dist/scripts/bundledoc/bundledoc
new file mode 100755
index 00000000000..169ca869ab3
--- /dev/null
+++ b/Master/texmf-dist/scripts/bundledoc/bundledoc
@@ -0,0 +1,806 @@
+#! /usr/bin/env perl
+
+##########################################################
+# Bundle all the files needed to build a LaTeX document. #
+# By Scott Pakin <scott+bdoc@pakin.org> #
+##########################################################
+
+########################################################################
+# bundledoc #
+# Copyright (C) 2010 Scott Pakin #
+# #
+# This program may be distributed and/or modified under the conditions #
+# of the LaTeX Project Public License, either version 1.3c of this #
+# license or (at your option) any later version. #
+# #
+# The latest version of this license is in: #
+# #
+# http://www.latex-project.org/lppl.txt #
+# #
+# and version 1.3c or later is part of all distributions of LaTeX #
+# version 2008/05/04 or later. #
+# #
+# This program consists of the file bundledoc and all the files listed #
+# in the Files section of the associated README file. #
+########################################################################
+
+use 5.006; # Fail gracefully if we're not using Perl v5.6.0.
+our $VERSION = "3.0"; # Specify the version of bundledoc.
+use File::Basename;
+use File::Copy;
+use File::Spec::Functions qw(catfile devnull rel2abs rootdir updir);
+use File::Path;
+use Getopt::Long;
+use Pod::Usage;
+use POSIX;
+use warnings;
+use strict;
+
+######################################################################
+
+# Variables the user can override with a configuration file
+# DEFAULTS: Unix + kpathsea
+my %uservariable;
+$uservariable{"bundle"} = '(tar -cvf - $BDINPUTS | compress > $BDBASE.tar.Z)';
+$uservariable{"find"} = 'kpsewhich -progname=latex $BDINPUTS';
+$uservariable{"sink"} = '> ' . devnull() . ' 2>&1';
+
+# OS path separator (Is there a better way to get this?)
+my $pathsep = catfile ("", "");
+
+# File that lists original directory names
+my $manifest = "MANIFEST";
+
+# Cleaned-up name of this Perl script
+my $progname = basename($0);
+
+# Other global variables
+my ($verbose, $keepdirs, $depfile, $localonly); # Taken from the command line
+my (@exclude_files, @include_files); # Taken from the command line
+my ($texfile, $docdirname); # Derived from $depfile
+my %subdirs; # Map from a qualified name to its subdirectory
+
+######################################################################
+
+# Find a file in the LaTeX hierarchy and fully qualify it,
+# or abort if we can't.
+sub qualifyname ($)
+{
+ my $command = $uservariable{find};
+ $command =~ s/[\$\%]BDINPUTS\%?/$_[0]/g;
+ $command =~ s/[\$\%]BDBASE\%?/$ENV{"BDBASE"}/g;
+ my $qualified = `$command` ||
+ die "${progname}: \"$uservariable{find}\" (BDINPUTS=\"$_[0]\") failed to find $_[0]\n";
+ chomp $qualified;
+ $qualified = rel2abs $qualified;
+ return $qualified;
+}
+
+# Execute a command, and return an error message if it fails.
+sub executecmd ($)
+{
+ my $command = ($verbose ? $_[0] : "$_[0] $uservariable{sink}");
+ $command =~ s/[\$\%]BDINPUTS\%?/$ENV{"BDINPUTS"}/g;
+ $command =~ s/[\$\%]BDBASE\%?/$ENV{"BDBASE"}/g;
+ my $retval;
+
+ if ($verbose) {
+ print "EXECUTING: $command\n";
+ print " (BDINPUTS = $ENV{BDINPUTS})\n";
+ }
+ if ($pathsep eq "\\") {
+ # Dirty trick to work around idiotic "\" --> "/" conversion
+ $retval = system qq("$command");
+ }
+ else {
+ $retval = system $command;
+ }
+ die "${progname}: $!. Failing command was:\n\t$command\n" if $retval;
+}
+
+# Read a configuration file, and set %uservariable accordingly.
+sub process_config_file ($)
+{
+ my $configfile = $_[0];
+ my $prevline = "";
+ open (CONFIGFILE, "<$configfile") || die "${progname}: $! ($configfile)\n";
+ while (my $oneline=<CONFIGFILE>) {
+ # Read a line and trim it.
+ chomp $oneline;
+ $oneline =~ s/^\s+//;
+ $oneline =~ s/\s+$//;
+
+ # Determine if we should process the line now, later, or never.
+ next if $oneline =~ /^\#.*$/; # Discard comments.
+ if ($oneline =~ m|^(.*)\\$|) { # Handle line continuations.
+ $prevline .= $1;
+ next;
+ }
+ $oneline = $prevline . $oneline;
+ $prevline = "";
+ next if $oneline =~ /^\s*$/; # Discard blank lines.
+
+ # Parse the line.
+ $oneline =~ /^(\w+)\s*:\s*(.*)$/;
+ $uservariable{lc($1)} = $2;
+ }
+ close CONFIGFILE;
+}
+
+# Find all dependencies listed in the input file.
+sub find_dependencies ()
+{
+ open (DEPFILE, "<$depfile") || die "${progname}: $! ($depfile)\n";
+ my $braced = "{([^\}]*)}"; # Regular expression for a braced name
+ my @dependencies; # List of fully-qualified filenames
+ @dependencies = qualifyname $texfile;
+ while (my $oneline=<DEPFILE>) {
+ # Parse an input line into its component fields.
+ next if !($oneline =~ /^\s*\*$braced\s*$braced\s*$braced\s*$/);
+ my $filetype = $1;
+ my $filename = $2;
+ my $versioninfo = $3;
+
+ # Extract the subdirectory if one exists.
+ my $subdir = dirname $filename;
+ my $qname = "";
+
+ # Determine what to do based on the file type.
+ # NOTE: The PROCESSDEP block currently ignores the following
+ # file types:
+ #
+ # * application
+ # * tfm
+ # * format
+ PROCESSDEP:
+ {
+ $filetype eq "package" && do {
+ $qname = qualifyname("$filename.sty");
+ last PROCESSDEP;
+ };
+ $filetype eq "class" && do {
+ $qname = qualifyname("$filename.cls");
+ last PROCESSDEP;
+ };
+ $filetype eq "file" && do {
+ $qname = qualifyname("$filename");
+ last PROCESSDEP;
+ };
+ }
+
+ # If the file is of one of the above types, add the qualified
+ # name to the list of dependencies. In addition, if it is in
+ # a proper subdirectory, add an entry to the subdirs hash.
+ unless ($qname eq "") {
+ push @dependencies, $qname;
+ $subdirs{$qname} = $subdir unless $subdir eq ".";
+ }
+ }
+ close DEPFILE;
+ @dependencies = sort @dependencies;
+
+ # If --localonly was specified, discard dependencies that are not
+ # in the same directory as the .tex file (or a subdirectory
+ # thereof).
+ if ($localonly) {
+ my @newdeps;
+ my $texdir = dirname qualifyname $texfile;
+ my $lentexdir = length $texdir;
+ my $numdeleted = 0;
+ foreach my $dep (@dependencies) {
+ if (substr($dep, 0, $lentexdir) ne $texdir) {
+ $numdeleted++;
+ }
+ else {
+ push @newdeps, $dep;
+ }
+ }
+ @dependencies = @newdeps;
+ print "OMITTING $numdeleted non-local file(s)\n" if $verbose;
+ }
+
+ # If --exclude was specified, discard all dependencies containing
+ # excluded text as a substring.
+ my $numexcluded = 0;
+ foreach my $excluded (@exclude_files) {
+ my @newdeps;
+ foreach my $dep (@dependencies) {
+ if ($dep =~ /\Q$excluded\E/) {
+ $numexcluded++;
+ }
+ else {
+ push @newdeps, $dep;
+ }
+ }
+ @dependencies = @newdeps;
+ }
+ print "OMITTING $numexcluded excluded file(s)\n" if $verbose && $numexcluded;
+
+ # If --include was specified, include the corresponding files.
+ my $numextras = 0;
+ foreach my $include_glob (@include_files) {
+ foreach my $include_file (glob $include_glob) {
+ push @dependencies, $include_file;
+ $numextras++;
+ }
+ }
+ print "INCLUDING $numextras additional file(s)\n" if $verbose && $numextras;
+
+ # Remove duplicates.
+ my %uniquedeps;
+ foreach my $dep (@dependencies) {
+ $uniquedeps{$dep} = 1;
+ }
+ my $numdups = @dependencies - keys %uniquedeps;
+ print "REMOVING $numdups duplicate file(s)\n" if $verbose && $numdups;
+ @dependencies = sort keys %uniquedeps;
+
+ # Return the list of dependencies.
+ return @dependencies;
+}
+
+######################################################################
+
+# Parse and process the command-line options.
+my $showhelp = "";
+$keepdirs = 0;
+$verbose = 0;
+$localonly = 0;
+GetOptions ('texfile=s' => \$texfile,
+ 'directory=s' => \$docdirname,
+ 'manifest:s' => \$manifest,
+ 'keepdirs!' => \$keepdirs,
+ 'localonly!' => \$localonly,
+ 'exclude=s' => \@exclude_files,
+ 'include=s' => \@include_files,
+ 'config=s' => sub { process_config_file($_[1]) },
+ 'verbose!' => \$verbose,
+ 'version' => sub { print "bundledoc $VERSION\n"; exit -1 },
+ 'help' => \$showhelp) || pod2usage (-exitval => -1, -verbose => 0);
+pod2usage (-exitval => 0,
+ -verbose => 1) if $showhelp && $verbose;
+pod2usage (-message => "(For more detailed help, enter \"$0 --help --verbose\".)",
+ -exitval => 0,
+ -verbose => 0) if $showhelp;
+pod2usage (-message => "${progname}: Too few arguments",
+ -exitval => -1,
+ -verbose => 0) if $#ARGV==-1;
+$depfile = shift; # Dependencies from snapshot.sty
+($texfile = $depfile) =~ s/\.[^.]*$/.tex/ if !$texfile; # Main LaTeX source file
+($docdirname = basename($depfile)) =~ s/\.[^.]*$// if !$docdirname; # Name to use for the document directory
+($ENV{"BDBASE"} = rel2abs($depfile)) =~ s/\.[^.]*$//; # May be needed by user-defined variables
+print "BDBASE = '$ENV{BDBASE}'\n" if $verbose;
+$ENV{"BDBASE"} = "\"$ENV{BDBASE}\"";
+
+# Create a bundled file.
+my @dependencies = find_dependencies();
+if ($keepdirs) {
+ # Put absolute pathnames in the tar file.
+ # QUESTIONS: Does this work with multiple drive letters in Windows?
+ # What about UNC names?
+ chdir rootdir() || die "${progname}: $! (".rootdir().")\n";
+ $ENV{"BDINPUTS"} = join (" ", map {s|^/+||; s/\"//g; "\"$_\""} @dependencies);
+ executecmd $uservariable{"bundle"};
+}
+else {
+ # Copy each of the dependencies to a temporary directory and tar it up.
+ my $tempdir = tmpnam();
+ my $tempdir2 = catfile $tempdir, $docdirname;
+ print "CREATING $tempdir\n" if $verbose;
+ mkdir ($tempdir, 0777) || die "${progname}: $! ($tempdir)\n";
+ print "CREATING $tempdir2\n" if $verbose;
+ mkdir ($tempdir2, 0777) || die "${progname}: $! ($tempdir2)\n";
+ foreach my $dep (@dependencies) {
+ # If the current dependency is in a subdirectory of the
+ # original location, create the same subdirectory in the
+ # temporary directory and copy the file there. Otherwise just
+ # copy it to the root of the temporary directory.
+ my $targetdir = $tempdir2;
+ if (my $sd = $subdirs{$dep}) {
+ $targetdir = catfile($targetdir, $sd);
+ unless (-d $targetdir) {
+ print "CREATING $targetdir\n" if $verbose;
+ mkpath($targetdir, 0, 0777) || die "${progname}: $! ($targetdir)\n";
+ }
+ }
+ copy ($dep, $targetdir) || die "${progname}: $! ($targetdir)\n";
+ }
+ if ($manifest ne "") {
+ my $manifest = catfile $tempdir2, $manifest;
+ my $manifestdir = dirname $manifest;
+ unless (-d $manifestdir) {
+ print "CREATING $manifestdir\n" if $verbose;
+ mkpath($manifestdir, 0, 0777) || die "${progname}: $! ($manifestdir)\n";
+ }
+ print "WRITING $manifest\n" if $verbose;
+ open (MANIFEST, ">$manifest") || die "${progname}: $! ($manifest)\n";
+ print MANIFEST join ("\n", @dependencies), "\n";
+ close MANIFEST;
+ }
+ chdir $tempdir || die "${progname}: $! ($tempdir)\n";
+ $ENV{"BDINPUTS"} = "\"$docdirname\"";
+ executecmd $uservariable{"bundle"};
+
+ # Clean up our mess.
+ # NOTE: We rmtree $tempdir2 and rmdir $tempdir because rmtree
+ # complained on WinNT when trying to remove a top-level
+ # directory (e.g., "\s4r.").
+ print "REMOVING $tempdir2\n" if $verbose;
+ rmtree $tempdir2, 0, 1;
+ chdir (updir());
+ print "REMOVING $tempdir\n" if $verbose;
+ rmdir $tempdir || die "${progname}: $! ($tempdir)\n";
+}
+print "FINISHED.\n" if $verbose;
+exit 0;
+
+__END__
+
+######################################################################
+
+=head1 NAME
+
+bundledoc - bundle all the files needed by a LaTeX document
+
+
+=head1 SYNOPSIS
+
+bundledoc
+[B<--version>]
+[B<--help>]
+[B<-->[B<no>]B<verbose>]
+[B<--texfile>=I<file>]
+[B<--directory>=I<directory>]
+[B<-->[B<no>]B<localonly>]
+[B<--exclude>=I<string>]
+[B<--include>=I<filespec>]
+[B<--manifest>=I<file>]
+[B<-->[B<no>]B<keepdirs>]
+[B<--config>=I<file>]
+I<.dep file>
+
+
+=head1 DESCRIPTION
+
+B<bundledoc> is a post-processor for the B<snapshot> package that
+bundles together all the classes, packages, and files needed to build
+a given LaTeX document. It reads the F<.dep> file that B<snapshot>
+produces, finds each of the files mentioned therein, and packages them
+into a single archive file (e.g., a F<.tar.gz> file), suitable for
+moving across systems, transmitting to a colleague, etc.
+
+As the simplest example possible, consider a LaTeX file called, say,
+F<hello.tex>:
+
+ \RequirePackage{snapshot} % Needed by bundledoc
+ \documentclass[11pt]{article}
+
+ \begin{document}
+ Hello, world!
+ \end{document}
+
+The C<\RequirePackage{snapshot}> causes a F<hello.dep> file to be produced.
+When B<bundledoc> is then given C<hello.dep> as an argument, it locates the
+dependent files -- F<snapshot.sty>, F<article.cls>, and F<size11.clo> --
+and bundles them into a single archive file, along with F<hello.tex> and a
+F<MANIFEST> file (described in L<"OPTIONS">, below).
+
+
+=head1 OPTIONS
+
+In the following descriptions, I<somefile> refers to the name of your
+main LaTeX document (no extension).
+
+B<bundledoc> requires the name of the dependency file produced by
+B<snapshot> (normally I<somefile>F<.dep>). The following options may
+also be given:
+
+=over 4
+
+=item B<--version>
+
+Output the B<bundledoc> script's version number. This overrides all the
+remaining options.
+
+=item B<--help>
+
+Give a brief usage message. This overrides all of the remaining options.
+
+=item B<-->[B<no>]B<verbose> (default: C<noverbose>)
+
+B<bundledoc> normally does not output anything except error messages.
+With C<--verbose>, it outputs copious status messages.
+
+
+=item B<--texfile>=I<main .tex file> (default: I<somefile>F<.tex>)
+
+B<snapshot>'s dependency file does not list the main LaTeX file (the
+one that gets passed to B<latex>). In order for B<bundledoc> to find
+and bundle that file, B<bundledoc> assumes it has the same name as the
+B<snapshot> dependency file but with a F<.tex> extension. If this is
+not the case, then use C<--texfile> to specify the correct filename.
+
+=item B<--directory>=I<archive directory> (default: I<somefile>)
+
+When B<bundledoc> creates an archive (e.g., a F<.tar> or F<.zip> file)
+containing the document's files, it puts all of them in a directory to
+avoid cluttering the current directory with files. If the given
+dependency file is called I<somefile>F<.dep> then the resulting
+archive will, by default, store all the dependent files in a
+I<somefile> directory. To change the directory name use the
+C<--directory> option.
+
+=item B<-->[B<no>]B<localonly> (default: C<nolocalonly>)
+
+Although B<bundledoc> normally archives all of the files named in the
+F<.dep> file, the C<--localonly> option tells B<bundledoc> to exclude
+all files located in a directory other than the F<.tex> file's
+directory or one of its subdirectories.
+
+=item B<--exclude>=I<string> (default: I<none>)
+
+While C<--localonly> causes files outside of the F<.tex> file's
+directory tree to be omitted from the archive, C<--exclude> provides
+finer-grained control over files to omit from the archive. The
+C<--exclude> option, which can be specified repeatedly on the command
+line, causes all files whose name contains I<string> to be omitted
+from the archive.
+
+=item B<--include>=I<filespec> (default: I<none>)
+
+The C<--include> option, which can be specified repeatedly on the
+command line, instructs B<bundledoc> to include in the archive all of
+the files matching I<filespec>, even if they're not referenced in the
+F<.dep> file.
+
+=item B<--manifest>=I<manifest file> (default: F<MANIFEST>)
+
+In addition to the dependent files, B<bundledoc> includes in the
+archive file one extra file called, by default, ``F<MANIFEST>''.
+F<MANIFEST> is a text file that lists the original filenames of all
+the dependencies. To change the filename from ``F<MANIFEST>'' to
+something else, use the C<--manifest> option. As a special case,
+C<--manifest=""> tells B<bundledoc> not to include a manifest file at
+all.
+
+=item B<-->[B<no>]B<keepdirs> (default: C<nokeepdirs>)
+
+Normally, the archive file that B<bundledoc> produces contains a
+single directory -- and subdirectories, if the document refers
+explicitly to them -- in which all the dependent files lie. If
+C<--keepdirs> is specified, all the dependent files are stored with
+their original pathnames. For example, if F<somefile.tex> depends on
+F<figures/somefigure.eps>, F<article.cls>, and F<snapshot.sty>, then
+the I<somefile> archive will normally contain the following files:
+
+=over 4
+
+=item *
+
+F<somefile/somefile.tex>
+
+=item *
+
+F<somefile/figures/somefigure.eps>
+
+=item *
+
+F<somefile/article.cls>
+
+=item *
+
+F<somefile/snapshot.sty>
+
+=item *
+
+F<somefile/MANIFEST>
+
+=back
+
+However, C<--keepdirs> will cause the I<somefile> archive to contain
+the following sorts of filenames instead:
+
+=over 4
+
+=item *
+
+F<home/me/mydocs/somefile.tex>
+
+=item *
+
+F<home/me/mydocs/figures/somefigure.eps>
+
+=item *
+
+F<usr/share/texmf/tex/latex/base/article.cls>
+
+=item *
+
+F<usr/share/texmf/tex/latex/snapshot/snapshot.sty>
+
+=back
+
+C<--directory> is not used when C<--keepdirs> is in effect. In
+addition, no manifest file is written to the archive file as it
+contains redundant information.
+
+=item B<--config>=I<configuration file> (default: E<lt>noneE<gt>)
+
+The C<--config> option is used to point B<bundledoc> to the
+appropriate configuration (F<.cfg>) file for your TeX distribution and
+operating system. B<bundledoc> comes with a few configuration files
+and it's easy to write more. See L<"CONFIGURATION FILES"> (below) for
+a description of the configuration file format.
+
+=back
+
+
+=head1 CONFIGURATION FILES
+
+=head2 Format
+
+Configuration files follow a fairly simple format. Lines beginning with
+C<#> are comments. Blank lines are ignored. All other lines are of the
+form:
+
+ variable: value
+
+The current version of B<bundledoc> recognizes the following variables:
+
+=over 4
+
+=item B<bundle>
+
+The command to use to bundle a set of files into a single archive file
+
+=item B<sink>
+
+The affix to a command to discard its output
+
+=item B<find>
+
+The command to find a file within the TeX tree(s).
+
+=back
+
+Values that are too long for one line can be split across multiple lines
+by using C<\> as the line-continuation symbol.
+
+There are two environment variables that B<bundledoc> makes available
+for use by configuration-file commands: C<BDBASE>, which is set to
+I<somefile> (as in L<"OPTIONS">), and C<BDINPUTS>, which is set to a
+space-separated list of files that a command is to operate upon. That
+is, when the command associated with C<bundle> is running, C<BDINPUTS>
+contains the list of all the files that are to be archived. In
+contrast, when the command associated with C<find> is running,
+C<BDINPUTS> contains the name of the file to search for.
+
+=head2 Examples
+
+The following configuration file parallels B<bundledoc>'s default
+values of the various configuration-file variables, which represents a
+kpathsea-based TeX distribution running on a generic Unix system,
+which doesn't necessarily have any of the GNU tools, such as B<gzip>
+or GNU B<tar>:
+
+ # "Default" configuration file
+ # By Scott Pakin <scott+bdoc@pakin.org>
+
+ bundle: (tar -cvf - $BDINPUTS | compress > $BDBASE.tar.Z)
+ sink: > /dev/null 2>&1
+ find: kpsewhich -progname=latex $BDINPUTS
+
+The parentheses in the C<bundle:> line tell the Unix shell to run the
+command in a subshell. This is to make the C<sink:> affix work
+properly (i.e., so there aren't two C<E<gt>>'s in the same command).
+
+Notice how the commands treat C<BDBASE> and C<BDINPUTS> like any other
+environment variables in a Unix shell, using C<$> to take their value.
+Other operating systems use different conventions for referring to
+environment variables. For instance, a configuration file for a
+Windows-based TeX distribution would use C<%BDBASE%> and C<%BDINPUTS%>
+instead.
+
+The value for C<sink:> is specific to an operating system. The value
+for C<find:> is specific to a TeX distribution. C<bundle:> is where
+the most opportunity for customization lies. You can use C<bundle:>
+to specify your favorite archive format. For example, you can produce
+a shar file on Unix with something like:
+
+ bundle: (shar --archive-name="$BDBASE" $BDINPUTS > $BDBASE.sh)
+
+or a CAB file on Microsoft Windows with something like:
+
+ bundle: cabarc -r -p N %BDBASE%.cab %BDINPUTS%
+
+
+=head1 EXAMPLES
+
+Assume that F<myfile.dep> was produced from F<myfile.tex> by following
+the instructions in L<the Description section|/"DESCRIPTION">. The
+following command produces a F<.zip> file with the MikTeX TeX
+distribution running on Microsoft Windows:
+
+ bundledoc --config=miktex.cfg myfile.dep
+
+(In practice, it's probably necessary to specify to C<--config> the
+complete path to B<bundledoc>'s F<miktex.cfg> configuration file.)
+
+The following builds a F<.tar.gz> archive with the TeX Live
+distribution running on a Unix-like operating system. B<bundledoc>
+will produce verbose output describing its operations. All files not
+in the same directory tree as F<myfile.tex> and all files containing
+".fd" or ".sty" in their names are omitted. However, all F<.bib>
+files in the current directory will be included in the archive even
+though none of them are referenced by F<myfile.dep>. Finally, no
+F<MANIFEST> file will be produced.
+
+ bundledoc --config=texlive-unix.cfg --verbose --localonly \
+ --exclude=.fd --exclude=.cfg --include="*.bib" --manifest="" \
+ myfile.dep
+
+
+=head1 FILES
+
+The user must have previously installed F<snapshot.sty> and used it to
+produce a dependency file for his document. Besides that, the set of
+external files needed by B<bundledoc> is system-specific and depends on the
+configuration file used. (See L<"CONFIGURATION FILES">, above.)
+
+B<bundledoc> currently comes with two configuration files:
+
+=over 4
+
+=item F<texlive-unix.cfg>
+
+Configuration file for TeX Live installations on Unix or Linux. TeX
+Live is a kpathsea-based TeX distribution that runs on various flavors
+of Unix and Microsoft Windows. F<texlive-unix.cfg> assumes you have
+B<gzip> and uses it to produce a F<.tar.gz> archive file. The
+configuration file has B<bundledoc> use B<kpsewhich> to find LaTeX
+files.
+
+=item F<miktex.cfg>
+
+Configuration file for MikTeX installations. MikTeX is a popular TeX
+distribution for Microsoft Windows. F<miktex.cfg> assumes you have
+B<zip> and uses it to produce a F<.zip> archive file. The
+configuration file has B<bundledoc> use the rather nonstandard
+B<initexmf> to find LaTeX files.
+
+=back
+
+
+=head1 NOTES
+
+=head2 Including and excluding files
+
+The C<--localonly>, C<--exclude>, and C<--include> options provide
+control over the archive's contents. C<--exclude> and C<--include>
+can be specified repeatedly on the command line. The order in which
+these options are specified is immaterial; B<bundledoc> processes file
+inclusions and exclusions in the following order:
+
+=over 4
+
+=item 1.
+
+All files referenced by the F<.dep> file are added to the list of
+files to archive.
+
+=item 2.
+
+If C<--localonly> is specified, all files not found in the F<.tex>
+file's directory are removed from the list.
+
+=item 3.
+
+For each C<--exclude> string specified, all files containing that
+string are removed from the list.
+
+=item 4.
+
+For each C<--include> file specification, the set of files designated
+by its expansion are added to the list.
+
+=back
+
+
+=head2 Issues When Running Under Microsoft Windows
+
+First, because B<bundledoc> is a Perl script, you should do one of the
+following to run it under Windows:
+
+=over 4
+
+=item *
+
+C<perl bundledoc>
+
+=item *
+
+Rename F<bundledoc> to F<bundledoc.pl> and run C<bundledoc.pl>. (This
+is assuming you have a file association set up for F<.pl>.)
+
+=item *
+
+Run the B<pl2bat> script (if you have it) to convert F<bundledoc> to
+F<bundledoc.bat>, then run C<bundledoc>.
+
+=back
+
+Second, Windows uses a multi-rooted filesystem (i.e., multiple drive
+letters). I wouldn't be surprised if bad things were to happen if the
+files to be bundled are scattered across drives. In addition, Windows
+supports ``UNC'' filenames, which have no drive letter at all, just a
+machine and share name. UNC filenames are also untested waters for
+B<bundledoc>. Be careful!
+
+
+=head2 Testing Status
+
+I have tested B<bundledoc> only with Perl v5.6.0 and later and only on
+the following platforms:
+
+=over 4
+
+=item *
+
+Linux + TeX Live
+
+=item *
+
+Linux + teTeX
+
+=item *
+
+Windows NT + MiKTeX
+
+=item *
+
+Solaris + ??? (something kpathsea-based)
+
+=back
+
+It is my hope that B<bundledoc> works on many more platforms than
+those. I tried to make the program itself fairly independent of the
+operating system; only the configuration files should have to change
+to run B<bundledoc> on a different system.
+
+=head2 Future Work
+
+I'd like B<bundledoc> to work on as wide a variety of TeX
+distributions as possible. If your platform is significantly
+different from the ones listed in L<"Testing Status"> (e.g., if you're
+running MacOS) and you need to create a substantially different
+configuration file from F<texlive-unix.cfg> and F<miktex.cfg>, please
+send it to me at the address listed in L<"AUTHOR"> so I can include it
+in a future version of B<bundledoc>. (I make no promises, though).
+
+Once B<bundledoc> works on all the major operating systems and TeX
+distributions it would be really convenient if I could get
+B<bundledoc> to detect the platform it's running on and automatically
+select an appropriate configuration file.
+
+Finally, it would be handy for B<bundledoc> to include fonts in the
+archive file. At a minimum, it should include F<.tfm> files, but it
+would be even better if it included F<.mf>, F<.pfb>, F<.ttf>, and
+other common font formats, as well.
+
+=head2 Acknowledgments
+
+Thanks to Fabien Vignes-Tourneret for suggesting what became the
+C<--localonly> option and for a discussion that led to the
+C<--exclude> and C<--include> options; and to Marius Kleiner for
+updating B<bundledoc> to properly handle document subdirectories.
+
+
+=head1 SEE ALSO
+
+gzip(1), kpsewhich(1), latex(1), perl(1), zip(1), the B<snapshot>
+documentation
+
+
+=head1 AUTHOR
+
+Scott Pakin, I<scott+bdoc@pakin.org>