Documentation cleanup.

doc/faq.html

@@ -78,16 +78,14 @@ has information about diverse topics.</li>
 <dl id="tech">
 <dt>Q: Where can I learn more about the compiler technology used by LuaJIT?</dt>
 <dd>
-I'm planning to write more documentation about the internals of LuaJIT.
+Please use the following Google Scholar searches to find relevant papers:<br>
-In the meantime, please use the following Google Scholar searches
-to find relevant papers:<br>
 Search for: <a href="https://scholar.google.com/scholar?q=Trace+Compiler"><span class="ext">&raquo;</span>&nbsp;Trace Compiler</a><br>
 Search for: <a href="https://scholar.google.com/scholar?q=JIT+Compiler"><span class="ext">&raquo;</span>&nbsp;JIT Compiler</a><br>
 Search for: <a href="https://scholar.google.com/scholar?q=Dynamic+Language+Optimizations"><span class="ext">&raquo;</span>&nbsp;Dynamic Language Optimizations</a><br>
 Search for: <a href="https://scholar.google.com/scholar?q=SSA+Form"><span class="ext">&raquo;</span>&nbsp;SSA Form</a><br>
 Search for: <a href="https://scholar.google.com/scholar?q=Linear+Scan+Register+Allocation"><span class="ext">&raquo;</span>&nbsp;Linear Scan Register Allocation</a><br>
 Here is a list of the <a href="http://lua-users.org/lists/lua-l/2009-11/msg00089.html"><span class="ext">&raquo;</span>&nbsp;innovative features in LuaJIT</a>.<br>
-And, you know, reading the source is of course the only way to enlightenment. :-)
+And, you know, reading the source is of course the only way to enlightenment.
 </dd>
 </dl>
 
@@ -126,12 +124,11 @@ Please check the Delphi docs for the Set8087CW method.
 <dl id="ctrlc">
 <dt>Q: Sometimes Ctrl-C fails to stop my Lua program. Why?</dt>
 <dd>The interrupt signal handler sets a Lua debug hook. But this is
-currently ignored by compiled code (this will eventually be fixed). If
+ignored by compiled code. If your program is running in a tight loop
-your program is running in a tight loop and never falls back to the
+and never falls back to the interpreter, the debug hook never runs and
-interpreter, the debug hook never runs and can't throw the
+can't throw the "interrupted!" error.<br>
-"interrupted!" error.<br> In the meantime you have to press Ctrl-C
+You have to press Ctrl-C twice to get stop your program. That's similar
-twice to get stop your program. That's similar to when it's stuck
+to when it's stuck running inside a C function under the Lua interpreter.</dd>
-running inside a C function under the Lua interpreter.</dd>
 </dl>
 
 <dl id="sandbox">
@@ -145,30 +142,20 @@ it's very hard to get this right even for the Lua core libraries. Of course,
 you'll need to inspect any extension library, too. And there are libraries
 that are inherently unsafe, e.g. the <a href="ext_ffi.html">FFI library</a>.<br>
 
-Relatedly, <b>loading untrusted bytecode is not safe!</b> It's trivial
+More reading material at the <a href="http://lua-users.org/wiki/SandBoxes"><span class="ext">&raquo;</span>&nbsp;Lua Wiki</a> and <a href="https://en.wikipedia.org/wiki/Sandbox_(computer_security)"><span class="ext">&raquo;</span>&nbsp;Wikipedia</a>.<br><br>
-to crash the Lua or LuaJIT VM with maliciously crafted bytecode. This is
+
-well known and there's no bytecode verification on purpose, so please
+Relatedly, <b>loading untrusted bytecode is not safe!</b><br>
+
+It's trivial to crash the Lua or LuaJIT VM with maliciously crafted bytecode.
+This is well known and there's no bytecode verification on purpose, so please
 don't report a bug about it. Check the <tt>mode</tt> parameter for the
-<tt>load*()</tt> functions to disable loading of bytecode.<br>
+<tt>load*()</tt> functions to disable loading of bytecode.<br><br>
 
-In general, the only promising approach is to sandbox Lua code at the
+<b>In general, the only promising approach is to sandbox Lua code at the
-process level and not the VM level.<br>
+process level and not the VM level.</b>
-
-More reading material at the <a href="http://lua-users.org/wiki/SandBoxes"><span class="ext">&raquo;</span>&nbsp;Lua Wiki</a> and <a href="https://en.wikipedia.org/wiki/Sandbox_(computer_security)"><span class="ext">&raquo;</span>&nbsp;Wikipedia</a>.
 </dd>
 </dl>
 
