1 files changed, 77 insertions, 41 deletions
diff --git a/doc/luac.html b/doc/luac.html
index 1948e7ab..92d9ddf1 100644
--- a/doc/luac.html
+++ b/doc/luac.html
@@ -1,35 +1,20 @@
-<!-- $Id: luac.man,v 1.8 1998/06/13 16:54:15 lhf Exp $ -->
-<TITLE>LUAC 1 "06 February 1998"</TITLE>
+<!-- luac.man,v 1.17 1999/07/07 16:02:07 lhf Exp -->
+<HTML>
+<HEAD>
+<TITLE>LUAC man page</TITLE>
+</HEAD>
+
+<BODY BGCOLOR="#FFFFFF">
+
 <H1>NAME</H1>
 luac - Lua compiler
 <H1>SYNOPSIS</H1>
 <B>luac</B>
 [
-<B>-c</B>
-|
-<B>-u</B>
-] [
-<B>-D</B>
-<I>name</I>
-] [
-<B>-d</B>
-] [
-<B>-l</B>
-] [
-<B>-O</B>
-] [
-<B>-o</B>
-<I>filename</I>
+<I>options</I>
 ] [
-<B>-p</B>
-] [
-<B>-q</B>
-] [
-<B>-v</B>
-] [
-<B>-V</B>
+<I>filenames</I>
 ]
-<I>sourcefile </I>...
 <H1>DESCRIPTION</H1>
 <B>luac</B>
 is the Lua compiler.
@@ -43,10 +28,16 @@ in Lua.
 The main advantages of pre-compiling chunks are:
 faster loading,
 protecting source code from user changes,
+and
 off-line syntax error detection.
 The binary files created by
 <B>luac</B>
-are portable to all known architectures.
+are portable to all architectures.
+<P>
+Pre-compiling does not imply faster execution
+because in Lua chunks are always compiled into bytecodes before being executed.
+<B>luac</B>
+simply allows those bytecodes to be saved in a file for later execution.
 <P>
 <B>luac</B>
 produces a single output file containing the bytecodes
@@ -71,16 +62,26 @@ option.
 <P>
 Binary files produced by differents runs of
 <B>luac</B>
+(even in different machines)
 can be combined into one large file,
 using 
 <B>cat</B>(1).
-The result is still a valid binary file,
+The result is still a valid binary file
 and can be loaded with a single call to
 <B>lua_dofile</B>
 or 
 <B>dofile</B>.
 <P>
+The internal format of the binary files produced by
+<B>luac</B>
+may change when a new version of Lua is released.
+We try to maintain compatibility even for binary files,
+but sometimes it cannot be done.
+So,
+save the source files of all Lua programs that you precompile.
+<P>
 <H1>OPTIONS</H1>
+Options must be separate.
 <P>
 <B>-c</B>
 compile (this is the default).
@@ -89,26 +90,44 @@ compile (this is the default).
 undump, i.e., load and list the given binary files.
 If no files are given, then luac undumps
 <B>luac.out</B>.
-<P>
-<B>-D "</B><I>name"</I>
-predefine symbol
-<I>name</I>
-for conditional compilation.
+Listing a binary file is useful to learn Lua's virtual machine.
+Listing is also useful to test the integrity of binary files:
+corrupted files will probably generate errors when undumped.
+To test without listing, use
+<B>-q</B>.
+For a thourough integrity test,
+use
+<B>-t</B>.
 <P>
 <B>-d</B>
 turn debugging on.
 Individual chunks may
 still control the generation of debug information with
 $debug and $nodebug.
+If debugging is on, then listings show the names of the local variables.
+<P>
+<B>-D "</B><I>name"</I>
+predefine symbol
+<I>name</I>
+for conditional compilation.
+By default,
+<B>luac</B>
+does
+<I>not</I>
+predefine any symbols,
+not even the built-in functions.
 <P>
 <B>-l</B>
 produce a listing of the compiled bytecode for Lua's virtual machine.
 This is the default when undumping.
 <P>
-<B>-O</B>
-optimize code.
-Debug information is removed,
-duplicate constants are coalesced.
+<B>-n</B>
+Save numbers in native format.
+By default,
+numbers are saved in text form,
+for maximum portability.
+Binary files with numbers in native format are slightly faster to load,
+but are not completely portable.
 <P>
 <B>-o "</B><I>filename"</I>
 output to
@@ -117,14 +136,33 @@ instead of the default
 <B>luac.out</B>.
 The output file cannot be a source file.
 <P>
+<B>-O</B>
+optimize.
+Debug information is removed
+and
+duplicate constants are coalesced.
+<P>
 <B>-p</B>
-parse sources files but does not generate any output file.
+parse sources files but do not generate any output file.
 Used mainly for syntax checking.
 <P>
 <B>-q</B>
 quiet; produces no listing.
 This is the default when compiling.
 <P>
+<B>-t</B>
+perform a thourough integrity test when undumping.
+Code that passes this test is completely safe,
+in the sense that it will not break the interpreter.
+However,
+there is no guarantee that such code does anything sensible.
+(None can be given, because the halting problem is unsolvable.)
+<P>
+<B>-U "</B><I>name"</I>
+undefine symbol
+<I>name</I>
+for conditional compilation.
+<P>
 <B>-v</B>
 print version information.
 <P>
@@ -135,7 +173,7 @@ print the names of the source files as they are processed.
 <P>
 <B>luac.out</B>
 default output file
-<H1>"SEE ALSO"</H1>
+<H1>SEE ALSO</H1>
 <B>lua</B>(1)
 <BR>
 <I>"Reference Manual of the Programming Language Lua"</I>
@@ -148,11 +186,9 @@ default output file
 #6 (1996) 635-652.
 <H1>DIAGNOSTICS</H1>
 Error messages should be self explanatory.
-<H1>BUGS</H1>
-Inherits any bugs from Lua,
-but Lua has no bugs...
 <H1>AUTHORS</H1>
 L. H. de Figueiredo,
 R. Ierusalimschy and
 W. Celes
 <I>(<A HREF="mailto:lua@tecgraf.puc-rio.br">lua@tecgraf.puc-rio.br</A>)</I>
+<!-- EOF -->