LaTeX-Driver-0.12/0000755000175000017500000000000012020204474013157 5ustar andrewandrewLaTeX-Driver-0.12/SIGNATURE0000664000175000017500000001064012020204474014446 0ustar andrewandrewThis file contains message digests of all files listed in MANIFEST, signed via the Module::Signature module, version 0.68. To verify the content in this distribution, first make sure you have Module::Signature installed, then type: % cpansign -v It will check each file's integrity, as well as the signature's validity. If "==> Signature verified OK! <==" is not displayed, the distribution may already have been compromised, and you should not run its Makefile.PL or Build.PL. -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 SHA1 d24bc03d438f47eee47cd7d2730b7719a269236f Changes SHA1 328b693546018d9238c1e55be9d89b1c284fecca INSTALL SHA1 812525e98d558764c5156faa35704785551752cd MANIFEST SHA1 821169136567c66f7fb722ff91973e5220f0a0bc MANIFEST.SKIP SHA1 f443e541daf5e24d3f49099f1ef8760927d1740f META.json SHA1 339ab8bbf78f3af8498dd024daf919036704c8bc META.yml SHA1 86181090efbbb55fc850e4f859afc68d9e8a3252 MYMETA.json SHA1 e0fb3d6c4d468ffabb6e5bf39d254d1e56f773b8 MYMETA.yml SHA1 7b1108351d71c00d06e7589bda4fbcfe6b98d0ce Makefile.PL SHA1 33c7504e98cde38c83746c687dc2077b09737d9a README SHA1 43cc4bf327a208bf8061c11fff72bff9d5b4df01 TODO SHA1 866d3588e19e245f8043ade50fd4c5617b73c146 lib/LaTeX/Driver.pm SHA1 e26ef8d90b30db5513a215e72001abeb01657127 lib/LaTeX/Driver/FilterProgram.pm SHA1 09c213d441188bcf900e94f20fa05199abdb8977 lib/LaTeX/Driver/Paths.pm SHA1 69a4a43829aa933a9afc9e181ff857fb51024150 scripts/README SHA1 50902ae2567fccf72478d7e4ef3e28388f917ef0 scripts/latex2dvi SHA1 c98d5172f0c305dffdd0507d2c875df6876129ec scripts/latex2pdf SHA1 a9751b0d62766e422818b90c855dca31c01cb20d scripts/latex2ps SHA1 848fde3e4ecdd2775cc1e89e0de77e2e7444c83f t/00-basic.t SHA1 c01a256dbea4351d4c8a0c1b9358334abb01d703 t/01-errors.t SHA1 4a6d997f278e4860a6a4913a291b88c6e3fcc9b4 t/02-brokendocs.t SHA1 797b4638c7f81f63419c4572ef715e4b4223d6f3 t/10-simpledoc.t SHA1 a9336058206bd7f07e97ec341ccb3a6c41d26b8d t/11-references.t SHA1 723783e60d11abc1ec4c8e80eb3db48ba13978d7 t/12-includes.t SHA1 366caaa4a5fc4d276690f56df8a6ff765e73fbb6 t/13-tableofcontents.t SHA1 20c950ca9fa7d00e88156ef42c959f588ae3f99d t/14-makeindex.t SHA1 0fb08e61c30096750bb6800f41f1c6185d6a285d t/15-bibtex.t SHA1 68d14ceefa3a9b1544ed0845600bbfa121f027cf t/20-complexdoc.t SHA1 091b882ab7120fa615c3a6e05ae19acd5a48e411 t/30-output-to-variable.t SHA1 242614d57cf16ed7a3b34a2e5aa7cd663ddb70ec t/31-input-from-variable.t SHA1 0b9b629ade8e6b677eca25393313703586a32377 t/90-kwalitee.t SHA1 5af4b015dad6fd6d6cb65d0698787af7c1ebbc65 t/91-pod.t SHA1 456a35112c5c8ce00dc02aee833b9037c058d7b8 t/92-pod-coverage.t SHA1 ec6c237d74d7a41e3a0acbf96cc9e7cab06b6ad8 t/93-perl-critic.t SHA1 322dc5748f4a09370203046a971bb966b80fae93 t/README SHA1 7e9925023cf974da7ce22a235c7404816cf035bd t/lib/Test/LaTeX/Driver.pm SHA1 a51f4c00a17b22f3b28a1b147b717294eebd4307 t/perlcriticrc SHA1 dff66d1dc61435c81d570b0350d0bb167401f6ea t/testdata/00-common/testinc2.tex SHA1 5416b42f3816f079d5d8608915658fc40312e172 t/testdata/01-errors/01-errors.tex SHA1 43d5a315c8f0940a718c65324d5f9074d9cd790f t/testdata/02-brokendocs/02-brokendocs.tex SHA1 d6d9719ea97b25217b4e79ef52ac23ddca7d4f25 t/testdata/10-simpledoc/10-simpledoc.tex SHA1 13ffdcd979ce8b5746ef2e9f7483a3773cdc7334 t/testdata/11-references/11-references.tex SHA1 826fd1e8ce8a272b56d0da94ad3c1b852d4057bb t/testdata/12-includes/12-includes.tex SHA1 f577323106137c63cd08ecf4660bc369a33772f3 t/testdata/12-includes/testinc.tex SHA1 451ce069063e600a8899ee786562ed36777862aa t/testdata/13-tableofcontents/13-tableofcontents.tex SHA1 8e4600e8eafd40eae4ac634168b48c56e743379b t/testdata/14-makeindex/14-makeindex.tex SHA1 28aa9cff532f9e98fcfc1e69c9f58490f1c19e0a t/testdata/14-makeindex/testind.ist SHA1 4f2756e7918404e35d1736551176a78939ac3f2d t/testdata/15-bibtex/15-bibtex.tex SHA1 85c975380b071d24564ea5acbb9998fb39259658 t/testdata/15-bibtex/testbib.bib SHA1 3fde257ee7b32297b11851e6091d661b497999c0 t/testdata/20-complexdoc/20-complexdoc.tex SHA1 85c975380b071d24564ea5acbb9998fb39259658 t/testdata/20-complexdoc/testbib.bib SHA1 830301be9ec87cc2628e7e6279b0f75a397bd4cd t/testdata/20-complexdoc/testinc.tex SHA1 947b3e994be2609ad3441646b7db52418e348a4a t/testdata/30-output-to-variable/30-output-to-variable.tex SHA1 947b3e994be2609ad3441646b7db52418e348a4a t/testdata/31-input-from-variable/31-input-from-variable.tex -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.12 (GNU/Linux) iEYEARECAAYFAlBBCTgACgkQ6Ftp4RHHKhuGXACfSvbOg2T30G6JIhhh9T9y6I00 JzwAn1je/dTMhDFQJfWOzSaMtbvqkdGB =gwn1 -----END PGP SIGNATURE----- LaTeX-Driver-0.12/TODO0000644000175000017500000000542512017743731013667 0ustar andrewandrew#================================================== -*- indented-text -*- # # TODO # # DESCRIPTION # TODO list for the LaTeX-Driver package, containing known bugs, # limitations, planned enhancements, long term visions and a few # whacky ideas. # # AUTHOR # Andrew Ford # #------------------------------------------------------------------------ # $Id: TODO 84 2012-08-30 20:19:25Z andrew $ #======================================================================== #------------------------------------------------------------------------ # Miscellaneous #------------------------------------------------------------------------ * add handling of luatex * improve Kwalitee and general adherance to Perl best practice [MOSTLY DONE] * add a script to invoke LaTeX::Driver on a specified file - need to think of a good name and a sensible set of options * add checks for timestamps (a la "make" and "latexmk") * check the mechanism whereby latex (or pdflatex) is re-run if the document contains undefined references after the first run. Bibtex is re-run if undefined citations are reported by latex, and makeindex is run if the driver detects a ".idx" file. If bibtex or makeindex are run then latex (or pdflatex) are run up to three more times to allow forward references to stabilize. This should all be coped with now but need to check on edge cases * look at how path variables could be specified to the filter (TEXINPUTS, TEXINPUTS_latex, TEXINPUTS_pdflatex, BIBINPUTS, etc), and how these should interact with the system paths. * get the filter working on Win32 how does one set environment variables with command.exe? * write unit tests for error conditions (invalid .bib file, etc) * test the scripts * make test scripts check for presence of tex components, such as dvitype, lastpage.sty * provide a facility for specifying pre- and post-processors, e.g. gnuplot, metapost, tpic or other graphics processors. May need to copy data files from the source location to the temporary directory. * benchmark the filter Note that the latex filter runs up to eight external programs, so it isn't very fast. But for modest documents the performance is adequate, even for interactive applications. * expand the documentation * try to fix the line numbers when formatting a template document with latex2xxx results in latex errors. If we get errors with line numbers, they will relate to the expanded document - not to the template source lines, but we could find the mapping by reexpanding the template, adding line numbers in TT2 "#" comments to the template source, and then go to the line number in error and read off the original line number. * check for further conditions that require re-running of one or more LaTeX programs. LaTeX-Driver-0.12/MANIFEST0000644000175000017500000000313512020204470014306 0ustar andrewandrewMANIFEST This list of files MANIFEST.SKIP README General information, installation, etc. INSTALL Changes TODO Makefile.PL MYMETA.yml MYMETA.json lib/LaTeX/Driver.pm lib/LaTeX/Driver/Paths.pm lib/LaTeX/Driver/FilterProgram.pm t/README t/00-basic.t t/01-errors.t t/02-brokendocs.t t/10-simpledoc.t t/11-references.t t/12-includes.t t/13-tableofcontents.t t/14-makeindex.t t/15-bibtex.t t/20-complexdoc.t t/30-output-to-variable.t t/31-input-from-variable.t t/90-kwalitee.t t/91-pod.t t/92-pod-coverage.t t/93-perl-critic.t t/lib/Test/LaTeX/Driver.pm t/perlcriticrc t/testdata/00-common/testinc2.tex t/testdata/01-errors/01-errors.tex t/testdata/02-brokendocs/02-brokendocs.tex t/testdata/10-simpledoc/10-simpledoc.tex t/testdata/11-references/11-references.tex t/testdata/12-includes/12-includes.tex t/testdata/12-includes/testinc.tex t/testdata/13-tableofcontents/13-tableofcontents.tex t/testdata/14-makeindex/14-makeindex.tex t/testdata/14-makeindex/testind.ist t/testdata/15-bibtex/15-bibtex.tex t/testdata/15-bibtex/testbib.bib t/testdata/20-complexdoc/20-complexdoc.tex t/testdata/20-complexdoc/testbib.bib t/testdata/20-complexdoc/testinc.tex t/testdata/30-output-to-variable/30-output-to-variable.tex t/testdata/31-input-from-variable/31-input-from-variable.tex scripts/README scripts/latex2dvi scripts/latex2pdf scripts/latex2ps META.yml Module meta-data (added by MakeMaker) META.json Module JSON meta-data (added by MakeMaker) SIGNATURE Public-key signature (added by MakeMaker) LaTeX-Driver-0.12/META.yml0000664000175000017500000000103212020204470014422 0ustar andrewandrew--- abstract: unknown author: - unknown build_requires: ExtUtils::MakeMaker: 0 configure_requires: ExtUtils::MakeMaker: 0 dynamic_config: 1 generated_by: 'ExtUtils::MakeMaker version 6.62, CPAN::Meta::Converter version 2.120921' license: unknown meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: 1.4 name: LaTeX-Driver no_index: directory: - t - inc requires: Class::Accessor: 0 Cwd: 0 Exception::Class: 0 File::Slurp: 0 File::Spec: 0 IO::File: 0 Readonly: 0 version: 0.12 LaTeX-Driver-0.12/MANIFEST.SKIP0000644000175000017500000000006212020117676015062 0ustar andrewandrew#defaults ^Makefile$ ^blib/ ^pm_to_blib ^blibdirs LaTeX-Driver-0.12/scripts/0000755000175000017500000000000012020204470014642 5ustar andrewandrewLaTeX-Driver-0.12/scripts/latex2ps0000755000175000017500000000271610705227307016354 0ustar andrewandrew#!/usr/bin/perl -w #======================================================================== # # latex2ps # # DESCRIPTION # Script for processing and rendering a template document using the # Perl Template Toolkit. # # AUTHOR # Andrew Ford # # COPYRIGHT # Copyright (C) 2007 Andrew Ford. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #------------------------------------------------------------------------ # # $Id: latex2ps 59 2007-09-28 14:39:34Z andrew $ # #======================================================================== use strict; use warnings; use LaTeX::Driver::FilterProgram; LaTeX::Driver::FilterProgram->execute(format => 'dvi'); exit(0); __END__ =head1 NAME latex2ps - script to convert LaTeX file to PostScript =head1 SYNOPSIS latex2ps [OPTIONS] [-o output] [sourcefile] =head1 DESCRIPTION C is a simple script to invoke the C module to convert a LaTeX file to PostScript. TO BE EXPANDED =head1 AUTHOR Andrew Ford EA.Ford@ford-mason.co.ukE =head1 LICENSE AND COPYRIGHT Copyright (C) 2007 Andrew Ford. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: LaTeX-Driver-0.12/scripts/latex2dvi0000755000175000017500000000501110705227307016503 0ustar andrewandrew#!/usr/bin/perl -w #======================================================================== # # latex2dvi # # DESCRIPTION # Script for processing and rendering a template document using the # Perl Template Toolkit. # # AUTHOR # Andrew Ford # # COPYRIGHT # Copyright (C) 2007 Andrew Ford. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #------------------------------------------------------------------------ # # $Id: latex2dvi 73 2007-10-12 23:11:27Z andrew $ # #======================================================================== use strict; use warnings; use LaTeX::Driver::FilterProgram; LaTeX::Driver::FilterProgram->execute(format => 'dvi'); exit 0; __END__ =head1 NAME latex2dvi - script to convert LaTeX file to DVI =head1 USAGE latex2dvi [OPTIONS] [-o output] [sourcefile] =head1 DESCRIPTION C is a simple script to invoke the C module to convert a LaTeX file to DVI (TeX's device independent output format). TO BE EXPANDED =head1 REQUIRED ARGUMENTS =head1 OPTIONS =over 4 =item C<-output=FILE> specifies that the formatted file should be written to C. If this option is not specified, or is specified as "C<->" then the file will be written to standard output, otherwise if an input file is specified then the it will be formatted in place and the output file will have the same name as the input file, but with the original extension replaced with C<.dvi>. =item C<-tt2> specifies that the source document should be taken to be a Template Toolkit template and processed through that before being fed to the C module for latex formatting. =item C<-define=I=I> defines the template variable I to have the value I. Multiple template variables may be defined and these are passed to the Template Toolkit processing stage (they are ignored if the C<-tt2> option is not specified). =back =head1 DIAGNOSTICS =head1 EXIT STATUS =head1 CONFIGURATION =head1 DEPENDENCIES =head1 INCOMPATIBILITIES =head1 BUGS AND LIMITATIONS =head1 AUTHOR Andrew Ford EA.Ford@ford-mason.co.ukE =head1 LICENSE AND COPYRIGHT Copyright (C) 2007 Andrew Ford. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: LaTeX-Driver-0.12/scripts/latex2pdf0000644000175000017500000000270310705227307016474 0ustar andrewandrew#!/usr/bin/perl -w #======================================================================== # # latex2pdf # # DESCRIPTION # Script for processing and rendering a template document using the # Perl Template Toolkit. # # AUTHOR # Andrew Ford # # COPYRIGHT # Copyright (C) 2007 Andrew Ford. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #------------------------------------------------------------------------ # # $Id: latex2pdf 59 2007-09-28 14:39:34Z andrew $ # #======================================================================== use strict; use warnings; use LaTeX::Driver::FilterProgram; LaTeX::Driver::FilterProgram->execute(format => 'pdf'); exit(0); __END__ =head1 NAME latex2pdf - script to convert LaTeX file to PDF =head1 SYNOPSIS latex2pdf [OPTIONS] [-o output] [sourcefile] =head1 DESCRIPTION C is a simple script to invoke the C module to convert a LaTeX file to PDF. TO BE EXPANDED =head1 AUTHOR Andrew Ford EA.Ford@ford-mason.co.ukE =head1 LICENSE AND COPYRIGHT Copyright (C) 2007 Andrew Ford. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: LaTeX-Driver-0.12/scripts/README0000644000175000017500000000037110705227307015537 0ustar andrewandrewThe scripts in this directory provide classic Unix-style filters for LaTeX source to dvi, PostScript and PDF output. The functionality of the three scripts is virtually identical so it is abstracted out into a module: LaTeX::Driver::FilterProgram. LaTeX-Driver-0.12/lib/0000755000175000017500000000000012020204470013721 5ustar andrewandrewLaTeX-Driver-0.12/lib/LaTeX/0000755000175000017500000000000012020204470014676 5ustar andrewandrewLaTeX-Driver-0.12/lib/LaTeX/Driver.pm0000644000175000017500000011774612020204340016503 0ustar andrewandrew#======================================================================== # # LaTeX::Driver # # DESCRIPTION # Driver module that encapsulates the details of formatting a LaTeX document # # AUTHOR # Andrew Ford (current maintainer) # # COPYRIGHT # Copyright (C) 2009-2012 Ford & Mason Ltd. All Rights Reserved. # Copyright (C) 2006-2007 Andrew Ford. All Rights Reserved. # Portions Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # # HISTORY # * Added test for reruns required by longtable environments changing (AF, 2009-01-19) # # * Extracted from the Template::Latex module (AF, 2007-09-10) # # $Id: Driver.pm 86 2012-08-31 19:09:10Z andrew $ #======================================================================== package LaTeX::Driver; use strict; use warnings; use base 'Class::Accessor'; use Cwd; # from PathTools use English qw( -no_match_vars ); # standard Perl class use Exception::Class ( 'LaTeX::Driver::Exception' ); use File::Copy; # standard Perl class use File::Compare; # standard Perl class use File::Path; # standard Perl class use File::Slurp; use File::Spec; # from PathTools use IO::File; # from IO use Readonly; Readonly our $DEFAULT_MAXRUNS => 10; our $VERSION = 0.12; __PACKAGE__->mk_accessors( qw( basename basedir basepath options source output tmpdir format formatter preprocessors postprocessors _program_path maxruns extraruns stats texinputs_path undefined_citations undefined_references labels_changed rerun_required ) ); our $DEBUG; $DEBUG = 0 unless defined $DEBUG; our $DEBUGPREFIX; # LaTeX executable paths set at installation time by the Makefile.PL eval { require LaTeX::Driver::Paths }; our @PROGRAM_NAMES = qw(latex pdflatex bibtex makeindex dvips dvipdfm ps2pdf pdf2ps); our %program_path; $program_path{$_} = $LaTeX::Driver::Paths::program_path{$_} || "/usr/bin/$_" for @PROGRAM_NAMES; our @LOGFILE_EXTS = qw( log blg ilg ); our @TMPFILE_EXTS = qw( aux log lot toc bbl ind idx cit cbk ibk ); our $DEFAULT_TMPDIR = 'latexdrv'; our $DEFAULT_DOCNAME = 'latexdoc'; # valid output formats and program alias our $DEFAULT_FORMAT = 'pdf'; our %FORMATTERS = ( dvi => [ 'latex' ], ps => [ 'latex', 'dvips' ], postscript => [ 'latex', 'dvips' ], pdf => [ 'pdflatex' ], 'pdf(dvi)' => [ 'latex', 'dvipdfm' ], 'pdf(ps)' => [ 'latex', 'dvips', 'ps2pdf' ], 'ps(pdf)' => [ 'pdflatex', 'pdf2ps' ], ); #------------------------------------------------------------------------ # new(%options) # # Constructor for the Latex driver #------------------------------------------------------------------------ sub new { my $class = shift; my $options = ref $_[0] ? shift : { @_ }; my ($volume, $basedir, $basename, $basepath, $orig_ext, $cleanup); my ($formatter, @postprocessors); $DEBUG = $options->{DEBUG} || 0; $DEBUGPREFIX = $options->{DEBUGPREFIX} if exists $options->{DEBUGPREFIX}; # Sanity check first - check we're running on a supported OS $class->throw("not available on $OSNAME") if $OSNAME =~ m/ ^ ( MacOS | os2 | VMS ) $ /ix; # Examine the options - we need at least a source to work with and # it should be a scalar reference or a valid filename. my $source = delete $options->{source}; $class->throw("no source specified") unless $source; if (ref $source) { $class->throw("source is an invalid reference $source") if ref $source ne 'SCALAR'; } else { $source =~ s/ ( [.] tex ) $ //x; $orig_ext = $1; $class->throw("source file ${source}.tex does not exist") unless -f $source or -f "${source}.tex"; } # Determine how the document is to be processed. Either specified # explicitly in the format parameter or if an output file is # specified it is taken from that, or the default is take. my $output = $options->{output}; my $format = lc($options->{format}); if ($output and (!ref $output)) { my ($volume, $dir, $file) = File::Spec->splitpath($output); $class->throw("output directory $dir does not exist") unless $dir and -d $dir; if ((!$format) and ($file =~ / [.] ( \w+ ) $ /x)) { $format = lc($1); } } # There is a formatter and zero or more postprocessors for each # format; there are also special formats 'pdf(dvi)', 'pdf(ps)' and # 'ps(pdf)' that specify alternate routes to generate the format. $format ||= $DEFAULT_FORMAT; $class->throw("invalid output format: '$format'") unless exists $FORMATTERS{$format}; ($formatter, @postprocessors) = @{$FORMATTERS{$format}}; # discard the parenthesized part of special formats $format =~ s/\(.*\)//; # If a temporary directory was specified or the LaTeX source was # given as a scalar reference then a temporary directory is # created and the document source written to that directory or # copied in if the source is a file. my $tmpdir = $options->{tmpdir}; if ($tmpdir or ref $source) { $basedir = $class->_setup_tmpdir($tmpdir); $cleanup = 'rmdir' if ((!defined($tmpdir)) or ($tmpdir eq "1")); if (ref $source) { $basename = $DEFAULT_DOCNAME; $basepath = File::Spec->catfile($basedir, $basename); write_file($basepath . ".tex", $source) or $class->throw("cannot create temporary latex file"); } else { ($basename = $source) =~ s{.*/}{}; $basepath = File::Spec->catfile($basedir, $basename); copy("$source$orig_ext", "${basepath}.tex") or $class->throw("cannot copy $source$orig_ext to temporary directory"); $output ||= "${source}.$format"; } } # Otherwise the source was given as a filename, so the base name # and directory are taken from the source name. else { ($volume, $basedir, $basename) = File::Spec->splitpath($source); $basename =~ s/\.tex$//; if ($basedir and $volume) { $basedir = File::Spec->catfile($volume, $basedir); } $basedir ||= getcwd; $basedir =~ s{(.)/$}{$1}; $basepath = File::Spec->catfile($basedir, $basename); } # Set up a mapping of program name to full pathname. # This is initialized from the paths detemined at installation # time, but any specified in the paths option override these # values. $options->{paths} ||= {}; my $path = {}; map { $path->{$_} = $program_path{$_}; } @PROGRAM_NAMES; map { $path->{$_} = $options->{paths}->{$_}; } keys %{ $options->{paths} }; # Set up the texinputs path my $texinputs_path = $options->{TEXINPUTS} || $options->{texinputs} || []; $texinputs_path = [ split(/:/, $texinputs_path) ] unless ref $texinputs_path; # construct and return the object return $class->SUPER::new( { basename => $basename, basedir => $basedir, basepath => $basepath, format => $format, output => $output, cleanup => $cleanup || '', options => $options, maxruns => $options->{maxruns} || $DEFAULT_MAXRUNS, extraruns => $options->{extraruns} || 0, formatter => $formatter, _program_path => $path, texinputs_path => join(':', ('.', @{$texinputs_path}, '')), preprocessors => [], postprocessors => \@postprocessors, stats => { runs => {} } } ); } #------------------------------------------------------------------------ # run() # # Runs the formatter and other programs to generate the ouptut. #------------------------------------------------------------------------ sub run { my $self = shift; $DEBUG = $self->options->{DEBUG} || 0; # Check that the file exists $self->throw(sprintf('file %s.tex does not exist', $self->basepath)) unless -f $self->basepath . '.tex'; # Run any preprocessors (none specified yet). map { $self->$_ } @{$self->preprocessors}; # Run LaTeX and friends until an error occurs, the document # stabilizes, or the maximum number of runs is reached. my $maxruns = $self->maxruns; my $extraruns = $self->extraruns; RUN: foreach my $run (1 .. $maxruns) { if ($self->need_to_run_latex) { $self->run_latex; } else { if ($self->need_to_run_bibtex) { $self->run_bibtex; } elsif ($self->need_to_run_makeindex) { $self->run_makeindex; } else { last RUN if $extraruns-- < 0; } $run--; } } # Run any postprocessors (e.g.: dvips, ps2pdf, etc). foreach my $postproc (@{$self->postprocessors}) { my $method = $postproc; if ($self->can($method)) { $self->$method(); } else { $method = 'run_' . $postproc; if ($self->can($method)) { $self->$method(); } else { $self->throw("cannot find postprocessor $postproc"); } } } # Return any output $self->copy_to_output if $self->output; ; return 1; } #------------------------------------------------------------------------ # destructor # #------------------------------------------------------------------------ sub DESTROY { my $self = shift; debug('DESTROY called') if $DEBUG; $self->cleanup(); return; } #------------------------------------------------------------------------ # run_latex() # # Run the latex processor (latex or pdflatex depending on what is configured). #------------------------------------------------------------------------ sub run_latex { my $self = shift; my $basename = $self->basename; my $exitcode = $self->run_command($self->formatter => "\\nonstopmode\\def\\TTLATEX{1}\\input{$basename}"); # If an error occurred attempt to extract the interesting lines # from the log file. Even without errors the log file may contain # interesting warnings indicating that LaTeX or one of its friends # must be rerun. my $errors = ""; my $logfile = $self->basepath . ".log"; if (my $fh = IO::File->new($logfile, "r")) { $self->reset_latex_required; my $matched = 0; while ( my $line = <$fh> ) { debug($line) if $DEBUG >= 9; # TeX errors start with a "!" at the start of the # line, and followed several lines later by a line # designator of the form "l.nnn" where nnn is the line # number. We make sure we pick up every /^!/ line, # and the first /^l.\d/ line after each /^!/ line. if ( $line =~ /^(!.*)/ ) { $errors .= $1 . "\n"; $matched = 1; } elsif ( $matched && ($line =~ /^(l\.\d.*)/) ) { $errors .= $1 . "\n"; $matched = 0; } elsif ( $line =~ /^Output written on (.*) \((\d+) pages, (\d+) bytes\)./ ) { my ($ofile, $pages, $bytes) = ($1, $2, $3); $self->{stats}{pages} = $pages; $self->{stats}{bytes} = $bytes; } elsif ( $line =~ /^LaTeX Warning: Reference .*? on page \d+ undefined/ ) { $self->undefined_references(1); } elsif ( $line =~ /^LaTeX Warning: Citation .* on page \d+ undefined/ ) { debug('undefined citations detected') if $DEBUG; $self->undefined_citations(1); } elsif ( $line =~ /LaTeX Warning: There were undefined references./i ) { debug('undefined reference detected') if $DEBUG; $self->undefined_references(1) unless $self->undefined_citations; } elsif ( $line =~ /No file $basename\.(toc|lof|lot)/i ) { debug("missing $1 file") if $DEBUG; $self->undefined_references(1); } elsif ( $line =~ /^LaTeX Warning: Label\(s\) may have changed./i ) { debug('labels have changed') if $DEBUG; $self->labels_changed(1); } elsif ( $line =~ /^Package longtable Warning: Table widths have changed[.] Rerun LaTeX[.]/i) { debug('table widths changed') if $DEBUG; $self->rerun_required(1); } # A number of packages emit 'rerun' warnings (revtex4, # pdfmark, etc); this regexp catches most of those. elsif ( $line =~ /Rerun to get (.*) right/i) { debug("$1 changed") if $DEBUG; $self->rerun_required(1); } } } else { $errors = "failed to open $logfile for input"; } if ($exitcode or $errors) { $self->throw($self->formatter . " exited with errors:\n$errors"); } $self->stats->{runs}{formatter}++; return; } sub reset_latex_required { my $self = shift; $self->rerun_required(0); $self->undefined_references(0); $self->labels_changed(0); return; } sub need_to_run_latex { my $self = shift; my $auxfile = $self->basepath . '.aux'; return 1 if $self->undefined_references || $self->labels_changed || $self->rerun_required || ! -f $auxfile; return; } #------------------------------------------------------------------------ # run_bibtex() # # Run bibtex to generate the bibliography # bibtex reads references from the .aux file and writes a .bbl file # It looks for .bib file in BIBINPUTS and TEXBIB # It looks for .bst file in BSTINPUTS #------------------------------------------------------------------------ sub run_bibtex { my $self = shift; my $basename = $self->basename; my $exitcode = $self->run_command(bibtex => $basename, 'BIBINPUTS'); # TODO: extract meaningful error message from .blg file $self->throw("bibtex $basename failed ($exitcode)") if $exitcode; # Make a backup of the citations file for future comparison, reset # the undefined citations flag and mark the driver as needing to # re-run the formatter. my $basepath = $self->basepath; copy("$basepath.cit", "$basepath.cbk"); $self->undefined_citations(0); $self->rerun_required(1); return; } #------------------------------------------------------------------------ # $self->need_to_run_bibtex # # LaTeX reports 'Citation ... undefined' if it sees a citation # (\cite{xxx}, etc) and hasn't read a \bibcite{xxx}{yyy} from the aux # file. Those commands are written by parsing the bbl file, but will # not be seen on the run after bibtex is run as the citations tend to # come before the \bibliography. # # The latex driver sets undefined_citations if it sees the message, # but we need to look at the .aux file and check whether the \citation # lines match those seen before the last time bibtex was run. We # store the citation commands in a .cit file, this is copied to a cbk # file by the bibtex method once bibtex has been run. Doing this # check saves an extra run of bibtex and latex. #------------------------------------------------------------------------ sub need_to_run_bibtex { my $self = shift; if ($self->undefined_citations) { my $auxfile = $self->basepath . '.aux'; my $citfile = $self->basepath . '.cit'; my $cbkfile = $self->basepath . '.cbk'; my $auxfh = IO::File->new($auxfile, 'r') or return; my $citfh = IO::File->new($citfile, 'w') or $self->throw("failed to open $citfile for output: $!"); while ( my $line = <$auxfh> ) { print($citfh $line) if $line =~ /^\\citation/; } undef $auxfh; undef $citfh; return if -e $cbkfile and (compare($citfile, $cbkfile) == 0); return 1; } return; } #------------------------------------------------------------------------ # $self->run_makeindex() # # Run makeindex to generate the index # # makeindex has a '-s style' option which specifies the style file. # The environment variable INDEXSTYLE defines the path where the style # file should be found. # TODO: sanity check the indexoptions? don't want the caller # specifying the output index file name as that might screw things up. #------------------------------------------------------------------------ sub run_makeindex { my $self = shift; my $basename = $self->basename; my @args; if (my $stylename = $self->options->{indexstyle}) { push @args, '-s', $stylename; } if (my $index_options = $self->options->{indexoptions}) { push @args, $index_options; } my $exitcode = $self->run_command(makeindex => join(" ", (@args, $basename))); # TODO: extract meaningful error message from .ilg file $self->throw("makeindex $basename failed ($exitcode)") if $exitcode; # Make a backup of the raw index file that was just processed, so # that we can determine whether makeindex needs to be rerun later. my $basepath = $self->basepath; copy("$basepath.idx", "$basepath.ibk"); $self->rerun_required(1); return; } #------------------------------------------------------------------------ # $self->need_to_run_makeindex() # # Determine whether makeindex needs to be run. Checks that there is a # raw index file and that it differs from the backup file (if that exists). #------------------------------------------------------------------------ sub need_to_run_makeindex { my $self = shift; my $basepath = $self->basepath; my $raw_index_file = "$basepath.idx"; my $backup_file = "$basepath.ibk"; return unless -e $raw_index_file; return if -e $backup_file and (compare($raw_index_file, $backup_file) == 0); return 1; } #------------------------------------------------------------------------ # $self->run_dvips() # # Run dvips to generate PostScript output #------------------------------------------------------------------------ sub run_dvips { my $self = shift; my $basename = $self->basename; my $exitstatus = $self->run_command(dvips => "$basename -o"); $self->throw("dvips $basename failed ($exitstatus)") if $exitstatus; return; } #------------------------------------------------------------------------ # $self->run_ps2pdf() # # Run ps2pdf to generate PDF from PostScript output #------------------------------------------------------------------------ sub run_ps2pdf { my $self = shift; my $basename = $self->basename; my $exitstatus = $self->run_command(ps2pdf => sprintf("%s.ps %s.pdf", $basename, $basename)); $self->throw("ps2pdf $basename failed ($exitstatus)") if $exitstatus; return; } #------------------------------------------------------------------------ # $self->run_pdf2ps() # # Run ps2pdf to generate PostScript from PDF output #------------------------------------------------------------------------ sub run_pdf2ps { my $self = shift; my $basename = $self->basename; my $exitstatus = $self->run_command(pdf2ps => sprintf("%s.pdf %s.ps", $basename, $basename)); $self->throw("pdf2ps $basename failed ($exitstatus)") if $exitstatus; return; } #------------------------------------------------------------------------ # $self->run_command($progname, $config, $dir, $args, $env) # # Run a command in the specified directory, setting up the environment # and allowing for the differences between operating systems. #------------------------------------------------------------------------ sub run_command { my ($self, $progname, $args, $envvars) = @_; # get the full path to the executable for this output format my $program = $self->program_path($progname) || $self->throw("$progname cannot be found, please specify its location"); my $dir = $self->basedir; my $null = File::Spec->devnull(); my $cmd; $args ||= ''; # Set up localized environment variables in preparation for running the command # Note that the localized hash slice assignment of %ENV ensures that # the localization is done at the same block level as the system(). # Even doing something like local($ENV{$_}) = $val for @{$envvars} # puts the localization in a deeper level block so the previous value # is restored before the system() call is made. $envvars ||= "TEXINPUTS"; $envvars = [ $envvars ] unless ref $envvars; local(@ENV{@{$envvars}}) = map { $self->texinputs_path } @{$envvars}; # Format the command appropriately for our O/S if ($OSNAME eq 'MSWin32') { $cmd = "cmd /c \"cd $dir && $program $args\""; } else { $args = "'$args'" if $args =~ / \\ /mx; $cmd = "cd $dir; $program $args 1>$null 2>$null 0<$null"; } $self->stats->{runs}{$progname}++; debug("running '$program $args'") if $DEBUG; my $exitstatus = system($cmd); return $exitstatus; } #------------------------------------------------------------------------ # $self->copy_to_output # #------------------------------------------------------------------------ sub copy_to_output { my $self = shift; my $output = $self->output or return; # construct file name of the generated document my $file = $self->basepath . '.' . $self->format; if (ref $output) { $$output = read_file($file); } else { # see if we can rename the generated file to the desired output # file - this may fail, e.g. across filesystem boundaries (and # it's quite common for /tmp to be a separate filesystem if (rename($file, $output)) { debug("renamed $file to $output") if $DEBUG; } elsif (copy($file, $output)) { debug("copied $file to $output") if $DEBUG; } else { $self->throw("failed to copy $file to $output"); } } return; } #------------------------------------------------------------------------ # _setup_tmpdir($dirname) # # create a temporary directory #------------------------------------------------------------------------ sub _setup_tmpdir { my ($class, $dirname) = @_; my $tmp = File::Spec->tmpdir(); if ($dirname and ($dirname ne 1)) { $dirname = File::Spec->catdir($tmp, $dirname); eval { mkpath($dirname, 0, oct(700)) } unless -d $dirname; } else { my $n = 0; do { $dirname = File::Spec->catdir($tmp, "$DEFAULT_TMPDIR$$" . '_' . $n++); } while (-e $dirname); eval { mkpath($dirname, 0, oct(700)) }; } $class->throw("cannot create temporary directory: $@") if $@; debug(sprintf("setting up temporary directory '%s'\n", $dirname)) if $DEBUG; return $dirname; } #------------------------------------------------------------------------ # $self->cleanup # # cleans up the temporary files # TODO: work out exactly what this should do #------------------------------------------------------------------------ sub cleanup { my ($self, $what) = @_; my $cleanup = $self->{cleanup}; debug('cleanup called') if $DEBUG; if ($cleanup eq 'rmdir') { if ((!defined $what) or ($what ne 'none')) { debug('cleanup removing directory tree ' . $self->basedir) if $DEBUG; rmtree($self->basedir); } } return; } #------------------------------------------------------------------------ # $self->program_path($progname, $optional_value) # # #------------------------------------------------------------------------ sub program_path { my $class_or_self = shift; my $href = ref $class_or_self ? $class_or_self->{_program_path} : \%program_path; my $progname = shift; return @_ ? ($href->{$progname} = shift) : $href->{$progname}; } #------------------------------------------------------------------------ # throw($error) # # Throw an error message #------------------------------------------------------------------------ sub throw { my ($self, @args) = @_; LaTeX::Driver::Exception->throw( error => join('', @args) ); return; # not needed - but satisfies perlcritic } sub debug { my (@args) = @_; print STDERR $DEBUGPREFIX || "[latex] ", @args; print STDERR "\n" unless @args and ($args[-1] =~ / \n $ /mx); return; } 1; __END__ =head1 NAME LaTeX::Driver - Latex driver =head1 VERSION This document describes version 0.08 of C. =head1 SYNOPSIS use LaTeX::Driver; $drv = LaTeX::Driver->new( source => \$doc_text, output => $filename, format => 'pdf', %other_params ); $ok = $drv->run; $stats = $drv->stats; $drv->cleanup($what); =head1 DESCRIPTION The LaTeX::Driver module encapsulates the details of invoking the Latex programs to format a LaTeX document. Formatting with LaTeX is complicated; there are potentially many programs to run and the output of those programs must be monitored to determine whether further processing is required. This module runs the required commands in the directory specified, either explicitly with the C option or implicitly by the directory part of C, or in the current directory. As a result of the processing up to a dozen or more intermediate files are created. These can be removed with the C method. =head1 SUBROUTINES/METHODS =over 4 =item C This is the constructor method. It creates a driver object on which the C method is used to format the document specified. The main arguments are C and C; the C argument is required to specify the input document; C is only mandatory if C is a scalar reference. The full list of arguments is as follows: =over 4 =item C This parameter is mandatory; it can either specify the name of the document to be formatted or be a reference to a scalar containing the document source. =item C specifies the output for the formatted document; this may either be a file name or be a scalar reference. In the latter case the contents of the formatted document file is copied into the scalar variable referenced. =item C the format of output required: one of C<"dvi"> (TeX Device Independent format), C<"ps"> (PostScript) or C<"pdf"> (Adobe Portable Document Format). The follow special values are also accepted: C<"pdf(ps)"> (generates PDF via PostScript, using C and C), C<"pdf(dvi)"> (generates PDF via dvi, using C). If not specified then the format is determined from the name of the output document if specified, or defaults to PDF. =item C Specifies whether the formatting should be done in a temporary directory in which case the source document is copied into the directory before formatting. This option can either take the value 1, in which case a temporary directory is automatically generated, or it is taken as the name of a subdirectory of the system temporary directory. A temporary directory is always created if the source document is specified as a scalar reference. =item C Specifies a mapping of program names to full pathname as a hash reference. These paths override the paths determined at installation time. =item C The maximum number of runs of the formatter program (defaults to 10). =item C The number of additional runs of the formatter program after the document has stabilized. =item C Specifies whether temporary files and directories should be automatically removed when the object destructor is called. Accepted values are C (do no cleanup), C (remove log files) and C (remove log and temporary files). By default the destructor will remove the entire contents of any automatically generated temporary directory, but will leave all other files intact. =item C The name of a C index style file that should be passed to C. =item C Specifies additional options that should be passed to C. Useful options are: C<-c> to compress intermediate blanks in index keys, C<-l> to specify letter ordering rather than word ordering, C<-r> to disable implicit range formation. Refer to L for full details. =item C Specifies one or more directories to be searched for LaTeX files. =item C Enables debug statements if set to a non-zero value. =item C Sets the debug prefix, which is prepended to debug output if debug statements. By default there is no prefix. =back The constructor performs sanity checking on the options and will die if the following conditions are detected: =over 4 =item * no source is specified =item * an invalid format is specified =back The constructor method returns a driver object. =item C Format the document. =item C Returns a reference to a hash containing stats about the processing that was performed, containing the following items: =over 4 =item C number of pages in the formatted document =item C number of bytes in the formatted document =item C hash of the number of times each of the programs was run =back Note: the return value will probably become an object in a future version of the module. =item C Removes temporary intermediate files from the document directory and resets the stats. Not yet implemented =item C Get or set the path to the named program. Can be used as a class method to set the default path or as an object method to set the path for that instance of the driver object. =back There are a number of other methods that are used internally by the driver. Calling these methods directly may lead to unpredictable results. =over 4 =item C Runs the formatter (C or C). =item C Determines whether the formatter needs to be run. =item C Reset the flags that indicate whether latex needs to be re-run (invoked prior to each iteration of running any necessary commands). =item C Runs bibtex to generate the bibliography. =item C Determines whether bibtex needs to be run. =item C Runs makeindex to generate the index. =item C Determines whether makeindex needs to be run. =item C Runs dvips to generate postscript output from an intermediate C<.dvi> file. =item C Runs ps2pdf to generate PDF output from an intermediate PostScript file. =item C Runs pdf2ps to generate PostScript output from an intermediate PDF file. =item C Run a command in a controlled environment, allowing for operating system differences. =item C Copy the output to its final destination. =item C Throw an exception. =item C Print a debug message - the caller should test C<$DEBUG> to determine whether to invoke this function. =back =head1 DIAGNOSTICS The following errors may be detected by the constructor method. =over 4 =item not available on XXX The module is not supported on MacOS, OS/2 or VMS (or on a host of other operating systems but these are the only ones that are explicitly tested for). =item no source specified The C parameter should be specified as the name of a LaTeX source file or it should be a reference to a scalar variable holding the LaTeX source document. =item source is an invalid reference C is a reference, but not a reference to a scalar variable =item source file XXX.tex does not exist The source file specified does not exist =item output directory DIR does not exist An C parameter was specified as a scalar value, which was taken as the name of the output file, but the directory part of the path does not exist. =item invalid output format XXX An output format was specified, either explicitly or implicitly as the extension of the output file, but the output format specified is not supported. =item cannot create temporary directory The module could not create the temporary directory, which is used if the source is not specified as a filename, and the output is not to be left in the same directory as the source, or if a temporary directory name is specified explicitly. =item cannot create temporary latex file The module has determined that it needs to create a temporary file containing the source document but it cannot. =item cannot copy XXX.ext to temporary directory The module was trying to copy the specified source file to the temporary directory but couldn't. Perhaps you specified the temporary directory name explicitly but the directory does not exist or is not writable. =back The following errors may be detected when the driver's C method is called: =over 4 =item file XXX.tex does not exist The source file does not exist; it may have been removed between the time the constructor was called and the time that the driver was run. =item PROGRAM exited with errors: ERRORS The named program (C or C) exited with the errors listed. You may have errors in your source file. =item bibtex FILE failed (EXITCODE) The C program exited with errors. These are not fully parsed yet. =item failed to open BASEPATH.cit The driver generates its own temporary file listing the citations for a document, so that it can determine whether the citations have changed. This error indicates that it was unable to create the file. =item makeindex FILE failed (EXITCODE) The C program exited with errors. These are not fully parsed yet. =item dvips FILE failed (EXITCODE) The C program exited with errors. These are not fully parsed yet. =item ps2pdf FILE failed (EXITCODE) The C program exited with errors. These are not fully parsed yet. =item PROGNAME cannot be found, please specify its location The pathname for the specified program was not found in the modules configuration. The program may not have been found and the pathname not been explicitly specified when the module was installed. =item failed to copy FILE to OUTPUT The driver failed to copy the formatted file to the specified output location. =back =head1 CONFIGURATION AND ENVIRONMENT =head1 DEPENDENCIES C depends on latex and friends being installed. =head1 INCOMPATIBILITIES None known. =head1 BUGS AND LIMITATIONS This is beta software - there are bound to be bugs and misfeatures. If you have any comments about this software I would be very grateful to hear them; email me at Ea.ford@ford-mason.co.ukE. Among the things I am aware of are: =over 4 =item * I haven't worked out how I am going to deal with tex-related environment variables. =back =head1 FUTURE DIRECTIONS =over 4 =item * Look at how path variables could be specified to the filter (C, C, C, C, etc), and how these should interact with the system paths. =item * Investigate pre- and post-processors and other auxiliary programs. =back =head1 BACKGROUND This module has its origins in the original C filter that was part of Template Toolkit prior to version 2.16. That code was fairly simplistic; it created a temporary directory, copied the source text to a file in that directory, and ran either C or C on the file once; if postscript output was requested then it would run C after running C. This did not cope with documents that contained forward references, a table of contents, lists of figures or tables, bibliographies, or indexes. The current module does not create a temporary directory for formatting the document; it is given the name and location of an existing LaTeX document and runs the latex programs in the directory specified (the Template Toolkit plugin will be modified to set up a temporary directory, copy the source text in, then run this module, extract the output and remove the temporary directory). =head1 INTERNALS This section is aimed at a technical audience. It documents the internal methods and subroutines as a reference for the module's developers, maintainers and anyone interesting in understanding how it works. You don't need to know anything about them to use the module and can safely skip this section. =head2 Formatting with LaTeX or PDFLaTeX LaTeX documents can be formatted with C or C; the former generates a C<.dvi> file (device independent - TeX's native output format), which can be converted to PostScript or PDF; the latter program generates PDF directly. finds inputs in C, C, C, etc =head2 Generating indexes The standard program for generating indexes is C, is a general purpose hierarchical index generator. C accepts one or more input files (C<.idx>), sorts the entries, and produces an output (C<.ind>) file which can be formatted. The style of the generated index is specified by a style file (C<.ist>), which is found in the path specified by the C environment variable. An alternative to C is C, but that program is not widespread yet. =head2 Generating bibliographies with BiBTeX BiBTeX generates a bibliography for a LaTeX document. It reads the top-level auxiliary file (C<.aux>) output during the running of latex and creates a bibliography file (C<.bbl>) that will be incorporated into the document on subsequent runs of latex. It looks up the entries specified by \cite and \nocite commands in the bibliographic database files (.bib) specified by the \bibliography commands. The entries are formatted according to instructions in a bibliography style file (C<.bst>), specified by the \bibliographystyle command. Bibliography style files are searched for in the path specified by the C environment variable; for bibliography files it uses the C environment variable. System defaults are used if these environment variables are not set. =head2 Running Dvips The C program takes a DVI file produced by TeX and converts it to PostScript. =head2 Running ps2pdf The C program invokes Ghostscript to converts a PostScript file to PDF. =head2 Running on Windows Commands are executed with C. The syntax is: cmd /c "cd $dir && $program $args" This changes to the specified directory and executes the program there, without affecting the working directory of the the Perl process. Need more information on how to set environment variables for the invoked programs. =head2 Miscellaneous Information This is a placeholder for information not yet incorporated into the rest of the document. May want to mention the kpathsea library, the C program, the web2c TeX distribution, TeX live, tetex, TeX on Windows, etc. =head1 AUTHOR Andrew Ford Ea.ford@ford-mason.co.ukE =head1 LICENSE AND COPYRIGHT Copyright (C) 2009-2011 Ford & Mason Ltd. All Rights Reserved. Copyright (C) 2007 Andrew Ford. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L, L, L, L, L, The dvips manual There are a number of books and other documents that cover LaTeX: =over 4 =item * The LaTeX Companion =item * Web2c manual =back =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: LaTeX-Driver-0.12/lib/LaTeX/Driver/0000755000175000017500000000000012020204470016131 5ustar andrewandrewLaTeX-Driver-0.12/lib/LaTeX/Driver/FilterProgram.pm0000644000175000017500000001007310705227307021261 0ustar andrewandrew#============================================================= -*-perl-*- # # LaTeX::Driver::FilterProgram # # DESCRIPTION # Implements the guts of the latex2xxx filter programs # # AUTHOR # Andrew Ford # # COPYRIGHT # Copyright (C) 2007 Andrew Ford. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # # HISTORY # # $Id: Paths.pm 45 2007-09-28 10:33:19Z andrew $ #======================================================================== package LaTeX::Driver::FilterProgram; use strict; use warnings; use Carp; use LaTeX::Driver; use Getopt::Long; use File::Slurp; sub execute { my ($class, %options) = @_; my ($source, $output, $tt2mode, $debug, @vars, %var); GetOptions( 'output:s' => \$output, 'tt2mode' => \$tt2mode, 'define:s' => \@vars, 'debug' => \$debug ); if ( @ARGV ) { $source = shift @ARGV; } else { my $input = join '', ; $source = \$input; } if ($tt2mode) { eval { use Template; }; if ($@) { die "Cannot load the Template Toolkit - tt2 mode is unavailable\n"; } if (!ref $source) { ${$source} = read_file($source); } foreach (@vars) { my ($name, $value) = split / \s* = \s* /mx; printf(STDERR "defining %s as '%s'\n", $name, $value) if $debug; $var{$name} = $value; } my $input; my $tt2 = Template->new({}); $tt2->process($source, \%var, \$input) or die $tt2->error(), "\n"; $source = \$input; } if (!$output or $output eq '-') { my $tmp; $output = \$tmp; } eval { my $drv = LaTeX::Driver->new( source => $source, output => $output, format => $options{format} ); $drv->run; }; if (my $e = LaTeX::Driver::Exception->caught()) { $e->show_trace(1); # my $extra = sprintf("\nat %s line %d (%s)\n%s", $e->file, $e->line, $e->package, $e->trace); die $e; #sprintf("%s\n%s", "$e", $e->trace); } if (ref $output) { print ${$output}; } return; } 1; __END__ =head1 NAME LaTeX::Driver::FilterProgram =head1 VERSION =head1 SYNOPSIS use LaTeX::Driver::FilterProgram; LaTeX::Driver::FilterProgram->execute(format => $format); =head1 DESCRIPTION This module is not intended to be used except by the programs C, C and C that are included in the LaTeX::Driver distribution. It implements the guts of those filter programs. =head1 SUBROUTINES/METHODS =over 4 =item C This is the only method. It implements the guts of the filter programs, gathering the parameters for the C object constructor from the command line options, along with the options passed from the calling script, which should be the format option. Having constructed a driver object it then runs the driver. If the C<-tt2> option is specified then the source document is taken to be a Template Toolkit template and a Template object is constructed and the template processed through that before being fed to the C module for latex formatting. Template variables may defined with the C<-define> option and these are passed to the Template Toolkit processing stage (they are ignored if the C<-tt2> option is not specified). =back =head1 DIAGNOSTICS The module invokes the C module and optionally the C