dok -> md

1 files changed, 279 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7c9d606
--- /dev/null
+++ b/README.md
@@ -0,0 +1,279 @@
+<a name="paths.dok"/>
+# Filename Manipulation Package #
+
+This package provides portable functions to manipulate filenames.
+
+When this package is loaded, it also computes a number of useful 
+variables indicating where the various Torch components are installed.  
+Do not change their values.
+
+
+<a name="paths.filenames.dok"/>
+## Manipulating file names ##
+
+The following functions can be used
+to manipulate filenames in a portable way
+over multiple platforms.
+
+
+<a name="paths.filep"/>
+### paths.filep(path) ###
+
+Return a boolean indicating whether `path` 
+refers to an existing file.
+
+<a name="paths.dirp"/>
+### paths.dirp(path) ###
+
+Return a boolean indicating whether `path` 
+refers to an existing directory.
+
+<a name="paths.basename"/>
+### paths.basename(path,[suffix]) ###
+
+Return the last path component of `path`
+and optionally strip the suffix `suffix`.
+This is similar to the well know shell command `"basename"`.
+
+<a name="paths.dirname"/>
+### paths.dirname(path) ###
+
+Return the name of directory containing file `path`.
+This is similar to the well known shell command `"dirname"`.
+
+<a name="paths.concat"/>
+### paths.concat([path1,....,pathn]) ###
+
+Concatenates relative filenames.
+
+First this function computes the full filename
+of `path1` relative to the current directory.
+Then it successively computes the full filenames
+of arguments `path2` to `pathn` relative to
+the filename returned for the previous argument.
+Finally the last result is returned.
+
+Calling this function without argument returns the
+full name of the current directory.
+
+
+<a name="paths.cwd"/>
+### paths.cwd() ###
+
+Return the full path of the current directory.
+
+
+<a name="paths.execdir"/>
+### paths.execdir() ###
+
+Return the name of the directory containing the
+current Lua executable.
+When the module `paths` is first loaded,
+this information is used to relocate
+the variables indicating 
+the location of the various Torch components.
+
+
+<a name="paths.tmpname"/>
+### paths.tmpname() ###
+
+Return the name of a temporary file.
+All the temporaty files whose name was obtained in this way
+are removed when Lua exits.
+
+This function should be preferred over `os.tmpname()`
+because it makes sure that the files are removed on exit.
+In addition, `os.tmpname()` under windows often returns filenames
+for which the user has no permission to write.
+
+
+
+
+<a name="paths.dirs.dok"/>
+## Directory functions ##
+
+The following functions can be used
+to examine directory contents or manipulate directories.
+
+
+<a name="paths.dir"/>
+### paths.dir(dname) ###
+
+Return a table containing the files in directory `dname`.
+This function return `nil` if the specified directory
+does not exists.
+
+<a name="paths.files"/>
+### paths.files(dname) ###
+
+Returns an iterator over the files located in directory `dname`.
+This can be used in *__for__* expression as shown below:
+```
+   for f in paths.files(".") do
+     print(f)
+   end
+```
+
+<a name="paths.mkdir"/>
+### paths.mkdir(s) ###
+
+Create a directory.
+Returns `true` on success.
+
+<a name="paths.rmdir"/>
+### paths.rmdir(s) ###
+
+Delete an empty directory.
+Returns `true` on success.
+
+<a name="paths.rmall"/>
+### paths.rmall(s, y) ###
+
+Recursively delete file or directory `s` and its contents.
+Argument `y` must be string `"yes"`
+Returns `true` on success.
+
+
+<a name="paths.findingfiles.dok"/>
+## Finding files relative to a Lua script ##
+
+<a name="paths.thisfile"/>
+### paths.thisfile([arg]) ###
+
+Calling `paths.thisfile()` without argument 
+inside a lua file returns returns the full 
+pathname of the file from which it is called. 
+This function always returns `nil` when called
+interactively.
+
+Calling `paths.thisfile(arg)` with a string argument `arg`
+returns the full pathname of the file `arg` relative 
+to the directory containing the file from which 
+function `paths.thisfile` is invoked. This is useful, 
+for instance, to locate files located in the same 
+directory as a lua script.
+
+
+<a name="paths.dofile"/>
+### paths.dofile(filename) ###
+
+This function is similar to the standard Lua function `dofile`
+but interprets `filename` relative to the directory containing 
+the file that contains the call to `paths.dofile`,
+or to the current directory when `paths.dofile` is 
+called interactively.
+
+<a name="paths.wellknowndirs.dok"/>
+## Well known directories ##
+
+These variables indicate where the various Torch components are installed.  
+It is not advisable to change their values!
+
+
+<a name="paths.install_prefix"/>
+### paths.install_prefix ###
+
+The base directory of the Torch installation.
+
+<a name="paths.install_bin"/>
+### paths.install_bin ###
+
+The name of the directory containing the executable programs.
+Under Windows, this directory also contains 
+the dynamically loadable libraries (`.dll`).
+
+<a name="paths.install_man"/>
+### paths.install_man ###
+
+The name of the directory containing the unix style manual pages.
+
+<a name="paths.install_lib"/>
+### paths.install_lib ###
+
+The name of the directory containing the object code libraries.
+Under Unix, this directory also contains the dynamically
+loadable libraries (`.so` or `.dylib`).
+
+<a name="paths.install_share"/>
+### paths.install_share ###
+
+The name of the directory containing processor independent data files,
+such as lua code and other text files.
+
+<a name="paths.install_include"/>
+### paths.install_include ###
+
+The name of the directory containing the include files
+for the various Torch libraries.
+
+<a name="paths.install_hlp"/>
+### paths.install_hlp ###
+
+The name of the directory containing the Torch help files.
+
+<a name="paths.install_html"/>
+### paths.install_html ###
+
+The name of the directory containing the HTML version
+of the Torch help files.  These files are generated
+when you enable the CMake option `HTML_DOC`.
+
+<a name="paths.install_cmake"/>
+### paths.install_cmake ###
+
+The name of the directory containing the CMake files
+used by external Torch modules.
+
+<a name="paths.install_lua_path"/>
+### paths.install_lua_path ###
+
+The name of the directory containing the Lua packages.
+This directory is used to build variable `package.path`.
+
+<a name="paths.install_lua_cpath"/>
+### paths.install_lua_cpath ###
+
+The name of the directory containing the Lua loadable binary modules.
+This directory is used to build variable `package.cpath`.
+
+<a name="paths.home"/>
+### paths.home ###
+
+The home directory of the current user.
+
+
+<a name="paths.misc.dok"/>
+## Miscellaneous ##
+
+
+<a name="paths.uname"/>
+### paths.uname() ###
+
+Returns up to three strings describing the operating system.
+The first string is a system name, e.g., "Windows", "Linux", "Darwin", "FreeBSD", etc.
+The second string is the network name of this computer.
+The third string indicates the processor type.
+
+<a name="paths.is_win"/>
+### paths.is_win() ###
+
+Returns true if the operating system is Microsoft Windows.
+
+<a name="paths.is_mac"/>
+### paths.is_mac() ###
+
+Returns true if the operating system is Mac OS X.
+
+### paths.getregistryvalue(key,subkey,value) ###
+
+Query a value in the Windows registry value. 
+Causes an error on other systems.
+
+### paths.findprogram(progname,...) ###
+
+Finds an executable program named "progname" and returns its full path.
+If none is found, continue searching programs named after the following arguments
+and return the full path of the first match.
+All the directories specified by the PATH variable are searched.
+Under windows, this also searches the "App Path" registry entries.
+