NAME
perltex - enable LaTeX macros to be defined in terms of Perl code
SYNOPSIS
perltex
[--help]
[--latex=program]
[--[no]safe]
[--permit=feature]
[latex options]
DESCRIPTION
LaTeX through the underlying TeX typesetting system produces
beautifully typeset documents but has a macro language that is
difficult to program. In particular, support for complex string
manipulation is largely lacking. Perl is a popular general-purpose
programming language whose forte is string manipulation. However, it
has no typesetting capabilities whatsoever.
Clearly, Perl's programmability could complement LaTeX's typesetting
strengths. perltex is the tool that enables a symbiosis between
the two systems. All a user needs to do is compile a LaTeX document
using perltex instead of latex. (perltex is actually a
wrapper for latex, so no latex functionality is lost.) If the
document includes a CW\usepackage{perltex} in its preamble, then
CW\perlnewcommand and CW\perlrenewcommand macros will be made
available. These behave just like LaTeX's CW\newcommand and
CW\renewcommand except that the macro body contains Perl code instead
of LaTeX code.
OPTIONS
perltex accepts the following command-line options:
"--help"
Display basic usage information.
"--latex=program"
Specify a program to use instead of latex. For example,
CW--latex=pdflatex would typeset the given document using
pdflatex instead of ordinary latex.
"--[no]safe"
Enable or disable sandboxing. With the default of CW--safe,
perltex executes the code from a CW\perlnewcommand or
CW\perlrenewcommand macro within a protected environment that
prohibits ``unsafe'' operations such as accessing files or executing
external programs. Specifying CW--nosafe gives the LaTeX document
carte blanche to execute any arbitrary Perl code, including that
which can harm the user's files. See Safe for more information.
"--permit=feature"
Permit particular Perl operations to be performed. The CW--permit
option, which can be specified more than once on the command line,
enables finer-grained control over the perltex sandbox. See
Opcode for more information.
These options are then followed by whatever options are normally
passed to latex (or whatever program was specified with
CW--latex), including, for instance, the name of the .tex file to
compile.
EXAMPLES
In its simplest form, perltex is run just like latex:
perltex myfile.tex
To use pdflatex instead of regular latex, use the CW--latex
option:
perltex --latex=pdflatex myfile.tex
If LaTeX gives a ``CWtrapped by operation mask'' error and you trust
the .tex file you're trying to compile not to execute malicious
Perl code (e.g., because you wrote it yourself), you can disable
perltex's safety mechansisms with CW--nosafe:
perltex --nosafe myfile.tex
The following command gives documents only perltex's default
permissions (CW:browse) plus the ability to open files and invoke the
CWtime command:
perltex --permit=:browse --permit=:filesys_open
--permit=time myfile.tex
ENVIRONMENT
perltex honors the following environment variables:
"\s-1PERLTEX\s0"
Specify the filename of the LaTeX compiler. The LaTeX compiler
defaults to ``CWlatex''. The CWPERLTEX environment variable
overrides this default, and the CW--latex command-line option (see
“\s-1OPTIONS\s0”) overrides that.
FILES
While compiling jobname.tex, perltex makes use of the following
files:
"jobname.lgpl"
log file written by Perl; helpful for debugging Perl macros
"jobname.topl"
information sent from LaTeX to Perl
"jobname.frpl"
information sent from Perl to LaTeX
"jobname.tfpl"
``flag'' file whose existence indicates that jobname.topl contains
valid data
"jobname.ffpl"
``flag'' file whose existence indicates that jobname.frpl contains
valid data
"jobname.dfpl"
``flag'' file whose existence indicates that jobname.ffpl has been
deleted
NOTES
perltex's sandbox defaults to what Opcode calls ``CW:browse''.
SEE ALSO
latex(1), pdflatex(1), perl(1), Safe(3pm), Opcode(3pm)
AUTHOR
Scott Pakin, scott+pt@pakin.org
