source/texk/web2c/man/luatex.man

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