1PERLTEX(1)                                                          PERLTEX(1)
2
3
4

NAME

6       perltex - enable LaTeX macros to be defined in terms of Perl code
7

SYNOPSIS

9       perltex [--help] [--latex=program] [--[no]safe] [--permit=feature]
10       [--makesty] [latex options]
11

DESCRIPTION

13       LaTeX -- through the underlying TeX typesetting system -- produces
14       beautifully typeset documents but has a macro language that is
15       difficult to program.  In particular, support for complex string
16       manipulation is largely lacking.  Perl is a popular general-purpose
17       programming language whose forte is string manipulation.  However, it
18       has no typesetting capabilities whatsoever.
19
20       Clearly, Perl's programmability could complement LaTeX's typesetting
21       strengths.  perltex is the tool that enables a symbiosis between the
22       two systems.  All a user needs to do is compile a LaTeX document using
23       perltex instead of latex.  (perltex is actually a wrapper for latex, so
24       no latex functionality is lost.)  If the document includes a
25       "\usepackage{perltex}" in its preamble, then "\perlnewcommand" and
26       "\perlrenewcommand" macros will be made available.  These behave just
27       like LaTeX's "\newcommand" and "\renewcommand" except that the macro
28       body contains Perl code instead of LaTeX code.
29

OPTIONS

31       perltex accepts the following command-line options:
32
33       --help
34           Display basic usage information.
35
36       --latex=program
37           Specify a program to use instead of latex.  For example,
38           "--latex=pdflatex" would typeset the given document using pdflatex
39           instead of ordinary latex.
40
41       --[no]safe
42           Enable or disable sandboxing.  With the default of --safe, perltex
43           executes the code from a "\perlnewcommand" or "\perlrenewcommand"
44           macro within a protected environment that prohibits ``unsafe''
45           operations such as accessing files or executing external programs.
46           Specifying --nosafe gives the LaTeX document carte blanche to
47           execute any arbitrary Perl code, including that which can harm the
48           user's files.  See Safe for more information.
49
50       --permit=feature
51           Permit particular Perl operations to be performed.  The --permit
52           option, which can be specified more than once on the command line,
53           enables finer-grained control over the perltex sandbox.  See Opcode
54           for more information.
55
56       --makesty
57           Generate a LaTeX style file called noperltex.sty.  Replacing the
58           document's "\usepackage{perltex}" line with
59           "\usepackage{noperltex}" produces the same output but does not
60           require PerlTeX, making the document suitable for distribution to
61           people who do not have PerlTeX installed.  The disadvantage is that
62           noperltex.sty is specific to the document that produced it.  Any
63           changes to the document's PerlTeX macro definitions or macro
64           invocations necessitates rerunning perltex with the --makesty
65           option.
66
67       These options are then followed by whatever options are normally passed
68       to latex (or whatever program was specified with "--latex"), including,
69       for instance, the name of the .tex file to compile.
70

EXAMPLES

72       In its simplest form, perltex is run just like latex:
73
74           perltex myfile.tex
75
76       To use pdflatex instead of regular latex, use the --latex option:
77
78           perltex --latex=pdflatex myfile.tex
79
80       If LaTeX gives a ``"trapped by operation mask"'' error and you trust
81       the .tex file you're trying to compile not to execute malicious Perl
82       code (e.g., because you wrote it yourself), you can disable perltex's
83       safety mechansisms with --nosafe:
84
85           perltex --nosafe myfile.tex
86
87       The following command gives documents only perltex's default
88       permissions (":browse") plus the ability to open files and invoke the
89       "time" command:
90
91           perltex --permit=:browse --permit=:filesys_open
92             --permit=time myfile.tex
93

ENVIRONMENT

95       perltex honors the following environment variables:
96
97       PERLTEX
98           Specify the filename of the LaTeX compiler.  The LaTeX compiler
99           defaults to ``"latex"''.  The "PERLTEX" environment variable
100           overrides this default, and the --latex command-line option (see
101           "OPTIONS") overrides that.
102

FILES

104       While compiling jobname.tex, perltex makes use of the following files:
105
106       jobname.lgpl
107           log file written by Perl; helpful for debugging Perl macros
108
109       jobname.topl
110           information sent from LaTeX to Perl
111
112       jobname.frpl
113           information sent from Perl to LaTeX
114
115       jobname.tfpl
116           ``flag'' file whose existence indicates that jobname.topl contains
117           valid data
118
119       jobname.ffpl
120           ``flag'' file whose existence indicates that jobname.frpl contains
121           valid data
122
123       jobname.dfpl
124           ``flag'' file whose existence indicates that jobname.ffpl has been
125           deleted
126
127       noperltex-#.tex
128           file generated by noperltex.sty for each PerlTeX macro invocation
129

NOTES

131       perltex's sandbox defaults to what Opcode calls ``":browse"''.
132

SEE ALSO

134       latex(1), pdflatex(1), perl(1), Safe(3pm), Opcode(3pm)
135

AUTHOR

137       Scott Pakin, scott+pt@pakin.org
138
139
140
141v2.2                              2019-09-15                        PERLTEX(1)
Impressum