manual/luatex.man

   1 .TH LUATEX 1 "2009.04.22" "luatex 0.40" "Web2C @VERSION@"
   2 .\"=====================================================================
   3 .if n .ds MF Metafont
   4 .if t .ds MF M\s-2ETAFONT\s0
   5 .if t .ds TX \fRT\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X\fP
   6 .if n .ds TX TeX
   7 .if n .ds WB Web
   8 .if t .ds WB W\s-2EB\s0
   9 .\"=====================================================================
  10 .SH NAME
  11 luatex, texlua, texluac \- An extended version of pdfTeX using Lua as
  12 an embedded scripting language
  13 .\"=====================================================================
  14 .SH SYNOPSIS
  15 .B luatex
  16 [\-\-lua=\fIFILE\fR] [\fIOPTION\fR]... [\fITEXNAME\fR[.tex]] [\fICOMMANDS\fR]
  17
  18 .B luatex
  19 [\-\-lua=\fIFILE\fR] [\fIOPTION\fR]... \fI\eFIRST\-LINE\fR
  20
  21 .B luatex
  22 [\-\-lua=\fIFILE\fR] [\fIOPTION\fR]... \fB&\fIFMT ARGS\fR
  23 .\"=====================================================================
  24 .SH DESCRIPTION
  25 Run the lua\*(TX typesetter on \fITEXNAME\fR, usually creating
  26 TEXNAME.pdf. Any
  27 remaining \fICOMMANDS\fR are processed as lua\*(TX input, after TEXNAME
  28 is read.
  29
  30 Alternatively, if the first non\-option argument begins with a backslash,
  31 interpret all non\-option arguments as a line of lua\*(TX input.
  32
  33 Alternatively, if the first non\-option argument begins with a \fB&\fR,
  34 the
  35 next word is taken as the \fIFMT\fR to read, overriding all else. Any
  36 remaining arguments are processed as above.
  37
  38 If no arguments or options are specified, prompt for input.
  39
  40 If called as \fBtexlua\fR it acts as lua interpreter.
  41 If called as \fBtexluac\fR it acts as lua bytecode compiler.
  42
  43 Lua\*(TX is an extended version of pdf\*(TX with Unicode and OpenType
  44 font support, embeded \fBLua\fR scripting language, the \fBe-\*(TX\fR
  45 and \fBOmega\fR extensions, as well as integrated MetaPost engine, that
  46 can create \fIPDF\fR files as well as \fIDVI\fR files.
  47 For more information about luatex, see http://www.luatex.org, you can
  48 read Lua\*(TX manual using texdoc utility (\fBtexdoc luatex\fR).
  49
  50 All Lua\*(TX text input and output is considered to be Unicode text.
  51
  52 In \fIDVI\fR mode, lua\*(TX can be used as a complete replacement for
  53 the \*(TX engine.
  54
  55 In \fIPDF\fR mode, lua\*(TX can natively handle the \fIPDF\fR, \fIJPG\fR,
  56 \fIJBIG2\fR, and \fIPNG\fR graphics formats.  lua\*(TX cannot include
  57 PostScript or Encapsulated PostScript (EPS) graphics files; first convert
  58 them to PDF using \fBepstopdf\fR (1).
  59
  60 .\"=====================================================================
  61 .SH "OPTIONS"
  62 When the Lua\*(TX executable starts, it looks for the \fB\-\-lua\fR
  63 commandline option.
  64 If there is no \fB\-\-lua\fR option, the commandline is interpreted in a
  65 similar fashion as in traditional pdf\*(TX and Aleph. But if the option
  66 is present, Lua\*(TX will enter an alternative mode of commandline parsing
  67 in comparison to the standard web2c programs. The presence of \fB--lua\fR
  68 makes most of other options unreliable, because the lua initialization
  69 file can disable kpathsea and/or hook functions into various callbacks.
  70 .ig
  71 Here is the list of possibly affected switches/functionality, and why:
  72 ..
  73 .TP
  74 .BI "\-\-lua=" FILE
  75 .rb
  76 The lua initialization file.
  77 .PP
  78 The following two options alter the executable behaviour:
  79 .TP
  80 .B \-\-luaonly
  81 .rb
  82 Start Lua\*(TX as a Lua interpreter. In this mode, it will set Lua's
  83 \fIarg[0]\fR to the found script name, pushing preceding options in
  84 negative values and the rest of the commandline in the positive values,
  85 just like the Lua interpreter. Lua\*(TX will exit immediately after
  86 executing the specified Lua script.
  87 .TP
  88 .BI \-\-luaconly
  89 .rb
  90 Start Lua\*(TX as a Lua byte compiler. In this mode, Lua\*(TX is exactly
  91 like \fBluac\fR from the standalone Lua distribution, except that it
  92 does not have the \fB\-l\fR switch, and that it accepts (but ignores)
  93 the \fB\-\-luaconly\fR switch.
  94 .PP
  95 Then the regular web2c options:
  96 .TP
  97 .B \-\-debug\-format
  98 .br
  99 Debug format loading.
 100 .TP
 101 .B \-\-draftmode
 102 .rb
 103 Sets \epdfdraftmode so lua\*(TX doesn't write a PDF and doesn't read
 104 any included images, thus speeding up execution.
 105 .TP
 106 .B \-\-enable\-write18
 107 .br
 108 Synonym for \fB\-\-shell\-escape\fR.
 109 .TP
 110 .B \-\-disable\-write18
 111 .br
 112 Synonym for \fB\-\-no\-shell\-escape\fR.
 113 .TP
 114 .B \-\-shell\-escape
 115 .br
 116 Enable the
 117 .BI \ewrite18{ command }
 118 construct, and Lua functions \fBos.execute()\fR, \fBos.exec()\fR,
 119 \fBos.spawn()\fR, and \fBio.popen()\fR.  The \fIcommand\fR can be any
 120 shell command.  This construct is normally disallowed for security
 121 reasons.
 122 .TP
 123 .B \-\-no\-shell-escape
 124 .br
 125 Disable the
 126 .BI \ewrite18{ command }
 127 construct and the other Lua functions, even if it is enabled in the
 128 \fItexmf.cnf\fR file.
 129 .TP
 130 .B \-\-shell-restricted
 131 .rb
 132 Enable restricted version of \fB\ewrite18\fR, \fBos.execute()\fR,
 133 \fBos.exec()\fR, \fBos.spawn()\fR, and \fBio.popen()\fR, only commands
 134 listed in \fItexmf.cnf\fR file are allowed.
 135 .TP
 136 .B \-\-file\-line\-error
 137 .rb
 138 Print error messages in the form \fIfile:line:error\fR which is similar
 139 to the way many compilers format them.
 140 .TP
 141 .B \-\-no\-file\-line\-error
 142 .rb
 143 Disable printing error messages in the \fIfile:line:error\fR style.
 144 .TP
 145 .BI "\-\-fmt=" FORMAT
 146 .rb
 147 Use \fIFORMAT\fR as the name of the format to be used, instead of the
 148 name by which lua\*(TX was called or a \fI%&\fR line.
 149 .TP
 150 .B \-\-help
 151 .rb
 152 Print help message and exit.
 153 .TP
 154 .B \-\-ini
 155 .rb
 156 Start in \fIINI\fR mode, which is used to dump formats.  The \fIINI\fR
 157 mode can be used for typesetting, but no format is preloaded, and basic
 158 initializations like setting catcodes may be required.
 159 .TP
 160 .BI "\-\-interaction=" MODE
 161 .rb
 162 Sets the interaction mode.  The \fIMODE\fR can be either
 163 .IR batchmode ,
 164 .IR nonstopmode ,
 165 .IR scrollmode ,
 166 and
 167 .IR errorstopmode .
 168 The meaning of these modes is the same as that of the corresponding
 169 \ecommands.
 170 .TP
 171 .BI "\-\-jobname=" NAME
 172 .rb
 173 Use \fINAME\fR for the job name, instead of deriving it from the name
 174 of the input file.
 175 .TP
 176 .BI "\-\-kpathsea-debug=" BITMASK
 177 .rb
 178 Sets path searching debugging flags according to the \fIBITMASK\fR.
 179 See the \fIKpathsea\fR manual for details.
 180 .TP
 181 .BI "\-\-mktex=" FMT
 182 .rb
 183 Enable mktex\fIFMT\fR generation, where \fIFMT\fR must be either \fItex\fR
 184 or \fItfm\fR.
 185 .TP
 186 .B \-\-nosocket
 187 .rb
 188 Disable the luasocket (network) library.
 189 .TP
 190 .TP
 191 .BI "\-\-output\-comment=" STRING
 192 .rb
 193 In \fIDVI\fR mode, use \fISTRING\fR for the \fIDVI\fR file comment
 194 instead of the date.  This option is ignored in\fIPDF\fR mode.
 195 .TP
 196 .BI "\-\-output\-directory=" DIRECTORY
 197 .rb
 198 Write output files in \fIDIRECTORY\fR instead of the current directory.
 199 Look up input files in \fIDIRECTORY\fR first, then along the normal
 200 search path.
 201 .TP
 202 .BI "\-\-output\-format=" FORMAT
 203 .rb
 204 Set the output format mode, where \fIFORMAT\fR must be either \fIpdf\fR
 205 or \fIdvi\fR.
 206 This also influences the set of graphics formats understood by lua\*(TX.
 207 .TP
 208 .BI "\-\-progname=" NAME
 209 .rb
 210 Pretend to be program \fINAME\fR (only for kpathsea).
 211 .TP
 212 .B \-\-recorder
 213 .rb
 214 Enable the filename recorder.
 215 This leaves a trace of the files opened for input and output
 216 in a file with extension \fI.fls\fR.
 217 .TP
 218 .B \-\-safer
 219 .rb
 220 Disable some Lua commands that can easily be abused by a malicious
 221 document.
 222 .TP
 223 .BI "\-\-synctex=" NUMBER
 224 .rb
 225 Enable/disable Sync\*(TX extension.
 226 .TP
 227 .B \-\-version
 228 .rb
 229 Print version information and exit.
 230 .TP
 231 .B \-\-credits
 232 .rb
 233 Print credits and version details.
 234 .TP
 235 The following options are ignored:
 236 .TP
 237 .BR "\-\-8bit" ,\  "\-\-etex" ,\  "\-\-parse\-first\-line" ,\
 238 "\-\-no\-parse\-first\-line"
 239 .rb
 240 These are always on.
 241 .TP
 242 .BI "\-\-default\-translate\-file=" TCXNAME  , \  "\-\-translate\-file="
 243 TCXNAME
 244 .rb
 245 These are always off.
 246
 247 .\"=====================================================================
 248 .SH "SEE ALSO"
 249 .BR pdftex (1),
 250 .BR etex (1),
 251 .BR aleph (1),
 252 .BR omega (1),
 253 .BR lua (1).
 254 .\"=====================================================================
 255 .SH "AUTHORS"
 256 The primary authors of Lua\*(TX are Hartmut Henkel, Taco Hoekwater,
 257 and Hans Hagen, with help from Martin Schr\[:o]der, Karel Skoupy, and
 258 Han The Thanh.
 259 .PP
 260 \*(TX was designed by Donald E. Knuth, who implemented it using his
 261 \*(WB system for Pascal programs.
 262 It was ported to Unix at Stanford by Howard Trickey, and at Cornell by
 263 Pavel Curtis.
 264 The version now offered with the Unix \*(TX distribution is that generated
 265 by the \*(WB to C system (\fBweb2c\fR), originally written by Tomas
 266 Rokicki and Tim Morgan.