Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LaTeX::Driver(3)      User Contributed Perl Documentation     LaTeX::Driver(3)

NAME
       LaTeX::Driver - Latex driver

VERSION
       1.1.1

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 <https://github.com/fordmason/LaTeX-Driver>

       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.

	       The following list of formats is	supported

	       o   dvi

	       o   ps

	       o   postscript

	       o   pdf

	       o   pdf(pdflatex)

	       o   pdf(xelatex)

	       o   pdf(lualatex)

	       o   pdf(dvi)

	       o   pdf(ps)

	       o   ps(pdf)

	       o   ps(pdflatex)

	       o   ps(xelatex)

	       o   ps(lualatex)

	   "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:

	   o   no source is specified

	   o   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 <a.ford@ford-mason.co.uk>.

       Among the things	I am aware of are:

       o   I haven't worked out	how I am going to deal with tex-related
	   environment variables.

FUTURE DIRECTIONS
       o   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.

       o   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
	  Chris	Travers	<chris.travers@gmail.com>  (current maintainer)

LICENSE	AND COPYRIGHT
	  Copyright (C)	2020  Erik Huelsmann.
	  Copyright (C)	2014  Chris Travers.
	  Copyright (C)	2009-2013 Ford & Mason Ltd.
	  Copyright (C)	2006-2007 Andrew Ford.
	  Portions Copyright (C) 1996-2006 Andy	Wardley.

       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:

       o   The LaTeX Companion

       o   Web2c manual

perl v5.32.1			  2020-07-29		      LaTeX::Driver(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | SOURCE | SUBROUTINES/METHODS | DIAGNOSTICS | CONFIGURATION AND ENVIRONMENT | DEPENDENCIES | INCOMPATIBILITIES | BUGS AND LIMITATIONS | FUTURE DIRECTIONS | BACKGROUND | INTERNALS | AUTHOR | LICENSE AND COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=LaTeX::Driver&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help