LaTeX::Driver(3pm)

📦
version 1.3.1 · 3 versions
, in ubuntu resolute, ubuntu stonking

💖 LaTeX::Driver — the LaTeX::Driver manual, but make it a group chat 💖

perl v5.8.0-ish era, User Contributed Perl Documentation ✨

🎀 NAME 🎀

LaTeX::Driver — bestie, it's a Latex driver. That's the whole name. Short, iconic, does what it says 💅

✨ VERSION ✨

1.3.1 🦋

🌸 SYNOPSIS 🌸

okay so this is literally the whole vibe in five lines:

use LaTeX::Driver;

$drv = LaTeX::Driver->new( source  => \$doc_text,
                           output  => $filename,
                           format  => 'pdf',
                           %other_params );
$ok    = $drv->run;
$stats = $drv->stats;

see? new, run, stats. that's the whole main character arc right there 🔥

💅 DESCRIPTION 💅

so LaTeX::Driver wraps up all the messy behind-the-scenes drama of calling the Latex programs to format a LaTeX document. like, formatting with LaTeX is genuinely complicated — there can be so many programs to run and you have to sit there watching their output to figure out if you need to run even more. it's giving "group project where nobody knows who's doing what" 😭

this module runs the commands it needs in the directory you specify — either you say it explicitly with the dirname option, or it's implied by the directory part of basename, or it just uses the current directory. and as a result of all that processing, up to a dozen or more intermediate files get created 🫶 those get removed when the object is destroyed, as long as you gave the cleanup argument to new.

🌈 SOURCE 🌈

source code lives at <https://github.com/fordmason/LaTeX-Driver>

feel free to fork and add your stuff! no gatekeeping here, bestie 💖

👑 SUBROUTINES/METHODS 👑

⭐ new(%params) ⭐

this is the constructor method. it builds you a driver object, and then you use the run method on that object to format the document you specified. the main arguments are source and output — source is required to say what the input document is, and output is only mandatory if source is a scalar reference.

the full list of arguments, no skips, no cuts, we don't do that here 🎀:

  • source — this parameter is mandatory. it can either be the name of the document to format, or a reference to a scalar that holds the document source itself. 💜
  • output — says where the formatted document goes. can be a file name, or a scalar reference. if it's a scalar reference, the contents of the formatted document file get copied into the scalar variable being referenced. ✨
  • format — the format of output you want. one of dvi (TeX Device Independent format), ps (PostScript) or pdf (Adobe Portable Document Format). and these special values are also accepted: pdf(ps) (makes PDF via PostScript, using dvips and ps2pdf), pdf(dvi) (makes PDF via dvi, using dvipdfm). if you don't specify it, the format gets figured out from the name of the output document if you gave one — otherwise it defaults to PDF.

the following list of formats is supported:

  • dvi
  • ps
  • postscript
  • pdf
  • pdf(pdflatex)
  • pdf(xelatex)
  • pdf(lualatex)
  • pdf(dvi)
  • pdf(ps)
  • ps(pdf)
  • ps(pdflatex)
  • ps(xelatex)
  • ps(lualatex)

thirteen formats, she contains multitudes 💅

  • tmpdir — says whether the formatting should happen in a temporary directory, in which case the source document gets copied in there before formatting. this option either takes the value 1, meaning a temporary directory gets automatically generated, or it's taken as the name of a subdirectory of the system temporary directory. oh and — a temporary directory is always created if the source document is given as a scalar reference. 📁
  • paths — a mapping of program names to full pathnames, as a hash reference. these paths override the paths that were determined at installation time. 🛠️
  • maxruns — the maximum number of runs of the formatter program. defaults to 10. 🔁
  • extraruns — how many additional runs of the formatter program happen after the document has stabilized. ✨
  • timeout — a timeout in seconds, within which any commands that get spawned should finish. ⏰
  • cleanup — 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 removes the entire contents of any automatically generated temporary directory, but leaves all other files intact. 🧹
  • indexstyle — the name of a makeindex index style file that should be passed to makeindex. 📚
  • indexoptions — additional options that should be passed to makeindex. useful ones are: -c to compress intermediate blanks in index keys, -l to specify letter ordering rather than word ordering, and -r to disable implicit range formation. refer to makeindex(1) for full details. 👑
  • texinputs — 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 gets prepended to debug output when there are debug statements. by default there's no prefix. 🎀

the constructor does sanity checking on the options and will die if it detects the following conditions 😭:

  • no source is specified
  • an invalid format is specified
🚨 bestie, seriously: no source = death. invalid format = death. the constructor does NOT play.

the constructor method returns a driver object. 🫶

🔥 run() 🔥

format the document. that's it. that's the whole job. go off, king 💅

🦋 "stderr" 🦋

holds the error output from subcommands — but only if the -capture_stderr option was passed to new(). 🙈

🌟 stats() 🌟

