Documentation refactoring

readthedocs/ravi-build-instructions.rst

@@ -97,7 +97,7 @@ I open the generated project in Xcode and do a build from there. You can also us
 
 Eclipse OMR JIT Backend
 =======================
-* Ravi uses a cut-down version of the [Eclipse OMR JIT engine](https://github.com/dibyendumajumdar/nj). First build this library and install it.
+* Ravi uses a cut-down version of the `Eclipse OMR JIT engine <https://github.com/dibyendumajumdar/nj>`_. First build this library and install it.
 * The Ravi CMake build assumes you have installed the OMR JIT library under ``\Software\omr`` on Windows and ``$HOME/Software/omr`` on Linux or Mac OSX.
 * Now you can build Ravi as follows on Linux or Mac OSX:
 

readthedocs/ravi-overview.rst

@@ -3,7 +3,8 @@ Ravi Programming Language
 =========================
 
 Ravi is a derivative/dialect of `Lua 5.3 <http://www.lua.org/>`_ with limited optional static typing and 
-an `LLVM <http://www.llvm.org/>`_ powered JIT compiler. The name Ravi comes from the Sanskrit word for the Sun. 
+features `LLVM <http://www.llvm.org/>`_ and `Eclipse OMR <https://github.com/dibyendumajumdar/nj>`_ 
+powered JIT compilers. The name Ravi comes from the Sanskrit word for the Sun. 
 Interestingly a precursor to Lua was `Sol <http://www.lua.org/history.html>`_ which had support for 
 static types; Sol means the Sun in Portugese.
 
@@ -25,10 +26,6 @@ Of course there is also the fantastic `LuaJIT <http://luajit.org>`_ implementati
 LuaJIT. Ravi prioritizes ease of maintenance and support, language safety, and compatibility with Lua 5.3, 
 over maximum performance. For more detailed comparison please refer to the documentation links below.
 
-.. contents:: Table of Contents
-   :depth: 1
-   :backlinks: top
-
 Features
 ========
 * Optional static typing - for details `see the reference manual <https://the-ravi-programming-language.readthedocs.io/en/latest/ravi-reference.html>`_.
@@ -59,6 +56,7 @@ Ravi should be able to run all Lua 5.3 programs in interpreted mode, but followi
 * Values crossing from Lua to Ravi will be subjected to typechecks should these values be assigned to typed variables.
 * Upvalues cannot subvert the static typing of local variables (issue #26) when types are annotated.
 * Certain Lua limits are reduced due to changed byte code structure. These are described below.
+* Ravi uses an extended bytecode which means it is not compatible with Lua 5.3 bytecode. 
 
 +-----------------+-------------+-------------+
 | Limit name      | Lua value   | Ravi value  |

readthedocs/ravi-reference.rst

@@ -1,6 +1,10 @@
 Ravi Extensions to Lua 5.3
 ==========================
 
+.. contents:: Table of Contents
+   :depth: 1
+   :backlinks: top
+
 Optional Static Typing
 ----------------------
 Ravi allows you to annotate ``local`` variables and function parameters with static types. The supported types and the resulting behaviour are as follows:
@@ -156,7 +160,8 @@ The scenarios where these type annotations have an impact are:
 ``closure``
   denotes a function
 Name
-  Denotes a value that has a `metatable registered under Name <https://www.lua.org/pil/28.2.html>`_ in the Lua registry. The Name must be a valid Lua name - hence periods in the name are not allowed. 
+  Denotes a value that has a `metatable registered under Name <https://www.lua.org/pil/28.2.html>`_ in the Lua registry. 
+  The Name must be a valid Lua name with the exception that periods are allowed in the name. 
 
 The main use case for these annotations is to help with type checking of larger Ravi programs. These type checks, particularly the one for user defined types, are executed directly by the VM and hence are more efficient than performing the checks in other ways.