Merge pull request #817 from gradha/pr_improves_docs2

Improves docs2

doc/lib.txt

@@ -227,7 +227,12 @@ Parsers
 -------
 
 * `parseopt <parseopt.html>`_
-  The ``parseopt`` module implements a command line option parser. This
+  The ``parseopt`` module implements a command line option parser.
+  **Deprecated since version 0.9.3:** Use the `parseopt2
+  <parseopt2.html>`_ module instead.
+
+* `parseopt2 <parseopt2.html>`_
+  The ``parseopt2`` module implements a command line option parser. This
   supports long and short command options with optional values and command line
   arguments.
 
@@ -381,9 +386,6 @@ Database support
 * `db_mongo <db_mongo.html>`_
   A higher level **mongodb** wrapper. 
 
-* `mongodb <mongo.html>`_
-  Lower level wrapper for the **mongodb** client C library.
-  
 
 Other
 -----
@@ -446,45 +448,6 @@ UNIX specific
 
 * `posix <posix.html>`_
   Contains a wrapper for the POSIX standard.
-* `cursorfont <cursorfont.html>`_
-  Part of the wrapper for X11.
-* `keysym <keysym.html>`_
-  Part of the wrapper for X11.
-* `x <x.html>`_
-  Part of the wrapper for X11.
-* `xatom <xatom.html>`_
-  Part of the wrapper for X11.
-* `xcms <xcms.html>`_
-  Part of the wrapper for X11.
-* `xf86dga <xf86dga.html>`_
-  Part of the wrapper for X11.
-* `xf86vmode <xf86vmode.html>`_
-  Part of the wrapper for X11.
-* `xi <xi.html>`_
-  Part of the wrapper for X11.
-* `xinerama <xinerama.html>`_
-  Part of the wrapper for X11.
-* `xkb <xkb.html>`_
-  Part of the wrapper for X11.
-* `xkblib <xkblib.html>`_
-  Part of the wrapper for X11.
-* `xlib <xlib.html>`_
-  Part of the wrapper for X11.
-* `xrandr <xrandr.html>`_
-  Part of the wrapper for X11.
-* `xrender <xrender.html>`_
-  Part of the wrapper for X11.
-* `xresource <xresource.html>`_
-  Part of the wrapper for X11.
-* `xshm <xshm.html>`_
-  Part of the wrapper for X11.
-* `xutil <xutil.html>`_
-  Part of the wrapper for X11.
-* `xv <xv.html>`_
-  Part of the wrapper for X11.
-* `xvlib <xvlib.html>`_
-  Part of the wrapper for X11.
-
 * `readline <readline.html>`_
   Part of the wrapper for the GNU readline library.
 * `history <history.html>`_
@@ -505,15 +468,6 @@ Regular expressions
 Graphics libraries
 ------------------
 
-* `cairo <cairo.html>`_
-  Wrapper for the cairo library.
-* `cairoft <cairoft.html>`_
-  Wrapper for the cairoft library.
-* `cairowin32 <cairowin32.html>`_
-  Wrapper for the cairowin32 library.
-* `cairoxlib <cairoxlib.html>`_
-  Wrapper for the cairoxlib library.
-
 * `sdl <sdl.html>`_
   Part of the wrapper for SDL.
 * `sdl_gfx <sdl_gfx.html>`_
@@ -529,47 +483,10 @@ Graphics libraries
 * `smpeg <smpeg.html>`_
   Part of the wrapper for SDL.
 
-* `gl <gl.html>`_
-  Part of the wrapper for OpenGL.
-* `glext <glext.html>`_
-  Part of the wrapper for OpenGL.
-* `glu <glu.html>`_
-  Part of the wrapper for OpenGL.
-* `glut <glut.html>`_
-  Part of the wrapper for OpenGL.
-* `glx <glx.html>`_
-  Part of the wrapper for OpenGL.
-* `wingl <wingl.html>`_
-  Part of the wrapper for OpenGL.
-
-* `opengl <opengl.html>`_
-  New wrapper for OpenGL supporting up to version 4.2.
-  
 
 GUI libraries
 -------------
