documentation improvements

7 files changed, 73 insertions, 71 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*

diff --git a/doc/tut1.txt b/doc/tut1.txt
index bb37bd84d..a06696878 100755
--- a/doc/tut1.txt
+++ b/doc/tut1.txt
@@ -10,7 +10,11 @@ Nimrod Tutorial (Part I)
 Introduction
 ============
 
-  "Der Mensch ist doch ein Augentier -- schöne Dinge wünsch ich mir."
+.. raw:: html
+  <blockquote><p>
+  "Der Mensch ist doch ein Augentier -- sch&ouml;ne Dinge w&uuml;nsch ich mir."
+  </p></blockquote>
+
 
 This document is a tutorial for the programming language *Nimrod*. After this
 tutorial you will have a decent knowledge about Nimrod. This tutorial assumes
@@ -91,8 +95,7 @@ means tabulator, etc. There are also *raw* string literals:
 .. code-block:: Nimrod
   r"C:\program files\nim"
 
-In raw literals the backslash is not an escape character, so they fit
-the principle *what you see is what you get*.
+In raw literals the backslash is not an escape character.
 
 The third and last way to write string literals are *long string literals*.
 They are written with three quotes: ``""" ... """``; they can span over
@@ -121,7 +124,7 @@ aligned to the preceding one, it does not start a new comment:
 
 Comments are tokens; they are only allowed at certain places in the input file
 as they belong to the syntax tree! This feature enables perfect source-to-source
-transformations (such as pretty-printing) and superior documentation generators.
+transformations (such as pretty-printing) and simpler documentation generators.
 A nice side-effect is that the human reader of the code always knows exactly
 which code snippet the comment refers to. Since comments are a proper part of
 the syntax, watch their indentation:
@@ -613,7 +616,7 @@ specify them:
 Now the call to ``createWindow`` only needs to set the values that differ
 from the defaults.
 
-Note that type inference works for parameters with default values, there is
+Note that type inference works for parameters with default values; there is
 no need to write ``title: string = "unknown"``, for example.
 
 
@@ -806,7 +809,7 @@ a sequence of bytes. The index operation ``s[i]`` means the i-th *char* of
 
 String variables are initialized with a special value, called ``nil``. However,
 most string operations cannot deal with ``nil`` (leading to an exception being
-raised) for performance reasons. Thus one should use empty strings ``""``
+raised) for performance reasons. One should use empty strings ``""``
 rather than ``nil`` as the *empty* value. But ``""`` often creates a string
 object on the heap, so there is a trade-off to be made here.
 
@@ -1025,7 +1028,7 @@ operation             meaning
 ==================    ========================================================
 
 Sets are often used to define a type for the *flags* of a procedure. This is
-much cleaner (and type safe) solution than just defining integer
+a much cleaner (and type safe) solution than just defining integer
 constants that should be ``or``'ed together.
 
 
@@ -1034,8 +1037,7 @@ Arrays
 An `array`:idx: is a simple fixed length container. Each element in
 the array has the same type. The array's index type can be any ordinal type.
 
-Arrays can be constructed via the array constructor: ``[]`` is the empty
-array. The constructor can also be used to include elements.
+Arrays can be constructed via ``[]``: 
 
 .. code-block:: nimrod
 
@@ -1199,41 +1201,6 @@ 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.
-
 
 Procedural type
 ---------------
diff --git a/install.txt b/install.txt
index 048cf8f98..eeea387f9 100755
--- a/install.txt
+++ b/install.txt
@@ -36,9 +36,9 @@ Installation on the Macintosh
 -----------------------------
 
 Only MacOS X is supported.
-Since MacOS X is UNIX based too, it works like the installation on Linux. You
-need to install Apple's developer's tools for the GNU Compiler Collection
-though.
+Since MacOS X is UNIX based too, it works like the installation on Linux. 
+However, for unknown reasons the symbolic link method does not work MacOS X. 
+You need to install Apple's developer's tools for the GNU Compiler Collection.
 
 
 Installation on Windows
diff --git a/lib/system/alloc.nim b/lib/system/alloc.nim
index 840107440..0e0b450b4 100755
--- a/lib/system/alloc.nim
+++ b/lib/system/alloc.nim
@@ -329,7 +329,6 @@ proc ListRemove[T](head: var T, c: T) {.inline.} =
   
 proc isSmallChunk(c: PChunk): bool {.inline.} = 
   return c.size <= SmallChunkSize-smallChunkOverhead()
-  #return c.size < SmallChunkSize
   
 proc chunkUnused(c: PChunk): bool {.inline.} = 
   result = not c.used
@@ -377,9 +376,6 @@ proc freeBigChunk(a: var TAllocator, c: PBigChunk) =
 proc splitChunk(a: var TAllocator, c: PBigChunk, size: int) = 
   var rest = cast[PBigChunk](cast[TAddress](c) +% size)
   assert(rest notin a.freeChunksList)
-  #  c_fprintf(c_stdout, "to add: %p\n", rest)
-  #  writeFreeList(allocator)
-  #  assert false
   rest.size = c.size - size
   rest.used = false
   rest.next = nil
@@ -397,14 +393,11 @@ proc getBigChunk(a: var TAllocator, size: int): PBigChunk =
   result = a.freeChunksList
   block search:
     while result != nil:
-      #if not chunkUnused(result): 
-      #  c_fprintf(c_stdout, "%lld\n", int(result.used))
       assert chunkUnused(result)
       if result.size == size: 
         ListRemove(a.freeChunksList, result)
         break search
       elif result.size > size:
-        #c_fprintf(c_stdout, "res size: %lld; size: %lld\n", result.size, size)
         ListRemove(a.freeChunksList, result)
         splitChunk(a, result, size)
         break search
diff --git a/readme.txt b/readme.txt
index 56821bece..aedf922b9 100755
--- a/readme.txt
+++ b/readme.txt
@@ -17,5 +17,5 @@ priority).
 See the file ``install.txt`` for installation instructions. See the file

 ``doc/intern.txt`` for the internal documentation for developers.

 

-Copyright (c) 2004-2010 Andreas Rumpf.

+Copyright (c) 2004-2011 Andreas Rumpf.

 All rights reserved.

diff --git a/rod/astalgo.nim b/rod/astalgo.nim
index 27e3ccfea..a4a6ec06e 100755
--- a/rod/astalgo.nim
+++ b/rod/astalgo.nim
@@ -194,7 +194,7 @@ proc toYamlChar(c: Char): string =
   of '\'', '\"', '\\': result = '\\' & c
   else: result = c & ""
   
-proc makeYamlString(s: string): PRope = 
+proc makeYamlString*(s: string): PRope = 
   # We have to split long strings into many ropes. Otherwise
   # this could trigger InternalError(111). See the ropes module for
   # further information.
diff --git a/rod/commands.nim b/rod/commands.nim
index 740d349c2..ef7f04eb8 100755
--- a/rod/commands.nim
+++ b/rod/commands.nim
@@ -280,7 +280,7 @@ proc addPath(path: string, info: TLineInfo) =
 
 proc addPathRec(dir: string, info: TLineInfo) =
   var pos = dir.len-1
-  if dir[pos] == '/': inc(pos)
+  if dir[pos] in {DirSep, AltSep}: inc(pos)
   for k,p in os.walkDir(dir):
     if k == pcDir and p[pos] != '.':
       addPathRec(p, info)