LaTeX::CatSuit

                             Version 0.11

                            25 November 2011

          Copyright (C) 2011 Jerome Eteve. All rights Reserved
        Copyright (C) 2009 Ford & Mason Ltd.  All Rights Reserved
           Copyright (C) 2007 Andrew Ford.  All Rights Reserved

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

              $Id: README 80 2009-01-19 13:42:25Z andrew $


I welcome any and all feedback - Andrew <a.ford@ford-mason.co.uk> / jerome.eteve@gmail.com

Please drop me an email if you use this module - I would be interested
to hear if anyone is actually using it.




DESCRIPTION
-----------

The LaTeX::CatSuit module takes care of running and re-running latex on
a LaTeX document so that forward references, tables of contents, and
lists of figures and tables are resolved.  It will also run bibtex and
makeindex if it detects that a bibliography or in index have been
specified, and will re-run latex again one or more times until the
formatting of the document has stabilized.

The code was in part derived from the Template Toolkit Latex plugin
and patches I had written for Template Toolkit before the Latex plugin
was forked off from the main TT distribution.  It was also inspired by
the latexn C Shell script and the latexmk script by John Collins, both
of which are on CTAN (the Comprehensive TeX Archive Network).


QUICK START
-----------

The latest version of the LaTeX::CatSuit module can be retrieved from:

    http://www.cpan.org/modules/by-module/LaTeX-CatSuit/

To install the module

    tar zxf LaTeX-CatSuit-0.06.tar.gz
    cd LaTeX-CatSuit-0.06
    perl Makefile.PL
    make
    make test
    make install    

The Makefile.PL will prompt for the location of the LaTeX binaries. If
it can locate the binaries then the paths will be given as defaults.
If neither the latex nor the pdflatex binary can be found and no paths
are given for these programs then Makefile.PL will ask whether you
want to continue with the installation (as the module depends on there
being a functional tex installation present on the system).

For further details on installation, see the separate INSTALL file.


WHAT'S NEW?
-----------

Version 0.11 adds the capture_stderr option, allowing you
to examine the STDERR of your LaTeX run.

Version 0.09 adds better diagnostic of LaTeX commands error
if they fail even before any log output. It also adds a timeout
option to avoid long runs.

Version 0.08 adds checks for documents that use the 'longtable'
package and other packages that can require latex reruns without
necessarily changing labels.  It also exposes the page count (and the
byte count) in the statistics hash.

Version 0.07 is the latest in a series of incremental improvements
that aims to stabilize the interface.

Version 0.01 is a new module.  It was factored out of Template-Latex,
which itself was created by moving the code out of the core Template
Toolkit distribution (version 2.15).

See the Changes file for further details of the changes in these
releases.


GENERAL FEATURES
----------------

Some of the key features of the LaTeX::CatSuit module are listed below.

The module is invoked like this:

    $drv = LaTeX::CatSuit->new( source  => $source,
			       output  => $output,
			       format  => 'pdf', # or 'dvi' or 'ps'
			       maxruns => 8, 
			       extraruns  => 1,
			       indexstyle => 'myindexstyle.ist',
			       texinputs  => \@latex_dirs );
    $drv->run();

The constructor creates a driver object that is run with $drv->run.

The source document is specified by the "source" argument, which can
be a filename or a reference to a scalar containing the document
source.  The other arguments are optional in most circumstances, with
sensible defaults.  An exception is that if the source is specified as
a scalar reference then the output must be specified (as the driver
has no filename to work with); the output may be either a filename or
another scalar reference into which the output document will be copied.

Three programs are included "latex2pdf", "latex2ps" and "latex2dvi",
which will take a LaTeX document and transform it into the respective
output format.  With the -tt2mode option the input is taken to be a
Template Toolkit template and the document content is processed by the
Template Toolkit (if it is installed) before being processed as a
LaTeX document.  The -define=name=value option allows variables to be
defined that are passed to the Template Toolkit.  The -define option
can be specified multiple times.  NOTE: THESE SCRIPTS ARE STILL ALPHA QUALITY.


See the documentation for further detail.


DOCUMENTATION
-------------

The 'Changes' file in the distribution directory documents all visible
changes between versions of the Template Toolkit.  See the section 
'VERSION COMPATABILITY' below for further details.

The 'TODO' file, also in the distribution directory, lists known bugs,
planned enhancements and possible new features for future versions.

The rest of the documentation is distributed in Pod and HTML formats.
The Pod pages are installed when you 'make install' and can be viewed
using 'perldoc', e.g. 'perldoc LaTeX::CatSuit'.


SUPPORT
-------

Currently the only support is direct from the author.



AUTHOR
------

This module has been forked from the original LaTeX::Driver.

LaTeX::Driver was originally written by Andrew Ford <a.ford@ford-mason.co.uk>.

It borrows from the Template Toolkit distribution by Andy Wardley
<abw@wardley.org> with the assistance and contributions from many
other people. In 2006 the Latex plugin was separated out into its own
distribution and Andrew Ford <a.ford@ford-mason.co.uk> took over as
maintainer.  He created this module as part of the refactoring of
Template-Latex.



COPYRIGHT
---------

Copyright (C) 2011 Jerome Eteve. All Rights Reserved.
Copyright (C) 2007 Andrew Ford.   All Rights Reserved.
Portions Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.

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