diff options
author | Karl Berry <karl@freefriends.org> | 2010-04-10 22:08:00 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2010-04-10 22:08:00 +0000 |
commit | 963b665a04c33ddcfe04234426c8bca1942589bf (patch) | |
tree | 2416c1045ecd8aaa916a512cf7a05cd4055661f9 /Master/texmf-dist/scripts/bundledoc/arlatex | |
parent | 5406b8e0ea1d596600f773e766975256e4087c51 (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/arlatex')
-rwxr-xr-x | Master/texmf-dist/scripts/bundledoc/arlatex | 283 |
1 files changed, 283 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> |