documentation improvements

doc/docs.txt

@@ -31,5 +31,5 @@ The documentation consists of several documents:
     this if you want to hack the compiler.
 
 - | `Index <theindex.html>`_
-  | The generated index. Often the quickest way to find the piece of
-    information you need.
+  | The generated index. **Index + (Ctrl+F) == Joy**
+

doc/manual.txt

@@ -193,18 +193,19 @@ contain the following `escape sequences`:idx:\ :
   ``\\``                   `backslash`:idx:
   ``\"``                   `quotation mark`:idx:
   ``\'``                   `apostrophe`:idx:
-  ``\d+``                  `character with decimal value d`:idx:;
+  ``\`` '0'..'9'+          `character with decimal value d`:idx:;
                            all decimal digits directly
                            following are used for the character
   ``\a``                   `alert`:idx:
   ``\b``                   `backspace`:idx:
   ``\e``                   `escape`:idx: `[ESC]`:idx:
-  ``\xHH``                 `character with hex value HH`:idx:;
+  ``\x`` HH                `character with hex value HH`:idx:;
                            exactly two hex digits are allowed
 ==================         ===================================================
 
 
-Strings in Nimrod may contain any 8-bit value, except embedded zeros.
+Strings in Nimrod may contain any 8-bit value, even embedded zeros. However 
+some operations may interpret the first binary zero as terminator.
 
 
 Triple quoted string literals
@@ -947,44 +948,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:
-
-.. 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.
+
+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
 ~~~~~~~~~~~~~~~
@@ -1750,17 +1751,17 @@ 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 ``'`'``:
-
-.. 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:
+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
@@ -2809,7 +2810,7 @@ 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 {.
+  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

doc/tut1.txt

@@ -17,11 +17,13 @@ Introduction
 
 
 This document is a tutorial for the programming language *Nimrod*. After this
-tutorial you will have a decent knowledge about Nimrod. This tutorial assumes
+tutorial you will have a decent knowledge of Nimrod. This tutorial assumes
 that you are familiar with basic programming concepts like variables, types
 or statements.
 
 
+
+
 The first program
 =================
 
@@ -44,10 +46,15 @@ appending them after the filename::
 
   nimrod compile --run greetings.nim arg1 arg2
 
-The most used commands and switches have abbreviations, so you can also use::
+Commonly used commands and switches have abbreviations, so you can also use::
 
   nimrod c -r greetings.nim
 
+To compile a `release`:idx: version use::
+  
+  nimrod c -d:release greetings.nim
+
+
 Though it should be pretty obvious what the program does, I will explain the
 syntax: statements which are not indented are executed when the program
 starts. Indentation is Nimrod's way of grouping statements. Indentation is