LaTeX-Driver-0.300.2/0000755000175000017500000000000012706223711013065 5ustar chrischrisLaTeX-Driver-0.300.2/README0000644000175000017500000004054612706223707013763 0ustar chrischrisNAME LaTeX::Driver - Latex driver VERSION This document describes version 0.200.4 of "LaTeX::Driver". 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); 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 "dirname" option or implicitly by the directory part of "basename", 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 "cleanup" method. SOURCE Source code can be found at Feel free to fork and add your stuff! SUBROUTINES/METHODS "new(%params)" This is the constructor method. It creates a driver object on which the "run" method is used to format the document specified. The main arguments are "source" and "output"; the "source" argument is required to specify the input document; "output" is only mandatory if "source" is a scalar reference. The full list of arguments is as follows: "source" 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. "output" 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. "format" the format of output required: one of "dvi" (TeX Device Independent format), "ps" (PostScript) or "pdf" (Adobe Portable Document Format). The follow special values are also accepted: "pdf(ps)" (generates PDF via PostScript, using "dvips" and "ps2pdf"), "pdf(dvi)" (generates PDF via dvi, using "dvipdfm"). If not specified then the format is determined from the name of the output document if specified, or defaults to PDF. "tmpdir" 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. "paths" Specifies a mapping of program names to full pathname as a hash reference. These paths override the paths determined at installation time. "maxruns" The maximum number of runs of the formatter program (defaults to 10). "extraruns" The number of additional runs of the formatter program after the document has stabilized. "timeout" Specifies a timeout in seconds within which any commands spawned should finish. "cleanup" Specifies whether temporary files and directories should be automatically removed when the object destructor is called. Accepted values are "none" (do no cleanup), "logfiles" (remove log files) and "tempfiles" (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. "indexstyle" The name of a "makeindex" index style file that should be passed to "makeindex". "indexoptions" Specifies additional options that should be passed to "makeindex". Useful options are: "-c" to compress intermediate blanks in index keys, "-l" to specify letter ordering rather than word ordering, "-r" to disable implicit range formation. Refer to makeindex(1) for full details. "texinputs" Specifies one or more directories to be searched for LaTeX files. "DEBUG" Enables debug statements if set to a non-zero value. "DEBUGPREFIX" Sets the debug prefix, which is prepended to debug output if debug statements. By default there is no prefix. The constructor performs sanity checking on the options and will die if the following conditions are detected: * no source is specified * an invalid format is specified The constructor method returns a driver object. "run()" Format the document. "stderr" Holds the error output from subcommands, if the "-capture_stderr" option was passed to "new()". "stats()" Returns a reference to a hash containing stats about the processing that was performed, containing the following items: "pages" number of pages in the formatted document "bytes" number of bytes in the formatted document "runs" hash of the number of times each of the programs was run Note: the return value will probably become an object in a future version of the module. "cleanup($what)" Removes temporary intermediate files from the document directory and resets the stats. Not yet implemented "program_path($program_name, $opt_value)" 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. There are a number of other methods that are used internally by the driver. Calling these methods directly may lead to unpredictable results. "run_latex" Runs the formatter ("latex" or "pdflatex"). "need_to_run_latex" Determines whether the formatter needs to be run. "reset_latex_required" Reset the flags that indicate whether latex needs to be re-run (invoked prior to each iteration of running any necessary commands). "run_bibtex" Runs bibtex to generate the bibliography. "need_to_run_bibtex" Determines whether bibtex needs to be run. "run_makeindex" Runs makeindex to generate the index. "need_to_run_makeindex" Determines whether makeindex needs to be run. "run_dvips" Runs dvips to generate postscript output from an intermediate ".dvi" file. "run_ps2pdf" Runs ps2pdf to generate PDF output from an intermediate PostScript file. "run_pdf2ps" Runs pdf2ps to generate PostScript output from an intermediate PDF file. "run_command" Run a command in a controlled environment, allowing for operating system differences. "copy_to_output" Copy the output to its final destination. "throw" Throw an exception. "debug" Print a debug message - the caller should test $DEBUG to determine whether to invoke this function. DIAGNOSTICS The following errors may be detected by the constructor method. 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). no source specified The "source" 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. source is an invalid reference "source" is a reference, but not a reference to a scalar variable source file XXX.tex does not exist The source file specified does not exist output directory DIR does not exist An "output" 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. 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. 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. cannot create temporary latex file The module has determined that it needs to create a temporary file containing the source document but it cannot. 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 writeable. The following errors may be detected when the driver's "run()" method is called: 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. PROGRAM exited with errors: ERRORS The named program ("latex" or "pdflatex") exited with the errors listed. You may have errors in your source file. bibtex FILE failed (EXITCODE) The "bibtex" program exited with errors. These are not fully parsed yet. 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. makeindex FILE failed (EXITCODE) The "makeindex" program exited with errors. These are not fully parsed yet. dvips FILE failed (EXITCODE) The "dvips" program exited with errors. These are not fully parsed yet. ps2pdf FILE failed (EXITCODE) The "ps2pdf" program exited with errors. These are not fully parsed yet. 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. failed to copy FILE to OUTPUT The driver failed to copy the formatted file to the specified output location. CONFIGURATION AND ENVIRONMENT DEPENDENCIES "LaTeX::Driver" depends on latex and friends being installed. INCOMPATIBILITIES None known. 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 . Among the things I am aware of are: * I haven't worked out how I am going to deal with tex-related environment variables. FUTURE DIRECTIONS * 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. * Investigate pre- and post-processors and other auxiliary programs. BACKGROUND This module has its origins in the original "latex" 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 "latex" or "pdflatex" on the file once; if postscript output was requested then it would run "dvips" after running "latex". 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). 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. Formatting with LaTeX or PDFLaTeX LaTeX documents can be formatted with "latex" or "pdflatex"; the former generates a ".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 "TEXINPUTS", "TEXINPUTS_latex", "TEXINPUTS_pdflatex", etc Generating indexes The standard program for generating indexes is "makeindex", is a general purpose hierarchical index generator. "makeindex" accepts one or more input files (".idx"), sorts the entries, and produces an output (".ind") file which can be formatted. The style of the generated index is specified by a style file (".ist"), which is found in the path specified by the "INDEXSTYLE" environment variable. An alternative to "makeindex" is "xindy", but that program is not widespread yet. Generating bibliographies with BiBTeX BiBTeX generates a bibliography for a LaTeX document. It reads the top-level auxiliary file (".aux") output during the running of latex and creates a bibliography file (".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 (".bst"), specified by the \bibliographystyle command. Bibliography style files are searched for in the path specified by the "BSTINPUTS" environment variable; for bibliography files it uses the "BIBINPUTS" environment variable. System defaults are used if these environment variables are not set. Running Dvips The "dvips" program takes a DVI file produced by TeX and converts it to PostScript. Running ps2pdf The "ps2pdf" program invokes Ghostscript to converts a PostScript file to PDF. Running on Windows Commands are executed with "cmd.exe". 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. 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 "kpsewhich" program, the web2c TeX distribution, TeX live, tetex, TeX on Windows, etc. AUTHOR Andrew Ford 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. SEE ALSO Template::Plugin::Latex, latex(1), makeindex(1), bibtex(1), dvips(1), The dvips manual There are a number of books and other documents that cover LaTeX: * The LaTeX Companion * Web2c manual LaTeX-Driver-0.300.2/TODO0000644000175000017500000000555512704232647013575 0ustar chrischris#================================================== -*- 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 #------------------------------------------------------------------------ * Win32 support * Path tests need to be reworked * get the filter working on Win32 (how does one set environment variables with command.exe?) * Add plugin model * 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. * 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.300.2/Makefile.PL0000644000175000017500000000174412704232647015053 0ustar chrischris#!/usr/bin/perl -w # -*- perl -*- use inc::Module::Install 0.91; use Module::Install::ReadmeFromPod; use Module::Install::AuthorRequires; use Module::Install::AuthorTests; license 'perl'; all_from 'lib/LaTeX/Driver.pm'; readme_from 'lib/LaTeX/Driver.pm'; requires_external_bin 'latex'; requires 'Class::Accessor'; requires 'Cwd'; requires 'Exception::Class'; requires 'File::Slurp'; requires 'File::Spec'; requires 'Getopt::Long'; requires 'IO::File'; requires 'parent'; requires 'Readonly'; requires 'File::pushd'; requires 'Capture::Tiny'; test_requires 'Test::More' => '0.88'; author_requires 'Test::NoTabs'; author_requires 'Test::Pod' => '1.14'; author_requires 'Test::Pod::Coverage' => '1.04'; author_requires 'Test::Spelling' => '0.11'; install_script 'latex2dvi'; install_script 'latex2pdf'; install_script 'latex2ps'; author_tests 'xt'; resources repository => 'https://github.com/Template-Toolkit-Latex/LaTeX-Driver.git'; WriteAll; LaTeX-Driver-0.300.2/Changes0000644000175000017500000001037012706223677014374 0ustar chrischrisRevision history for the LaTeX::Driver module -*- indented-text -*- 0.300.2 2016-04-21 - Added ps support via pdflatex 0.300.1 2016-04-17 - Added ps support for xelatex 0.300.0 2016-04-16 - Fix 0.20 refactoring made stdout 'bleed' into caller's stdout - Add more formats for explicit processor (pdf|xe)latex selection - Win32 fixes 0.200.4 2014-04-12 - Disabled bibtex tests by default due to frequently not found LaTex sty not found. - Disabled t/30 and t/31 unless dvips is found 0.200.3 2014-04-11 - xelatex tests now optional because they add too many external dependencies 0.200.1 2014-04-10 - Fixed stale dependency (unused) in Test::LaTeX::Driver 0.20 2014-04-09 - Removed IPC::ShellCmd dependency since newer versions not on CPAN - Fixed Win32 support 0.20_03 2013-10-31 - switched Makefile.PL to Module::Install 0.20_02 2013-10-29 - added -timeout option (requires IPC::ShellCmd 0.003) - added -capture_stderr option and stderr() method to retrieve captured stderr 0.20_01 2013-10-18 - Now maintained on github - reformatted Changes file - removed MYMETA.{json,yml} from MANIFEST and added to MANIFEST.SKIP (RT89155) - use IPC::ShellCmd to run commands - remove LaTeX::Driver::Paths - paths determined at runtime 0.12 2012-08-31 - fixed typo in settings of ps2pdf/pdf2ps (RT79233) - add missing dependency on Readonly (RT79330) 0.11 2012-08-30 - rewrote loop in run_latex() and need_to_run_bibtex() to use a lexical variable to avoid subtle errors with Template::Plugin::Latex (RT50684) 0.10 2011-09-18 - use system tmp directory rather than hardcoded /tmp - Makefile.PL exits if latex binary is not found (rather than dieing 0.09 2011-08-18 - Tidied up for perlcritic 0.08 2009-01-19 - Added two elements to the stats hash - 'pages' and 'bytes' - Added check for rerun required by use of the longtable package (patch submitted by Yitzchack Scott-Thoennes - cpan id: YSTM), also added test script - also check for generic /rerun to get .* right/ warning - expand documentation for Pod::Coverage 0.07 2007-10-12 - Updated documentation - specifically the diagnostics section for LaTeX::Driver and just expanded LaTeX::Driver::FilterProgram - fixed Makefile.PL, which was using LaTeX::Driver to get the module version, but this broke horribly if the prerequisite modules were not installed. - added missing test and test data files to MANIFEST 0.06 2007-09-27 - rationalized the constructor arguments - now the source and output are controlled just by three arguments: "source" and optionally "output" and "format". - the "source" and "output" parameters can be scalar references, in which case the LaTeX source and formatted output is taken from or output to the variables referenced respectively. This facilitates the creation of Unix filter type scripts. - added the Unix-style filter programs latex2dvi, latex2pdf and latex2ps (these use the common module LaTeX::Driver::FilterProgram) 0.05 2007-09-25 - default output type is now 'pdf' (that is probably what most people are going to want to generate) - added texinputs option - added the following methods: latex_path, pdflatex_path, bibtex_path, makeindex_path, dvips_path, dvipdfm_path, ps2pdf_path and program_path - the program path defaults are now stored in a package-level hash 0.04 2007-09-24 - Expanded documentation a bit more - added option parsing to test library so that test scripts can be run with -d to switch on debug messages - added basic Exception::Class based exceptions (still need to differentiate between exception types. 0.03 2007-09-24 - Expanded documentation - Reorganized testdata so that the directories/files match the names of the test scripts that use them - Added tests for constructor errors, running the module on broken LaTeX files, specifying options to makeindex, and quality metrics 0.02 2007-09-21 - First public release. 0.01 2007-09-20 - Initial version. Code extracted from the Template-Latex distribution. New maintainer: Andrew Ford. LaTeX-Driver-0.300.2/lib/0000755000175000017500000000000012706223711013633 5ustar chrischrisLaTeX-Driver-0.300.2/lib/LaTeX/0000755000175000017500000000000012706223711014610 5ustar chrischrisLaTeX-Driver-0.300.2/lib/LaTeX/Driver/0000755000175000017500000000000012706223711016043 5ustar chrischrisLaTeX-Driver-0.300.2/lib/LaTeX/Driver/FilterProgram.pm0000644000175000017500000001007312704232647021165 0ustar chrischris#============================================================= -*-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