Moves addr out of tutorial into manual, indexing it too.

doc/manual.txt

@@ -2232,7 +2232,6 @@ Type casts
 ----------
 Example:
 
-
 .. code-block:: nimrod
   cast[int](x)
 
@@ -2243,11 +2242,27 @@ only needed for low-level programming and are inherently unsafe.
 
 The addr operator
 -----------------
-The `addr` operator returns the address of an l-value. If the
+The `addr`:idx: operator returns the address of an l-value. If the type of the
-type of the location is ``T``, the `addr` operator result is
+location is ``T``, the `addr` operator result is of the type ``ptr T``. An
-of the type ``ptr T``. Taking the address of an object that resides
+address is always an untraced reference. Taking the address of an object that
-on the stack is **unsafe**, as the pointer may live longer than the
+resides on the stack is **unsafe**, as the pointer may live longer than the
-object on the stack and can thus reference a non-existing object.
+object on the stack and can thus reference a non-existing object. You can get
+the address of variables, but you can't use it on variables declared through
+``let`` statements:
+
+.. code-block:: nimrod
+
+  let t1 = "Hello"
+  var
+    t2 = t1
+    t3 : pointer = addr(t2)
+  echo repr(addr(t2))
+  # --> ref 0x7fff6b71b670 --> 0x10bb81050"Hello"
+  echo cast[ptr string](t3)[]
+  # --> Hello
+  # The following line doesn't compile:
+  echo repr(addr(t1))
+  # Error: expression has no address
 
 
 Procedures

doc/tut1.txt

@@ -1304,13 +1304,9 @@ Traced references are declared with the **ref** keyword, untraced references
 are declared with the **ptr** keyword.
 
 The empty ``[]`` subscript notation can be used to *derefer* a reference,
-meaning to retrieve the item the reference points to. The ``addr`` operator 
+meaning to retrieve the item the reference points to. The ``.`` (access a
-returns the address of an item. An address is always an untraced reference:
+tuple/object field operator) and ``[]`` (array/string/sequence index operator)
-``addr`` is an *unsafe* feature.
+operators perform implicit dereferencing operations for reference types:
-
-The ``.`` (access a tuple/object field operator)
-and ``[]`` (array/string/sequence index operator) operators perform implicit
-dereferencing operations for reference types:
 
 .. code-block:: nimrod
 
@@ -1327,8 +1323,8 @@ dereferencing operations for reference types:
 
 To allocate a new traced object, the built-in procedure ``new`` has to be used.
 To deal with untraced memory, the procedures ``alloc``, ``dealloc`` and
-``realloc`` can be used. The documentation of the system module contains
+``realloc`` can be used. The documentation of the `system <system.html>`_
-further information.
+module contains further information.
 
 If a reference points to *nothing*, it has the value ``nil``.
 

lib/system.nim

@@ -38,7 +38,8 @@ type
   char* {.magic: Char.} ## built-in 8 bit character type (unsigned)
   string* {.magic: String.} ## built-in string type
   cstring* {.magic: Cstring.} ## built-in cstring (*compatible string*) type
-  pointer* {.magic: Pointer.} ## built-in pointer type
+  pointer* {.magic: Pointer.} ## built-in pointer type, use the ``addr``
+                              ## operator to get a pointer to a variable
 
 const
   on* = true    ## alias for ``true``