Merge remote-tracking branch 'upstream/devel' into test-7010

6 files changed, 107 insertions, 87 deletions

diff --git a/doc/apis.txt b/doc/apis.rst
index 277c1925b..277c1925b 100644
--- a/doc/apis.txt
+++ b/doc/apis.rst
diff --git a/doc/backends.txt b/doc/backends.rst
index 13ef7bf4d..13ef7bf4d 100644
--- a/doc/backends.txt
+++ b/doc/backends.rst
diff --git a/doc/intern.txt b/doc/intern.rst
index b253cac42..b253cac42 100644
--- a/doc/intern.txt
+++ b/doc/intern.rst
diff --git a/doc/lib.rst b/doc/lib.rst
index f0569070d..bfb7306fb 100644
--- a/doc/lib.rst
+++ b/doc/lib.rst
@@ -425,7 +425,7 @@ Miscellaneous
   Turns access violations or segfaults into a ``NilAccessError`` exception.
 
 Modules for JS backend
----------------------------
+----------------------
 
 * `dom <dom.html>`_
   Declaration of the Document Object Model for the JS backend.
@@ -440,30 +440,6 @@ Modules for JS backend
   Wrapper of core JavaScript functions. For most purposes you should be using
   the ``math``, ``json``, and ``times`` stdlib modules instead of this module.
 
-Deprecated modules
-------------------
-
-* `asyncio <asyncio.html>`_
-  This module implements an asynchronous event loop for sockets.
-  **Deprecated since version 0.11.2:**
-  Use the `asyncnet <asyncnet.html>`_ together with the
-  `asyncdispatch <asyncdispatch.html>`_ module instead.
-
-* `ftpclient <ftpclient.html>`_
-  This module implements an FTP client.
-  **Deprecated since version 0.11.3:**
-  Use the `asyncftpclient <asyncftpclient.html>`_ module instead.
-
-* `sockets <sockets.html>`_
-  This module implements a simple portable type-safe sockets layer.
-  **Deprecated since version 0.11.2:**
-  Use the `net <net.html>`_ or the `rawsockets <rawsockets.html>`_ module
-  instead.
-
-* `rawsockets <rawsockets.html>`_
-  **Deprecated since version 0.11.4:**
-  This module has been renamed to `nativesockets <nativesockets.html>`_.
-
 
 Impure libraries
 ================
@@ -475,9 +451,6 @@ Regular expressions
   This module contains procedures and operators for handling regular
   expressions. The current implementation uses PCRE.
 
-* `nre <nre.html>`_
-  Another implementation of procedures for using regular expressions. Also uses
-  PCRE.
 
 
 Database support
diff --git a/doc/manual.rst b/doc/manual.rst
index 6dc6794f1..7946e88dd 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -6534,6 +6534,111 @@ iterator in which case the overloading resolution takes place:
   var x = 4
   write(stdout, x) # not ambiguous: uses the module C's x
 
+Code reordering
+~~~~~~~~~~~~~~~
+
+**Note**: Code reordering is experimental and must be enabled via the
+``{.experimental.}`` pragma.
+
+The code reordering feature can implicitly rearrange procedure, template, and
+macro definitions along with variable declarations and initializations at the top
+level scope so that, to a large extent, a programmer should not have to worry
+about ordering definitions correctly or be forced to use forward declarations to
+preface definitions inside a module.
+
+..
+   NOTE: The following was documentation for the code reordering precursor,
+   which was {.noForward.}.
+   
+   In this mode, procedure definitions may appear out of order and the compiler
+   will postpone their semantic analysis and compilation until it actually needs
+   to generate code using the definitions. In this regard, this mode is similar
+   to the modus operandi of dynamic scripting languages, where the function
+   calls are not resolved until the code is executed. Here is the detailed
+   algorithm taken by the compiler:
+
+   1. When a callable symbol is first encountered, the compiler will only note
+   the symbol callable name and it will add it to the appropriate overload set
+   in the current scope. At this step, it won't try to resolve any of the type
+   expressions used in the signature of the symbol (so they can refer to other
+   not yet defined symbols).
+
+   2. When a top level call is encountered (usually at the very end of the
+   module), the compiler will try to determine the actual types of all of the
+   symbols in the matching overload set. This is a potentially recursive process
+   as the signatures of the symbols may include other call expressions, whose
+   types will be resolved at this point too.
+
+   3. Finally, after the best overload is picked, the compiler will start
+   compiling the body of the respective symbol. This in turn will lead the
+   compiler to discover more call expressions that need to be resolved and steps
+   2 and 3 will be repeated as necessary.
+
+   Please note that if a callable symbol is never used in this scenario, its
+   body will never be compiled. This is the default behavior leading to best
+   compilation times, but if exhaustive compilation of all definitions is
+   required, using ``nim check`` provides this option as well.
+
+Example:
+
+.. code-block:: nim
+
+  {.experimental: "codeReordering".}
+
+  proc foo(x: int) =
+    bar(x)
+
+  proc bar(x: int) =
+    echo(x)
+
+  foo(10)
+
+Variables can also be reordered as well. Variables that are *initialized* (i.e.
+variables that have their declaration and assignment combined in a single
+statement) can have their entire initialization statement reordered. Be wary of
+what code is executed at the top level:
+
+.. code-block:: nim
+  {.experimental: "codeReordering".}
+
+  proc a() =
+    echo(foo)
+
+  var foo = 5
+
+  a() # outputs: "5"
+
+..
+   TODO: Let's table this for now. This is an *experimental feature* and so the
+   specific manner in which ``declared`` operates with it can be decided in
+   eventuality, because right now it works a bit weirdly.
+
+   The values of expressions involving ``declared`` are decided *before* the
+   code reordering process, and not after. As an example, the output of this
+   code is the same as it would be with code reordering disabled.
+
+   .. code-block:: nim
+     {.experimental: "codeReordering".}
+
+     proc x() =
+       echo(declared(foo))
+
+     var foo = 4
+
+     x() # "false"
+
+It is important to note that reordering *only* works for symbols at top level
+scope. Therefore, the following will *fail to compile:*
+
+.. code-block:: nim
+  {.experimental: "codeReordering".}
+
+  proc a() =
+    b()
+    proc b() =
+      echo("Hello!")
+
+  a()
 
 Compiler Messages
 =================
