Merge pull request #9061 from kaushalmodi/nims-update

Minor edits to NimScript (nims) docs

doc/nims.rst

@@ -4,39 +4,56 @@
 
 Strictly speaking, ``NimScript`` is the subset of Nim that can be evaluated
 by Nim's builtin virtual machine (VM). This VM is used for Nim's compiletime
-function evaluation features, but also replaces Nim's existing configuration
+function evaluation features.
-system.
 
-So instead of a ``myproject.nim.cfg`` configuration file, you can use
+You can use a ``<myproject>.nims`` file that simply contains Nim code
-a ``myproject.nims`` file that simply contains Nim code controlling the
+controlling the compilation process. For a directory wide
-compilation process. For a directory wide configuration, use ``config.nims``
+configuration, use ``config.nims`` instead of ``<myproject>.nims``.
-instead of ``nim.cfg``.
 
-The VM cannot deal with ``importc``, the FFI is not available, so there are not
+The VM cannot deal with ``importc`` because the FFI is not
-many stdlib modules that you can use with Nim's VM. However, at least the
+available. So the stdlib modules using ``importc`` cannot be used with
-following modules are available:
+Nim's VM. However, at least the following modules are available:
 
-* `strutils <strutils.html>`_
+* `macros <macros.html>`_
 * `ospaths <ospaths.html>`_
+* `strutils <strutils.html>`_
 * `math <math.html>`_
 * `distros <distros.html>`_
 
-The `system <system.html>`_ module in NimScript mode additionally supports
+In addition to the standard Nim syntax (`system <system.html>`_
-these operations: `nimscript <nimscript.html>`_.
+module), NimScripts support the procs and templates defined in the
+`nimscript <nimscript.html>`_ module too.
 
 
 NimScript as a configuration file
 =================================
 
-What is ``x.y.key = "value"`` in the configuration file
+A command-line switch ``--FOO`` is written as ``switch("FOO")`` in
-becomes ``switch("x.y.key", "value")``. ``--option`` is ``switch("option")``.
+NimScript. Similarly, command-line ``--FOO:VAL`` translates to
-The ``system`` module also exports 2 ``--`` templates for convenience:
+``switch("FOO", "VAL")``.
+
+Here are few examples of using the ``switch`` proc:
 
 .. code-block:: nim
-  --forceBuild
+  # command-line: --opt:size
-  # is the same as:
+  switch("opt", "size")
+  # command-line: --define:foo or -d:foo
+  switch("define", "foo")
+  # command-line: --forceBuild
   switch("forceBuild")
 
+*Note that specifically the ``-d:release`` define cannot be set using
+``switch`` in NimScripts.*
+
+NimScripts also support ``--`` templates for convenience, which look
+like command-line switches written as-is in the NimScript file. So the
+above example can be rewritten as:
+
+.. code-block:: nim
+  --opt:size
+  --define:foo
+  --forceBuild
+
 
 NimScript as a build tool
 =========================
@@ -91,7 +108,7 @@ Standalone NimScript
 
 NimScript can also be used directly as a portable replacement for Bash and
 Batch files. Use ``nim e myscript.nims`` to run ``myscript.nims``. For example,
-installation of Nimble is done with this simple script:
+installation of Nimble could be accomplished with this simple script:
 
 .. code-block:: nim