-<dl id="patches">
-<dt>Q: Why doesn't my favorite power-patch for Lua apply against LuaJIT?</dt>
-<dd>Because it's a completely redesigned VM and has very little code
-in common with Lua anymore. Also, if the patch introduces changes to
-the Lua semantics, these would need to be reflected everywhere in the
-VM, from the interpreter up to all stages of the compiler.<br> Please
-use only standard Lua language constructs. For many common needs you
-can use source transformations or use wrapper or proxy functions.
-The compiler will happily optimize away such indirections.</dd>
-</dl>
-
 <dl id="arch">
 <dt>Q: Lua runs everywhere. Why doesn't LuaJIT support my CPU?</dt>
 <dd>Because it's a compiler &mdash; it needs to generate native
@@ -176,17 +163,11 @@ machine code. This means the code generator must be ported to each
 architecture. And the fast interpreter is written in assembler and
 must be ported, too. This is quite an undertaking.<br>
 The <a href="install.html">install documentation</a> shows the supported
-architectures. Other architectures will follow based on sufficient user
+architectures.<br>
-demand and/or sponsoring.</dd>
+Other architectures may follow based on sufficient user demand and
-</dl>
+market-relevance of the architecture. Sponsoring is required to develop
-
+the port itself, to integrate it and to continuously maintain it in the
-<dl id="when">
+actively developed branches.</dd>
-<dt>Q: When will feature X be added? When will the next version be released?</dt>
-<dd>When it's ready.<br>
-C'mon, it's open source &mdash; I'm doing it on my own time and you're
-getting it for free. You can either contribute a patch or sponsor
-the development of certain features, if they are important to you.
-</dd>
 </dl>
 <br class="flush">
 </div>

doc/install.html

@@ -101,8 +101,8 @@ operating systems, CPUs and compilers:
 <td class="compatcpu">CPU / OS</td>
 <td class="compatos"><a href="#posix">Linux</a> or<br><a href="#android">Android</a></td>
 <td class="compatos"><a href="#posix">*BSD, Other</a></td>
-<td class="compatos"><a href="#posix">OSX 10.4+</a> or<br><a href="#ios">iOS 3.0+</a></td>
+<td class="compatos"><a href="#posix">macOS 10.4+</a> or<br><a href="#ios">iOS 3.0+</a></td>
-<td class="compatos"><a href="#windows">Windows<br>XP/Vista/7</a></td>
+<td class="compatos"><a href="#windows">Windows XP<br>or later</a></td>
 </tr>
 <tr class="odd separate">
 <td class="compatcpu">x86 (32 bit)</td>
@@ -168,7 +168,7 @@ Please read the instructions given in these files, before changing
 any settings.
 </p>
 
-<h2 id="posix">POSIX Systems (Linux, OSX, *BSD etc.)</h2>
+<h2 id="posix">POSIX Systems (Linux, macOS, *BSD etc.)</h2>
 <h3>Prerequisites</h3>
 <p>
 Depending on your distribution, you may need to install a package for
@@ -176,8 +176,9 @@ GCC, the development headers and/or a complete SDK. E.g. on a current
 Debian/Ubuntu, install <tt>libc6-dev</tt> with the package manager.
 </p>
 <p>
-Download the current source package of LuaJIT (pick the .tar.gz),
+The recommended way to fetch the latest version is to do a pull from
-if you haven't already done so. Move it to a directory of your choice,
+the git repository. Alternatively download the latest source package of
+LuaJIT (pick the .tar.gz). Move it to a directory of your choice,
 open a terminal window and change to this directory. Now unpack the archive
 and change to the newly created directory:
 </p>
@@ -207,7 +208,7 @@ You can add an extra prefix to the search paths by appending the
 make PREFIX=/home/myself/lj2
 </pre>
 <p>
-Note for OSX: you must set the <tt>MACOSX_DEPLOYMENT_TARGET</tt>
+Note for macOS: you must set the <tt>MACOSX_DEPLOYMENT_TARGET</tt>
 environment variable to a value supported by your toolchain.
 </p>
 <h3>Installing LuaJIT</h3>
@@ -241,8 +242,9 @@ GCC plus the required development headers.
 Or install Microsoft's Visual Studio (MSVC).
 </p>
 <p>
-Next, download the source package and unpack it using an archive manager
+Next, pull from the git repository or download the source package and
-(e.g. the Windows Explorer) to a directory of your choice.
+unpack it using an archive manager (e.g. the Windows Explorer) to
+a directory of your choice.
 </p>
 <h3>Building with MSVC</h3>
 <p>