-* `atk <atk.html>`_
+
-  Wrapper for the atk library.
-* `gdk2 <gdk2.html>`_
-  Wrapper for the gdk2 library.
-* `gdk2pixbuf <gdk2pixbuf.html>`_
-  Wrapper for the gdk2pixbuf library.
-* `gdkglext <gdkglext.html>`_
-  Wrapper for the gdkglext library.
-* `glib2 <glib2.html>`_
-  Wrapper for the glib2 library.
-* `gtk2 <gtk2.html>`_
-  Wrapper for the gtk2 library.
-* `gtkglext <gtkglext.html>`_
-  Wrapper for the gtkglext library.
-* `gtkhtml <gtkhtml.html>`_
-  Wrapper for the gtkhtml library.
-* `libglade2 <libglade2.html>`_
-  Wrapper for the libglade2 library.
-* `pango <pango.html>`_
-  Wrapper for the pango library.
-* `pangoutils <pangoutils.html>`_
-  Wrapper for the pangoutils library.
 * `iup <iup.html>`_
   Wrapper of the IUP GUI library.
 
@@ -583,6 +500,8 @@ Database support
   Contains a wrapper for the mySQL API.
 * `sqlite3 <sqlite3.html>`_
   Contains a wrapper for SQLite 3 API.
+* `mongodb <mongo.html>`_
+  Lower level wrapper for the **mongodb** client C library.
 * `odbcsql <odbcsql.html>`_
   interface to the ODBC driver.
 * `sphinx <sphinx.html>`_
@@ -612,21 +531,6 @@ Network Programming and Internet Protocols
   Wrapper for OpenSSL.
 
 
-Scripting languages
--------------------
-
-* `lua <lua.html>`_
-  Part of the wrapper for Lua.
-* `lualib <lualib.html>`_
-  Part of the wrapper for Lua.
-* `lauxlib <lauxlib.html>`_
-  Part of the wrapper for Lua.
-* `tcl <tcl.html>`_
-  Wrapper for the TCL programming language.
-* `python <python.html>`_
-  Wrapper for the Python programming language.
-
-
 Data Compression and Archiving
 ------------------------------
 

doc/manual.txt

@@ -312,14 +312,39 @@ Character literals
 ------------------
 
 Character literals are enclosed in single quotes ``''`` and can contain the
-same escape sequences as strings - with one exception: ``\n`` is not allowed
+same escape sequences as strings - with one exception: `newline`:idx: (``\n``)
-as it may be wider than one character (often it is the pair CR/LF for example).
+is not allowed as it may be wider than one character (often it is the pair
+CR/LF for example).  Here are the valid `escape sequences`:idx: for character
+literals:
+
+==================         ===================================================
+  Escape sequence          Meaning
+==================         ===================================================
+  ``\r``, ``\c``           `carriage return`:idx:
+  ``\l``                   `line feed`:idx:
+  ``\f``                   `form feed`:idx:
+  ``\t``                   `tabulator`:idx:
+  ``\v``                   `vertical tabulator`:idx:
+  ``\\``                   `backslash`:idx:
+  ``\"``                   `quotation mark`:idx:
+  ``\'``                   `apostrophe`: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:
+  ``\x`` HH                `character with hex value HH`:idx:;
+                           exactly two hex digits are allowed
+==================         ===================================================
+
 A character is not an Unicode character but a single byte. The reason for this
 is efficiency: for the overwhelming majority of use-cases, the resulting
 programs will still handle UTF-8 properly as UTF-8 was specially designed for
-this.
+this. Another reason is that Nimrod can thus support ``array[char, int]`` or
-Another reason is that Nimrod can thus support ``array[char, int]`` or
+``set[char]`` efficiently as many algorithms rely on this feature.  The `TRune`
-``set[char]`` efficiently as many algorithms rely on this feature.
+type is used for Unicode characters, it can represent any Unicode character.
+``TRune`` is declared in the `unicode module <unicode.html>`_.
 
 
 Numerical constants
@@ -750,7 +775,8 @@ designed for this.
 Another reason is that Nimrod can support ``array[char, int]`` or
 ``set[char]`` efficiently as many algorithms rely on this feature. The
 `TRune` type is used for Unicode characters, it can represent any Unicode
-character. ``TRune`` is declared in the ``unicode`` module.
+character. ``TRune`` is declared in the `unicode module <unicode.html>`_.
+
 
 
 
