documentation improvements

1 files changed, 52 insertions, 51 deletions

diff --git a/doc/manual.txt b/doc/manual.txt
index 06accc953..7c0619ba7 100755
--- a/doc/manual.txt
+++ b/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