returns a reference to a hash containing stats about all the processing that was performed. it contains:

  • 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. so don't get too attached to the hash, bestie, it might glow up 👀

💜 program_path($program_name, $opt_value) 💜

get or set the path to the named program. you can use it as a class method to set the default path, or as an object method to set the path for that specific instance of the driver object. both, she's versatile ✨

there are a number of other methods that are used internally by the driver. calling these methods directly may lead to unpredictable results. ⚠️

fr fr, hands off these unless you know exactly what you're doing. unpredictable results is not a vibe.
  • run_latex — runs the formatter (latex or pdflatex).
  • need_to_run_latex — determines whether the formatter needs to be run.
  • reset_latex_required — resets 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.

okay that's part one bestie, breathe, hydrate, part two is coming 💧🌸

💅 DIAGNOSTICS 💅

ok bestie so this is the part where things can go 💀 but it's fine, it's fine, we just need to know what the errors mean. These first ones get caught by the constructor method:

  • not available on XXX — the module isn't supported on MacOS, OS/2 or VMS (and honestly probably a whole host of other operating systems too, but those three are the only ones that get explicitly tested for 🙈).
  • no source specified — you gotta hand over the source parameter!! It should be either the name of a LaTeX source file, or a reference to a scalar variable that's holding your LaTeX source document. Pick one, bestie.
  • source is an invalid reference — source is a reference, sure, but it's not a reference to a scalar variable. Wrong vibe, rejected.
  • source file XXX.tex does not exist — the source file you named just… isn't there. Nowhere. Not found. 😭
  • output directory DIR does not exist — you gave an output parameter as a scalar value (which got read as the output filename), but the directory part of that path doesn't exist. Rude of the path, honestly.
  • invalid output format XXX — an output format got specified, either explicitly or sneakily implied by the extension of your output file, and that format is just not supported. ✋
  • cannot create temporary directory — the module couldn't make the temp directory. It needs one when the source isn't given as a filename, and the output isn't meant to stay in the same directory as the source, or when a temporary directory name was explicitly specified.
  • cannot create temporary latex file — the module figured out it needs a temp file holding the source document and… just couldn't make it happen. 💀
  • cannot copy XXX.ext to temporary directory — it was trying to copy the specified source file into the temporary directory and couldn't. Maybe you specified the temp dir name explicitly but that directory doesn't exist or isn't writeable 👀.

And these next ones get caught when the driver's run() method is called:

  • file XXX.tex does not exist — the source file doesn't exist; it might've gotten removed between the moment the constructor ran and the moment the driver actually ran. Chaos.
  • PROGRAM exited with errors: ERRORS — the named program (latex or pdflatex) exited with the errors listed. You might have errors in your source file, bestie, check it 🫶.
  • 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 it can figure out whether the citations changed. This error means it couldn't create that file.
  • makeindex FILE failed (EXITCODE) — the makeindex program exited with errors. Not fully parsed yet.
  • dvips FILE failed (EXITCODE) — the dvips program exited with errors. Not fully parsed yet.
  • ps2pdf FILE failed (EXITCODE) — the ps2pdf program exited with errors. Not fully parsed yet.
  • PROGNAME cannot be found, please specify its location — the pathname for the specified program wasn't found in the module's configuration. The program may not have been found, and the pathname may not have been explicitly specified back when the module was installed.
  • failed to copy FILE to OUTPUT — the driver failed to copy the formatted file to the output location you specified.

🌈 CONFIGURATION AND ENVIRONMENT 🌈

When the using application configures Log::Any, this module will use it to log debug and trace level messages to the LaTeX::Driver category. Please note that the $DEBUG variable does not need to be set to enable this type of logging. And when this type of logging is enabled, the value of $DEBUG is just straight up ignored. periodt.

🔗 DEPENDENCIES 🔗

LaTeX::Driver depends on latex and friends being installed. The whole squad. 💫

🚫 INCOMPATIBILITIES 🚫

None known. slay.

🐛 BUGS AND LIMITATIONS 🐛

If you have any comments about this software I would be very grateful to hear them; please file your comments as issues at <https://github.com/Template-Toolkit-Latex/LaTeX-Driver/issues>. 💌

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 📜

ok so 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 ngl; 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. The way that it did not cope with documents that contained forward references, a table of contents, lists of figures or tables, bibliographies, or indexes… 😬 iconic behavior, honestly.

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. like genuinely, skip it if you want, no hard feelings 💖

🖋️ 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. Two paths, two vibes, both valid 💅

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. no cap.

👻 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 👑

Erik Huelsmann <erik@efficito.com> (current maintainer)

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:

  • The LaTeX Companion
  • Web2c manual

and that's a wrap bestie!! 🌸 this lil page is from perl v5.40.1 and it's dated 2026-01-25 — that's the LaTeX::Driver(3pm) footer btw, we're just saying it cute. now go format something gorgeous 💖✨🎀

📦 where this page comes from