@@ -847,8 +873,8 @@ arrays, they can be used in case statements:
 Per convention, all strings are UTF-8 strings, but this is not enforced. For
 example, when reading strings from binary files, they are merely a sequence of
 bytes. The index operation ``s[i]`` means the i-th *char* of ``s``, not the
-i-th *unichar*. The iterator ``runes`` from the ``unicode``
+i-th *unichar*. The iterator ``runes`` from the `unicode module
-module can be used for iteration over all Unicode characters.
+<unicode.html>`_ can be used for iteration over all Unicode characters.
 
 
 CString type
@@ -2206,12 +2232,12 @@ Instead of:
 Using statement
 ---------------
 
-The using statement provides syntactic convenience for procs that heavily use a
+The `using statement`:idx: provides syntactic convenience for procs that
-single contextual parameter. When applied to a variable or a constant, it will
+heavily use a single contextual parameter. When applied to a variable or a
-instruct Nimrod to automatically consider the used symbol as a hidden leading
+constant, it will instruct Nimrod to automatically consider the used symbol as
-parameter for any procedure calls, following the using statement in the current
+a hidden leading parameter for any procedure calls, following the using
-scope. Thus, it behaves much like the hidden `this` parameter available in some
+statement in the current scope. Thus, it behaves much like the hidden `this`
-object-oriented programming languages.
+parameter available in some object-oriented programming languages.
 
 .. code-block:: nimrod
 
@@ -2234,6 +2260,24 @@ from different modules having the same name.
   import windows, sdl
   using sdl.SetTimer
 
+Note that ``using`` only *adds* to the current context, it doesn't remove or
+replace, **neither** does it create a new scope. What this means is that if you
+apply this to multiple variables the compiler will find conflicts in what
+variable to use:
+
+.. code-block:: nimrod
+  var a, b = "kill it"
+  using a
+  add(" with fire")
+  using b
+  add(" with water")
+  echo a
+  echo b
+
+When the compiler reaches the second ``add`` call, both ``a`` and ``b`` could
+be used with the proc, so you get ``Error: expression '(a|b)' has no type (or
+is ambiguous)``. To solve this you would need to nest ``using`` with a
+``block`` statement so as to control the reach of the ``using`` statement.
 
 If expression
 -------------

doc/subexes.txt

@@ -14,7 +14,9 @@ Thanks to its conditional construct ``$[0|1|2|else]`` it supports
 Notation                meaning
 =====================   =====================================================
 ``$#``                  use first or next argument
-``$name``               use named argument
+``$name``               use named argument, you can wrap the named argument
+                        in curly braces (eg. ``${name}``) to separate it from
+                        the next characters.
 ``$1``                  use first argument
 ``$-1``                 use last argument
 ``${1..3}``             use arguments 1 to 3

doc/tut1.txt

@@ -202,6 +202,12 @@ statement and all the variables will have the same value:
   echo "x ", x  # outputs "x 42"
   echo "y ", y  # outputs "y 3"
 
+Note that declaring multiple variables with a single assignment which calls a
+procedure can have unexpected results: the compiler will *unroll* the
+assignments and end up calling the procedure several times. If the result of
+the procedure depends on side effects, your variables may end up having
+different values! For safety use only constant values.
+
 
 Constants
 =========
@@ -807,7 +813,11 @@ important differences:
 
 However, you can also use a ``closure`` iterator to get a different set of
 restrictions. See `first class iterators <manual.html#first-class-iterators>`_
-for details.
+for details. Iterators can have the same name and parameters as a proc,
+essentially they have their own namespace. Therefore it is common practice to
+wrap iterators in procs of the same name which accumulate the result of the
+iterator and return it as a sequence, like ``split`` from the `strutils module
+<strutils.html>`_.
 
 
 Basic types

lib/packages/docutils/rstgen.nim

@@ -44,7 +44,7 @@ type
     splitAfter*: int          # split too long entries in the TOC
     tocPart*: seq[TTocEntry]
     hasToc*: bool
-    theIndex: string
+    theIndex: string # Contents of the index file to be dumped at the end.
     options*: TRstParseOptions
     findFile*: TFindFileHandler
     msgHandler*: TMsgHandler
