summaryrefslogtreecommitdiff
path: root/Master/texmf/doc/man/man1/luatex.1
blob: ccd1b1d501f49e1e2dfb37d495fc6280c6ac1f6d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
.TH LUATEX 1 "14 May 2010" "luatex 0.40" "Web2C 2010"
.\"=====================================================================
.if n .ds MF Metafont
.if t .ds MF M\s-2ETAFONT\s0
.if t .ds TX \fRT\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X\fP
.if n .ds TX TeX
.if n .ds WB Web
.if t .ds WB W\s-2EB\s0
.\"=====================================================================
.SH NAME
luatex, texlua, texluac \- An extended version of pdfTeX using Lua as
an embedded scripting language
.\"=====================================================================
.SH SYNOPSIS
.B luatex
.RB [ \-\-lua=\fIFILE\fP ]
.RI [ OPTION ].\|.\|.
.RI [ TEXNAME [ \fB.tex\fP ]]
.RI [ COMMANDS ]
.br
.B luatex
.RB [ \-\-lua=\fIFILE\fP ]
.RI [ OPTION ].\|.\|.
.BI \e FIRST\-LINE
.br
.B luatex
.RB [ \-\-lua=\fIFILE\fP ]
.RI [ OPTION ].\|.\|.
.BI & FMT
.RI [ ARGS ]
.\"=====================================================================
.SH DESCRIPTION
Run the lua\*(TX typesetter on
.IR TEXNAME ,
usually creating
.IR TEXNAME\fB.pdf\fP .
Any remaining
.I COMMANDS
are processed as lua\*(TX input, after
.I TEXNAME
is read.

Alternatively, if the first non\-option argument begins with a backslash,
interpret all non\-option arguments as a line of lua\*(TX input.

Alternatively, if the first non\-option argument begins with a \fB&\fR,
the
next word is taken as the \fIFMT\fR to read, overriding all else. Any
remaining arguments are processed as above.

If no arguments or options are specified, prompt for input.

If called as \fBtexlua\fR it acts as lua interpreter.
If called as \fBtexluac\fR it acts as lua bytecode compiler.

Lua\*(TX is an extended version of pdf\*(TX with Unicode and OpenType
font support, embeded \fBLua\fR scripting language, the \fBe-\*(TX\fR
and \fBOmega\fR extensions, as well as integrated MetaPost engine, that
can create \fIPDF\fR files as well as \fIDVI\fR files.
For more information about luatex, see http://www.luatex.org, you can
read Lua\*(TX manual using texdoc utility (\fBtexdoc luatex\fR).

All Lua\*(TX text input and output is considered to be Unicode text.

In \fIDVI\fR mode, lua\*(TX can be used as a complete replacement for
the \*(TX engine.

In \fIPDF\fR mode, lua\*(TX can natively handle the \fIPDF\fR, \fIJPG\fR,
\fIJBIG2\fR, and \fIPNG\fR graphics formats.  lua\*(TX cannot include
PostScript or Encapsulated PostScript (EPS) graphics files; first convert
them to PDF using \fBepstopdf\fR (1).

.\"=====================================================================
.SH "OPTIONS"
When the Lua\*(TX executable starts, it looks for the \fB\-\-lua\fR
commandline option.
If there is no \fB\-\-lua\fR option, the commandline is interpreted in a
similar fashion as in traditional pdf\*(TX and Aleph. But if the option
is present, Lua\*(TX will enter an alternative mode of commandline parsing
in comparison to the standard web2c programs. The presence of \fB--lua\fR
makes most of other options unreliable, because the lua initialization
file can disable kpathsea and/or hook functions into various callbacks.
.ig
Here is the list of possibly affected switches/functionality, and why:
..
.TP
.BI "\-\-lua=" FILE
.rb
The lua initialization file.
.PP
The following two options alter the executable behaviour:
.TP
.B \-\-luaonly
.rb
Start Lua\*(TX as a Lua interpreter. In this mode, it will set Lua's
\fIarg[0]\fR to the found script name, pushing preceding options in
negative values and the rest of the commandline in the positive values,
just like the Lua interpreter. Lua\*(TX will exit immediately after
executing the specified Lua script.
.TP
.BI \-\-luaconly
.rb
Start Lua\*(TX as a Lua byte compiler. In this mode, Lua\*(TX is exactly
like \fBluac\fR from the standalone Lua distribution, except that it
does not have the \fB\-l\fR switch, and that it accepts (but ignores)
the \fB\-\-luaconly\fR switch.
.PP
Then the regular web2c options:
.TP
.B \-\-debug\-format
.br
Debug format loading.
.TP
.B \-\-draftmode
.rb
Sets \epdfdraftmode so lua\*(TX doesn't write a PDF and doesn't read
any included images, thus speeding up execution.
.TP
.B \-\-enable\-write18
.br
Synonym for \fB\-\-shell\-escape\fR.
.TP
.B \-\-disable\-write18
.br
Synonym for \fB\-\-no\-shell\-escape\fR.
.TP
.B \-\-shell\-escape
.br
Enable the
.BI \ewrite18{ command }
construct, and Lua functions \fBos.execute()\fR, \fBos.exec()\fR,
\fBos.spawn()\fR, and \fBio.popen()\fR.  The \fIcommand\fR can be any
shell command.  This construct is normally disallowed for security
reasons.
.TP
.B \-\-no\-shell-escape
.br
Disable the
.BI \ewrite18{ command }
construct and the other Lua functions, even if it is enabled in the
\fItexmf.cnf\fR file.
.TP
.B \-\-shell-restricted
.rb
Enable restricted version of \fB\ewrite18\fR, \fBos.execute()\fR,
\fBos.exec()\fR, \fBos.spawn()\fR, and \fBio.popen()\fR, only commands
listed in \fItexmf.cnf\fR file are allowed.
.TP
.B \-\-file\-line\-error
.rb
Print error messages in the form \fIfile:line:error\fR which is similar
to the way many compilers format them.
.TP
.B \-\-no\-file\-line\-error
.rb
Disable printing error messages in the \fIfile:line:error\fR style.
.TP
.BI "\-\-fmt=" FORMAT
.rb
Use \fIFORMAT\fR as the name of the format to be used, instead of the
name by which lua\*(TX was called or a \fI%&\fR line.
.TP
.B \-\-help
.rb
Print help message and exit.
.TP
.B \-\-ini
.rb
Start in \fIINI\fR mode, which is used to dump formats.  The \fIINI\fR
mode can be used for typesetting, but no format is preloaded, and basic
initializations like setting catcodes may be required.
.TP
.BI "\-\-interaction=" MODE
.rb
Sets the interaction mode.  The \fIMODE\fR can be either
.IR batchmode ,
.IR nonstopmode ,
.IR scrollmode ,
and
.IR errorstopmode .
The meaning of these modes is the same as that of the corresponding
\ecommands.
.TP
.BI "\-\-jobname=" NAME
.rb
Use \fINAME\fR for the job name, instead of deriving it from the name
of the input file.
.TP
.BI "\-\-kpathsea-debug=" BITMASK
.rb
Sets path searching debugging flags according to the \fIBITMASK\fR.
See the \fIKpathsea\fR manual for details.
.TP
.BI "\-\-mktex=" FMT
.rb
Enable mktex\fIFMT\fR generation, where \fIFMT\fR must be either \fItex\fR
or \fItfm\fR.
.TP
.B \-\-nosocket
.rb
Disable the luasocket (network) library.
.TP
.TP
.BI "\-\-output\-comment=" STRING
.rb
In \fIDVI\fR mode, use \fISTRING\fR for the \fIDVI\fR file comment
instead of the date.  This option is ignored in\fIPDF\fR mode.
.TP
.BI "\-\-output\-directory=" DIRECTORY
.rb
Write output files in \fIDIRECTORY\fR instead of the current directory.
Look up input files in \fIDIRECTORY\fR first, then along the normal
search path.
.TP
.BI "\-\-output\-format=" FORMAT
.rb
Set the output format mode, where \fIFORMAT\fR must be either \fIpdf\fR
or \fIdvi\fR.
This also influences the set of graphics formats understood by lua\*(TX.
.TP
.BI "\-\-progname=" NAME
.rb
Pretend to be program \fINAME\fR (only for kpathsea).
.TP
.B \-\-recorder
.rb
Enable the filename recorder.
This leaves a trace of the files opened for input and output
in a file with extension \fI.fls\fR.
.TP
.B \-\-safer
.rb
Disable some Lua commands that can easily be abused by a malicious
document.
.TP
.BI "\-\-synctex=" NUMBER
.rb
Enable/disable Sync\*(TX extension.
.TP
.B \-\-version
.rb
Print version information and exit.
.TP
.B \-\-credits
.rb
Print credits and version details.
.TP
The following options are ignored:
.TP
.BR \-\-8bit ,\  \-\-etex ,\  \-\-parse\-first\-line ,\  \-\-no\-parse\-first\-line
.rb
These are always on.
.TP
.BR \-\-default\-translate\-file=\fITCXNAME\fP  ,\  \-\-translate\-file=\fITCXNAME\fP
.rb
These are always off.

.\"=====================================================================
.SH "SEE ALSO"
.BR pdftex (1),
.BR etex (1),
.BR aleph (1),
.BR omega (1),
.BR lua (1).
.\"=====================================================================
.SH "AUTHORS"
The primary authors of Lua\*(TX are Hartmut Henkel, Taco Hoekwater,
and Hans Hagen, with help from Martin Schr\[:o]der, Karel Skoupy, and
Han The Thanh.
.PP
\*(TX was designed by Donald E. Knuth, who implemented it using his
\*(WB system for Pascal programs.
It was ported to Unix at Stanford by Howard Trickey, and at Cornell by
Pavel Curtis.
The version now offered with the Unix \*(TX distribution is that generated
by the \*(WB to C system (\fBweb2c\fR), originally written by Tomas
Rokicki and Tim Morgan.