dok -> md

README.md

@@ -0,0 +1,29 @@
+<a name="torch.reference.dok"/>
+# Torch Package Reference Manual #
+
+__Torch__ is the main package in [Torch7](http://torch.ch) where data
+structures for multi-dimensional tensors and mathematical operations
+over these are defined. Additionally, it provides many utilities for
+accessing files, serializing objects of arbitrary types and other
+useful utilities.
+
+<a name="torch.reference.dok"/>
+## Torch Packages ##
+
+  * Tensor Library
+    * [Tensor](doc/tensor.md) defines the _all powerful_ tensor object that provides multi-dimensional numerical arrays with type templating.
+    * [Mathematical operations](doc/maths.md) that are defined for the tensor object types.
+    * [Storage](doc/storage.md) defines a simple storage interface that controls the underlying storage for any tensor object.
+  * File I/O Interface Library
+    * [File](doc/file.md) is an abstract interface for common file operations.
+    * [Disk File](doc/diskfile.md) defines operations on files stored on disk.
+    * [Memory File](doc/memoryfile.md) defines operations on stored in RAM.
+    * [Pipe File](doc/pipefile.md) defines operations for using piped commands.
+    * [High-Level File operations](doc/serialization.md) defines higher-level serialization functions.
+  * Useful Utilities
+    * [Timer](doc/timer.md) provides functionality for _measuring time_.
+    * [Tester](doc/tester.md) is a generic tester framework.
+    * [CmdLine](doc/cmdline.md) is a command line argument parsing utility.
+    * [Random](doc/random.md) defines a random number generator package with various distributions.
+    * Finally useful [utility](doc/utility.md) functions are provided for easy handling of torch tensor types and class inheritance.
+

dok/cmdline.dok → doc/cmdline.md

@@ -1,16 +1,16 @@
-======  CmdLine ======
-{{anchor:torch.CmdLine.dok}}
+<a name="torch.CmdLine.dok"/>
+# CmdLine #
 
 This class provides a parameter parsing framework which is very
 usefull when one needs to run several experiments that rely on
 different parameter settings that are passed in the command line.
 This class will also override the default print function to direct
 all the output to a log file as well as screen at the same time.
 
-A sample ''lua'' file is given below that makes use of ''CmdLine''
+A sample `lua` file is given below that makes use of `CmdLine`
 class.
 
-<file lua>
+```lua
 
 cmd = torch.CmdLine()
 cmd:text()
@@ -31,16 +31,16 @@ params.rundir = cmd:string('experiment', params, {dir=true})
 -- create log file
 cmd:log(params.rundir .. '/log', params)
 
-</file>
+```
 
 When this file is run on the lua commandline as follows
-<file shell>
+```shell
 # lua myscript.lua
-</file>
+```
 
 It will produce the following output:
 
-<file>
+```
 [program started on Tue Jan 10 15:33:49 2012]
 [command line arguments]
 booloption	false
@@ -52,20 +52,20 @@ booloption	false
 seed	123
 rundir	experiment
 stroption	mystring
-</file>
+```
 
 The same output will also be written to file
-''experiment/log''. Whenever one of the options are passed on the
-command line and is different than the default value, the ''rundir''
+`experiment/log`. Whenever one of the options are passed on the
+command line and is different than the default value, the `rundir`
 is name is produced to reflect the parameter setting.
 
-<file shell>
+```shell
 # lua myscript.lua -seed 456 -stroption mycustomstring
-</file>
+```
 
 This will produce the following output:
 
-<file>
+```
 [program started on Tue Jan 10 15:36:55 2012]
 [command line arguments]
 booloption	false
@@ -77,69 +77,70 @@ booloption	false
 seed	456
 rundir	experiment,seed=456,stroption=mycustomstring
 stroption	mycustomstring
-</file>
+```
 
 and the output will be logged in
-''experiment,seed=456,stroption=mycustomstring/log''
+`experiment,seed=456,stroption=mycustomstring/log`
 
-==== addTime([name] [,format]) ====
-{{anchor:torch.CmdLine.addtime}}
+<a name="torch.CmdLine.addtime"/>
+### addTime([name] [,format]) ###
 
 Adds a prefix to every line in the log file with the date/time in the
 given format with an optional name argument. The date/time format is
-the same as ''os.date()''. Note that the prefix is only added to the
+the same as `os.date()`. Note that the prefix is only added to the
 log file, not the screen output. The default value for name is empty
 and the default format is '%F %T'.
 
 The final produced output for the following command is:
 
-<file lua>
+```lua
 > cmd:addTime('your project name','%F %T')
 > print('Your log message')
-</file>
+```
 
-<file>
+```
 2012-02-07 08:21:56[your project name]: Your log message
-</file>
+```
 
-==== log(filename, parameter_table) ====
-{{anchor:torch.CmdLine.log}}
+<a name="torch.CmdLine.log"/>
+### log(filename, parameter_table) ###
 
-It sets the log filename to ''filename'' and prints the values of
-parameters in the ''parameter_table''.
+It sets the log filename to `filename` and prints the values of
+parameters in the `parameter_table`.
 
-==== option(name, default, help) ====
-{{anchor:torch.CmdLine.option}}
+<a name="torch.CmdLine.option"/>
+### option(name, default, help) ###
 
 Stores an option argument. The name should always start with '-'.
 
-==== [table] parse(arg) ====
-{{anchor:torch.CmdLine.parse}}
+<a name="torch.CmdLine.parse"/>
+### [table] parse(arg) ###
 
-Parses a given table, ''arg'' is by default the argument table that 
-is created by ''lua'' using the command line arguments passed to the 
+Parses a given table, `arg` is by default the argument table that 
+is created by `lua` using the command line arguments passed to the 
 executable. Returns a table of option values.
 
-==== silent() ====
-{{anchor:torch.CmdLine.silent}}
+<a name="torch.CmdLine.silent"/>
+### silent() ###
 
 Silences the output to standard output. The only output is written to
 the log file.
 
-==== [string] string(prefix, params, ignore) ====
-{{anchor:torch.CmdLine.string}}
+<a name="torch.CmdLine.string"/>
+### [string] string(prefix, params, ignore) ###
 
 Returns a string representation of the options by concatenating the
-non-default options. ''ignore'' is a table ''{dir=true}'', which will
-ensure that option named ''dir'' will be ignored while creating the
+non-default options. `ignore` is a table `{dir=true}`, which will
+ensure that option named `dir` will be ignored while creating the
 string representation.
 
 This function is usefull for creating unique experiment directories that
 depend on the parameter settings.
 
-==== text(string) ====
-{{anchor:torch.CmdLine.text}}
+<a name="torch.CmdLine.text"/>
+### text(string) ###
 
 Logs a custom text message.
 
 
+

doc/diskfile.md

@@ -0,0 +1,65 @@
+<a name="torch.DiskFile.dok"/>
+# DiskFile #
+
+Parent classes: [File](file.md)
+
+A `DiskFile` is a particular `File` which is able to perform basic read/write operations
+on a file stored on disk. It implements all methods described in [File](file.md), and
+some additional methods relative to _endian_ encoding.
+
+By default, a `DiskFile` is in [ASCII](file.md#torch.File.binary) mode. If changed to
+the [binary](file.md#torch.File.binary) mode, the default endian encoding is the native
+computer one.
+
+The file might be open in read, write, or read-write mode, depending on the parameter
+`mode` (which can take the value `"r"`, `"w"` or `"rw"` respectively) 
+given to the [torch.DiskFile(fileName, mode)](#torch.DiskFile).
+
+<a name="torch.DiskFile"/>
+### torch.DiskFile(fileName, [mode], [quiet]) ###
+
+_Constructor_ which opens `fileName` on disk, using the given `mode`. Valid `mode` are
+`"r"` (read), `"w"` (write) or `"rw"` (read-write). Default is read mode.
+
+If read-write mode, the file _will be created_ if it does not exists. If it
+exists, it will be positionned at the beginning of the file after opening.
+
+If (and only if) `quiet` is `true`, no error will be raised in case of
+problem opening the file: instead `nil` will be returned.
+
+The file is opened in [ASCII](file.md#torch.File.ascii) mode by default.
+
+<a name="torch.DiskFile.bigEndianEncoding"/>
+### bigEndianEncoding() ###
+
+In [binary](file.md#torch.File.binary) mode, force encoding in _big endian_. 
+(_big end first_: decreasing numeric significance with increasing memory
+addresses)
+
+<a name="torch.DiskFile.isBigEndianCPU"/>
+### [boolean] isBigEndianCPU() ###
+
+Returns `true` if, and only if, the computer CPU operates in _big endian_.
+_Big end first_: decreasing numeric significance with increasing
+memory addresses.
+
+<a name="torch.DiskFile.isLittleEndianCPU"/>
+### [boolean] isLittleEndianCPU() ###
+
+Returns `true` if, and only if, the computer CPU operates in _little endian_.
+_Little end first_: increasing numeric significance with increasing
+memory addresses.
+
+<a name="torch.DiskFile.littleEndianEncoding"/>
+### littleEndianEncoding() ###
+
+In [binary](file.md#torch.File.binary) mode, force encoding in _little endian_.
+(_little end first_: increasing numeric significance with increasing memory
+addresses)
+
+<a name="torch.DiskFile.nativeEndianEncoding"/>
+### nativeEndianEncoding() ###
+
+In [binary](file.md#torch.File.binary) mode, force encoding in _native endian_.
+
+