@@ -111,6 +111,10 @@ proc initRstGenerator*(g: var TRstGenerator, target: TOutputTarget,
   for i in low(g.meta)..high(g.meta): g.meta[i] = ""
 
 proc writeIndexFile*(g: var TRstGenerator, outfile: string) =
+  ## Writes the current index buffer to the specified output file.
+  ##
+  ## You previously need to add entries to the index with the ``setIndexTerm``
+  ## proc. If the index is empty the file won't be created.
   if g.theIndex.len > 0: writeFile(outfile, g.theIndex)
   
 proc addXmlChar(dest: var string, c: char) = 
@@ -224,6 +228,13 @@ proc renderAux(d: PDoc, n: PRstNode, frmtA, frmtB: string, result: var string) =
 # ---------------- index handling --------------------------------------------
 
 proc setIndexTerm*(d: var TRstGenerator, id, term: string) =
+  ## Adds a `term` to the index using the specified hyperlink identifier.
+  ##
+  ## The ``d.theIndex`` string will be used to append the term in the format
+  ## ``term<tab>file#id``. The anchor will be the based on the name of the file
+  ## currently being parsed plus the `id`, which will be appended after a hash.
+  ##
+  ## The index won't be written to disk unless you call ``writeIndexFile``.
   d.theIndex.add(term)
   d.theIndex.add('\t')
   let htmlFile = changeFileExt(extractFilename(d.filename), HtmlExt)

lib/pure/parseopt.nim

@@ -11,8 +11,8 @@
 ## It supports one convenience iterator over all command line options and some
 ## lower-level features.
 ##
-## DEPRECATED. Use parseopt2 instead as this version has issues with spaces
+## **Deprecated since version 0.9.3:** Use the `parseopt2 <parseopt2.html>`_
-## in arguments.
+## module instead as this version has issues with spaces in arguments.
 {.deprecated.}
 {.push debugger: off.}
 

lib/system.nim

@@ -2236,8 +2236,19 @@ when not defined(JS): #and not defined(NimrodVM):
 
   when hostOS != "standalone":
     iterator lines*(filename: string): TaintedString {.tags: [FReadIO].} =
-      ## Iterate over any line in the file named `filename`.
+      ## Iterates over any line in the file named `filename`.
-      ## If the file does not exist `EIO` is raised.
+      ##
+      ## If the file does not exist `EIO` is raised. The trailing newline
+      ## character(s) are removed from the iterated lines. Example:
+      ##
+      ## .. code-block:: nimrod
+      ##   import strutils
+      ##
+      ##   proc transformLetters(filename: string) =
+      ##     var buffer = ""
+      ##     for line in filename.lines:
+      ##       buffer.add(line.replace("a", "0") & '\x0A')
+      ##     writeFile(filename, buffer)
       var f = open(filename)
       var res = TaintedString(newStringOfCap(80))
       while f.readLine(res): yield res
@@ -2245,6 +2256,17 @@ when not defined(JS): #and not defined(NimrodVM):
 
     iterator lines*(f: TFile): TaintedString {.tags: [FReadIO].} =
       ## Iterate over any line in the file `f`.
+      ##
+      ## The trailing newline character(s) are removed from the iterated lines.
+      ## Example:
+      ##
+      ## .. code-block:: nimrod
+      ##   proc countZeros(filename: TFile): tuple[lines, zeros: int] =
+      ##     for line in filename.lines:
+      ##       for letter in line:
+      ##         if letter == '0':
+      ##           result.zeros += 1
+      ##       result.lines += 1
       var res = TaintedString(newStringOfCap(80))
       while f.readLine(res): yield res
 

web/nimrod.ini

@@ -45,7 +45,7 @@ srcdoc2: "impure/re;pure/sockets"
 srcdoc: "system/threads.nim;system/channels.nim;js/dom"
 srcdoc2: "pure/os;pure/strutils;pure/math;pure/matchers;pure/algorithm"
 srcdoc2: "pure/complex;pure/times;pure/osproc;pure/pegs;pure/dynlib"
-srcdoc2: "pure/parseopt;pure/hashes;pure/strtabs;pure/lexbase"
+srcdoc2: "pure/parseopt;pure/parseopt2;pure/hashes;pure/strtabs;pure/lexbase"
 srcdoc2: "pure/parsecfg;pure/parsexml;pure/parsecsv;pure/parsesql"
 srcdoc2: "pure/streams;pure/terminal;pure/cgi;impure/web;pure/unicode"
 srcdoc2: "impure/zipfiles;pure/htmlgen;pure/parseutils;pure/browsers"