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

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

lib/core/marshal.nim

@@ -12,15 +12,31 @@
 
 import streams
 
-proc load*[T](s: PStream, data: var T) {.magic: "Load".}
+proc load*[T](s: PStream, data: var T) =
   ## loads `data` from the stream `s`. Raises `EIO` in case of an error.
 
-proc store*[T](s: PStream, data: T) {.magic: "Store".}
+proc store*[T](s: PStream, data: T) =
   ## stores `data` into the stream `s`. Raises `EIO` in case of an error.
 
 
-proc reprInt(x: int64): string {.compilerproc.} = return $x
-proc reprFloat(x: float): string {.compilerproc.} = return $x
+type
+  TTypeInfo = distinct whatever
+  
+  TValue = object
+    t: TTypeInfo
+    x: pointer
+    
+  
+proc rtti[T](x: T): TTypeInfo {.magic: "rtti".}
+
+proc `[]` (a: TValue, i: int): TValue = 
+  ## works for arrays, objects, etc.
+
+proc `[]=` (a: TValue, i: int, x: TValue) = 
+  ## 
+  
+
+
 
 proc reprPointer(x: pointer): string {.compilerproc.} =
   var buf: array [0..59, char]

lib/pure/os.nim

@@ -284,7 +284,7 @@ proc fileNewer*(a, b: string): bool {.rtl, extern: "nos$1".} =
   result = getLastModificationTime(a) - getLastModificationTime(b) > 0
 
 proc getCurrentDir*(): string {.rtl, extern: "nos$1".} =
-  ## Returns the current working directory.
+  ## Returns the `current working directory`:idx:.
   const bufsize = 512 # should be enough
   result = newString(bufsize)
   when defined(windows):
@@ -298,7 +298,7 @@ proc getCurrentDir*(): string {.rtl, extern: "nos$1".} =
       OSError()
 
 proc setCurrentDir*(newDir: string) {.inline.} =
-  ## Sets the current working directory; `EOS` is raised if
+  ## Sets the `current working directory`:idx:; `EOS` is raised if
   ## `newDir` cannot been set.
   when defined(Windows):
     if SetCurrentDirectoryA(newDir) == 0'i32: OSError()
@@ -661,7 +661,7 @@ proc executeShellCommand*(command: string): int {.deprecated.} =
   result = csystem(command)
 
 proc execShellCmd*(command: string): int {.rtl, extern: "nos$1".} =
-  ## Executes a shell command.
+  ## Executes a `shell command`:idx:.
   ##
   ## Command has the form 'program args' where args are the command
   ## line arguments given to program. The proc returns the error code
@@ -720,7 +720,7 @@ proc findEnvVar(key: string): int =
   return -1
 
 proc getEnv*(key: string): string =
-  ## Returns the value of the environment variable named `key`.
+  ## Returns the value of the `environment variable`:idx: named `key`.
   ##
   ## If the variable does not exist, "" is returned. To distinguish
   ## whether a variable exists or it's value is just "", call
@@ -740,7 +740,7 @@ proc existsEnv*(key: string): bool =
   else: return findEnvVar(key) >= 0
 
 proc putEnv*(key, val: string) =
-  ## Sets the value of the environment variable named `key` to `val`.
+  ## Sets the value of the `environment variable`:idx: named `key` to `val`.
   ## If an error occurs, `EInvalidEnvVar` is raised.
 
   # Note: by storing the string in the environment sequence,
@@ -770,15 +770,17 @@ iterator iterOverEnvironment*(): tuple[key, value: string] {.deprecated.} =
     yield (copy(environment[i], 0, p-1), copy(environment[i], p+1))
 
 iterator envPairs*(): tuple[key, value: string] =
-  ## Iterate over all environments variables. In the first component of the
-  ## tuple is the name of the current variable stored, in the second its value.
+  ## Iterate over all `environments variables`:idx:. In the first component 
+  ## of the tuple is the name of the current variable stored, in the second
+  ## its value.
   getEnvVarsC()
   for i in 0..high(environment):
     var p = find(environment[i], '=')
     yield (copy(environment[i], 0, p-1), copy(environment[i], p+1))
 
 iterator walkFiles*(pattern: string): string =
-  ## Iterate over all the files that match the `pattern`.
+  ## Iterate over all the files that match the `pattern`. On POSIX this uses
+  ## the `glob`:idx: call.
   ##
   ## `pattern` is OS dependant, but at least the "\*.ext"
   ## notation is supported.
@@ -914,7 +916,7 @@ proc rawCreateDir(dir: string) =
       OSError()
 
 proc createDir*(dir: string) {.rtl, extern: "nos$1".} =
-  ## Creates the directory `dir`.
+  ## Creates the `directory`:idx: `dir`.
   ##
   ## The directory may contain several subdirectories that do not exist yet.
   ## The full path is created. If this fails, `EOS` is raised. It does **not**
@@ -1122,13 +1124,13 @@ when defined(windows):
     ownArgv: seq[string]
 
   proc paramCount*(): int {.rtl, extern: "nos$1".} =
-    ## Returns the number of command line arguments given to the
+    ## Returns the number of `command line arguments`:idx: given to the
     ## application.
     if isNil(ownArgv): ownArgv = parseCmdLine($getCommandLineA())
     result = ownArgv.len-1
 
   proc paramStr*(i: int): string {.rtl, extern: "nos$1".} =
-    ## Returns the `i`-th command line argument given to the
+    ## Returns the `i`-th `command line argument`:idx: given to the
     ## application.
     ##
     ## `i` should be in the range `1..paramCount()`, else

lib/pure/strutils.nim

@@ -205,6 +205,7 @@ proc `%` *(formatstr: string, a: openarray[string]): string {.noSideEffect,
   ##
   ## The substitution variables (the thing after the ``$``) are enumerated
   ## from 1 to ``a.len``.
+  ## To produce a verbatim ``$``, use ``$$``.
   ## The notation ``$#`` can be used to refer to the next substitution variable:
   ##
   ## .. code-block:: nimrod

rod/docgen.nim

@@ -254,7 +254,7 @@ proc setIndexForSourceTerm(d: PDoc, name: PRstNode, id: int) =
 
 proc renderIndexTerm(d: PDoc, n: PRstNode): PRope = 
   inc(d.id)
-  result = dispF("<em id=\"$1\">$2</em>", "$2\\label{$1}", 
+  result = dispF("<span id=\"$1\">$2</span>", "$2\\label{$1}", 
                  [toRope(d.id), renderAux(d, n)])
   var h = newRstNode(rnHyperlink)
   var a = newRstNode(rnLeaf, d.indexValFilename & disp("#", "") & $d.id)
@@ -739,7 +739,7 @@ proc renderRstToOut(d: PDoc, n: PRstNode): PRope =
     result = renderAux(d, n, disp("<cite>$1</cite>", "\\emph{$1}"))
   of rnIdx: 
     if d.theIndex == nil: 
-      result = renderAux(d, n, disp("<em>$1</em>", "\\emph{$1}"))
+      result = renderAux(d, n, disp("<span>$1</span>", "\\emph{$1}"))
     else: 
       result = renderIndexTerm(d, n)
   of rnInlineLiteral: 

todo.txt

@@ -1,6 +1,7 @@
 - thread support: threadvar on Windows seems broken; 
   add --deadlock_prevention:on|off switch
 - built-in serialization
+- change how generalized raw string literals work
 
 - we need a way to disable tests
 - deprecate ^ and make it available as operator