@@ -6943,55 +7048,6 @@ the created global variables within a module is not defined, but all of them
 will be initialized after any top-level variables in their originating module
 and before any variable in a module that imports it.
 
-
-..
-  NoForward pragma
-  ----------------
-  The ``noforward`` pragma can be used to turn on and off a special compilation
-  mode that to large extent eliminates the need for forward declarations. In this
-  mode, the proc definitions may appear out of order and the compiler will postpone
-  their semantic analysis and compilation until it actually needs to generate code
-  using the definitions. In this regard, this mode is similar to the modus operandi
-  of dynamic scripting languages, where the function calls are not resolved until
-  the code is executed. Here is the detailed algorithm taken by the compiler:
-
-  1. When a callable symbol is first encountered, the compiler will only note the
-  symbol callable name and it will add it to the appropriate overload set in the
-  current scope. At this step, it won't try to resolve any of the type expressions
-  used in the signature of the symbol (so they can refer to other not yet defined
-  symbols).
-
-  2. When a top level call is encountered (usually at the very end of the module),
-  the compiler will try to determine the actual types of all of the symbols in the
-  matching overload set. This is a potentially recursive process as the signatures
-  of the symbols may include other call expressions, whose types will be resolved
-  at this point too.
-
-  3. Finally, after the best overload is picked, the compiler will start
-  compiling the body of the respective symbol. This in turn will lead the
-  compiler to discover more call expressions that need to be resolved and steps
-  2 and 3 will be repeated as necessary.
-
-  Please note that if a callable symbol is never used in this scenario, its body
-  will never be compiled. This is the default behavior leading to best compilation
-  times, but if exhaustive compilation of all definitions is required, using
-  ``nim check`` provides this option as well.
-
-  Example:
-
-  .. code-block:: nim
-
-    {.noforward: on.}
-
-    proc foo(x: int) =
-      bar x
-
-    proc bar(x: int) =
-      echo x
-
-    foo(10)
-
-
 pragma pragma
 -------------
 
diff --git a/doc/tools.txt b/doc/tools.rst
index 070deb806..6757621fb 100644
--- a/doc/tools.txt
+++ b/doc/tools.rst
@@ -5,7 +5,7 @@ Tools available with Nim
 The standard distribution ships with the following tools:
 
 - | `Documentation generator <docgen.html>`_
-  | The builtin document generator ``nim doc2`` generates HTML documentation
+  | The builtin document generator ``nim doc`` generates HTML documentation
     from ``.nim`` source files.
 
 - | `Nimsuggest for IDE support <nimsuggest.html>`_
@@ -13,17 +13,8 @@ The standard distribution ships with the following tools:
     and obtain useful information like definition of symbols or suggestions for
     completion.
 
-- | `Nim Installation Generator <niminst.html>`_
-  | How to generate a nice installer for your Nim program.
-
 - | `C2nim <c2nim.html>`_
   | C to Nim source converter. Translates C header files to Nim.
 
 - | `nimgrep <nimgrep.html>`_
   | Nim search and replace utility.
-
-- | `endb <endb.html>`_
-  | Nim's slow platform independent embedded debugger.
-
-- | `estp <estp.html>`_
-  | Nim's slow platform independent embedded stack trace profiler.