Merge pull request #1381 from gradha/pr_links_echo_variants

Hyperlinks echo variants with noSideEffect pragma. Refs #1379.

doc/manual.txt

@@ -4970,9 +4970,9 @@ or ``ref T`` or ``ptr T`` this means no locations are modified. It is a static
 error to mark a proc/iterator to have no side effect if the compiler cannot
 verify this.
 
-As a special semantic rule, the built-in ``debugEcho`` pretends to be free of 
+As a special semantic rule, the built-in `debugEcho <system.html#debugEcho>`_
-side effects, so that it can be used for debugging routines marked as
+pretends to be free of side effects, so that it can be used for debugging
-``noSideEffect``.
+routines marked as ``noSideEffect``.
 
 **Future directions**: ``func`` may become a keyword and syntactic sugar for a
 proc with no side effects:

lib/system.nim

@@ -2026,19 +2026,25 @@ elif hostOS != "standalone":
   {.pop.}
 
 proc echo*[T](x: varargs[T, `$`]) {.magic: "Echo", tags: [FWriteIO], gcsafe.}
-  ## special built-in that takes a variable number of arguments. Each argument
+  ## Writes and flushes the parameters to the standard output.
+  ##
+  ## Special built-in that takes a variable number of arguments. Each argument
   ## is converted to a string via ``$``, so it works for user-defined
   ## types that have an overloaded ``$`` operator.
   ## It is roughly equivalent to ``writeln(stdout, x); flush(stdout)``, but
   ## available for the JavaScript target too.
+  ##
   ## Unlike other IO operations this is guaranteed to be thread-safe as
-  ## ``echo`` is very often used for debugging convenience.
+  ## ``echo`` is very often used for debugging convenience. If you want to use
+  ## ``echo`` inside a `proc without side effects
+  ## <manual.html#nosideeffect-pragma>`_ you can use `debugEcho <#debugEcho>`_
+  ## instead.
 
 proc debugEcho*[T](x: varargs[T, `$`]) {.magic: "Echo", noSideEffect, 
                                          tags: [], raises: [].}
-  ## Same as ``echo``, but as a special semantic rule, ``debugEcho`` pretends
+  ## Same as `echo <#echo>`_, but as a special semantic rule, ``debugEcho``
-  ## to be free of side effects, so that it can be used for debugging routines
+  ## pretends to be free of side effects, so that it can be used for debugging
-  ## marked as ``noSideEffect``.
+  ## routines marked as `noSideEffect <manual.html#nosideeffect-pragma>`_.
 
 template newException*(exceptn: typedesc, message: string): expr =
   ## creates an exception object of type ``exceptn`` and sets its ``msg`` field