[other] Documentation NimScript (#11548)

* Documentation of NimScript, update and expand, mention the benefits aside of its limitations, add examples, update the list of usable std lib modules

doc/nims.rst

@@ -28,8 +28,9 @@ previous settings):
 
 For available procs and implementation details see `nimscript <nimscript.html>`_.
 
+
 Limitations
-=================================
+===========
 
 NimScript is subject to some limitations caused by the implementation of the VM
 (virtual machine):
@@ -47,18 +48,50 @@ NimScript is subject to some limitations caused by the implementation of the VM
 * More than one level of `ref` is generally not supported (for example, the type
   `ref ref int`).
 
-* multimethods are not available.
+* Multimethods are not available.
 
-Given the above restrictions, at least the following modules are available:
+* ``random.randomize()`` requires an ``int64`` explicitly passed as argument, you *must* pass a Seed integer.
+
+* ``unicode`` can be imported, but not ``unidecode``.
+
+
+Standard library modules
+========================
+
+At least the following standard library modules are available:
 
 * `macros <macros.html>`_
 * `os <os.html>`_
 * `strutils <strutils.html>`_
 * `math <math.html>`_
 * `distros <distros.html>`_
+* `sugar <sugar.html>`_
+* `algorithm <algorithm.html>`_
+* `base64 <base64.html>`_
+* `bitops <bitops.html>`_
+* `chains <chains.html>`_
+* `colors <colors.html>`_
+* `complex <complex.html>`_
+* `htmlgen <htmlgen.html>`_
+* `httpcore <httpcore.html>`_
+* `lenientops <lenientops.html>`_
+* `mersenne <mersenne.html>`_
+* `options <options.html>`_
+* `parseutils <parseutils.html>`_
+* `punycode <punycode.html>`_
+* `random <punycode.html>`_
+* `stats <stats.html>`_
+* `strformat <strformat.html>`_
+* `strmisc <strmisc.html>`_
+* `strscans <strscans.html>`_
+* `unicode <unicode.html>`_
+* `uri <uri.html>`_
+* `std/editdistance <editdistance.html>`_
+* `std/wordwrap <wordwrap.html>`_
+* `std/sums <sums.html>`_
 
-In addition to the standard Nim syntax (`system <system.html>`_
+In addition to the standard Nim syntax (`system <system.html>`_ module),
-module), NimScripts support the procs and templates defined in the
+NimScripts support the procs and templates defined in the
 `nimscript <nimscript.html>`_ module too.
 
 
@@ -130,8 +163,6 @@ See the `Nimble readme <https://github.com/nim-lang/nimble#readme>`_
 for more information.
 
 
-
-
 Standalone NimScript
 ====================
 
@@ -165,3 +196,136 @@ ends with ``.nims``:
   echo "hello world"
 
 Use ``#!/usr/bin/env -S nim --hints:off`` to disable hints.
+
+
+Benefits
+========
+
+Cross-Platform
+--------------
+
+It is a cross-platform scripting language that can run where Nim can run,
+e.g. you can not run Batch or PowerShell on Linux or Mac,
+the Bash for Linux might not run on Mac,
+there are no unit tests tools for Batch, etc.
+
+NimScript can detect on which platform, operating system,
+architecture, and even which Linux distribution is running on,
+allowing the same script to support a lot of systems.
+
+See the following (incomplete) example:
+
+.. code-block:: nim
+
+  import distros
+
+  # Architectures.
+  if defined(amd64):
+    echo "Architecture is x86 64Bits"
+  elif defined(i386):
+    echo "Architecture is x86 32Bits"
+  elif defined(arm):
+    echo "Architecture is ARM"
+
+  # Operating Systems.
+  if defined(linux):
+    echo "Operating System is GNU Linux"
+  elif defined(windows):
+    echo "Operating System is Microsoft Windows"
+  elif defined(macosx):
+    echo "Operating System is Apple OS X"
+
+  # Distros.
+  if detectOs(Ubuntu):
+    echo "Distro is Ubuntu"
+  elif detectOs(ArchLinux):
+    echo "Distro is ArchLinux"
+  elif detectOs(Debian):
+    echo "Distro is Debian"
+
+
+Uniform Syntax
+--------------
+
+The syntax, style, and rest of the ecosystem is the same as for compiled Nim,
+that means there is nothing new to learn, no context switch for developers.
+
+
+Powerful Metaprogramming
+------------------------
+
+NimScript can use Nim's templates, macros, types, concepts, effect tracking system, and more,
+you can create modules that work on compiled Nim and also on interpreted NimScript.
+
+``func`` will still check for side effects, ``debugEcho`` also works as expected,
+making it ideal for functional scripting metaprogramming.
+
+This is an example of a third party module that uses macros and templates to
+translate text strings on unmodified NimScript:
+
+.. code-block:: nim
+
+  import nimterlingua
+  nimterlingua("translations.cfg")
+  echo "cat"  # Run with -d:RU becomes "kot", -d:ES becomes "gato", ...
+
+translations.cfg
+
+.. code-block:: none
+
+  [cat]
+  ES = gato
+  PT = minino
+  RU = kot
+  FR = chat
+
+
+* `Nimterlingua <https://nimble.directory/pkg/nimterlingua>`_
+
+
+Graceful Fallback
+-----------------
+
+Some features of compiled Nim may not work on NimScript,
+but often a graceful and seamless fallback degradation is used.
+
+See the following NimScript:
+
+.. code-block:: nim
+
+  if likely(true):
+    discard
+  elif unlikely(false):
+    discard
+
+  proc foo() {.compiletime.} = echo NimVersion
+
+  static:
+    echo CompileDate
+
+
+``likely()``, ``unlikely()``, ``static:`` and ``{.compiletime.}``
+will produce no code at all when run on NimScript,
+but still no error nor warning is produced and the code just works.
+
+Evolving Scripting language
+---------------------------
+
+NimScript evolves together with Nim,
+`occasionally new features might become available on NimScript <https://github.com/nim-lang/Nim/pulls?utf8=%E2%9C%93&q=nimscript>`_ ,
+adapted from compiled Nim or added as new features on both.
+
+Scripting Language with a Package Manager
+-----------------------------------------
+
+You can create your own modules to be compatible with NimScript,
+and check `Nimble <https://nimble.directory>`_
+to search for third party modules that may work on NimScript.
+
+DevOps Scripting
+----------------
+
+You can use NimScript to deploy to production, run tests, build projects, do benchmarks,
+generate documentation, and all kinds of DevOps/SysAdmin specific tasks.
+
+* `An example of a third party NimScript that can be used as a project-agnostic tool. <https://github.com/kaushalmodi/nim_config#list-available-tasks>`_