/ 
TeX-AutoTeX-v0.906.0
River stage zero No dependents
/ TeX::AutoTeX

NAME

TeX::AutoTeX - automated processing of (La-)TeX sources

WARNING

TeX::AutoTeX::process will modify, overwrite, and delete files in the specified directory. It is assumed that directory is a temporary working directory and that the sources were copied from elsewhere for processing. Make sure you have copies of your files before attempting to run this module.

VERSION

see CVS revision number

SYNOPSIS

use TeX::AutoTeX;
my $t = TeX::AutoTeX->new( workdir => '/some/temp/directory',);
$t->process or warn 'processing failed';

A more elaborate example

use TeX::AutoTeX;

my $t = TeX::AutoTeX->new( workdir => '/some/temp/directory', verbose => 1,);
$t->{log} = TeX::AutoTeX::Log->new(
				   dir     => $t->{workdir},
				   verbose => $t->{verbose},
				   dupefh  => $t->{verbose} ? \*STDOUT : undef,
				  );
}
$t->{log}->open_logfile();
$t->set_dvips_resolution(600);
$t->set_stampref(['foobar paper', 'http://example.com/my/paper.pdf']);
if ($t->process()) {
  print "Success\n"
} else {
  print "Processing failed: inspect $t->{workdir}/auto_gen_ps.log\n";
}

DESCRIPTION

This module is the basis for arXiv's automatic (La-)TeX processing. The normal use is to point it at a directory with an assortment of files in it, and the process method will attempt to generated DVI, PostScript, or PDF from the input based on heuristics which have been developed and employed by arXiv for many years. The resulting file(s) remain in the same directory. It is up to the calling process to pre- or post-process the directory contents as required.

No particular naming conventions or other requirements are imposed on the source material, and sub-directories are permitted. The module attempts to determine processing order and input format based on file characteristics and heuristics and generally does not require any user input.

Note that arXiv does not allow execution of external programs from TeX or dvips (paranoid setting in texmf.cnf), and that neither makeindex or bibtex or similar intermediate programs are run. These are deliberate choices. Consequently this module doesn't provide that functionality either.

METHODS

The main purpose of TeX::AutoTeX is to create an instance for a given source directory, set attributes relevant for processing and then call process to do the work.

new

new( workdir => <directory_name>, ) instantiates a TeX::AutoTeX object with default settings. The single required argument is the workdir, which is the directory in which the source material can be found and processed.

All other attributes outlined below can be set, i.e. defaults can be overwritten, via a hashref passed to new.

process

This is the main method of a TeX::AutoTeX object. It will start the processing and perform the format conversion according to the object's attributes. process itself does not take any parameters.

process returns 1 on success and undef on failure.

email

sends email about a failure to the recipient for such messages configured in $TeX::AutoTeX::Config::MAIL_FAILURES_ADDRESS

OPTIONS

These are simple (get|set)_accessors for attributes and flags

workdir

get/set the directory in which the source material will be processed.

Note that processing typically is done in a chroot jail, and the processing directory should be inside that jail.

branch

get/set the branch, e.g. the TeX installation, input tree(s), etc. This allows to select between various TeX installations or texmf input trees. It is a path based selection of the top level directory and associated texmf.cnf file. At arXiv we have e.g. teTeX/2/texmf-2003 teTeX/2/texmf-2004 teTeX/3/texmf-2006. This method should be overloaded with custom selection settings to reflect local directory hierarchies. Something along the lines of

if (!$self->{branch}) { # use the latest branch, unless specified otherwise
  $self->{branch} = '3';
  $ENV{TEXMFCNF} = '/3/texmf/web2c';
  $self->{tex_env_path} =  '/3/bin:/bin';
}

The example above reflects arXiv's use of PATH settings relative to a chroot root directory.

(get|set)_tex_env_path

get or set the $ENV{PATH} value for system calls, defaults to /$branch/bin:/bin. This allows for branch based path variations like /2/bin, /3/amd64/bin, /texlive/x86_64/bin depending on available local tex trees

use_stamp

get/set flag to enable or disable stamping of the first page. This is a simple on/off switch. (default 1)

stampref

get/set the array ref holding the text of the stamp and the URL to hyperlink on the first page. At arXiv the values are derived from the item identifier and local link structure.

