documentation improvements

1 files changed, 56 insertions, 14 deletions

diff --git a/doc/manual.txt b/doc/manual.txt
index 6671d5875..06accc953 100755
--- a/doc/manual.txt
+++ b/doc/manual.txt
@@ -533,11 +533,11 @@ The IEEE standard defines five types of floating-point exceptions:
   precision, for example, 2.0 / 3.0, log(1.1) and 0.1 in input.

 

 The IEEE exceptions are either ignored at runtime or mapped to the 

-Nimrod exceptions: `EFloatInvalidOp`:idx, `EFloatDivByZero`:idx:,

-`EFloatOverflow`:idx:, `EFloatUnderflow`:idx:, and `EFloatInexact`:idx:\. 

+Nimrod exceptions: `EFloatInvalidOp`:idx:, `EFloatDivByZero`:idx:,

+`EFloatOverflow`:idx:, `EFloatUnderflow`:idx:, and `EFloatInexact`:idx:. 

 These exceptions inherit from the `EFloatingPoint`:idx: base class.

 

-Nimrod provides the pragmas `NaNChecks`:idx and `InfChecks`:idx:\ to control

+Nimrod provides the pragmas `NaNChecks`:idx: and `InfChecks`:idx: to control

 whether the IEEE exceptions are ignored or trap a Nimrod exception:

 

 .. code-block:: nimrod

@@ -947,13 +947,44 @@ To deal with untraced memory, the procedures ``alloc``, ``dealloc`` and
 further information.

 

 If a reference points to *nothing*, it has the value ``nil``.

-

-Special care has to be taken if an untraced object contains traced objects like

-traced references, strings or sequences: in order to free everything properly,

-the built-in procedure ``GCunref`` has to be called before freeing the

-untraced memory manually!

+
+Special care has to be taken if an untraced object contains traced objects like
+traced references, strings or sequences: in order to free everything properly,
+the built-in procedure ``GCunref`` has to be called before freeing the untraced
+memory manually:
+
+.. code-block:: nimrod
+  type
+    TData = tuple[x, y: int, s: string]
+
+  # allocate memory for TData on the heap:
+  var d = cast[ptr TData](alloc0(sizeof(TData)))
+
+  # create a new string on the garbage collected heap:
+  d.s = "abc"
+
+  # tell the GC that the string is not needed anymore:
+  GCunref(d.s)
+
+  # free the memory:
+  dealloc(d)
+
+Without the ``GCunref`` call the memory allocated for the ``d.s`` string would
+never be freed. The example also demonstrates two important features for low
+level programming: the ``sizeof`` proc returns the size of a type or value
+in bytes. The ``cast`` operator can circumvent the type system: the compiler
+is forced to treat the result of the ``alloc0`` call (which returns an untyped
+pointer) as if it would have the type ``ptr TData``. Casting should only be
+done if it is unavoidable: it breaks type safety and bugs can lead to
+mysterious crashes.
+
+**Note**: The example only works because the memory is initialized with zero
+(``alloc0`` instead of ``alloc`` does this): ``d.s`` is thus initialized to
+``nil`` which the string assignment can handle. You need to know low level
+details like this when mixing garbage collected data with unmanaged memory.
 

 .. XXX finalizers for traced objects

+
 

 Procedural type

 ~~~~~~~~~~~~~~~

@@ -1719,8 +1750,18 @@ Syntax::
 The direct embedding of `assembler`:idx: code into Nimrod code is supported

 by the unsafe ``asm`` statement. Identifiers in the assembler code that refer to

 Nimrod identifiers shall be enclosed in a special character which can be

-specified in the statement's pragmas. The default special character is ``'`'``.

-

+specified in the statement's pragmas. The default special character is ``'`'``:
+
+.. code-block:: nimrod
+  proc addInt(a, b: int): int {.pure.} =
+    # a in eax, and b in edx
+    asm """
+        mov eax, `a`
+        add eax, `b`
+        jno theEnd
+        call `raiseOverflow`
+      theEnd:
+    """

 

 If expression

 ~~~~~~~~~~~~~

@@ -1729,7 +1770,7 @@ An `if expression` is almost like an if statement, but it is an expression.
 Example:

 

 .. code-block:: nimrod

-  p(if x > 8: 9 else: 10)

+  var y = if x > 8: 9 else: 10

 

 An if expression always results in a value, so the ``else`` part is

 required. ``Elif`` parts are also allowed (but unlikely to be good

@@ -2040,7 +2081,7 @@ convention ``inline``.
 

 If the iterator yields a tuple, there have to be as many iteration variables

 as there are components in the tuple. The i'th iteration variable's type is

-the one of the i'th component.

+the type of the i'th component.

 

 

 Type sections

@@ -2213,7 +2254,7 @@ special ``:`` syntax:
 In the example the two ``writeln`` statements are bound to the ``actions``

 parameter. 

 

-**Note:** Symbol binding rules in templates might change!

+**Note:** Symbol binding rules for templates might change!

 

 Symbol binding within templates happens after template instantation: 

 

@@ -2768,7 +2809,8 @@ a dynamic library (``.dll`` files for Windows, ``lib*.so`` files for UNIX). The
 non-optional argument has to be the name of the dynamic library:

 

 .. code-block:: Nimrod

-  proc gtk_image_new(): PGtkWidget {.cdecl, dynlib: "libgtk-x11-2.0.so", importc.}

+  proc gtk_image_new(): PGtkWidget {.
+    cdecl, dynlib: "libgtk-x11-2.0.so", importc.}

 

 In general, importing a dynamic library does not require any special linker

 options or linking with import libraries. This also implies that no *devel*