Debian Codegraph @

texmf-dist/doc/man/man1/perltex.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PERLTEX 1"
58 .TH PERLTEX 1 2024-12-03 v2.3 " "
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 perltex \- enable LaTeX macros to be defined in terms of Perl code
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 perltex
68 [\fB\-\-help\fR]
69 [\fB\-\-latex\fR=\fIprogram\fR]
70 [\fB\-\-\fR[\fBno\fR]\fBsafe\fR]
71 [\fB\-\-permit\fR=\fIfeature\fR]
72 [\fB\-\-makesty\fR]
73 [\fIlatex options\fR]
74 .SH DESCRIPTION
75 .IX Header "DESCRIPTION"
76 LaTeX \-\- through the underlying TeX typesetting system \-\- produces
77 beautifully typeset documents but has a macro language that is
78 difficult to program. In particular, support for complex string
79 manipulation is largely lacking. Perl is a popular general-purpose
80 programming language whose forte is string manipulation. However, it
81 has no typesetting capabilities whatsoever.
82 .PP
83 Clearly, Perl's programmability could complement LaTeX's typesetting
84 strengths. \fBperltex\fR is the tool that enables a symbiosis between
85 the two systems. All a user needs to do is compile a LaTeX document
86 using \fBperltex\fR instead of \fBlatex\fR. (\fBperltex\fR is actually a
87 wrapper for \fBlatex\fR, so no \fBlatex\fR functionality is lost.) If the
88 document includes a \f(CW\*(C`\eusepackage{perltex}\*(C'\fR in its preamble, then
89 \&\f(CW\*(C`\eperlnewcommand\*(C'\fR and \f(CW\*(C`\eperlrenewcommand\*(C'\fR macros will be made
90 available. These behave just like LaTeX's \f(CW\*(C`\enewcommand\*(C'\fR and
91 \&\f(CW\*(C`\erenewcommand\*(C'\fR except that the macro body contains Perl code instead
92 of LaTeX code.
93 .SH OPTIONS
94 .IX Header "OPTIONS"
95 \&\fBperltex\fR accepts the following command-line options:
96 .IP \fB\-\-help\fR 4
97 .IX Item "--help"
98 Display basic usage information.
99 .IP \fB\-\-latex\fR=\fIprogram\fR 4
100 .IX Item "--latex=program"
101 Specify a program to use instead of \fBlatex\fR. For example,
102 \&\f(CW\*(C`\-\-latex=pdflatex\*(C'\fR would typeset the given document using
103 \&\fBpdflatex\fR instead of ordinary \fBlatex\fR.
104 .IP \fB\-\-\fR[\fBno\fR]\fBsafe\fR 4
105 .IX Item "--[no]safe"
106 Enable or disable sandboxing. With the default of \fB\-\-safe\fR,
107 \&\fBperltex\fR executes the code from a \f(CW\*(C`\eperlnewcommand\*(C'\fR or
108 \&\f(CW\*(C`\eperlrenewcommand\*(C'\fR macro within a protected environment that
109 prohibits ``unsafe'' operations such as accessing files or executing
110 external programs. Specifying \fB\-\-nosafe\fR gives the LaTeX document
111 \&\fIcarte blanche\fR to execute any arbitrary Perl code, including that
112 which can harm the user's files. See Safe for more information.
113 .IP \fB\-\-permit\fR=\fIfeature\fR 4
114 .IX Item "--permit=feature"
115 Permit particular Perl operations to be performed. The \fB\-\-permit\fR
116 option, which can be specified more than once on the command line,
117 enables finer-grained control over the \fBperltex\fR sandbox. See
118 Opcode for more information.
119 .IP \fB\-\-makesty\fR 4
120 .IX Item "--makesty"
121 Generate a LaTeX style file called \fInoperltex.sty\fR. Replacing the
122 document's \f(CW\*(C`\eusepackage{perltex}\*(C'\fR line with \f(CW\*(C`\eusepackage{noperltex}\*(C'\fR
123 produces the same output but does not require PerlTeX, making the
124 document suitable for distribution to people who do not have PerlTeX
125 installed. The disadvantage is that \fInoperltex.sty\fR is specific to
126 the document that produced it. Any changes to the document's PerlTeX
127 macro definitions or macro invocations necessitates rerunning
128 \&\fBperltex\fR with the \fB\-\-makesty\fR option.
129 .PP
130 These options are then followed by whatever options are normally
131 passed to \fBlatex\fR (or whatever program was specified with
132 \&\f(CW\*(C`\-\-latex\*(C'\fR), including, for instance, the name of the \fI.tex\fR file to
133 compile.
134 .SH EXAMPLES
135 .IX Header "EXAMPLES"
136 In its simplest form, \fBperltex\fR is run just like \fBlatex\fR:
137 .PP
138 .Vb 1
139 \& perltex myfile.tex
140 .Ve
141 .PP
142 To use \fBpdflatex\fR instead of regular \fBlatex\fR, use the \fB\-\-latex\fR
143 option:
144 .PP
145 .Vb 1
146 \& perltex \-\-latex=pdflatex myfile.tex
147 .Ve
148 .PP
149 If LaTeX gives a ``\f(CW\*(C`trapped by operation mask\*(C'\fR'' error and you trust
150 the \fI.tex\fR file you're trying to compile not to execute malicious
151 Perl code (e.g., because you wrote it yourself), you can disable
152 \&\fBperltex\fR's safety mechansisms with \fB\-\-nosafe\fR:
153 .PP
154 .Vb 1
155 \& perltex \-\-nosafe myfile.tex
156 .Ve
157 .PP
158 The following command gives documents only \fBperltex\fR's default
159 permissions (\f(CW\*(C`:browse\*(C'\fR) plus the ability to open files and invoke the
160 \&\f(CW\*(C`time\*(C'\fR command:
161 .PP
162 .Vb 2
163 \& perltex \-\-permit=:browse \-\-permit=:filesys_open
164 \& \-\-permit=time myfile.tex
165 .Ve
166 .SH ENVIRONMENT
167 .IX Header "ENVIRONMENT"
168 \&\fBperltex\fR honors the following environment variables:
169 .IP PERLTEX 4
170 .IX Item "PERLTEX"
171 Specify the filename of the LaTeX compiler. The LaTeX compiler
172 defaults to ``\f(CW\*(C`latex\*(C'\fR''. The \f(CW\*(C`PERLTEX\*(C'\fR environment variable
173 overrides this default, and the \fB\-\-latex\fR command-line option (see
174 "OPTIONS") overrides that.
175 .SH FILES
176 .IX Header "FILES"
177 While compiling \fIjobname.tex\fR, \fBperltex\fR makes use of the following
178 files:
179 .IP \fIjobname.lgpl\fR 4
180 .IX Item "jobname.lgpl"
181 log file written by Perl; helpful for debugging Perl macros
182 .IP \fIjobname.topl\fR 4
183 .IX Item "jobname.topl"
184 information sent from LaTeX to Perl
185 .IP \fIjobname.frpl\fR 4
186 .IX Item "jobname.frpl"
187 information sent from Perl to LaTeX
188 .IP \fIjobname.tfpl\fR 4
189 .IX Item "jobname.tfpl"
190 ``flag'' file whose existence indicates that \fIjobname.topl\fR contains
191 valid data
192 .IP \fIjobname.ffpl\fR 4
193 .IX Item "jobname.ffpl"
194 ``flag'' file whose existence indicates that \fIjobname.frpl\fR contains
195 valid data
196 .IP \fIjobname.dfpl\fR 4
197 .IX Item "jobname.dfpl"
198 ``flag'' file whose existence indicates that \fIjobname.ffpl\fR has been
199 deleted
200 .IP \fInoperltex\-#.tex\fR 4
201 .IX Item "noperltex-#.tex"
202 file generated by \fInoperltex.sty\fR for each PerlTeX macro invocation
203 .SH NOTES
204 .IX Header "NOTES"
205 \&\fBperltex\fR's sandbox defaults to what Opcode calls ``\f(CW\*(C`:browse\*(C'\fR''.
206 .SH "SEE ALSO"
207 .IX Header "SEE ALSO"
208 \&\fBlatex\fR\|(1), \fBpdflatex\fR\|(1), \fBperl\fR\|(1), \fBSafe\fR\|(3pm), \fBOpcode\fR\|(3pm)
209 .SH AUTHOR
210 .IX Header "AUTHOR"
211 Scott Pakin, \[email protected]\fR