@@ -260,8 +262,8 @@ Then follow the installation instructions below.
 <h3>Building with MinGW or Cygwin</h3>
 <p>
 Open a command prompt window and make sure the MinGW or Cygwin programs
-are in your path. Then <tt>cd</tt> to the directory where
+are in your path. Then <tt>cd</tt> to the directory of the git repository
-you've unpacked the sources and run this command for MinGW:
+or where you've unpacked the sources. Then run this command for MinGW:
 </p>
 <pre class="code">
 mingw32-make
@@ -302,7 +304,7 @@ x64 OS, you need to install the multilib development package (e.g.
 <p>
 You need to specify <tt>TARGET_SYS</tt> whenever the host OS and the
 target OS differ, or you'll get assembler or linker errors. E.g. if
-you're compiling on a Windows or OSX host for embedded Linux or Android,
+you're compiling on a Windows or macOS host for embedded Linux or Android,
 you need to add <tt>TARGET_SYS=Linux</tt> to the examples below. For a
 minimal target OS, you may need to disable the built-in allocator in
 <tt>src/Makefile</tt> and use <tt>TARGET_SYS=Other</tt>. Don't forget to
@@ -461,15 +463,14 @@ intend to load Lua/C modules at runtime.
 </li></ul>
 </li>
 <li>
-If you're building a 64 bit application on OSX which links directly or
+<i>Important: this relates to LuaJIT 2.0 only &mdash; use LuaJIT 2.1 to
+avoid these complications.</i><br>
+If you're building a 64 bit application on macOS which links directly or
 indirectly against LuaJIT, you need to link your main executable
 with these flags:
 <pre class="code">
 -pagezero_size 10000 -image_base 100000000
 </pre>
-Also, it's recommended to <tt>rebase</tt> all (self-compiled) shared libraries
-which are loaded at runtime on OSX/x64 (e.g. C extension modules for Lua).
-See: <tt>man rebase</tt>
 </li>
 </ul>
 <p>Additional hints for initializing LuaJIT using the C API functions:</p>
@@ -479,7 +480,7 @@ See: <tt>man rebase</tt>
 for embedding Lua or LuaJIT into your application.</li>
 <li>Make sure you use <tt>luaL_newstate</tt>. Avoid using
 <tt>lua_newstate</tt>, since this uses the (slower) default memory
-allocator from your system (no support for this on x64).</li>
+allocator from your system (no support for this on 64&nbsp;bit architectures).</li>
 <li>Make sure you use <tt>luaL_openlibs</tt> and not the old Lua 5.0 style
 of calling <tt>luaopen_base</tt> etc. directly.</li>
 <li>To change or extend the list of standard libraries to load, copy

doc/luajit.html

@@ -152,7 +152,7 @@ LuaJIT is Copyright © 2005-2020 Mike Pall, released under the
 
 <h2>Compatibility</h2>
 <table class="feature os os1">
-<tr><td>Windows</td><td>Linux</td><td>BSD</td><td>OSX</td><td>POSIX</td></tr>
+<tr><td>Windows</td><td>Linux</td><td>BSD</td><td>macOS</td><td>POSIX</td></tr>
 </table>
 <table class="feature os os2">
 <tr><td><span style="font-size:90%;">Embedded</span></td><td>Android</td><td>iOS</td></tr>

doc/status.html

@@ -56,9 +56,15 @@ ul li { padding-bottom: 0.3em; }
 </div>
 <div id="main">
 <p>
-<span style="color: #0000c0;">LuaJIT&nbsp;2.0</span> is the current
+This documentation is for LuaJIT 2.0.5. Please check the <tt>doc</tt>
-<span style="color: #0000c0;">stable branch</span>. This branch is in
+directory in each git branch for the version-specific documentation.
-feature-freeze &mdash; new features will only be added to LuaJIT&nbsp;2.1.
+</p>
+<p>
+The currently developed branches are LuaJIT&nbsp;2.1 and LuaJIT&nbsp;2.0.
+</p>
+<p>
+LuaJIT&nbsp;2.0 is in feature-freeze &mdash; new features will only
+be added to LuaJIT&nbsp;2.1.
 </p>
 
 <h2>Current Status</h2>
@@ -86,8 +92,7 @@ in LuaJIT (no per-coroutine hooks, no tail call counting).
 Currently some <b>out-of-memory</b> errors from <b>on-trace code</b> are not
 handled correctly. The error may fall through an on-trace
 <tt>pcall</tt> or it may be passed on to the function set with
-<tt>lua_atpanic</tt> on x64. This issue will be fixed with the new
+<tt>lua_atpanic</tt> on x64.
-garbage collector.
 </li>
 </ul>
 <br class="flush">