log

get/set the TeX::AutoTeX::Log object for logging of warnings/errors. The default is to instantiate a TeX::AutoTeX::Log object with the default logfile, auto_gen_ps.log, and if set verbose logging to STDOUT.

verbose

get/set flag to enable verbose logging to the logfile specified in the TeX::AutoTeX::Log object and STDOUT. This is a simple on/off switch. (default 0)

send_email

get/set flag to send email alerts about processing problems to addresses specified in TeX::AutoTeX::Config. This is a simple on/off switch. (default 0)

dvips_paper_type

get/set the dvips -t command line flag for papertype selection. The main use of this flag is the "landscape" option, since other document layout decisions should be taken in the source. arXiv in particular distinguishes between US letter size paper as the default latex and dvips option on North American sites, and A4 paper on all other sites. This affects macro packages, etc, via .cfg files (hyperref.cfg, geometry.cfg) or explicit modification, and dvips' global config.ps.

dvips_resolution

get/set the target resolution (dpi) for dvips (-D command line option of dvips), valid options are 300, 400, 600. (default 600)

dvips_printer

get/set the dvips printer type (-P command line option of dvips), relevant for font creation and selection. (default none, valid choices type1, pdf). The default metafont mode and associated resolution are configured in the TeX installation. The main use of this option is to generate PostScript with type1 fonts for PDF generation. (default none)

dvips_mapfile

get/set the name of a custom fontmap. If the sources contain private font files and associated macros, this option can be used to pass an additional font map file to dvips via the -u dvips command line option, so that dvips can resolve those font references (default none)

output_format

get/set the output format. This is typically derived from other dvips flags, in particular resolution and printer option and allows calling applications to distinguish between various types of generated PostScript, e.g. 300 dpi bitmap, 600 dpi bitmap, PostScript with outline (type1) fonts, uncompressed PostScript or Postscript for a particular paper type (A4, letter, landscape) (default none)

EXIT STATUS

The main method, process returns 1 on success and undef if there was a processing error. The log file will have more information on the error in this case.

In addition there may be fatal errors in system calls etc.. These will croak.

DIAGNOSTICS

Enable verbose logging for lots of informative messages, and look at the log file (default auto_gen_ps.log)

CONFIGURATION AND ENVIRONMENT

Most of the configuration is taken from TeX::AutoTeX::Config. Influencing the TeX process via environment variables is not encouraged.

TeX::AutoTeX::Config must be customized and adapted to local requirements before use.

DEPENDENCIES

Class::Accessor::Fast

This module relies on access to a complete TeX installation. A recent TeXLive distribution should be sufficient to get started, however in the scholarly publication realm a lot of additional macro packages from publishers and societies may need to be added to a local texmf tree.

TeX::AutoTeX::Config holds all of the necessary configuration and customization. This module will not work without proper settings in the config file.

arXiv::FileGuess is required for contents based file type determination. This could be mostly substituted for by one of File::Type File::MimeInfo::Magic or File::LibMagic.

BUGS AND LIMITATIONS

Let us know http://arxiv.org/help/contact

HISTORY

AutoTeX automatic TeX processing system
Copyright (C) 1994-2006 arXiv.org and contributors

AutoTeX is supplied under the GNU Public License and comes
with ABSOLUTELY NO WARRANTY; see COPYING for more details.

AutoTeX is an automatic TeX processing system designed to
process TeX/LaTeX/AMSTeX/etc source code of papers submitted
to the arXiv.org (nee xxx.lanl.gov) e-print archive. The
portable part of this code has been extracted and is made
available in the hope that it will be useful to other projects
and that the input of others will benefit arXiv.org.

Code developed and contributed to by Tanmoy Bhattacharya, Rob
Hartill, Mark Doyle, Thorsten Schwander, and Simeon Warner.
Refactored to separate generic code from arXiv.org specific code
by Stephen Marsh, Michael Fromerth, and Simeon Warner 2005/2006.

Major cleanups and algorithmic improvements/corrections by
Thorsten Schwander 2006 - 2011

AUTHOR

Thorsten Schwander for arXiv.org

LICENSE AND COPYRIGHT

Copyright (c) 2008 - 2011 arxiv.org http://arxiv.org/help/contact

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.