updating docs

5 files changed, 20 insertions, 9 deletions

diff --git a/docs/config.ld b/docs/config.ld
index e41a41c..8206fae 100644
--- a/docs/config.ld
+++ b/docs/config.ld
@@ -4,7 +4,7 @@ full_description = 'The documentation is available @{01-introduction.md|here}.'
 title = 'Penlight Documentation'

 dir = 'api_docs'

 topics = 'manual'

-examples = {'../examples','../teststest=data.lua'}

+examples = {'../examples','../tests/test-data.lua'}

 package = 'pl'

 format = 'discount'

 file = '../lua/pl'

diff --git a/docs/manual/01-introduction.md b/docs/manual/01-introduction.md
index c1cc77d..1604f18 100644
--- a/docs/manual/01-introduction.md
+++ b/docs/manual/01-introduction.md
@@ -16,7 +16,7 @@ If you are used to Python conventions, please note that all indices consistently
 
 The Lua function `table.foreach` has been deprecated in favour of the `for in` statement, but such an operation becomes particularly useful with the higher-order function support in Penlight. Note that `tablex.foreach` reverses the order, so that the function is passed the value and then the key. Although perverse, this matches the intended use better.
 
-The only important external dependence of Penlight is LuaFileSystem (`lfs`), and if you want `dir.copyfile` to work cleanly on Windows, you will need `alien` as well. (The fallback is to call the equivalent shell commands.)
+The only important external dependence of Penlight is [LuaFileSystem](http://keplerproject.github.com/luafilesystem/manual.html) (`lfs`), and if you want `dir.copyfile` to work cleanly on Windows, you will need either [alien](http://alien.luaforge.net/) or be using [LuaJIT](http://luajit.org) as well. (The fallback is to call the equivalent shell commands.)
 
 Some of the examples in this guide were created using [ilua](http://lua-users.org/wiki/InteractiveLua), which doesn't require '=' to print out expressions, and will attempt to print out table results as nicely as possible.  This is also available under Lua for Windows, as a library, so the command `lua -lilua -s` will work (the s option switches off 'strict' variable checking, which is annoying and conflicts with the use of `_DEBUG` in some of these libraries.
 
@@ -256,3 +256,5 @@ So `Alice = class(); Alice._name = 'Alice'` is exactly the same as `class.Alice(
 
 This useful notation is borrowed from Hugo Etchegoyen's [classlib](http://lua-users.org/wiki/MultipleInheritanceClasses) which further extends this concept to allow for multiple inheritance.
 
+Penlight provides a number of useful classes; there is `List`, which is a Lua clone of the standard Python list object, and `Set` which represents sets. There are three kinds of _map_ defined: `Map`, `MultiMap` (where a key may have multiple values) and `OrderedMap` (where the order of insertion is remembered.).  There is nothing special about these classes and you may inherit from them.
+
diff --git a/docs/manual/02-arrays.md b/docs/manual/02-arrays.md
index 89fb264..ed63d88 100644
--- a/docs/manual/02-arrays.md
+++ b/docs/manual/02-arrays.md
@@ -400,9 +400,9 @@ There is `product` which returns  the _Cartesian product_ of two 1D arrays. The
     > array2d.product('{}',{1,2},{'a','b'})
     {{{1,'b'},{2,'a'}},{{1,'a'},{2,'b'}}}
 
-There is a set of operations which work in-place on 2D arrays. You can `swap_rows` and `swap_cols`; the first really is a simple one-liner, but the idea is to give the operation a name. `remove_row` and `remove_col` are generalizations of `table.remove`. Likewise, `extract_rows` and `extract_cols` are given arrays of indices and discard anything else. So, for instance, `extract_cols(A,{2,4})` will leave just columns 2 and 4 in the array.
+There is a set of operations which work in-place on 2D arrays. You can `swap_rows` and `swap_cols`; the first really is a simple one-liner, but the idea here is to give the operation a name. `remove_row` and `remove_col` are generalizations of `table.remove`. Likewise, `extract_rows` and `extract_cols` are given arrays of indices and discard anything else. So, for instance, `extract_cols(A,{2,4})` will leave just columns 2 and 4 in the array.
 
-`List.slice` is often useful on 1D arrays; `array2d.slice` does the same thing, but is generally given a start (row,column) and a end (row,column).
+`List.slice` is often useful on 1D arrays; `slice` does the same thing, but is generally given a start (row,column) and a end (row,column).
 
     > A = {{1,2,3},{4,5,6},{7,8,9}}
     > B = slice(A,1,1,2,2)
@@ -414,7 +414,7 @@ There is a set of operations which work in-place on 2D arrays. You can `swap_row
      5.0 6.0
      8.0 9.0
 
-Here `array2d.write` is used to print out an array nicely; the second parameter is `nil`, which is the default (stdout) but can be any file object and the third parameter is an optional format (as used in `string.format`).
+Here `write` is used to print out an array nicely; the second parameter is `nil`, which is the default (stdout) but can be any file object and the third parameter is an optional format (as used in `string.format`).
 
 `parse_range` will take a spreadsheet range like 'A1:B2' or 'R1C1:R2C2' and return the range as four numbers, which can be passed to `slice`. The rule is that `slice` will return an array of the appropriate shape depending on the range; if a range represents a row or a column, the result is 1D, otherwise 2D.
 
@@ -427,4 +427,13 @@ This applies to `iter` as well, which can also optionally be given a range:
     3       2       8
     3       3       9
 
+`new` will construct a new 2D array with the given dimensions. You provide an initial value for the elements, which is interpreted as a function if it's callable. With `L` being `utils.string_lambda` we then have the following way to make an _identity matrix_:
+
+    asserteq(
+        array.new(3,3,L'|i,j| i==j and 1 or 0'),
+        {{1,0,0},{0,1,0},{0,0,1}}
+    )
+
+Please note that most functions in `array2d` are _covariant_, that is, they return an array of the same type as they receive.  In particular, any objects created with `data.new` or `matrix.new` will remain data or matrix objects when reshaped or sliced, etc.  Data objects have the `array2d` functions available as methods.
+
 
diff --git a/docs/manual/06-data.md b/docs/manual/06-data.md
index 70f56ba..5d24be7 100644
--- a/docs/manual/06-data.md
+++ b/docs/manual/06-data.md
@@ -231,7 +231,7 @@ And it can be used generally as a filter command to extract columns from data. (
 
 As a tutorial resource, have a look at `test-data.lua` in the PL tests directory for other examples of use, plus comments.
 
-The data returned by `read` or constructed by `copy_select` from a query is basically just an array of rows: `{{1,2},{3,4}}`. So you may use `read` to pull in any array-like dataset, and process with any function that expects such a implementation. In particular, the functions in `array2d` will work fine with this data. In fact, these functions are available as methods; e.g. `array2d.flatten` can be called directly like so to give us a one-dimensional list:
+The data returned by `read` or constructed by `Data.copy_select` from a query is basically just an array of rows: `{{1,2},{3,4}}`. So you may use `read` to pull in any array-like dataset, and process with any function that expects such a implementation. In particular, the functions in `array2d` will work fine with this data. In fact, these functions are available as methods; e.g. `array2d.flatten` can be called directly like so to give us a one-dimensional list:
 
     v = data.read('dat.txt'):flatten()
 
@@ -550,7 +550,7 @@ Rather then dumping the whole list, with its duplicates, we pass it through `seq
 
 You could further pass this through `tablex.keys` to get a unique list of symbols. This can be useful when writing 'strict' Lua modules, where all global symbols must be defined as locals at the top of the file.
 
-For a more detailed use of `lexer.scan`, please look at 'testxml.lua' in the examples directory.
+For a more detailed use of `lexer.scan`, please look at `testxml.lua` in the examples directory.
 
 ### XML
 
@@ -637,7 +637,7 @@ It's common to find configurations expressed with XML these days. It's straightf
       name = "bozo"
     }
 
-The only gotcha is that here we must use the `childtags` method, which will skip over any text elements.
+The only gotcha is that here we must use the `Doc:childtags` method, which will skip over any text elements.
 
 A more involved example is this excerpt from `serviceproviders.xml`, which is usually found at `/usr/share/mobile-broadband-provider-info/serviceproviders.xml` on Debian/Ubuntu Linux systems.
 
diff --git a/docs/manual/09-discussion.md b/docs/manual/09-discussion.md
index 68beed8..9b42372 100644
--- a/docs/manual/09-discussion.md
+++ b/docs/manual/09-discussion.md
@@ -14,7 +14,7 @@ This is the style that I follow in Penlight itself, so that modules don't mess w
 

 But `require 'pl'` is more convenient in scripts; the question is how to ensure that one doesn't load the whole kitchen sink as the price of convenience. The strategy is to only load modules when they are referenced. In 'init.lua' (which is loaded by `require 'pl'`) a metatable is attached to the global table with an `__index` metamethod. Any unknown name is looked up in the list of modules, and if found, we require it and make that module globally available. So when `tablex.deepcompare` is encountered, looking up `tablex` causes 'pl.tablex' to be required.  .

 

-Modifying the behaviour of the global table has consequences. For instance, there is the famous module `strict` which comes with Lua itself (perhaps the only standard Lua module written in Lua itself) which also does this modification so that global variiables must be defined before use.  So the implementation in 'init.lua' allows for a 'not found' hook, which 'pl.strict.lua' uses.

+Modifying the behaviour of the global table has consequences. For instance, there is the famous module `strict` which comes with Lua itself (perhaps the only standard Lua module written in Lua itself) which also does this modification so that global variiables must be defined before use.  So the implementation in 'init.lua' allows for a 'not found' hook, which 'pl.strict.lua' uses.  Other libraries may install their own metatables for `_G`, but Penlight will now forward any unknown name to the `__index` defined by the original metatable.

 

 But the strategy is worth the effort: the old 'kitchen sink' 'init.lua' would pull in about 260K of bytecode, whereas now typical programs use about 100K less, and short scripts even better - for instance, if they were only needing functionality in `utils`.