diff options
Diffstat (limited to 'Master')
43 files changed, 2046 insertions, 16 deletions
diff --git a/Master/bin/alpha-linux/arlatex b/Master/bin/alpha-linux/arlatex new file mode 120000 index 00000000000..16f679d6d26 --- /dev/null +++ b/Master/bin/alpha-linux/arlatex @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/arlatex
\ No newline at end of file diff --git a/Master/bin/alpha-linux/bundledoc b/Master/bin/alpha-linux/bundledoc new file mode 120000 index 00000000000..f7ea6372b95 --- /dev/null +++ b/Master/bin/alpha-linux/bundledoc @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/bundledoc
\ No newline at end of file diff --git a/Master/bin/amd64-freebsd/arlatex b/Master/bin/amd64-freebsd/arlatex new file mode 120000 index 00000000000..16f679d6d26 --- /dev/null +++ b/Master/bin/amd64-freebsd/arlatex @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/arlatex
\ No newline at end of file diff --git a/Master/bin/amd64-freebsd/bundledoc b/Master/bin/amd64-freebsd/bundledoc new file mode 120000 index 00000000000..f7ea6372b95 --- /dev/null +++ b/Master/bin/amd64-freebsd/bundledoc @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/bundledoc
\ No newline at end of file diff --git a/Master/bin/i386-cygwin/arlatex b/Master/bin/i386-cygwin/arlatex new file mode 120000 index 00000000000..16f679d6d26 --- /dev/null +++ b/Master/bin/i386-cygwin/arlatex @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/arlatex
\ No newline at end of file diff --git a/Master/bin/i386-cygwin/bundledoc b/Master/bin/i386-cygwin/bundledoc new file mode 120000 index 00000000000..f7ea6372b95 --- /dev/null +++ b/Master/bin/i386-cygwin/bundledoc @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/bundledoc
\ No newline at end of file diff --git a/Master/bin/i386-freebsd/arlatex b/Master/bin/i386-freebsd/arlatex new file mode 120000 index 00000000000..16f679d6d26 --- /dev/null +++ b/Master/bin/i386-freebsd/arlatex @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/arlatex
\ No newline at end of file diff --git a/Master/bin/i386-freebsd/bundledoc b/Master/bin/i386-freebsd/bundledoc new file mode 120000 index 00000000000..f7ea6372b95 --- /dev/null +++ b/Master/bin/i386-freebsd/bundledoc @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/bundledoc
\ No newline at end of file diff --git a/Master/bin/i386-kfreebsd/arlatex b/Master/bin/i386-kfreebsd/arlatex new file mode 120000 index 00000000000..16f679d6d26 --- /dev/null +++ b/Master/bin/i386-kfreebsd/arlatex @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/arlatex
\ No newline at end of file diff --git a/Master/bin/i386-kfreebsd/bundledoc b/Master/bin/i386-kfreebsd/bundledoc new file mode 120000 index 00000000000..f7ea6372b95 --- /dev/null +++ b/Master/bin/i386-kfreebsd/bundledoc @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/bundledoc
\ No newline at end of file diff --git a/Master/bin/i386-linux/arlatex b/Master/bin/i386-linux/arlatex new file mode 120000 index 00000000000..16f679d6d26 --- /dev/null +++ b/Master/bin/i386-linux/arlatex @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/arlatex
\ No newline at end of file diff --git a/Master/bin/i386-linux/bundledoc b/Master/bin/i386-linux/bundledoc new file mode 120000 index 00000000000..f7ea6372b95 --- /dev/null +++ b/Master/bin/i386-linux/bundledoc @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/bundledoc
\ No newline at end of file diff --git a/Master/bin/i386-netbsd/arlatex b/Master/bin/i386-netbsd/arlatex new file mode 120000 index 00000000000..16f679d6d26 --- /dev/null +++ b/Master/bin/i386-netbsd/arlatex @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/arlatex
\ No newline at end of file diff --git a/Master/bin/i386-netbsd/bundledoc b/Master/bin/i386-netbsd/bundledoc new file mode 120000 index 00000000000..f7ea6372b95 --- /dev/null +++ b/Master/bin/i386-netbsd/bundledoc @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/bundledoc
\ No newline at end of file diff --git a/Master/bin/i386-solaris/arlatex b/Master/bin/i386-solaris/arlatex new file mode 120000 index 00000000000..16f679d6d26 --- /dev/null +++ b/Master/bin/i386-solaris/arlatex @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/arlatex
\ No newline at end of file diff --git a/Master/bin/i386-solaris/bundledoc b/Master/bin/i386-solaris/bundledoc new file mode 120000 index 00000000000..f7ea6372b95 --- /dev/null +++ b/Master/bin/i386-solaris/bundledoc @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/bundledoc
\ No newline at end of file diff --git a/Master/bin/mips-irix/arlatex b/Master/bin/mips-irix/arlatex new file mode 120000 index 00000000000..16f679d6d26 --- /dev/null +++ b/Master/bin/mips-irix/arlatex @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/arlatex
\ No newline at end of file diff --git a/Master/bin/mips-irix/bundledoc b/Master/bin/mips-irix/bundledoc new file mode 120000 index 00000000000..f7ea6372b95 --- /dev/null +++ b/Master/bin/mips-irix/bundledoc @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/bundledoc
\ No newline at end of file diff --git a/Master/bin/powerpc-aix/arlatex b/Master/bin/powerpc-aix/arlatex new file mode 120000 index 00000000000..16f679d6d26 --- /dev/null +++ b/Master/bin/powerpc-aix/arlatex @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/arlatex
\ No newline at end of file diff --git a/Master/bin/powerpc-aix/bundledoc b/Master/bin/powerpc-aix/bundledoc new file mode 120000 index 00000000000..f7ea6372b95 --- /dev/null +++ b/Master/bin/powerpc-aix/bundledoc @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/bundledoc
\ No newline at end of file diff --git a/Master/bin/powerpc-linux/arlatex b/Master/bin/powerpc-linux/arlatex new file mode 120000 index 00000000000..16f679d6d26 --- /dev/null +++ b/Master/bin/powerpc-linux/arlatex @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/arlatex
\ No newline at end of file diff --git a/Master/bin/powerpc-linux/bundledoc b/Master/bin/powerpc-linux/bundledoc new file mode 120000 index 00000000000..f7ea6372b95 --- /dev/null +++ b/Master/bin/powerpc-linux/bundledoc @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/bundledoc
\ No newline at end of file diff --git a/Master/bin/sparc-linux/arlatex b/Master/bin/sparc-linux/arlatex new file mode 120000 index 00000000000..16f679d6d26 --- /dev/null +++ b/Master/bin/sparc-linux/arlatex @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/arlatex
\ No newline at end of file diff --git a/Master/bin/sparc-linux/bundledoc b/Master/bin/sparc-linux/bundledoc new file mode 120000 index 00000000000..f7ea6372b95 --- /dev/null +++ b/Master/bin/sparc-linux/bundledoc @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/bundledoc
\ No newline at end of file diff --git a/Master/bin/sparc-solaris/arlatex b/Master/bin/sparc-solaris/arlatex new file mode 120000 index 00000000000..16f679d6d26 --- /dev/null +++ b/Master/bin/sparc-solaris/arlatex @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/arlatex
\ No newline at end of file diff --git a/Master/bin/sparc-solaris/bundledoc b/Master/bin/sparc-solaris/bundledoc new file mode 120000 index 00000000000..f7ea6372b95 --- /dev/null +++ b/Master/bin/sparc-solaris/bundledoc @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/bundledoc
\ No newline at end of file diff --git a/Master/bin/universal-darwin/arlatex b/Master/bin/universal-darwin/arlatex new file mode 120000 index 00000000000..16f679d6d26 --- /dev/null +++ b/Master/bin/universal-darwin/arlatex @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/arlatex
\ No newline at end of file diff --git a/Master/bin/universal-darwin/bundledoc b/Master/bin/universal-darwin/bundledoc new file mode 120000 index 00000000000..f7ea6372b95 --- /dev/null +++ b/Master/bin/universal-darwin/bundledoc @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/bundledoc
\ No newline at end of file diff --git a/Master/bin/x86_64-linux/arlatex b/Master/bin/x86_64-linux/arlatex new file mode 120000 index 00000000000..16f679d6d26 --- /dev/null +++ b/Master/bin/x86_64-linux/arlatex @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/arlatex
\ No newline at end of file diff --git a/Master/bin/x86_64-linux/bundledoc b/Master/bin/x86_64-linux/bundledoc new file mode 120000 index 00000000000..f7ea6372b95 --- /dev/null +++ b/Master/bin/x86_64-linux/bundledoc @@ -0,0 +1 @@ +../../texmf-dist/scripts/bundledoc/bundledoc
\ No newline at end of file diff --git a/Master/texmf-dist/doc/support/bundledoc/README b/Master/texmf-dist/doc/support/bundledoc/README new file mode 100644 index 00000000000..f6ee8c586a3 --- /dev/null +++ b/Master/texmf-dist/doc/support/bundledoc/README @@ -0,0 +1,105 @@ + ######################################################### + # Bundle all the files needed to build a LaTeX document # + # By Scott Pakin, scott+bdoc@pakin.org # + ######################################################### + + +Description +----------- + +bundledoc is a post-processor for the snapshot package that bundles +together all the classes, packages, and files needed to build a given +LaTeX document. It reads the .dep file that snapshot produces, finds +each of the files mentioned therein, and archives them into a single +.tar.gz (or .zip, or whatever) file, suitable for moving across +systems, transmitting to a colleague, etc. + +As an added bonus, this distribution includes a small script called +arlatex. arlatex is a LaTeX-specific archiving program that combines +a bunch of files into a single .tex file. When the .tex file is run +through latex, all of the original files are recreated and the LaTeX +document is built. bundledoc can be easily configured to use arlatex +as its archiver in place of tar, zip, etc. + + +Files +----- + +-rwxrwxr-x 1 pakin users 9595 2010-04-09 17:09 arlatex +-rw-rw-r-- 1 pakin users 10061 2010-04-09 17:09 arlatex.1 +-rw-rw-r-- 1 pakin users 9852 2010-04-10 11:11 arlatex.pdf +-rwxrwxr-x 1 pakin users 27435 2010-04-09 17:06 bundledoc +-rw-rw-r-- 1 pakin users 21738 2010-04-09 17:06 bundledoc.1 +-rw-rw-r-- 1 pakin users 21663 2010-04-10 11:11 bundledoc.pdf +-rw-rw-r-- 1 pakin users 344 2006-03-11 18:44 miktex.cfg +-rw-rw-r-- 1 pakin users 4397 2010-04-10 11:11 README +-rw-rw-r-- 1 pakin users 230 2010-04-09 16:45 texlive-unix.cfg + + +Requirements +------------ + +bundledoc and arlatex are both Perl scripts, so you naturally need +Perl installed on your system. bundledoc relies on the snapshot +package, which is available from CTAN (http://www.ctan.org). Before +running bundledoc, you must have used snapshot to produce a dependency +list for your document. Finally, bundledoc requires that you have +some program for archiving a bunch of files into a single file +(e.g. tar, shar, zip, or arlatex) and some program that can search +your TeX tree(s) for a given file (e.g., kpsewhich or initexmf). + + +Installation +------------ + +Installation is fairly flexible. The bundledoc and arlatex scripts +should be put somewhere in your executable search path (e.g., +/usr/local/bin on a typical Unix-like system). The Unix man pages, +bundledoc.1 and arlatex.1, should be put in the corresponding man +directory (e.g., /usr/local/man/man1) -- or discarded, if you're not +on a Unix-like system and therefore have no interest in having a man +page. + +The *.cfg files can go anywhere -- just don't forget where you put +them. ;-) I guess I'd recommend .../texmf/tex/latex/bundledoc (where +"..." is /usr/share or wherever your TeX tree is rooted), assuming +your TeX distribution follows the TDS directory structure (meaning, it +*has* a .../texmf/tex/latex directory). + +bundledoc.pdf and arlatex.pdf are pretty-printed PDF versions of +bundledoc.1 and arlatex.1 and can also go anywhere. If you want +printed documentation, these PDF files will give the nicest results. +Just note that they're formatted for U.S. Letter-sized paper, so you +may need to scale them slightly to print on A4 paper. + +Note that it's possible to produce documentation in other formats. +The bundledoc and arlatex scripts contain documentation in POD format. +You can therefore extract the documentation into your favorite format -- +LaTeX, HTML, plain text, etc. -- using the various pod2*** tools that +come with Perl. + + +Copyright and license +--------------------- + + 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. + +The license basically says that you can do whatever you want with +bundledoc, as long as you give me credit for writing it. Also, if you +modify any of the files, you have to call your modified version +something other than "bundledoc". 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> diff --git a/Master/texmf-dist/tex/latex/bundledoc/miktex.cfg b/Master/texmf-dist/tex/latex/bundledoc/miktex.cfg new file mode 100644 index 00000000000..8a31743194a --- /dev/null +++ b/Master/texmf-dist/tex/latex/bundledoc/miktex.cfg @@ -0,0 +1,9 @@ +# bundledoc configuration file for MikTeX +# By Scott Pakin <scott+bdoc@pakin.org> + +# ASSUMPTION: You have "zip" somewhere in your path, and it accepts the +# command-line options utilized by the "bundle" line below. + +bundle: zip -r -v -9 %BDBASE%.zip %BDINPUTS% +sink: > NUL: +find: initexmf --find-latex-input %BDINPUTS% diff --git a/Master/texmf-dist/tex/latex/bundledoc/texlive-unix.cfg b/Master/texmf-dist/tex/latex/bundledoc/texlive-unix.cfg new file mode 100644 index 00000000000..2f31ab586d0 --- /dev/null +++ b/Master/texmf-dist/tex/latex/bundledoc/texlive-unix.cfg @@ -0,0 +1,6 @@ +# bundledoc configuration file for TeX Live on Unix/Linux +# By Scott Pakin <scott+bdoc@pakin.org> + +bundle: (tar -cvf - $BDINPUTS | gzip --best > $BDBASE.tar.gz) +sink: > /dev/null 2>&1 +find: kpsewhich -progname=latex $BDINPUTS diff --git a/Master/texmf/doc/man/man1/arlatex.1 b/Master/texmf/doc/man/man1/arlatex.1 new file mode 100644 index 00000000000..8ef4f1d12b0 --- /dev/null +++ b/Master/texmf/doc/man/man1/arlatex.1 @@ -0,0 +1,279 @@ +.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "ARLATEX 1" +.TH ARLATEX 1 "2010-04-09" " " "User Commands" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +arlatex \- archive a number of ancillary LaTeX files into a master +\&\fI.tex\fR file +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +arlatex +[\fB\-\-outfile\fR=\fIfilename\fR\fI.tex\fR] +\&\fB\-\-document\fR=\fIfilename\fR\fI.tex\fR +\&\fIfilename\fR +\&... +.PP +arlatex +\&\fB\-\-version\fR +.PP +arlatex +\&\fB\-\-help\fR +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBarlatex\fR is an archiving program like \fBshar\fR, \fBtar\fR, \fBzip\fR, etc. +Unlike those other archivers, however, \fBarlatex\fR is designed +specifically for use with LaTeX. \fBarlatex\fR takes the name of a +master \fI.tex\fR file and a number of ancillary files used by that +master file (e.g., \fI.tex\fR, \fI.sty\fR, \fI.cls\fR, and \fI.eps\fR files). +From these, \fBarlatex\fR outputs a single file that, when it's run +through \fBlatex\fR, both regenerates the ancillary files and compiles +the document into a \fI.dvi\fR file. +.PP +\&\fBarlatex\fR has a few advantages over other archiving programs: +.IP "\(bu" 4 +The \fI.tex\fR files produced by \fBarlatex\fR are in a plain-text format. +They are therefore perfectly portable and trivial to e\-mail to +colleagues. +.IP "\(bu" 4 +\&\fBarlatex\fR needs only LaTeX to run. There is no dependence on any +external tools. +.IP "\(bu" 4 +There is no explicit extraction step. As the generated document is +run through \fBlatex\fR, it extracts the ancillary files and builds the +document in the same step. The user running \fBlatex\fR may not even +notice that additional files are being produced. +.PP +\&\fBarlatex\fR works by writing a number of \f(CW\*(C`\ebegin{filecontents*}\*(C'\fR\ ... +\&\f(CW\*(C`\eend{filecontents*}\*(C'\fR 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 +\&\f(CW\*(C`filecontents*\*(C'\fR environment, part of standard LaTeX2e, writes its +contents verbatim to a specified file. +.SH "OPTIONS" +.IX Header "OPTIONS" +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +Output the \fBarlatex\fR script's version number. +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +Output brief \fBarlatex\fR usage information. +.IP "\fB\-\-document\fR=\fI.tex file\fR" 4 +.IX Item "--document=.tex file" +Specify the master document. The output from \fBarlatex\fR is this file +with all of the other files named on the command line prepended to it. +Note that \f(CW\*(C`\-\-document\*(C'\fR is a \fImandatory\fR parameter; \fBarlatex\fR will +abort with an error message if \f(CW\*(C`\-\-document\*(C'\fR is not specified. +.IP "\fB\-\-outfile\fR=\fI.tex file\fR" 4 +.IX Item "--outfile=.tex file" +Specify the output file. The output file looks just like the master +document, but with a number of \f(CW\*(C`filecontents*\*(C'\fR environments preceding +the \f(CW\*(C`\edocumentclass\*(C'\fR line. If \f(CW\*(C`\-\-outfile\*(C'\fR is not specified, output +will be written to the standard output device. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +Suppose you have a paper called \fIpaper.tex\fR that loads a custom +package with \f(CW\*(C`\eusepackage{mypackage}\*(C'\fR. You want to submit the paper +to a conference, but you want to be absolutely certain that +\&\fImypackage.sty\fR doesn't get lost as your paper is shuttled from +person to person. Here's how \fBarlatex\fR can be of use: +.PP +.Vb 1 +\& arlatex \-\-document=paper.tex mypackage.sty \-\-outfile=paper\-submit.tex +.Ve +.PP +When \fIpaper\-submit.tex\fR is processed with \fBlatex\fR, it builds just +like the original \fIpaper.tex\fR, except that it additionally creates a +\&\fImypackage.sty\fR in the current directory: +.PP +.Vb 5 +\& 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\*(Aq. +\& +\& (/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) +\& . +\& . +\& . +.Ve +.PP +As another example, here's how you could bundle together all of the +files needed to build a large document for longevity: +.PP +.Vb 4 +\& 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 +.Ve +.PP +As the number of files to archive together increases it becomes more +cumbersome to run \fBarlatex\fR manually. Fortunately, using \fBarlatex\fR +with \fBbundledoc\fR is straightforward. \fBbundledoc\fR finds all of the +files needed to build the document, and \fBarlatex\fR combines them into +a single file. The following are examples of the \f(CW\*(C`bundle:\*(C'\fR line you +might use in a \fBbundledoc\fR configuration file: +.IP "Unix:" 1 +.IX Item "Unix:" +.Vb 2 +\& bundle: (arlatex \-\-document=$BDBASE.tex $BDINPUTS \e +\& \-\-outfile=$BDBASE\-all.tex) +.Ve +.IP "Windows:" 1 +.IX Item "Windows:" +.Vb 2 +\& bundle: arlatex \-\-document=%BDBASE%.tex %BDINPUTS% \e +\& \-\-outfile=%BDBASE%\-all.tex +.Ve +.PP +See the \fBbundledoc\fR documentation for more information. +.SH "CAVEATS" +.IX Header "CAVEATS" +\&\fBarlatex\fR makes use of LaTeX2e's \f(CW\*(C`filecontents*\*(C'\fR environment. +\&\f(CW\*(C`filecontents*\*(C'\fR refuses to overwrite an existing file. However, it +also refuses to create a file that exists \fIanywhere\fR that LaTeX can +find it. That is, if the user running \fBlatex\fR on an +\&\fBarlatex\fR\-generated \fI.tex\fR file already has a +\&\fI/usr/share/texmf/tex/latex/whatever/whatever.sty\fR file then +\&\f(CW\*(C`filecontents*\*(C'\fR will refuse to create a \fIwhatever.sty\fR file, even in +a different directory. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIbundledoc\fR\|(1), \fIlatex\fR\|(1), \fIshar\fR\|(1), \fItar\fR\|(1), \fIzip\fR\|(1) +.SH "AUTHOR" +.IX Header "AUTHOR" +Scott Pakin, \fIscott+bdoc@pakin.org\fR diff --git a/Master/texmf/doc/man/man1/arlatex.man1.pdf b/Master/texmf/doc/man/man1/arlatex.man1.pdf Binary files differnew file mode 100644 index 00000000000..94cba9ba66a --- /dev/null +++ b/Master/texmf/doc/man/man1/arlatex.man1.pdf diff --git a/Master/texmf/doc/man/man1/bundledoc.1 b/Master/texmf/doc/man/man1/bundledoc.1 new file mode 100644 index 00000000000..9f649f1d96f --- /dev/null +++ b/Master/texmf/doc/man/man1/bundledoc.1 @@ -0,0 +1,505 @@ +.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "BUNDLEDOC 1" +.TH BUNDLEDOC 1 "2010-04-09" " " "User Commands" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +bundledoc \- bundle all the files needed by a LaTeX document +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +bundledoc +[\fB\-\-version\fR] +[\fB\-\-help\fR] +[\fB\-\-\fR[\fBno\fR]\fBverbose\fR] +[\fB\-\-texfile\fR=\fIfile\fR] +[\fB\-\-directory\fR=\fIdirectory\fR] +[\fB\-\-\fR[\fBno\fR]\fBlocalonly\fR] +[\fB\-\-exclude\fR=\fIstring\fR] +[\fB\-\-include\fR=\fIfilespec\fR] +[\fB\-\-manifest\fR=\fIfile\fR] +[\fB\-\-\fR[\fBno\fR]\fBkeepdirs\fR] +[\fB\-\-config\fR=\fIfile\fR] +\&\fI.dep file\fR +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBbundledoc\fR is a post-processor for the \fBsnapshot\fR package that +bundles together all the classes, packages, and files needed to build +a given LaTeX document. It reads the \fI.dep\fR file that \fBsnapshot\fR +produces, finds each of the files mentioned therein, and packages them +into a single archive file (e.g., a \fI.tar.gz\fR file), suitable for +moving across systems, transmitting to a colleague, etc. +.PP +As the simplest example possible, consider a LaTeX file called, say, +\&\fIhello.tex\fR: +.PP +.Vb 2 +\& \eRequirePackage{snapshot} % Needed by bundledoc +\& \edocumentclass[11pt]{article} +\& +\& \ebegin{document} +\& Hello, world! +\& \eend{document} +.Ve +.PP +The \f(CW\*(C`\eRequirePackage{snapshot}\*(C'\fR causes a \fIhello.dep\fR file to be produced. +When \fBbundledoc\fR is then given \f(CW\*(C`hello.dep\*(C'\fR as an argument, it locates the +dependent files \*(-- \fIsnapshot.sty\fR, \fIarticle.cls\fR, and \fIsize11.clo\fR \*(-- +and bundles them into a single archive file, along with \fIhello.tex\fR and a +\&\fI\s-1MANIFEST\s0\fR file (described in \*(L"\s-1OPTIONS\s0\*(R", below). +.SH "OPTIONS" +.IX Header "OPTIONS" +In the following descriptions, \fIsomefile\fR refers to the name of your +main LaTeX document (no extension). +.PP +\&\fBbundledoc\fR requires the name of the dependency file produced by +\&\fBsnapshot\fR (normally \fIsomefile\fR\fI.dep\fR). The following options may +also be given: +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +Output the \fBbundledoc\fR script's version number. This overrides all the +remaining options. +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +Give a brief usage message. This overrides all of the remaining options. +.ie n .IP "\fB\-\-\fR[\fBno\fR]\fBverbose\fR (default: ""noverbose"")" 4 +.el .IP "\fB\-\-\fR[\fBno\fR]\fBverbose\fR (default: \f(CWnoverbose\fR)" 4 +.IX Item "--[no]verbose (default: noverbose)" +\&\fBbundledoc\fR normally does not output anything except error messages. +With \f(CW\*(C`\-\-verbose\*(C'\fR, it outputs copious status messages. +.IP "\fB\-\-texfile\fR=\fImain .tex file\fR (default: \fIsomefile\fR\fI.tex\fR)" 4 +.IX Item "--texfile=main .tex file (default: somefile.tex)" +\&\fBsnapshot\fR's dependency file does not list the main LaTeX file (the +one that gets passed to \fBlatex\fR). In order for \fBbundledoc\fR to find +and bundle that file, \fBbundledoc\fR assumes it has the same name as the +\&\fBsnapshot\fR dependency file but with a \fI.tex\fR extension. If this is +not the case, then use \f(CW\*(C`\-\-texfile\*(C'\fR to specify the correct filename. +.IP "\fB\-\-directory\fR=\fIarchive directory\fR (default: \fIsomefile\fR)" 4 +.IX Item "--directory=archive directory (default: somefile)" +When \fBbundledoc\fR creates an archive (e.g., a \fI.tar\fR or \fI.zip\fR 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 \fIsomefile\fR\fI.dep\fR then the resulting +archive will, by default, store all the dependent files in a +\&\fIsomefile\fR directory. To change the directory name use the +\&\f(CW\*(C`\-\-directory\*(C'\fR option. +.ie n .IP "\fB\-\-\fR[\fBno\fR]\fBlocalonly\fR (default: ""nolocalonly"")" 4 +.el .IP "\fB\-\-\fR[\fBno\fR]\fBlocalonly\fR (default: \f(CWnolocalonly\fR)" 4 +.IX Item "--[no]localonly (default: nolocalonly)" +Although \fBbundledoc\fR normally archives all of the files named in the +\&\fI.dep\fR file, the \f(CW\*(C`\-\-localonly\*(C'\fR option tells \fBbundledoc\fR to exclude +all files located in a directory other than the \fI.tex\fR file's +directory or one of its subdirectories. +.IP "\fB\-\-exclude\fR=\fIstring\fR (default: \fInone\fR)" 4 +.IX Item "--exclude=string (default: none)" +While \f(CW\*(C`\-\-localonly\*(C'\fR causes files outside of the \fI.tex\fR file's +directory tree to be omitted from the archive, \f(CW\*(C`\-\-exclude\*(C'\fR provides +finer-grained control over files to omit from the archive. The +\&\f(CW\*(C`\-\-exclude\*(C'\fR option, which can be specified repeatedly on the command +line, causes all files whose name contains \fIstring\fR to be omitted +from the archive. +.IP "\fB\-\-include\fR=\fIfilespec\fR (default: \fInone\fR)" 4 +.IX Item "--include=filespec (default: none)" +The \f(CW\*(C`\-\-include\*(C'\fR option, which can be specified repeatedly on the +command line, instructs \fBbundledoc\fR to include in the archive all of +the files matching \fIfilespec\fR, even if they're not referenced in the +\&\fI.dep\fR file. +.IP "\fB\-\-manifest\fR=\fImanifest file\fR (default: \fI\s-1MANIFEST\s0\fR)" 4 +.IX Item "--manifest=manifest file (default: MANIFEST)" +In addition to the dependent files, \fBbundledoc\fR includes in the +archive file one extra file called, by default, ``\fI\s-1MANIFEST\s0\fR''. +\&\fI\s-1MANIFEST\s0\fR is a text file that lists the original filenames of all +the dependencies. To change the filename from ``\fI\s-1MANIFEST\s0\fR'' to +something else, use the \f(CW\*(C`\-\-manifest\*(C'\fR option. As a special case, +\&\f(CW\*(C`\-\-manifest=""\*(C'\fR tells \fBbundledoc\fR not to include a manifest file at +all. +.ie n .IP "\fB\-\-\fR[\fBno\fR]\fBkeepdirs\fR (default: ""nokeepdirs"")" 4 +.el .IP "\fB\-\-\fR[\fBno\fR]\fBkeepdirs\fR (default: \f(CWnokeepdirs\fR)" 4 +.IX Item "--[no]keepdirs (default: nokeepdirs)" +Normally, the archive file that \fBbundledoc\fR produces contains a +single directory \*(-- and subdirectories, if the document refers +explicitly to them \*(-- in which all the dependent files lie. If +\&\f(CW\*(C`\-\-keepdirs\*(C'\fR is specified, all the dependent files are stored with +their original pathnames. For example, if \fIsomefile.tex\fR depends on +\&\fIfigures/somefigure.eps\fR, \fIarticle.cls\fR, and \fIsnapshot.sty\fR, then +the \fIsomefile\fR archive will normally contain the following files: +.RS 4 +.IP "\(bu" 4 +\&\fIsomefile/somefile.tex\fR +.IP "\(bu" 4 +\&\fIsomefile/figures/somefigure.eps\fR +.IP "\(bu" 4 +\&\fIsomefile/article.cls\fR +.IP "\(bu" 4 +\&\fIsomefile/snapshot.sty\fR +.IP "\(bu" 4 +\&\fIsomefile/MANIFEST\fR +.RE +.RS 4 +.Sp +However, \f(CW\*(C`\-\-keepdirs\*(C'\fR will cause the \fIsomefile\fR archive to contain +the following sorts of filenames instead: +.IP "\(bu" 4 +\&\fIhome/me/mydocs/somefile.tex\fR +.IP "\(bu" 4 +\&\fIhome/me/mydocs/figures/somefigure.eps\fR +.IP "\(bu" 4 +\&\fIusr/share/texmf/tex/latex/base/article.cls\fR +.IP "\(bu" 4 +\&\fIusr/share/texmf/tex/latex/snapshot/snapshot.sty\fR +.RE +.RS 4 +.Sp +\&\f(CW\*(C`\-\-directory\*(C'\fR is not used when \f(CW\*(C`\-\-keepdirs\*(C'\fR is in effect. In +addition, no manifest file is written to the archive file as it +contains redundant information. +.RE +.IP "\fB\-\-config\fR=\fIconfiguration file\fR (default: <none>)" 4 +.IX Item "--config=configuration file (default: <none>)" +The \f(CW\*(C`\-\-config\*(C'\fR option is used to point \fBbundledoc\fR to the +appropriate configuration (\fI.cfg\fR) file for your TeX distribution and +operating system. \fBbundledoc\fR comes with a few configuration files +and it's easy to write more. See \*(L"\s-1CONFIGURATION\s0 \s-1FILES\s0\*(R" (below) for +a description of the configuration file format. +.SH "CONFIGURATION FILES" +.IX Header "CONFIGURATION FILES" +.SS "Format" +.IX Subsection "Format" +Configuration files follow a fairly simple format. Lines beginning with +\&\f(CW\*(C`#\*(C'\fR are comments. Blank lines are ignored. All other lines are of the +form: +.PP +.Vb 1 +\& variable: value +.Ve +.PP +The current version of \fBbundledoc\fR recognizes the following variables: +.IP "\fBbundle\fR" 4 +.IX Item "bundle" +The command to use to bundle a set of files into a single archive file +.IP "\fBsink\fR" 4 +.IX Item "sink" +The affix to a command to discard its output +.IP "\fBfind\fR" 4 +.IX Item "find" +The command to find a file within the TeX tree(s). +.PP +Values that are too long for one line can be split across multiple lines +by using \f(CW\*(C`\e\*(C'\fR as the line-continuation symbol. +.PP +There are two environment variables that \fBbundledoc\fR makes available +for use by configuration-file commands: \f(CW\*(C`BDBASE\*(C'\fR, which is set to +\&\fIsomefile\fR (as in \*(L"\s-1OPTIONS\s0\*(R"), and \f(CW\*(C`BDINPUTS\*(C'\fR, which is set to a +space-separated list of files that a command is to operate upon. That +is, when the command associated with \f(CW\*(C`bundle\*(C'\fR is running, \f(CW\*(C`BDINPUTS\*(C'\fR +contains the list of all the files that are to be archived. In +contrast, when the command associated with \f(CW\*(C`find\*(C'\fR is running, +\&\f(CW\*(C`BDINPUTS\*(C'\fR contains the name of the file to search for. +.SS "Examples" +.IX Subsection "Examples" +The following configuration file parallels \fBbundledoc\fR'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 \s-1GNU\s0 tools, such as \fBgzip\fR +or \s-1GNU\s0 \fBtar\fR: +.PP +.Vb 2 +\& # "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 +.Ve +.PP +The parentheses in the \f(CW\*(C`bundle:\*(C'\fR line tell the Unix shell to run the +command in a subshell. This is to make the \f(CW\*(C`sink:\*(C'\fR affix work +properly (i.e., so there aren't two \f(CW\*(C`>\*(C'\fR's in the same command). +.PP +Notice how the commands treat \f(CW\*(C`BDBASE\*(C'\fR and \f(CW\*(C`BDINPUTS\*(C'\fR like any other +environment variables in a Unix shell, using \f(CW\*(C`$\*(C'\fR 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 \f(CW\*(C`%BDBASE%\*(C'\fR and \f(CW\*(C`%BDINPUTS%\*(C'\fR +instead. +.PP +The value for \f(CW\*(C`sink:\*(C'\fR is specific to an operating system. The value +for \f(CW\*(C`find:\*(C'\fR is specific to a TeX distribution. \f(CW\*(C`bundle:\*(C'\fR is where +the most opportunity for customization lies. You can use \f(CW\*(C`bundle:\*(C'\fR +to specify your favorite archive format. For example, you can produce +a shar file on Unix with something like: +.PP +.Vb 1 +\& bundle: (shar \-\-archive\-name="$BDBASE" $BDINPUTS > $BDBASE.sh) +.Ve +.PP +or a \s-1CAB\s0 file on Microsoft Windows with something like: +.PP +.Vb 1 +\& bundle: cabarc \-r \-p N %BDBASE%.cab %BDINPUTS% +.Ve +.SH "EXAMPLES" +.IX Header "EXAMPLES" +Assume that \fImyfile.dep\fR was produced from \fImyfile.tex\fR by following +the instructions in the Description section. The +following command produces a \fI.zip\fR file with the MikTeX TeX +distribution running on Microsoft Windows: +.PP +.Vb 1 +\& bundledoc \-\-config=miktex.cfg myfile.dep +.Ve +.PP +(In practice, it's probably necessary to specify to \f(CW\*(C`\-\-config\*(C'\fR the +complete path to \fBbundledoc\fR's \fImiktex.cfg\fR configuration file.) +.PP +The following builds a \fI.tar.gz\fR archive with the TeX Live +distribution running on a Unix-like operating system. \fBbundledoc\fR +will produce verbose output describing its operations. All files not +in the same directory tree as \fImyfile.tex\fR and all files containing +\&\*(L".fd\*(R" or \*(L".sty\*(R" in their names are omitted. However, all \fI.bib\fR +files in the current directory will be included in the archive even +though none of them are referenced by \fImyfile.dep\fR. Finally, no +\&\fI\s-1MANIFEST\s0\fR file will be produced. +.PP +.Vb 3 +\& bundledoc \-\-config=texlive\-unix.cfg \-\-verbose \-\-localonly \e +\& \-\-exclude=.fd \-\-exclude=.cfg \-\-include="*.bib" \-\-manifest="" \e +\& myfile.dep +.Ve +.SH "FILES" +.IX Header "FILES" +The user must have previously installed \fIsnapshot.sty\fR and used it to +produce a dependency file for his document. Besides that, the set of +external files needed by \fBbundledoc\fR is system-specific and depends on the +configuration file used. (See \*(L"\s-1CONFIGURATION\s0 \s-1FILES\s0\*(R", above.) +.PP +\&\fBbundledoc\fR currently comes with two configuration files: +.IP "\fItexlive\-unix.cfg\fR" 4 +.IX Item "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. \fItexlive\-unix.cfg\fR assumes you have +\&\fBgzip\fR and uses it to produce a \fI.tar.gz\fR archive file. The +configuration file has \fBbundledoc\fR use \fBkpsewhich\fR to find LaTeX +files. +.IP "\fImiktex.cfg\fR" 4 +.IX Item "miktex.cfg" +Configuration file for MikTeX installations. MikTeX is a popular TeX +distribution for Microsoft Windows. \fImiktex.cfg\fR assumes you have +\&\fBzip\fR and uses it to produce a \fI.zip\fR archive file. The +configuration file has \fBbundledoc\fR use the rather nonstandard +\&\fBinitexmf\fR to find LaTeX files. +.SH "NOTES" +.IX Header "NOTES" +.SS "Including and excluding files" +.IX Subsection "Including and excluding files" +The \f(CW\*(C`\-\-localonly\*(C'\fR, \f(CW\*(C`\-\-exclude\*(C'\fR, and \f(CW\*(C`\-\-include\*(C'\fR options provide +control over the archive's contents. \f(CW\*(C`\-\-exclude\*(C'\fR and \f(CW\*(C`\-\-include\*(C'\fR +can be specified repeatedly on the command line. The order in which +these options are specified is immaterial; \fBbundledoc\fR processes file +inclusions and exclusions in the following order: +.IP "1." 4 +All files referenced by the \fI.dep\fR file are added to the list of +files to archive. +.IP "2." 4 +If \f(CW\*(C`\-\-localonly\*(C'\fR is specified, all files not found in the \fI.tex\fR +file's directory are removed from the list. +.IP "3." 4 +For each \f(CW\*(C`\-\-exclude\*(C'\fR string specified, all files containing that +string are removed from the list. +.IP "4." 4 +For each \f(CW\*(C`\-\-include\*(C'\fR file specification, the set of files designated +by its expansion are added to the list. +.SS "Issues When Running Under Microsoft Windows" +.IX Subsection "Issues When Running Under Microsoft Windows" +First, because \fBbundledoc\fR is a Perl script, you should do one of the +following to run it under Windows: +.IP "\(bu" 4 +\&\f(CW\*(C`perl bundledoc\*(C'\fR +.IP "\(bu" 4 +Rename \fIbundledoc\fR to \fIbundledoc.pl\fR and run \f(CW\*(C`bundledoc.pl\*(C'\fR. (This +is assuming you have a file association set up for \fI.pl\fR.) +.IP "\(bu" 4 +Run the \fBpl2bat\fR script (if you have it) to convert \fIbundledoc\fR to +\&\fIbundledoc.bat\fR, then run \f(CW\*(C`bundledoc\*(C'\fR. +.PP +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 ``\s-1UNC\s0'' filenames, which have no drive letter at all, just a +machine and share name. \s-1UNC\s0 filenames are also untested waters for +\&\fBbundledoc\fR. Be careful! +.SS "Testing Status" +.IX Subsection "Testing Status" +I have tested \fBbundledoc\fR only with Perl v5.6.0 and later and only on +the following platforms: +.IP "\(bu" 4 +Linux + TeX Live +.IP "\(bu" 4 +Linux + teTeX +.IP "\(bu" 4 +Windows \s-1NT\s0 + MiKTeX +.IP "\(bu" 4 +Solaris + ??? (something kpathsea-based) +.PP +It is my hope that \fBbundledoc\fR 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 \fBbundledoc\fR on a different system. +.SS "Future Work" +.IX Subsection "Future Work" +I'd like \fBbundledoc\fR 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\*(R" (e.g., if you're +running MacOS) and you need to create a substantially different +configuration file from \fItexlive\-unix.cfg\fR and \fImiktex.cfg\fR, please +send it to me at the address listed in \*(L"\s-1AUTHOR\s0\*(R" so I can include it +in a future version of \fBbundledoc\fR. (I make no promises, though). +.PP +Once \fBbundledoc\fR works on all the major operating systems and TeX +distributions it would be really convenient if I could get +\&\fBbundledoc\fR to detect the platform it's running on and automatically +select an appropriate configuration file. +.PP +Finally, it would be handy for \fBbundledoc\fR to include fonts in the +archive file. At a minimum, it should include \fI.tfm\fR files, but it +would be even better if it included \fI.mf\fR, \fI.pfb\fR, \fI.ttf\fR, and +other common font formats, as well. +.SS "Acknowledgments" +.IX Subsection "Acknowledgments" +Thanks to Fabien Vignes-Tourneret for suggesting what became the +\&\f(CW\*(C`\-\-localonly\*(C'\fR option and for a discussion that led to the +\&\f(CW\*(C`\-\-exclude\*(C'\fR and \f(CW\*(C`\-\-include\*(C'\fR options; and to Marius Kleiner for +updating \fBbundledoc\fR to properly handle document subdirectories. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIgzip\fR\|(1), \fIkpsewhich\fR\|(1), \fIlatex\fR\|(1), \fIperl\fR\|(1), \fIzip\fR\|(1), the \fBsnapshot\fR +documentation +.SH "AUTHOR" +.IX Header "AUTHOR" +Scott Pakin, \fIscott+bdoc@pakin.org\fR diff --git a/Master/texmf/doc/man/man1/bundledoc.man1.pdf b/Master/texmf/doc/man/man1/bundledoc.man1.pdf Binary files differnew file mode 100644 index 00000000000..685ee26b787 --- /dev/null +++ b/Master/texmf/doc/man/man1/bundledoc.man1.pdf diff --git a/Master/tlpkg/bin/tlpkg-ctan-check b/Master/tlpkg/bin/tlpkg-ctan-check index 1ea66299372..230a303d4b9 100755 --- a/Master/tlpkg/bin/tlpkg-ctan-check +++ b/Master/tlpkg/bin/tlpkg-ctan-check @@ -55,7 +55,7 @@ my @TLP_working = qw( boites boldtensors bookest booklet booktabs boolexpr bophook bosisio boxedminipage boxhandler bpchem bpolynomial bracketkey braille braket breakcites breakurl - bullcntr bussproofs bytefield + bullcntr bundledoc bussproofs bytefield cachepic calctab calligra calrsfs cancel capt-of captcont captdef caption carlisle carolmin-ps cases casyl catechis cbcoptic cbfonts diff --git a/Master/tlpkg/libexec/ctan2tds b/Master/tlpkg/libexec/ctan2tds index 6ac8ccad0c4..db603e120db 100755 --- a/Master/tlpkg/libexec/ctan2tds +++ b/Master/tlpkg/libexec/ctan2tds @@ -992,24 +992,25 @@ $standardtex='\.(.bx|cfg|sty|clo|ldf|cls|def|fd|cmap|4ht)$'; 'antomega', 'omega', 'arabxetex', 'xelatex', 'archaic', 'fonts', - 'arev', 'fonts', - 'around-the-bend', 'generic', - 'arrayjob', 'generic', - 'astro', 'fonts', + 'arev', 'fonts', + 'around-the-bend', 'generic', + 'arrayjob', 'generic', + 'astro', 'fonts', 'asymptote-faq-zh-cn', 'support', 'asymptote-by-example-zh-cn', 'support', 'asymptote-manual-zh-cn', 'support', - 'aurical', 'fonts', - 'automata', 'metapost', - 'ascii', 'fonts', - 'barr', 'generic', - 'bbm', 'fonts', - 'bera', 'fonts', - 'bghyphen', 'generic', - 'bib-fr', 'bibtex', - 'bibhtml', 'bibtex', - 'blacklettert1', 'fonts', - 'boisik', 'fonts', + 'aurical', 'fonts', + 'automata', 'metapost', + 'ascii', 'fonts', + 'barr', 'generic', + 'bbm', 'fonts', + 'bera', 'fonts', + 'bghyphen', 'generic', + 'bib-fr', 'bibtex', + 'bibhtml', 'bibtex', + 'blacklettert1', 'fonts', + 'boisik', 'fonts', + 'bundledoc', 'support', 'cbfonts', 'fonts', 'cc-pl', 'fonts', 'chicago-annote', 'bibtex', @@ -1573,6 +1574,7 @@ $standardxmt='\.xmt'; 'a2ping' => '\.pl$', 'accfonts' => 'mkt1font|vpl2', 'bibexport' => 'bibexport\.sh$', + 'bundledoc' => '(arlatex|bundledoc)$', 'de-macro' => 'de-macro', 'dviasm' => '\.py$', 'epspdf' => '(epspdf(|\.help|boot|tk)|\.rb|makegray\.pro)$', @@ -1610,6 +1612,7 @@ $standardxmt='\.xmt'; # packages which have man pages to install. %specialmans = ( + 'bundledoc' => '\.1$', 'epstopdf' => 'epstopdf.1|epstopdf.man1.pdf', 'findhyph' => 'findhyph.1', 'latexdiff' => '\.1$', @@ -1632,6 +1635,7 @@ $standardclean = '\.head|\.tmp|\.dvi|\.log|\.out|\.aux|\.toc|\.lof|\.lot' 'acmconf' => $standardclean . '|flushend.sty', # dup with sttools 'apalike' => "apalike2.bst", # does not belong 'bbm-macros' => $standardclean . '|^bbm$', # symlink + 'bundledoc' => $standardclean . '|\.pdf$', # regen for a4 'chemscheme' => $standardclean . '|jawltxdoc.sty', # temp file for doc 'chemstyle' => $standardclean . '|jawltxdoc.sty', # temp file for doc 'dateiliste' => $standardclean . '|dateiliste.README*', # already in dist diff --git a/Master/tlpkg/tlpsrc/bundledoc.tlpsrc b/Master/tlpkg/tlpsrc/bundledoc.tlpsrc new file mode 100644 index 00000000000..6fe4bdfd92e --- /dev/null +++ b/Master/tlpkg/tlpsrc/bundledoc.tlpsrc @@ -0,0 +1,2 @@ +docpattern +f texmf/doc/man/man1/arlatex.* +binpattern f bin/${ARCH}/a2ping diff --git a/Master/tlpkg/tlpsrc/collection-binextra.tlpsrc b/Master/tlpkg/tlpsrc/collection-binextra.tlpsrc index f2e14d0d1cf..22ce0150ff4 100644 --- a/Master/tlpkg/tlpsrc/collection-binextra.tlpsrc +++ b/Master/tlpkg/tlpsrc/collection-binextra.tlpsrc @@ -8,6 +8,7 @@ depend collection-basic depend a2ping depend asymptote depend bibtex8 +depend bundledoc depend ctie depend cweb depend de-macro |