docs: import Wiki docs into the main repo

64 files changed, 4828 insertions, 0 deletions

diff --git a/docs/browse_rocks.md b/docs/browse_rocks.md
new file mode 100644
index 00000000..80be38d8
--- /dev/null
+++ b/docs/browse_rocks.md
@@ -0,0 +1,13 @@
+# Browse rocks
+
+To browse rocks, simply go to:
+
+* [http://luarocks.org](http://luarocks.org)
+
+You can also use the [luarocks search](luarocks_search.md) command in the [luarocks](luarocks.md) command-line tool.
+
+We also have the following mirrors:
+
+* [https://github.com/rocks-moonscript-org/moonrocks-mirror/](https://github.com/rocks-moonscript-org/moonrocks-mirror/)
+* [loadk.com/luarocks](https://loadk.com/luarocks)
+
diff --git a/docs/config_file_format.md b/docs/config_file_format.md
new file mode 100644
index 00000000..3cbe5deb
--- /dev/null
+++ b/docs/config_file_format.md
@@ -0,0 +1,226 @@
+# Config file format
+
+The LuaRocks configuration file is a Lua file containing assignments. Default
+values are assumed for variables that are not assigned explicitly.
+
+The location of the configuration file can be configured through flags during
+installation. If no `--force-config` or `/FORCECONFIG` flags were used on
+installation, the `LUAROCKS_CONFIG` environment variable can be used as well
+(or for a particular Lua version, `LUAROCKS_CONFIG_5_2`, similar to the
+`LUA_PATH_5_2` feature introduced in Lua 5.2).
+
+The default value is platform-dependent; exact paths depend on flags given
+during installation, but on Unix systems it would be something like
+`/etc/luarocks/config.lua` or `/etc/luarocks/config-5.1.lua` for older
+versions of lua; on Windows systems, `c:\luarocks\config.lua`.
+
+Specifically on Unix systems, the following directories are searched (in this
+order) for a user config file:
+
+* `$XDG_CONFIG_HOME/luarocks/`.
+* `$HOME/.config/luarocks/`.
+* `$HOME/.luarocks/`.
+
+# Locations 
+
+* `rocks_trees` (array of strings or tables) - The path to the local rocks
+  trees, where rocks are installed. When installing rocks, LuaRocks tries to
+  pick a location to store the rock starting from the bottom of the list; when
+  loading rocks in runtime, LuaRocks scans from the top of the list. This way,
+  if one has the local dir first and the system-wide dir last (this is what
+  the default installation does, for instance), rocks installed by the user
+  take precedence over rocks installed system-wide, and rocks installed by the
+  admin user go to the system-wide dir while user installations go to their
+  home directory. An entry in this table can be:
+  * a string, denoting the prefix of a tree. For example: `home.."/.luarocks"`
+  * a table, where deployment subdirectories of a tree can be further
+    customized. The 'root' field is mandatory; 'bin_dir', 'lib_dir' and
+    'lua_dir' are optional. Example: `{ root = home.."/local", bin_dir =
+    home.."/local/arch/bin", lib_dir = home.."/local/arch/lib/lua/5.1",
+    lua_dir = home.."/local/share/lua/5.1" }`
+
+* `rocks_servers` (array of strings) - Remote URLs or local pathnames of rocks
+  servers: directories containing .rock or .rockspec files, and a "manifest"
+  file, generated by the luarocks-admin make_manifest command. Default is {
+  "http://luarocks.org/repositories/rocks" }.
+
+* `external_deps_dirs` (array of strings) - Where to look for external
+  dependencies, when a prefix is not set for a specific dependency in the
+  _variables_ table (see below) or through the command-line. Default is {
+  "/usr/local", "/usr" } on Unix; { "c:\\external" } on Windows.
+
+* `external_deps_subdirs` (table with string keys and string values) -
+  Subdirectories to be used in conjunction with external_deps_dirs. Specifies
+  where to look for specific types external dependencies. This can be
+  overriden, for example, on Linux distributions which feature multiarch
+  libraries and libraries are no longer in the "lib" subdir. Default is { bin
+  = "bin", lib = "lib", include = "include" }.
+
+* `runtime_external_deps_subdirs` (table with string keys and string values) -
+  Same as the above, to be used with _luarocks install_.
+
+* `lib_modules_path` (string) - The path where modules with native C
+  extensions will be installed. If you are using a x86_64 *nix OS, you will
+  probably need this line in `config.lua`:
+  `lib_modules_path="/lib64/lua/"..lua_version`. See [issue
+  416](https://github.com/keplerproject/luarocks/issues/416).
+
+# File upload 
+
+* `upload_server` (string) - An FTP URL for a rock server (optionally
+  including username and password), or an alias specified in the
+  upload_servers table. Example:
+  `"ftp://_user_:_password_@ftp.luarocks.org/repositories/rocks"`
+
+* `upload_user` (string) - Default login name rock servers.
+
+* `upload_password` (string) - Default password rock servers.
+
+* `upload_servers` (table with string keys and table values) - A list of
+  aliases for URLs, to be used for accessing repositories through various
+  protocols. Each entry has a string alias as a key and a table as a value.
+  This table value contains protocol names as keys and pathnames as values.
+  Protocols "http", "ftp" and "sftp" are supported. Example: `{ rocks = { http
+  = "www.example.com/rocks", sftp = "example.com/var/rocks" } }`
+
+# Platform-specific settings 
+
+* `lua_extension` (string) - Filename extension of Lua files (without the
+  dot/separator). Default is "lua".
+
+* `lib_extension` (string) - Filename extension of dynamic library files
+  (without the dot/separator). Default is "so" on Unix; "dll" on Windows.
+
+* `arch` (string) - A two-part string identifying operating system and
+  hardware architecture, for filtering binary rocks. This value is
+  autodetected by LuaRocks. Example values are "macosx-powerpc" and
+  "win32-x86".
+
+* `platforms` (array of string) - A list of string identifiers indicating
+  which platform constraints can be satisfied by the running system. This is
+  used for filtering commands on the LuaRocks build rules. This allows a more
+  general platform definition such as "unix" when the same build commands are
+  valid for all Unix variants, instead of enumerating all known valid arch
+  entries, and at the same time using a more specific definition such as
+  "macosx" when a platform-specific flag is used. This value is automatically
+  filled according to the value of _arch_.
+
+* `external_deps_patterns` (table) - Name patterns to be used when matching
+  dependencies in a  [portable
+  way](platform_agnostic_external_dependencies.md).
+
+* `runtime_external_deps_patterns` (table) - Name patterns to be used by
+  _luarocks install_ when matching dependencies in a [portable
+  way](platform_agnostic_external_dependencies.md).
+
+* `link_lua_explicitly` (boolean) - Link the Lua library to the built modules
+  when using the builtin mode (this is set to true for Cygwin).
+
+# Variables 
+
+* `variables` (table) - A table containing string-to-string key-value pairs
+  containing variables to be substituted by build rules in rockspecs. LuaRocks
+  provides a general facility for build back-ends in which they can substitute
+  the entries of this table in strings containing references written
+  $(LIKE_THIS). Some standard variables are expected by the included
+  back-ends. For example, the "make" back-end expects the LIBFLAG to contain
+  the flag to be passed to the C compiler to instruct it to build a shared
+  library. So, in Linux systems, `variables["LIBFLAG"] = "-shared"`.
+
+After reading the user entries, LuaRocks dynamically adds entries to this
+table that refer to the rock being compiled, to make values available to the
+build back-end. These are:
+
+* `PREFIX` - The installation prefix of the rock (absolute path inside the
+  rocks tree). Example: `"/home/hisham/.luarocks/5.1/foo/1.0-1/"`
+
+  * `LUADIR` - Directory for storing Lua modules written in Lua (absolute path
+    inside the rock entry of the rocks tree). Example:
+    `"/home/hisham/.luarocks/5.1/foo/1.0-1/lua/"`
+
+  * `LIBDIR` - Directory for storing Lua modules written in C (absolute path
+    inside the rock entry of the rocks tree). Example:
+    `"/home/hisham/.luarocks/5.1/foo/1.0-1/lib/"`
+
+  * `BINDIR` - Directory for storing command-line scripts (absolute path
+    inside the rock entry of the rocks tree). Example:
+    `"/home/hisham/.luarocks/5.1/foo/1.0-1/bin/"`
+
+  * `CONFDIR` - Directory for storing configuration files for a module
+    (absolute path inside the rock entry of the rocks tree). Example:
+    `"/home/hisham/.luarocks/5.1/foo/1.0-1/conf/"`
+
+Such entries should not be added by the user in the configuration file, as
+they are dynamically constructed for each different rock. If you need to
+customize the various locations where files are deployed in a tree, use the
+table syntax for `rocks_trees` entries (see above).
+
+<font color="green">(since 2.0.5)</font> You can also override external
+commands called by LuaRocks by using entries in the _variables_ table, in case
+you need to customize the way they are called. Note that by installing
+appropriate Lua modules, most of these external command invocations can be
+avoided. Currently recognized entries in the _variables_ table are:
+
+* `MAKE` for build.type="make";
+
+* `CC, LD` (and `RC` on Windows) for build.type="builtin";
+
+* `CVS, GIT, SSCM, SVN` for their respective download protocols;
+
+* `RSYNC, SCP` for luarocks-admin operations;
+
+* `WGET` or `CURL` when LuaSocket is not installed;
+
+* `PWD, MKDIR, RMDIR, CP, LS, RM, FIND, TEST, CHMOD, STAT` when LuaFileSystem
+  is not installed;
+
+* `ZIP` when Lua-Zlib is not installed;
+
+* `UNZIP` when LuaZip is not installed;
+
+* `GUNZIP, BUNZIP2, TAR` on Unix or `SEVENZ` on Windows for source extraction
+  during "luarocks build";
+
+* `MD5SUM, OPENSSL` or `MD5` according to the operating system, when the Lua
+  md5 module is not installed.
+
+# External input 
+
+As the config file itself is a Lua code file, there is some possibility to
+execute Lua code. Because it is run in a sandbox this is very limited, but
+might still be useful.
+
+What LuaRocks makes available:
+
+* parameters/values: several values are made available to the config file
+  (pre-loaded in the sandbox) and include things like processor and OS
+  platform, rocks trees which are in use, etc. (see `dump_env()` below)
+
+* function: `os_getenv(varname)`; this is the regular Lua function
+  `os.getenv()` and allows one to fetch environment variable values from the
+  OS.
+
+* function: `dump_env()`; this will dump a list of all variables provided by
+  LuaRocks as a debug aid.
+
+To test this, add a line `dump_env()` to your config file and execute
+`luarocks` on the commandline to see the results.
+
+# Other 
+
+* `cmake_generator` (string) - If specified it overrides the default cmake
+  generator. Currently only Makefile-based generators are supported.
+
+* `wrap_bin_scripts` (boolean) - The default value is true: scripts installed
+  at bin/ are launched by a wrapper script that sets path environment
+  variables to ensure Lua modules are found. If set to false, scripts
+  installed at bin/ are copied directly, and no wrappers are generated.
+
+* `use_extensions` (boolean) - If specified, rockspec format verison 1.1 is
+  enabled, adding the deploy.wrap_bin_scripts option to the rockspec format,
+  which acts like the wrap_bin_scripts option above, in a rock by rock basis.
+
+* `local_by_default` (boolean) - If `true`, the tree in the user's home
+  directory is used as if the command line option `--local` had been given
+
+
diff --git a/docs/creating_a_makefile_that_plays_nice_with_luarocks.md b/docs/creating_a_makefile_that_plays_nice_with_luarocks.md
new file mode 100644
index 00000000..d6d43a6b
--- /dev/null
+++ b/docs/creating_a_makefile_that_plays_nice_with_luarocks.md
@@ -0,0 +1,189 @@
+# Creating a Makefile that plays nice with LuaRocks
+
+The page about [Recommended practices for
+Makefiles](recommended_practices_for_makefiles.md) mentions what you should do
+in order to create a Makefile that LuaRocks can work with. What it does not do
+is to explain how to interact between your rockspec and the Makefile so that
+your rock will install in a way such that LuaRocks knows everything it needs
+to know to handle everything after the installation (like, for example,
+removal).
+
+LuaRocks creates a few very important variables for you, that you can pass to
+your Makefile. They come in 2 varieties, one set for building the module and
+another set for installing it. The variables are:
+
+For building:
+
+* `CFLAGS` - flags for the C compiler
+* `LIBFLAG` - the flags needed for the linker to create shared libraries
+* `LUA_LIBDIR` - where to find the lua libraries
+* `LUA_BINDIR` - where to find the lua binary
+* `LUA_INCDIR` - where to find the lua headers
+* `LUALIB` - the name of the lua library. This is not available nor needed on all platforms.
+* `LUA` - the name of the lua interpreter
+
+For installing:
+
+* `PREFIX` - basic installation prefix for the module
+* `BINDIR` - where to put user callable programs or scripts
+* `LIBDIR` - where to put the shared libraries
+* `LUADIR` - where to put the lua files
+* `CONFDIR` - where to put your modules configuration
+
+Most of these variables point immediately where you'd expect them to, but
+`BINDIR`, `LIBDIR` and `LUADIR` are special. These point to a location where
+you need to put the files in order for LuaRocks to move them to their final
+destination. If you install your stuff here, then LuaRocks will know what
+files your module installed and can later remove them.
+
+These variables are not readily available in the Makefile, you need to tell
+LuaRocks to pass them to make. A simple rockspec that will do this looks
+like this:
+
+```
+package = "lrtest"
+version = "1.0-1"
+source = {
+   url = "http://..."
+}
+build = {
+   type = "make",
+   build_variables = {
+      CFLAGS="$(CFLAGS)",
+      LIBFLAG="$(LIBFLAG)",
+      LUA_LIBDIR="$(LUA_LIBDIR)",
+      LUA_BINDIR="$(LUA_BINDIR)",
+      LUA_INCDIR="$(LUA_INCDIR)",
+      LUA="$(LUA)",
+   },
+   install_variables = {
+      INST_PREFIX="$(PREFIX)",
+      INST_BINDIR="$(BINDIR)",
+      INST_LIBDIR="$(LIBDIR)",
+      INST_LUADIR="$(LUADIR)",
+      INST_CONFDIR="$(CONFDIR)",
+   },
+}
+```
+
+The corresponding Makefile looks like this:
+
+```
+all:
+        @echo --- build
+        @echo CFLAGS: $(CFLAGS)
+        @echo LIBFLAG: $(LIBFLAG)
+        @echo LUA_LIBDIR: $(LUA_LIBDIR)
+        @echo LUA_BINDIR: $(LUA_BINDIR)
+        @echo LUA_INCDIR: $(LUA_INCDIR)
+        @echo LUA: $(LUA) 
+
+install:
+        @echo --- install
+        @echo INST_PREFIX: $(INST_PREFIX)
+        @echo INST_BINDIR: $(INST_BINDIR)
+        @echo INST_LIBDIR: $(INST_LIBDIR)
+        @echo INST_LUADIR: $(INST_LUADIR)
+@echo INST_CONFDIR: $(INST_CONFDIR)
+```
+
+Now, if you call `luarocks make`, the output will look something
+like this:
+
+```
+-- build
+CFLAGS: -O2 -fPIC
+LIBFLAG: -shared
+LUA_LIBDIR: /usr/local/lib
+LUA_BINDIR: /usr/local/bin
+LUA_INCDIR: /usr/local/include
+
+-- install
+INST_PREFIX: /usr/local/lib/luarocks/rocks/lrtest/1.0-1
+INST_BINDIR: /usr/local/lib/luarocks/rocks/lrtest/1.0-1/bin
+INST_LIBDIR: /usr/local/lib/luarocks/rocks/lrtest/1.0-1/lib
+INST_LUADIR: /usr/local/lib/luarocks/rocks/lrtest/1.0-1/lua
+INST_CONFDIR: /usr/local/lib/luarocks/rocks/lrtest/1.0-1/conf
+```
+
+You will notice that the aforementioned special variables do not point to
+the location you'd expect them to. LuaRocks will move files you put there
+to their final destination for you, and in the process keep track of what
+was installed.
+
+The `CONFDIR` and `PREFIX` variables point to locations
+where you can store configuration or other data for your module. Your code
+must be made aware of these paths in order to use them. If you use the
+`copy_directories` entry in the build section of your rockspec,
+then what is mentioned there is copied to $(PREFIX) (i.e. a directory doc
+will be available unter $(PREFIX)/doc). If you copy directories in your
+`install` Makefile rule, you should do the same.
+
+Now, if your Makefile is meant to be used standalone as well, which it
+probably is, you would also want to define these variables inside of your
+Makefile, but in such a way that it will not hinder LuaRocks. Luckily
+variables passed on the command line to make override those defined in
+the Makefile.
+
+With this, a Makefile that is usable both from LuaRocks and standalone
+might look like this:
+
+```
+CFLAGS = -fPIC -O2
+LIBFLAG = -shared
+LUA_LIBDIR = /usr/local/lib/lua/5.2
+LUA_BINDIR = /usr/local/bin
+LUA_INCDIR = /usr/local/include
+LUA = lua
+   
+INST_PREFIX = /usr/local
+INST_BINDIR = $(INST_PREFIX)/bin
+INST_LIBDIR = $(INST_PREFIX)/lib/lua/5.2
+INST_LUADIR = $(INST_PREFIX)/share/lua/5.2
+INST_CONFDIR = $(INST_PREFIX)/etc
+   
+all:
+        @echo --- build
+        @echo CFLAGS: $(CFLAGS)
+        @echo LIBFLAG: $(LIBFLAG)
+        @echo LUA_LIBDIR: $(LUA_LIBDIR)
+        @echo LUA_BINDIR: $(LUA_BINDIR)
+        @echo LUA_INCDIR: $(LUA_INCDIR)
+
+install:
+        @echo --- install
+        @echo INST_PREFIX: $(INST_PREFIX)
+        @echo INST_BINDIR: $(INST_BINDIR)
+        @echo INST_LIBDIR: $(INST_LIBDIR)
+        @echo INST_LUADIR: $(INST_LUADIR)
+        @echo INST_CONFDIR: $(INST_CONFDIR)
+```
+
+You probably don't just want to echo stuff, so here's how to use the variables
+when actually building or installing something:
+
+```
+...
+
+all: lrtest.so
+
+lrtest.so: lrtest.o
+        $(CC) $(LIBFLAG) -o $@ -L$(LUA_LIBDIR) $<
+
+lrtest.o: lrtest.c
+        $(CC) -c $(CFLAGS) -I$(LUA_INCDIR) $< -o $@
+
+install: lrtest.so lrtest.lua
+        cp lrtest.so $(INST_LIBDIR)
+        cp lrtest.lua $(INST_LUADIR)
+```
+
+There is of course a lot more to a proper Makefile and rockspec, this is only
+to show how to take advantage of LuaRocks' builtin helpers for this sort of
+thing. Also, keep in mind that for additional external dependencies, more
+variables are created by LuaRocks, which have to be passed to the Makefile in
+the same way. Check the other documentation, especially [Rockspec
+format](rockspec_format.md) and [Recommended practices for
+Makefiles](recommended_practices_for_makefiles.md), for details.
+
+
diff --git a/docs/creating_a_rock.md b/docs/creating_a_rock.md
new file mode 100644
index 00000000..e93505ac
--- /dev/null
+++ b/docs/creating_a_rock.md
@@ -0,0 +1,438 @@
+# Creating a rock
+
+So, you wrote a Lua package (containing one or more modules) and want to make
+it available to users through LuaRocks. The process consists essentially of
+the following steps:
+
+* Writing a rockspec file
+* Publishing your code online
+* Submitting a rockspec for inclusion in the rocks server
+
+## Writing a rockspec
+
+A rockspec file is the metadata file for your package, containing all the
+information LuaRocks needs in order to fetch, build and install your package.
+The [Rockspec format](rockspec_format.md) supports various kinds of build
+systems, but in this tutorial we'll use LuaRocks' own built-in build system --
+that's why we're listing "Writing a rockspec" as the first step. We'll use the
+rockspec in place of a Makefile.
+
+A rockspec is actually a Lua file, but it is loaded in an empty environment,
+so there are no Lua functions available. A skeleton for a basic rockspec looks
+can be written by hand or generated using [luarocks write_rockspec](luarocks_write_rockspec.md).
+It may look like this:
+
+```lua
+package = "LuaFruits"
+version = "1.0-1"
+source = {
+   url = "..." -- We don't have one yet
+}
+description = {
+   summary = "An example for the LuaRocks tutorial.",
+   detailed = [[
+      This is an example for the LuaRocks tutorial.
+      Here we would put a detailed, typically
+      paragraph-long description.
+   ]],
+   homepage = "http://...", -- We don't have one yet
+   license = "MIT/X11" -- or whatever you like
+}
+dependencies = {
+   "lua >= 5.1, < 5.4"
+   -- If you depend on other rocks, add them here
+}
+build = {
+   -- We'll start here.
+}
+```
+
+This should be saved in a file called luafruits-1.0-1.rockspec. The name must
+contain lowercase versions of the "package" and "version" fields, or else
+LuaRocks will complain.
+
+There is some missing stuff in our rockspec which we will fill later, such as
+the source.url and description.homepage fields. We'll add those when we upload
+our sources whatever server you choose to.
+
+Right now our focus will be on the "build" section.
+
+### Building a module
+
+LuaRocks supports a number of "build types": "make" for using Makefiles,
+"cmake" for using CMake, etc. In this tutorial, however, we'll use its
+built-in build system, called the "builtin" type.
+
+```lua
+build = {
+   type = "builtin"
+   -- Now we need to tell it what to build.
+}
+```
+
+In the "builtin" type, we add a subtable called "modules", in which keys are
+module names in Lua notation, and values indicate how to build them. This
+example shows the various possibilities supported:
+
+```lua
+build = {
+   type = "builtin",
+   modules = {
+      -- A simple module written in Lua
+      apricot = "src/apricot.lua",
+
+      -- Note the required Lua syntax when listing submodules as keys
+      ["apricot.seeds"]("apricot.seeds") = "src/apricot/seeds.lua",
+
+      -- A simple module written in C
+      banana = "src/banana.c",
+
+      -- C modules can span multiple files.
+      cherry = {"src/cherry.c", "src/cherry_pie.c"},
+
+      -- C modules also support an extended syntax, supporting
+      -- cross-platform specifications of C defines, libraries and
+      -- paths for external dependencies.
+      date = {
+         sources = {"src/date.c", "src/cali_date.c", "src/arab_date.c"},
+         defines = {"MAX_DATES_PER_MEAL=50"},
+         libraries = {"date"},
+         incdirs = {"$(LIBDATE_INCDIR)"},
+         libdirs = {"$(LIBDATE_LIBDIR)"}
+      }
+   }
+}
+```
+
+Since modules written in Lua do not need to be compiled, LuaRocks only needs
+to know where they are in your source directory tree  in order to copy them to
+the proper place on installation (see the "apricot" and "apricot.seeds" in the
+above example).
+
+Similarly, for C code with no dependencies on external libraries, it suffices
+to say where the sources are and LuaRocks will invoke the appropriate compiler
+and linker for the platform. You can use a simple string value for single-file
+modules, such as the "banana" example above or an array value for multiple
+source files (as in the "cherry" example).
+
+To make writing rocks for projects with a common directory layout even easier,
+the "builtin" build type recursively copies all files and directories it finds
+in a folder called "./lua" (if it exists) to the same place as other Lua
+files.  It's almost as if an entry had been added to `modules` for every file
+in `lua`, except that the files will only be copied - files ending in ".c"
+won't be compiled.
+
+#### Depending on other rocks
+
+You can specify that your code depends on other rocks, so you can use modules
+from other rocks in your code and have them be automatically downloaded and
+installed when a user installs your rock. 
+
+Suppose we need the modules from the "luaknife" rock, in order to cut our
+fruits. But we need version later than 2.3 of luaknife, because we're using
+functions that were introduced in that version. We'll add that to our
+dependencies table:
+
+```lua
+dependencies = {
+   "lua >= 5.1, < 5.4",
+   "luaknife >= 2.3"
+}
+```
+
+Note that the dependency on Lua itself is also given in that table, and that
+it uses two constraints on its version at once: `>= 5.1` and `< 5.4`. When
+several constraints are used like this, they all have to be satisfied.
+Therefore, `lua >= 5.1, < 5.4` means that our rock supports Lua `5.1`, `5.2`,
+and `5.3`, but not yet-to-be-released `5.4`. There are a few other operators
+for specifying version constraints, see
+[Rockspec format](rockspec_format.md#dependency-information).
+
+#### C modules linking to external libraries
+
+*If your code does not use third-party libraries, you may skip this subsection.*
+
+For building C code that links to C libraries, you can use the long syntax
+given in the "date" example above, in which sources are listed in the
+"sources" subtable. You need to specify the libraries to be linked in the
+"libraries" subtable. The library name is specified in a platform-independent
+way: in the above example, `libraries={"date"}` will result in `-ldate` for
+GCC on Unix and `DATE.LIB` for MSVC on Windows. (Note that if this is not
+appropriate, the rockspec format allows [per-platform
+overrides](platform_overrides.md).) If you need to link code that uses
+libraries, you need to tell LuaRocks where to find them. You do this by adding
+a new section to the rockspec:
+
+```lua
+external_dependencies = {
+   LIBDATE = {
+      header = "libdate.h"
+   }
+}
+```
+
+Adding the "external_dependencies" table will make LuaRocks search for the
+external dependencies in its lookup path (on Unix the defaults are
+`/usr/local` and `/usr`; on Windows, which doesn't have a standard for
+development trees, you'll probably have to specify it yourself through the
+[Config file format](config_file_format.md) or the [luarocks](luarocks.md) when
+invoking "luarocks"). We give a hint to LuaRocks, the `libdate.h` header, so
+it can test whether the development package is really there (on many Linux
+distros, one needs to install "-dev" packages in order to have all headers and
+libraries needed for compilation available, so header files are a good hint).
+In this case, for example, it would look for `/usr/local/include/libdate.h`
+and `/usr/include/libdate.h` on Unix. If you (or your users) have LibDate
+installed elsewhere, it's always possible to tell LuaRocks so through the
+command-line, passing for example `LIBDATE_DIR=/opt/libdate` as an argument.
+
+When LuaRocks succeeds finding an external dependency, it creates special
+variables for it which can be used in incdirs and libdirs fields. The example
+above shows two such variables, `LIBDATE_INCDIR` and `LIBDATE_LIBDIR` being
+use. It's important to always pass those variables: if LibDate happened to be
+in the system lookup path of your compiler, compilation would succeed without
+those variables, but they would fail in a user's system where they are
+somewhere else, such as in the `LIBDATE_DIR=/opt/libdate` example given
+earlier.
+
+### Using LuaRocks as a build system
+
+Now that your build section is written, you can use LuaRocks as a build system
+and have it compile and install your code as a rock. Just type:
+
+```
+luarocks make
+```
+
+and it will do its thing. Like "make", it will look for the appropriate rules
+file (in our case, the rockspec) in the current directory and then will
+proceed to build and install the package in your rocks tree, assuming the
+sources are in the current directory as well.
+
+### Including documentation and other files
+
+In the build section you can include arbitrary files through the
+"copy_directories" table. In this table you can list directories in your rock
+that will be copied to the target rocktree during installation. 
+
+```lua
+   copy_directories = { "doc", "test" }
+```
+
+A special case for these is the "doc" directory for locally installed
+documentation. Documentation installed this way will be available on the
+target system through
+
+```
+luarocks doc ROCKNAME
+```
+
+## Publishing your code online
+
+Now, to complete the rockspec for public consumption we need to fill the
+sources.url field. For that, we need the code to be available online. We have
+two approaches for that: if you have your source code in an online repository
+such as [GitHub](GitHub)(https://github.com), you may use that directly.
+Alternatively, you can publish a tarball with the sources on the web.
+
+### Method 1: using a repository such as Github
+
+Make sure your release is tagged in your repository. Failing to use a tag will
+make LuaRocks point at your latest development code, making it a "moving
+target". LuaRocks users should be directed to a specific version of your code.
+(If you want to make a rockspec pointing at your repository's HEAD, use "scm"
+as the version number of your rockspec -- this will identify it as a rockspec
+for the "unstable" version.)
+
+In the `source.url` field, enter the URL for your repository using your SCM tool
+as the protocol. For git repositories, you don't need use the .git extension.
+Then, use the `source.tag` entry to specify your tag. For example, this is how
+our source section would look like if we hosted LuaFruits on Github:
+
+```lua
+source = {
+   url = "git://github.com/me/luafruits",
+   tag = "v1.0",
+}
+```
+
+To tag a release in Git, use the "git tag" command, and remember to pass the
+"--tags" flag to "git push":
+
+```
+git tag v1.0
+git push --tags
+```
+
+Or use GitHub's "Releases" interface.
+
+LuaRocks also supports other source control management systems, such as CVS
+(cvs://), Subversion (svn://) and Mercurial (hg://).
+
+Don't worry about deployment complications when using this method. When you
+submit a rock for inclusion in the LuaRocks repository, a .src.rock file is
+generated which contains a copy of the source code, so LuaRocks users won't
+need to have Git or any other such tool installed to use your rock.
+
+### Method 2: publishing a tarball
+
+When using a zip or tarball, by default LuaRocks expects it to contain a
+top-level directory with your code. This directory should be named the same as
+the tarball itself (but without the .zip or .tar.gz extension) and its
+recommended that this name be the lowercase name of the package with its
+version number (but without the LuaRocks revision number). If your code is
+located in a different directory, please see [Rockspec
+format](rockspec_format.md) for instructions. In our example, we should make a
+tarball with the following contents:
+
+```
+luafruits-1.0/
+luafruits-1.0/src/apricot.lua
+luafruits-1.0/src/apricot/seeds.lua
+luafruits-1.0/src/banana.c
+luafruits-1.0/src/cherry.c
+luafruits-1.0/src/cherry_pie.c
+luafruits-1.0/src/date.c
+luafruits-1.0/src/cali_date.c
+luafruits-1.0/src/arab_date.c
+```
+
+Note that the rockspec itself doesn't need to be stored in the tarball
+(actually, storing the final rockspec inside the package is a chicken-egg
+problem because rockspecs can contain the source.md5 field with a checksum of
+the tarball).
+
+It's important to note that LuaRocks does not enforce the internal structure.
+Our example only has a src/ subdirectory because the build rules listed above
+used it (we could have done without it if we wanted to). The tarball could
+contain other files as well, such as licenses and documentation. The only
+convention used here is the top level directory name, and if desired this can
+be overridden in the rockspec using the sources.dir field. So, now we pack our
+code. On Unix, for example, that would be:
+
+```
+tar czvpf luafruits-1.0.tar.gz luafruits-1.0/
+```
+
+And now we're ready to publish the tarball online. You can upload it to any
+public web server; if you need hosting space, you can use the Pages feature
+from [GitHub](GitHub)(https://github.com). Your source section would then look
+something like this:
+
+```lua
+source = {
+   url = "http://me.github.com/luafruits/luafruits-1.0.tar.gz"
+}
+```
+
+## The completed rockspec
+
+We're ready to complete our rockspec. By now it will look like this:
+
+```lua
+package = "LuaFruits"
+version = "1.0-1"
+source = {
+   url = "git://github.com/me/luafruits",
+   tag = "v1.0",
+}
+description = {
+   summary = "An example for the LuaRocks tutorial.",
+   detailed = [[
+      This is an example for the LuaRocks tutorial.
+      Here we would put a detailed, typically
+      paragraph-long description.
+   ]],
+   homepage = "http://me.github.com/luafruits",
+   license = "MIT/X11"
+}
+dependencies = {
+   "lua >= 5.1, < 5.4",
+   "luaknife >= 2.3"
+}
+external_dependencies = {
+   LIBDATE = {
+      header = "libdate.h"
+   }
+}
+build = {
+   type = "builtin",
+   modules = {
+      apricot = "src/apricot.lua",
+      ["apricot.seeds"]("apricot.seeds") = "src/apricot/seeds.lua",
+      banana = "src/banana.c",
+      cherry = {"src/cherry.c", "src/cherry_pie.c"},
+      date = {
+         sources = {"src/date.c", "src/cali_date.c", "src/arab_date.c"},
+         defines = {"MAX_DATES_PER_MEAL=50"}
+         libraries = {"date"},
+         incdirs = {"$(LIBDATE_INCDIR)"},
+         libdirs = {"$(LIBDATE_LIBDIR)"}
+      }
+   },
+   copy_directories = { "doc", "test" }
+}
+```
+
+## Submitting a rockspec for inclusion in the rocks server
+
+### Web upload
+
+This is the simplest step: just create an account at
+https://luarocks.org/register and upload your rockspec. It will automatically
+be included in the public LuaRocks repository once the mirror propagates the
+change. Users of LuaRocks >= 2.2 will be able to download your package
+immediately. We will usually publish both the .rockspec file and the
+appropriate .rock file in the server.
+
+### Pack command
+
+You can also create .rock files yourself. If you run the [luarocks
+pack](luarocks_pack.md) command on your rockspec, like this:
+
+```
+luarocks pack luafruits-1.0-1.rockspec
+```
+
+you will get a file called luafruits-1.0-1.src.rock, which contains the
+rockspec itself and your sources. Since it contains the source code, users
+won't need to use Git or whatever tool specified in source.url to fetch the
+code; it's all in the rock.
+
+If you have the rock installed in your local tree, you can also pack the
+binaries you just built:
+
+```
+luarocks pack luafruits
+```
+
+(The version is optional, latest is assumed.) This will create a file with a
+name such as luafruits-1.0-1.linux-x86.rock.
+
+### Upload command
+
+When you've verified that creating the rock works, you can upload it to the
+LuaRocks server with the [luarocks upload](luarocks_upload.md) command:
+
+```
+luarocks upload luafruits-1.0-1.rockspec --api-key=<your API key>
+```
+
+You can get an API from the [settings page of your account on the LuaRocks web
+site](https://luarocks.org/settings/api-keys).
+
+## Conclusion
+
+And we're done -- by writing a simple rules file which simply describes which
+sources compose the project and which libraries they use, we actually achieved
+a lot behind the scenes: LuaRocks takes care of using the right compiler for
+your platform (GCC? MSVC?), passing the right flags (-fpic? -shared? -bundle
+-undefined dynamic_lookup?) and checking external dependencies (/usr/lib?
+/usr/local/lib? Is it really there?). Getting all these little portability
+details right is not always easy to do on hand-written Makefiles, so that's
+why we recommend using LuaRocks's own build system whenever possible. There
+are many other features of LuaRocks we haven't covered in this tutorial
+(per-platform overrides, support for command-line scripts, etc.), but this
+should get you started.
+
+
+
diff --git a/docs/creating_luarocks_with_gnu_autotools.md b/docs/creating_luarocks_with_gnu_autotools.md
new file mode 100644
index 00000000..3e684691
--- /dev/null
+++ b/docs/creating_luarocks_with_gnu_autotools.md
@@ -0,0 +1,67 @@
+# Creating LuaRocks with GNU autotools
+
+Note that LuaRocks requires packages to be relocatable, and GNU autotools by
+default builds non-relocatable packages. For many programs it's not necessary
+to do anything particular to make them relocatable; applications which need to
+find resources at run-time may be problematic. See GNU Smalltalk for one
+approach (look at the RELOCATABILITY section in its configure.ac).
+[Zee](http://github.com/rrthomas/zee) uses another approach, of patching in
+paths for in-place running of the program during development, and relying on
+Lua search paths at run-time, purely to find Lua modules. Search for
+'in_place_lua_path'.
+
+Use a rockspec template like the following, and call it $PACKAGE.rockspec.in:
+
+```
+package="@PACKAGE@"
+ version="@VERSION@-1"
+ source = {
+   url = "https://github.com/downloads/<USER>/@PACKAGE@/@PACKAGE@-@VERSION@.tar.gz",
+   md5 = "@MD5@",
+   dir = "@PACKAGE@-@VERSION@"
+ }
+ description = {
+   summary = "<Short summary>",
+   detailed = [[
+       <Detailed information.>
+   ]],
+   homepage = "http://github.com/<USER>/@PACKAGE@/",
+   license = "<LICENSE>"
+ }
+ dependencies = {
+   "lua >= 5.1"
+ }
+ build = {
+   type = "command",
+   build_command = "LUA=$(LUA) CPPFLAGS=-I$(LUA_INCDIR) ./configure --prefix=$(PREFIX) --libdir=$(LIBDIR) --datadir=$(LUADIR) && make clean && make",
+   install_command = "make install"
+ }
+```
+
+Add "$PACKAGE.rockspec.in" to AC_CONFIG_FILES in your configure.ac:
+
+Add or amend the following rules in your Makefile.am:
+
+```
+ROCKSPEC = $(PACKAGE)-$(VERSION)-1.rockspec
+```
+
+```
+$(ROCKSPEC): $(PACKAGE).rockspec dist
+        sed -e 's/@MD5@/'`$(MD5SUM) $(distdir).tar.gz | \
+        cut -d " " -f 1`'/g' < $(PACKAGE).rockspec > $@
+```
+
+```
+EXTRA_DIST = $(PACKAGE).rockspec.in
+```
+
+```
+DISTCLEANFILES = $(PACKAGE).rockspec
+```
+
+You can use [woger](http://github.com/rrthomas/woger/) to automate your
+releases, uploading rockspecs to luarocks.org and announcements to the Lua
+mailing list. The details are evolving, so see woger itself for details, and a
+frequently-updated project such as
+[luaposix](http://github.com/luaposix/luaposix/) for example Makefile.am code.
diff --git a/docs/credits.md b/docs/credits.md
new file mode 100644
index 00000000..e5d6232c
--- /dev/null
+++ b/docs/credits.md
@@ -0,0 +1,24 @@
+# Credits
+
+# Institutional Sponsors
+
+While developed by an open source community, LuaRocks has been supported in
+various forms by a number of organizations over the years and we thank every
+one of them:
+
+* [CNPq](http://www.cnpq.br)
+* [Fábrica Digital](http://www.fabricadigital.com.br/)
+* [FINEP](http://www.finep.gov.br/)
+* [IMPA](http://www.impa.br/)
+* [LabLua](http://www.lua.inf.puc-rio.br/)
+* [itch.io](http://itch.io/)
+* [Kong](http://getkong.org/)
+
+# Developers
+
+LuaRocks is a collective project, a product of [many
+hands](https://github.com/luarocks/luarocks/graphs/contributors). The
+implementation is led by [Hisham Muhammad](http://hisham.hm), but see the [Git
+history](https://github.com/luarocks/luarocks/commits/master) for
+detailed credits.
+
diff --git a/docs/dependencies.md b/docs/dependencies.md
new file mode 100644
index 00000000..eab287aa
--- /dev/null
+++ b/docs/dependencies.md
@@ -0,0 +1,91 @@
+# Dependencies
+
+LuaRocks handles dependencies on Lua modules — rocks can specify other rocks
+it depends on, and attempts to fulfill those dependencies at install time. A
+rock will only be installed if all its dependencies can be fulfilled.
+
+LuaRocks also supports verification of dependencies on external libraries. A
+rock can specify an external package it depends on (for example, a C library),
+and give to LuaRocks hints on how to detect if it is present, typically as C
+header or library filenames. LuaRocks then looks for these files in a
+pre-configured search path and, if found, assumes the dependency is fulfilled.
+If not found, an error message is reported and the user can then install the
+missing external dependency (using the tools provided by their operating
+system) or inform LuaRocks of the location of the external dependency in case
+it was installed and LuaRocks failed to find it.
+
+Dependencies of a rock are specified in its [rockspec](rockspec_format.md)
+file. See the complete specification of the dependency syntax in the [Rockspec
+format](rockspec_format.md) page and examples in rockspec files of the [public
+rocks server](http://luarocks.org/).
+
+# Dependency modes 
+
+Since 2.0.12, the LuaRocks command-line tool supports different "dependency
+modes". These are useful to specify how it should behave on the presence of
+multiple rocks trees specified in the [config file](config_file_format.md):
+
+* `one`
+* `all`
+* `order`
+* `none`
+
+This can be set through the configuration file, using the string variable
+deps_mode (example: `deps_mode="order"`) or through the command-line, using the
+`--deps-mode` flag (example: `--deps-mode=order`).
+
+## one 
+
+This is the default behavior. LuaRocks only takes **one** rocks tree into
+account when checking dependencies. For example, if you have two rocks trees
+configured (`rocks_trees={home.."/.luarocks", "/usr"}`) and you try to install
+a rock in `$HOME/.luarocks`, it will check that all required dependencies are
+installed _in that tree_. If the dependency rock is already installed under
+`/usr`, it will ignore that copy.
+
+This is a cautious behavior because it ensures that a rock and all its
+dependencies are installed under the same tree. So, if another user modifies
+the other tree, there's no risk that the rock installed in your home tree
+might stop working.
+
+## all 
+
+LuaRocks scans **all** configured rocks trees to search for dependencies. If
+the required rock for a dependency is available in _any_ tree, it will
+consider that dependency fulfilled, and will not install that again.
+
+However, note for example that if you install a rock in /usr and its
+dependency was installed in your $HOME tree, the installed rock will work for
+your user account (which has access to the /usr tree and your home tree), but
+will probably not work for other users, if they don't have a compatible
+dependency installed in their own home trees.
+
+## order 
+
+LuaRocks uses the **order** of the list of rocks trees to determine if a rocks
+tree should be used as a valid provider of dependencies or not. LuaRocks will
+only use rocks from either the tree it is installing to, or trees that appear
+**below** the rock that's in use in the rocks_trees array. So, if your
+rocks_trees array looks like `{home.."/.luarocks", "/usr/local", "/usr"}`,
+installing a rock under your $HOME directory will accept dependencies from any
+of the three trees. Installing into `/usr/local` will use dependencies from `/usr`
+but not from the `$HOME` directory. Installing into `/usr` will use rocks from
+that tree only.
+
+So, by carefully ordering your array of rocks trees in the configuration file,
+you can use the same configuration file for both your administrator account
+and your regular user account.
+
+Note, however, that like in the "all" mode, an administrator can break a rock
+you installed in your home account by removing a dependency rock from the
+global tree.
+
+## none 
+
+LuaRocks does not use any tree, or install any dependencies. This means, of
+course, that installed rocks may be installed with missing dependencies and
+may simply not work. This mode is not recommended for general use, but it is
+useful in some specific scenarios (incorrect dependencies, batch
+recompilation, etc.)
+
+This is equivalent to the old `--nodeps` option.
diff --git a/docs/download.md b/docs/download.md
new file mode 100644
index 00000000..fd8c6655
--- /dev/null
+++ b/docs/download.md
@@ -0,0 +1,39 @@
+# Download
+
+# Downloading 
+
+Latest release: **LuaRocks 3.11.1** - '31/May/2024'
+
+* [Tarball for Unix](https://luarocks.org/releases/luarocks-3.11.1.tar.gz)
+* [Windows all-in-one executable (32-bit)](https://luarocks.org/releases/luarocks-3.11.1-windows-32.zip)
+* [Windows all-in-one executable (64-bit)](https://luarocks.org/releases/luarocks-3.11.1-windows-64.zip)
+* [other files](https://luarocks.github.io/luarocks/releases)
+
+For release notes and older versions, see the [release history](release_history.md).
+
+# Installing 
+
+* [Installation instructions for Unix](installation_instructions_for_unix.md) (Linux, BSDs, etc.)
+* [Installation instructions for macOS](installation_instructions_for_macos.md)
+* [Installation instructions for Windows](installation_instructions_for_windows.md)
+
+LuaRocks is a pure Lua application with no library dependencies. Its current
+release depends on some helper tools, but you shouldn't worry about them, as
+they are shipped by default on most Unix systems. For Windows, the all-in-one
+package already includes them and a binary of Lua, as a convenience.
+
+Once LuaRocks is installed, make sure to read the
+[Documentation](index.md) for more information!
+
+# The bleeding edge 
+
+Development is done using Git. To get the latest development sources, run:
+
+```
+git clone git://github.com/luarocks/luarocks.git
+```
+
+There is also a web interface available at:
+
+* [http://github.com/luarocks/luarocks](http://github.com/luarocks/luarocks)
+
diff --git a/docs/embedding_luarocks_in_an_application.md b/docs/embedding_luarocks_in_an_application.md
new file mode 100644
index 00000000..008be1d4
--- /dev/null
+++ b/docs/embedding_luarocks_in_an_application.md
@@ -0,0 +1,36 @@
+# Embedding LuaRocks in an application
+
+You can use LuaRocks bundled inside your application, for example, to install
+application-specific extension modules. Packaging those extensions or plugins
+as rocks reduces maintenance overhead and allows the user to perform updates.
+
+In this scenario, it is not desirable to have the application-specific
+LuaRocks and any other copy of LuaRocks installed by the user (or other
+applications!) to interfere with each other. For this reason, the `configure` 
+script allows hardcoding the location of a configuration file. For example,
+the compilation process of a package bundling LuaRocks could do something like
+this:
+
+```bash
+export PREFIX=$HOME/my-app/
+./configure --prefix=$PREFIX --sysconfdir=$PREFIX/luarocks --force-config
+```
+
+The copy of LuaRocks installed in `$HOME/my-app/` will ignore customization
+schemes such as the `$LUAROCKS_CONFIG` environment variable and will only use
+`$HOME/my-app/luarocks/config-5.x.lua`.
+
+An interesting option in those cases is for the application to provide in its
+configuration file an URL for their own rocks repository, so they can have
+control over updates to be performed. Continuing the previous example, the
+config-5.x.lua file could contain something like this:
+
+```lua
+ rocks_servers = {
+    "http://www.example.com/my-app-plugins/rocks/"
+ }
+```
+
+This way the bundled copy of LuaRocks will download rocks from your app's
+plugins and not the https://luarocks.org server (note that the user would
+still be able to override it explicitly using the `--server` flag).
diff --git a/docs/file_formats.md b/docs/file_formats.md
new file mode 100644
index 00000000..9030cd26
--- /dev/null
+++ b/docs/file_formats.md
@@ -0,0 +1,23 @@
+# File formats
+
+These pages are the reference specification for file formats used by LuaRocks.
+All files are actual Lua files, but they are loaded in a restricted
+environment in which the standard Lua libraries are not available.
+
+* [Rockspec format](rockspec_format.md) - Rockspecs are the files which
+  contain rules explaining how rocks are built and installed as well as their
+  dependencies and other metadata.
+
+* [Config file format](config_file_format.md) - The specification of the
+  LuaRocks configuration file format, as it takes shape.
+
+* [Manifest file format](manifest_file_format.md) - The index file that
+  describes a LuaRocks [repository](rocks_repositories.md), used by both rocks
+  servers and rocks trees.
+
+* [Rock file format](rock_file_format.md) - Reference to the .rock file
+  format: the installable packages produced from
+  [rockspecs](rockspec_format.md).
+
+
+
diff --git a/docs/file_locations.md b/docs/file_locations.md
new file mode 100644
index 00000000..d8e1c684
--- /dev/null
+++ b/docs/file_locations.md
@@ -0,0 +1,110 @@
+# File locations
+
+This is a summary of all file paths related to LuaRocks, including the files
+that compose LuaRocks (its scripts and modules), files installed by LuaRocks
+(Lua modules and scripts), and files required by LuaRocks (programs, libraries
+and headers).
+
+For each path, the default value is also listed.
+
+Whenever "5.x" is used, it refers to the Lua version you configured during
+installation.
+
+# Path to LuaRocks 
+
+* LuaRocks command-line scripts. These are the main LuaRocks commands
+  (`luarocks`, `luarocks-admin`); it should be in your system PATH.
+
+  * Unix default: /usr/local/bin
+
+* LuaRocks modules. These are Lua modules (`luarocks.fs`, etc.) used by
+  LuaRocks. The LuaRocks command-line tools are configured during installation
+  to be able to find those files.
+
+  * Unix default: /usr/local/share/lua/5.x/
+
+# Path to Lua binaries and associated data 
+
+* Lua interpreter. Where to find the Lua interpreter to execute scripts and
+  LuaRocks itself.
+
+  * Unix default: /usr/local/bin/lua
+
+* Lua libraries. The directory containing the Lua virtual machine as a shared
+  library. On some platforms, Lua modules written in C (also called "C
+  modules") should link against this library
+
+  * Unix default: /usr/local/lib
+
+* Lua header files (lua.h, etc.). They are required when compiling C modules.
+
+  * Unix default: /usr/local/include
+
+On Unix, those locations vary according to your OS variant or distribution. If
+you're using a Linux distribution, for example, you may have installed Lua
+using your package manager and paths use /usr/ rather than /usr/local/, and
+the `lua` binary may be called `lua-5.x`.
+
+For Windows users, having libraries and headers around may be uncommon, as
+Windows tends to have binary distributions. LuaRocks can provide binary rocks,
+but rocks in the standard repository are often available only as source code
+and need to be compiled during the installation process.
+
+# Paths to rocks trees 
+
+LuaRocks by default is configured to use two rocks trees:
+
+* System-wide [rock tree](rocks_repositories.md) (used by default)
+  * Unix default: /usr/local/
+* Per-user [rock tree](rocks_repositories.md) (may be selected by the user with the --local flag).
+  * Unix default: $HOME/.luarocks/
+
+In order to use the modules installed in the rock trees, the [deployment
+directories](rocks_repositories.md) should be in the `LUA_PATH` and
+`LUA_CPATH` environment variables. 
+
+On Unix, performing a vanilla installation of Lua from lua.org and a vanilla
+installation of LuaRocks will install both under /usr/local, meaning that the
+environment variables for the system-wide rock tree are correct by default.
+
+The command `[luarocks path](luarocks_path.md)` outputs the correct environment
+variables set for a rock tree.
+
+# Path where command-line scripts are installed 
+
+Rocks may also deploy command-line scripts. This location is relative to the
+rock tree where they are installed:
+
+* System-wide [rock tree](rocks_repositories.md) (used by default)
+
+  * Unix default: /usr/local/bin/
+
+* Per-user [rock tree](rocks_repositories.md) (may be selected by the user
+  with the --local flag).
+
+  * Unix default: $HOME/.luarocks/bin/
+
+To be able to call those scripts from the shell, the location where they are
+installed need to be in your environment path. 
+
+On Unix, /usr/local/bin is usually in the $PATH by default, but
+$HOME/.luarocks/bin is not. 
+
+The command `[luarocks path](luarocks_path.md) --bin` outputs the correct PATH
+environment variables set for a rock tree.
+
+# Compiler 
+
+For compiling modules written in C, you need a compiler toolchain installed.
+
+For many platforms this is a non-issue: Linux distribution often include
+`gcc` (the default installation of Ubuntu, notably, ships without build
+tools by default: run `sudo apt-get install build-essential`).
+
+On Windows, where binary distribution is the standard, this might be an
+additional requirement. Because more rocks are available as source code than
+as binary rocks, it is probably best to have a C compiler available. LuaRocks
+supports MinGW and the Microsoft Visual Studio toolchains. The compiler should
+be in the system path, or explicitly configured in the LuaRocks config files.
+
+
diff --git a/docs/hosting_binary_rocks.md b/docs/hosting_binary_rocks.md
new file mode 100644
index 00000000..1df055ab
--- /dev/null
+++ b/docs/hosting_binary_rocks.md
@@ -0,0 +1,41 @@
+# Hosting binary rocks
+
+At the moment, LuaRocks.org hosts only rockspecs and src.rock files, and not
+binary rocks. But you can host your own repository of binary rocks at any
+static HTTP server (for example, Github Pages).
+
+Suppose you want to host a binary rock for a rock of yours named `my_rock`:
+
+Step 1: build your rocks with `luarocks build my_rock`. This will compile your
+rocks locally in your system. After a successful build, you should see them
+installed with `luarocks list`.
+
+Step 2: create binary rocks from using `luarocks pack my_rock`. This will
+create a binary rock file, named after your operating system and processor,
+for example, `my_rock-1.0-1-macosx-x86_64.rock`. Note that this binary is
+dependent on library versions of your own machine. This is more of an issue in
+some operating systems than others (Linux binaries are very picky with library
+dependencies, so it's helpful to build binaries on older distros for greater
+compatibility.)
+
+Step 2.5: if your rock has dependencies, repeat step 2 for them as well.
+
+Step 3: create a new directory `my_dir`, copy your rock binary into it (and
+possibly your rockspec and src.rock as well, for a nice one-stop-shop of your
+rock) and run `luarocks-admin make-manifest my_dir`. This will create files
+named `manifest-*` in it, which turn this directory into a working LuaRocks
+server. You can even use it locally: `luarocks install --server=my_dir
+my_rock` should work!
+
+Step 4: upload the contents of `my_dir`, manifest files and rocks, into a HTTP
+server and use its URL as the argument of `--server`. For example, if you
+uploaded it into `http://example.com/binary-rock/manifest-5.3` and
+`http://example.com/binary-rock/my-rock-1.0-1-macosx-x86_64.rock`, then using
+`luarocks install --server=http://example.com/binary-rock my_rock` should
+fetch the manifest, read it, find the rock name, download it and install it.
+
+Note that in a repo that contains both binary and source rocks, running
+`luarocks install http://example.com/binary-rock my_rock` will download and
+install the binary rock, and  `luarocks build http://example.com/binary-rock
+my_rock` will download, compile and install the source rock.
+
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..584414ab
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,80 @@
+# Index
+
+* [Welcome](welcome.md)
+
+* Installing LuaRocks
+  * [Download](download.md)
+    * [Installation instructions for Unix](installation_instructions_for_unix.md)
+    * [Installation instructions for macOS](installation_instructions_for_macos.md)
+    * [Installation instructions for Windows](installation_instructions_for_windows.md)
+
+* Using LuaRocks
+  * [Using LuaRocks](using_luarocks.md)
+  * [Types of rocks](types_of_rocks.md)
+  * [Rocks repositories](rocks_repositories.md)
+  * [Browse rocks](browse_rocks.md)
+  * [Dependencies](dependencies.md)
+    * [Paths and external dependencies](paths_and_external_dependencies.md)
+    * [Namespaces](namespaces.md)
+    * [Pinning versions with a lock file](pinning_versions_with_a_lock_file.md)
+  * [Community support and more resources](more_resources.md)
+
+* Creating rocks
+  * [Creating a rock](creating_a_rock.md)
+  * [Platform overrides](platform_overrides.md)
+  * [Platform-agnostic external dependencies](platform_agnostic_external_dependencies.md)
+  * [Recommended practices for Makefiles](recommended_practices_for_makefiles.md)
+    * [Creating a Makefile that plays nice with LuaRocks](creating_a_makefile_that_plays_nice_with_luarocks.md)
+  * [Creating LuaRocks with GNU autotools](creating_luarocks_with_gnu_autotools.md)
+
+* Advanced topics
+  * [LuaRocks through a proxy](luarocks_through_a_proxy.md)
+  * [Embedding LuaRocks in an application](embedding_luarocks_in_an_application.md)
+  * [Integrating distro modules with LuaRocks](integrating_distro_modules_with_luarocks.md)
+  * [Hosting binary rocks](hosting_binary_rocks.md)
+
+* Reference
+  * [File formats](file_formats.md)
+    * [Config file format](config_file_format.md)
+    * [Rock file format](rock_file_format.md)
+    * [Rockspec format](rockspec_format.md)
+    * [Rock manifest file format](rock_manifest_file_format.md)
+    * [Manifest file format](manifest_file_format.md)
+
+  * [File locations](file_locations.md)
+
+  * Command-line interface
+    * [luarocks](luarocks.md)
+      * [luarocks build](luarocks_build.md)
+      * [luarocks config](luarocks_config.md)
+      * [luarocks doc](luarocks_doc.md)
+      * [luarocks download](luarocks_download.md)
+      * [luarocks help](luarocks_help.md)
+      * [luarocks install](luarocks_install.md)
+      * [luarocks lint](luarocks_lint.md)
+      * [luarocks list](luarocks_list.md)
+      * [luarocks make](luarocks_make.md)
+      * [luarocks new_version](luarocks_new_version.md)
+      * [luarocks pack](luarocks_pack.md)
+      * [luarocks path](luarocks_path.md)
+      * [luarocks purge](luarocks_purge.md)
+      * [luarocks remove](luarocks_remove.md)
+      * [luarocks search](luarocks_search.md)
+      * [luarocks show](luarocks_show.md)
+      * [luarocks test](luarocks_test.md)
+      * [luarocks unpack](luarocks_unpack.md)
+      * [luarocks upload](luarocks_upload.md)
+      * [luarocks write_rockspec](luarocks_write_rockspec.md)
+
+    * [luarocks-admin](luarocks_admin.md)
+      * [luarocks-admin add](luarocks_admin_add.md)
+      * [luarocks-admin help](luarocks_admin_help.md)
+      * [luarocks-admin make manifest](luarocks_admin_make_manifest.md)
+      * [luarocks-admin refresh cache](luarocks_admin_refresh_cache.md)
+      * [luarocks-admin remove](luarocks_admin_remove.md)
+
+  * [Release history](release_history.md)
+
+* [Credits](credits.md)
+* [License](license.md)
+* [Index](index.md)
diff --git a/docs/installation_instructions_for_macos.md b/docs/installation_instructions_for_macos.md
new file mode 100644
index 00000000..216e042d
--- /dev/null
+++ b/docs/installation_instructions_for_macos.md
@@ -0,0 +1,39 @@
+# Installation instructions for macOS
+
+LuaRocks is a command-line tool. You can install LuaRocks using one of the
+third-party package managers available for macOS (formerly known as "Mac OS X"
+or "OS X"), or you may install it manually, in the Unix way.
+
+# Option 1: using Homebrew 
+
+One option is to use [Homebrew](https://brew.sh). If you don't have it
+installed, follow its installation instructions.
+
+If you already have it installed, make sure it is up to date so you pick the
+most recent version of LuaRocks:
+
+```
+brew update
+```
+
+and then install LuaRocks:
+
+```
+  brew install luarocks
+```
+
+# Option 2: installing it manually 
+
+If you do not wish to use a package management tool to install LuaRocks, you
+can install it on macOS as you would do in any other Unix system, assuming you
+have the Mac Developer Tools installed. Download the Unix tarball and then
+follow the [installation instructions for
+Unix](installation_instructions_for_unix.md) to install it to /usr/local.
+
+# Next steps 
+
+Once LuaRocks is installed, learn more about [using
+LuaRocks](using_luarocks.md).
+
+
+
diff --git a/docs/installation_instructions_for_unix.md b/docs/installation_instructions_for_unix.md
new file mode 100644
index 00000000..79afc64e
--- /dev/null
+++ b/docs/installation_instructions_for_unix.md
@@ -0,0 +1,140 @@
+# Installation instructions for Unix
+
+First of all, get the [latest ".tar.gz" package
+here](http://luarocks.github.io/luarocks/releases).
+
+The LuaRocks build system for Unix is based on a simple "configure" script and
+a Makefile. The "configure" script offers some flags that are useful for
+different models of use of LuaRocks. Run `./configure --help` for details.
+
+## Quick start
+
+To get a default installation of Lua and LuaRocks under `/usr/local`:
+
+First, ensure that you have development tools installed on your system,
+otherwise run the command below to install them.
+
+For Ubuntu/Debian systems, this should do it:
+
+``` 
+-$ sudo apt install build-essential libreadline-dev unzip
+```
+
+For Yum-based distributions, try this:
+
+``` 
+-$ sudo yum install libtermcap-devel ncurses-devel libevent-devel readline-devel
+```
+
+Then, to build and install Lua, either install it using your package
+manager of choice, or run the following commands to download the
+package tarball, extract, build and install it. (Replace 5.3.5 with the
+latest Lua version.)
+
+```
+-$ curl -R -O http://www.lua.org/ftp/lua-5.3.5.tar.gz
+-$ tar -zxf lua-5.3.5.tar.gz
+-$ cd lua-5.3.5
+-$ make linux test
+-$ sudo make install
+```
+
+Once Lua and its dependencies are installed, it is time to install LuaRocks:
+
+* Download and unpack [latest ".tar.gz" file](http://luarocks.github.io/luarocks/releases).
+
+* Run `./configure --with-lua-include=/usr/local/include`. (This will attempt
+  to detect your installation of Lua. If you get any error messages, see the
+  section [Customizing your settings](#customizing-your-settings), below.)
+
+* Run `make`.
+
+* As superuser, run `make install`.
+
+Installation should be done! Run `luarocks` with no arguments to 
+see a summary of your settings.
+
+This should be sufficient. For more information and installation options, read on.
+
+## The default settings
+
+The default settings are suitable for installing LuaRocks globally in your
+system while allowing both system-wide and per-user sets of rocks. User
+accounts will be able to install their own rocks in their $HOME directory, and
+the superuser can install rocks that will be available for everyone.
+
+By default LuaRocks will install itself in `/usr/local`, like Lua, and will
+use `/usr/local/etc/luarocks/config.lua` as a default path for the
+configuration file. The default system-wide rocks trees is configured as
+`/usr/local/lib/luarocks`, and per-user rocks install at
+`$HOME/.luarocks/rocks/`. Command-line scripts provided by rocks will be
+installed in `/usr/local/lib/luarocks/bin/` or `$HOME/.luarocks/bin/`,
+respectively. The user may then add these directories to their `$PATH`
+variable.
+
+## Customizing your settings
+
+All paths described above can be overridden with flags in the `configure`
+script, or entries in the configuration file. These are the supported flags,
+as presented by the `--help` option:
+
+```
+Installation directories:
+  --prefix=PREFIX              Directory where LuaRocks should be installed,
+                               Default is '/usr/local'
+
+By default, `make install' will install all the files in `/usr/local',
+`/usr/local/lib' etc.  You can specify an installation prefix other than
+`/usr/local/' using `--prefix', for instance `--prefix=$HOME'.
+
+For better control, use the options below.
+
+Fine tuning of the installation directories:
+  --sysconfdir=SYSCONFDIR      Directory for single-machine config.
+                               Default is PREFIX/etc
+
+Where to install files provided by rocks:
+  --rocks-tree=DIR             Root of the local tree of installed rocks.
+                               To make files installed in this location
+                               accessible to Lua and your $PATH, see
+                               "luarocks path --help" after installation.
+                               Avoid using paths controlled by your
+                               system's package manager, such as /usr.
+                               - Default is PREFIX
+
+Where is your Lua interpreter:
+  --lua-version=VERSION        Use specific Lua version: 5.1, 5.2, 5.3, or 5.4
+                               - Default is auto-detected.
+  --with-lua-bin=LUA_BINDIR    Location of your Lua binar(y/ies).
+                               - Default is the directory of the
+                               auto-detected Lua interpreter,
+                               (or DIR/bin if --with-lua is used)
+  --with-lua=LUA_DIR           Use Lua from given directory. Default is LUA_BINDIR/..
+  --with-lua-include=DIR       Lua's includes dir. Default is LUA_DIR/include
+  --with-lua-lib=DIR           Lua's libraries dir. Default is LUA_DIR/lib
+  --with-lua-interpreter=NAME  Lua interpreter name.
+                               - Default is to auto-detected
+
+For specialized uses of LuaRocks:
+  --force-config               Force using a single config location.
+                               Do not honor the $LUAROCKS_CONFIG_5_x
+                               or $LUAROCKS_CONFIG environment
+                               variable or the user's local config.
+                               Useful to avoid conflicts when LuaRocks
+                               is embedded within an application.
+  --disable-incdir-check       If you do not wish to use "luarocks build",
+                               (e.g. when only deploying binary packages)
+                               you do not need lua.h installed. This flag
+                               skips the check for lua.h in "configure".
+
+```
+
+After installation, a default config file called config.lua will be installed
+at the directory defined by `--sysconfdir`. For further configuration of
+LuaRocks paths, see the [Config file format](config_file_format.md).
+
+## Next steps
+
+Once LuaRocks is installed, learn more about [using LuaRocks](using_luarocks.md).
+
+
diff --git a/docs/installation_instructions_for_windows.md b/docs/installation_instructions_for_windows.md
new file mode 100644
index 00000000..b8c18c9d
--- /dev/null
+++ b/docs/installation_instructions_for_windows.md
@@ -0,0 +1,159 @@
+# Installation instructions for Windows
+
+There are two packages for Windows:
+
+* if you already have a Lua installation, the <b>single binary</b> package
+  which you can use: get the [latest windows-32.zip file
+  here](http://luarocks.github.io/luarocks/releases), unpack it and you'll
+  have a <tt>luarocks.exe</tt> ready to use. Make sure the executable is
+  available from your executable PATH so you can run <tt>luarocks</tt> from
+  the command line the same way you run <tt>lua</tt>.
+
+* we also provide an all-in-one package which includes Lua 5.1 and LuaRocks in
+  source format; get the [latest win32.zip file
+  here](http://luarocks.github.io/luarocks/releases). The instructions below
+  are about this package.
+
+This page refers to the second method. The all-in-one package includes
+everything you need to launch LuaRocks, including helper binaries and a
+Lua interpreter. (You can use your own Lua interpreter if you already have
+one installed, see below.)
+
+<b>Important:</b> To compile many Lua packages, you will also need a C compiler.
+The installer batch file included in the all-in-one package attempts to detect
+if you have Microsoft Visual Studio or [Mingw](https://mingw.org) (Minimalistic GNU for Windows, which includes GCC).
+
+The installer script, <tt>INSTALL.BAT</tt>, provides a number of options for
+customizing your installation. Run <tt>INSTALL /?</tt> for details.
+
+Run `INSTALL.BAT` it from a Command Prompt window. If you will be using it
+with Microsoft Visual Studio, it is recommended to use LuaRocks with the
+Visual Studio Command Prompt, where all environment variables for using the
+MSVC compiler, `cl`, are set.
+
+* If you using <a href="https://www.cygwin.com/">Cygwin</a> then go through [installation instructions for Unix](installation_instructions_for_unix.md).
+
+# The default settings 
+
+The default settings are suitable for installing LuaRocks globally
+in your system while allowing both system-wide and per-user sets of rocks.
+Non-priviledged accounts will be able to install their own rocks in their
+%APPDATA% directory, and administrator accounts can install rocks that
+will be available for everyone.
+
+# Making a system-wide repository 
+
+All paths described above can be overridden with flags in the INSTALL.BAT script,
+or entries in the configuration file.
+
+{|
+| /P _dir_       || Where to install. Default is %PROGRAMFILES%\LuaRocks\_version_. Because LuaRocks contains 32bit executables, this will be in the c:\program files (x86)\ path on 64bit systems.
+|}
+
+Configuring the destinations:
+
+{| cellpadding=5px
+| /TREE _dir_    || Root of the local tree of installed rocks. Default is %PROGRAMFILES%\LuaRocks\systree. On 64bit systems this default depends on the Lua interpreter used. A 64bit interpreter will have the c:\program files\ path, where a 32bit interpreter on a 64bit system will follow the c:\program files (x86)\ path.
+|-------------------------------------------------------------------------
+| /SCRIPTS _dir_ || Where to install commandline scripts installed by rocks. Default is {TREE}/bin.
+|-------------------------------------------------------------------------
+| /CONFIG _dir_  || Location where the config file should be installed. Default is to follow /P option
+|-------------------------------------------------------------------------
+| /SELFCONTAINED   || Creates a self contained installation in a single directory given by /P. Sets the /TREE and /CONFIG options to the same location as /P. And does not load registry info with option /NOREG. The only option NOT self contained is the user rock tree, so don't use that if you create a self contained installation.
+|}
+
+Configuring the Lua interpreter:
+
+{| cellpadding=5px
+| /LV _version_  || Lua version to use; either 5.1, 5.2 or 5.3. Default is auto-detected.
+|-------------------------------------------------------------------------
+| /LUA _dir_     || Location where Lua is installed - e.g. c:\lua\5.1\. If not provided, the installer will search the system path and some default locations for a valid Lua installation. This is the base directory, the installer will look for subdirectories bin, lib, include. Alternatively these can be specified explicitly using the /INC, /LIB, and /BIN options.
+|-------------------------------------------------------------------------
+| /INC _dir_     || Location of Lua includes - e.g. c:\lua\5.1\include. If provided overrides sub directory found using /LUA.
+|-------------------------------------------------------------------------
+| /LIB _dir_     || Location of Lua libraries (.dll/.lib) - e.g. c:\lua\5.1\lib. If provided overrides sub directory found using /LUA.
+|-------------------------------------------------------------------------
+| /BIN _dir_     || Location of Lua executables - e.g. c:\lua\5.1\bin. If provided overrides sub directory found using /LUA.
+|-------------------------------------------------------------------------
+| /L             || Install LuaRocks' own copy of Lua even if detected, this will always be a 5.1 installation. (/LUA, /INC, /LIB, /BIN cannot be used with /L)
+within an application.
+|}
+
+Compiler configuration:
+
+{| cellpadding=5px
+| /MW             || Use mingw as build system instead of MSVC.
+|}
+
+Other options:
+
+{| cellpadding=5px
+| /FORCECONFIG   || Use a single config location. Do not use the LUAROCKS_CONFIG variable or the user's home directory. Useful to avoid conflicts when LuaRocks is embedded 
+|-------------------------------------------------------------------------
+| /F             || Force. Remove installation directory if it already exists.
+|-------------------------------------------------------------------------
+| /NOREG         || Do not load registry info to register '.rockspec' extension with LuaRocks commands (right-click).
+|-------------------------------------------------------------------------
+| /NOADMIN       || The installer requires admin priviledges. If not available it will elevate a new process. Use this switch to prevent elevation, but make sure the destination paths are all accessible for the current user.
+|-------------------------------------------------------------------------
+| /Q             || Do not prompt for confirmation of settings
+|}
+
+After installation, a default config file called config.lua will be installed at the directory defined by /CONFIG. For further configuration of LuaRocks paths, see the [Config file format](config_file_format.md). For more information on the structure of rocks trees see [rocks repositories](rocks_repositories.md).
+
+# Making a self-contained installation 
+
+Another option is to install LuaRocks in a self-contained manner. This
+is an interesting alternative when shipping an application which uses
+third-party modules. Bundling them as rocks reduces maintenance overhead
+and allows the user to perform updates.
+
+In this scenario, it is not desired to have the user's (or the system's)
+configuration affect the self-contained LuaRocks install, in case the 
+user or the system also have different LuaRocks installations. For this
+reason, the INSTALL.BAT script allows to hardcode the location of a
+configuration file. For example, the compilation process of a package
+bundling LuaRocks could do something like this:
+
+```
+SET PREFIX=C:\mypackage
+ INSTALL /P %PREFIX% /CONFIG %PREFIX%\luarocks
+```
+
+The copy of LuaRocks installed in C:\mypackage will ignore
+customization schemes such as the %LUAROCKS_CONFIG% environment variable
+and will only use C:\mypackage\luarocks\config.lua.
+
+An interesting option in those cases is for the application to provide
+in its configuration file an URL for their own rocks repository, so they
+can have control over updates to be performed. Continuing the previous
+example, luarocks\config.lua could contain something like this:
+
+```
+repositories = {
+    "http://www.example.com/rocks/"
+ }
+```
+
+# Picking the Lua interpreter 
+
+LuaRocks can use its own Lua interpreter provided by the Lua for WIndows project,
+and will do so by default if it fails to find your Lua installation
+automatically. If you want to use your own interpreter, which is not on the system path, 
+you can pass its path using the /LUA variable (or /BIN, /LIB and /INC explicitly, if 
+you have a custom directory structure).
+
+When looking for an interpreter, it will also try to figure out the name of 
+the Lua binary (lua.exe, lua5.1.exe). This is set in the `lua_interpreter`
+variable in the configuration file. If you want to use an alternative name to the
+interpreter, you can set that variable in your configuration file directly.
+
+An important element is the runtime libraries used by the interpreter, as LuaRocks must
+compile additional rocks installed with the same runtime as the interpreter. To do this
+LuaRocks will analyse the executable found.
+
+# Next steps 
+
+Once LuaRocks is installed, learn more about [using LuaRocks](using_luarocks.md).
+
+
diff --git a/docs/integrating_distro_modules_with_luarocks.md b/docs/integrating_distro_modules_with_luarocks.md
new file mode 100644
index 00000000..fb073500
--- /dev/null
+++ b/docs/integrating_distro_modules_with_luarocks.md
@@ -0,0 +1,190 @@
+# Integrating distro modules with LuaRocks
+
+This is documentation on strategies to integrate OS-installed modules (e.g.
+packages such as `luafilesystem` and `lpeg` provided by Linux distros) with
+existing versions of LuaRocks.
+
+This page will list two approaches: the minimal one, and a more complete one
+that extends the first one.
+
+## Assumptions
+
+* The examples below use Lua 5.3 — just change "5.3" to "5.1" or "5.2" and the
+  same applies.
+* Distro-installed modules live at standard Lua locations under `/usr`, such
+  as `/usr/lib/lua/5.3/lfs.so`
+
+## The bare minimum approach
+
+This is the _minimum_ that should be added to distro module packages so that
+they visible as dependencies by LuaRocks:
+
+### The main manifest file
+
+For LuaRocks to be able to find any OS-installed modules, there needs to be an
+index file called `manifest` at `/usr/lib/luarocks/rocks-5.3/`.
+
+This file should be generated running:
+
+```
+luarocks-admin make-manifest --local-tree --tree=/usr
+```
+
+This should be run as a post-install action after installing any module via
+the distro. This file is the LuaRocks "index" and should be kept up-to-date or
+else LuaRocks doesn't know about the installed modules.
+
+### Rock metadata necessary to build the main manifest
+
+For the above command to work, there has to be a directory tree for each rock
+and version, containing, at the bare minimum, a `rock_manifest` file. The
+structure looks like this:
+
+`/usr/lib/luarocks/rocks-$LUA_VERSION/$ROCK_NAME/$ROCK_VERSION-$ROCK_REVISION/`
+
+* $LUA_VERSION with with a dot: "5.3"
+
+* $ROCK_NAME should match the name used in the luarocks.org repository — in other words, `luafilesystem` has to be called `luafilesystem`, not `lfs`. LuaRocks checks dependencies by rock name, not by individual module name.
+
+* $ROCK_VERSION usually matches upstream, so that's not an issue.
+
+* $ROCK_REVISION can always be 0 for our purposes here.
+
+Examples:
+
+* /usr/lib/luarocks/rocks-5.3/lpeg/1.0.0-0/
+* /usr/lib/luarocks/rocks-5.3/luafilesystem/1.6.0-0/
+* /usr/lib/luarocks/rocks-5.3/lua-cjson/2.1.0-0/
+
+### The rock_manifest file
+
+Inside the version directory for a rock there must be a `rock_manifest` file.
+The minimal contents of `rock_manifest` to make `luarocks-admin` not fail is
+simply:
+
+```lua
+rock_manifest = {}
+```
+
+This means that in the above examples, we'd have several identical one-liner files:
+
+* /usr/lib/luarocks/rocks-5.3/lpeg/1.0.0-0/rock_manifest
+* /usr/lib/luarocks/rocks-5.3/luafilesystem/1.6.0-0/rock_manifest
+* /usr/lib/luarocks/rocks-5.3/lua-cjson/2.1.0-0/rock_manifest
+
+### Necessary LuaRocks configuration
+
+With those empty manifests, the post-install operation mentioned above works
+and a later `luarocks install` will the existence of the "rocks" in /usr,
+given the following configuration in `/etc/luarocks/config-5.3.lua`:
+
+```
+rocks_trees = {
+   { name = "user", root = home.."/.luarocks" },
+   { name = "distro-modules", root = "/usr" },
+   { name = "system", root = "/usr/local" },
+}
+deps_mode = "all"
+```
+
+It's important that the "system" tree is the last entry: it is the one used
+for system-wide installation of rocks using LuaRocks (when `sudo luarocks` is
+used). The "distro-modules" tree should never be used directly by the user.
+
+For more info on the deps_mode flag, see the [Dependency
+modes](dependencies.md#dependency-modes) documentation.
+
+### Caveats
+
+*Error messages*: Running with such bare minimum setup will resolve
+dependencies, but running the post-install operation above will output error
+messages when running, such as...
+
+```
+Tree inconsistency detected: luafilesystem 1.6.0-0 has no rockspec. Could not load rockspec file /usr/lib/luarocks/rocks-5.3/luafilesystem/1.6.0-0/luafilesystem-1.6.0-0.rockspec (/usr/lib/luarocks/rocks-5.3/luafilesystem/1.6.0-0/luafilesystem-1.6.0-0.rockspec: No such file or directory)"
+```
+
+...for each entry under `/usr/lib/luarocks/rocks-5.3` (for our purposes, these
+can be simply ignored and silenced away with `&> /dev/null`).
+
+*Failed commands*: this minimal tree will work for solving dependencies, but
+not for much else. In particular, `luarocks list --tree=/usr` will work, but
+`luarocks show lpeg --tree=/user` will not, complaining that it can't find a
+rockspec.
+
+## A more complete approach
+
+A more complete approach to make commands such as `luarocks show` to work
+would entail two steps: adding proper contents to `rock_manifest` and
+including a rockspec file for each module.
+
+### A complete rock_manifest
+
+A workable version of `rock_manifest` with contents would look like this:
+
+```
+rock_manifest = {
+   lib = {
+      ["lpeg.so"] = "136a74c6e472c36a65449184e1820a31"
+   },
+   ["lpeg-1.0.0-0.rockspec"] = "4933a611af43404761002ee139c393e8",
+   lua = {
+      ["re.lua"] = "5f09bb0129b09b6a8e8c1db1b206b1ca"
+   }
+}
+```
+
+The entries under `lib` are the files installed by the package at `/usr/lib/5.3`.
+The entries under `lua` are the files installed by the package at `/usr/share/5.3`.
+The rockspec key is the rockspec file to be stored alongside the `rock_manifest` file.
+The values to these entries are MD5 sums to the files in question.
+
+### Including a rockspec file
+
+For `luarocks show` to display metadata properly, a rockspec file must exist.
+It should be named according to the pattern
+`$ROCK_NAME-$ROCK_VERSION-$ROCK_REVISION.rockspec` (in all lowercase).
+Continuing the examples above:
+
+* /usr/lib/luarocks/rocks-5.3/lpeg/1.0.0-0/lpeg-1.0.0-0.rockspec
+* /usr/lib/luarocks/rocks-5.3/luafilesystem/1.6.0-0/luafilesystem-1.6.0-0.rockspec
+* /usr/lib/luarocks/rocks-5.3/lua-cjson/2.1.0-0/lua-cjson-2.1.0-0.rockspec
+
+For simplicity, I would recommend just copying over the appropriate rockspec
+file from [luarocks.org](http://luarocks.org) and bundling them in the package
+metadata. For completeness, this is how the one for LPeg 1.0 looks like:
+
+```
+package = "LPeg"
+version = "1.0.0-1"
+source = {
+   url = "http://www.inf.puc-rio.br/~roberto/lpeg/lpeg-1.0.0.tar.gz",
+   md5 = "0aec64ccd13996202ad0c099e2877ece",
+}
+description = {
+   summary = "Parsing Expression Grammars For Lua",
+   detailed = [[
+      LPeg is a new pattern-matching library for Lua, based on Parsing
+      Expression Grammars (PEGs). The nice thing about PEGs is that it
+      has a formal basis (instead of being an ad-hoc set of features),
+      allows an efficient and simple implementation, and does most things
+      we expect from a pattern-matching library (and more, as we can
+      define entire grammars).
+   ]],
+   homepage = "http://www.inf.puc-rio.br/~roberto/lpeg.html",
+   maintainer = "Gary V. Vaughan <gary@vaughan.pe>",
+   license = "MIT/X11"
+}
+dependencies = {
+   "lua >= 5.1"
+}
+build = {
+   type = "builtin",
+   modules = {
+      lpeg = {
+         "lpcap.c", "lpcode.c", "lpprint.c", "lptree.c", "lpvm.c"
+      },
+      re = "re.lua"
+   }
+}
+```
diff --git a/docs/license.md b/docs/license.md
new file mode 100644
index 00000000..7ff07be0
--- /dev/null
+++ b/docs/license.md
@@ -0,0 +1,5 @@
+# License
+
+LuaRocks uses the MIT license. See the file
+[COPYING](https://github.com/luarocks/luarocks/blob/master/COPYING) at the
+root of the repository for the license text.
diff --git a/docs/luarocks.md b/docs/luarocks.md
new file mode 100644
index 00000000..91bb6731
--- /dev/null
+++ b/docs/luarocks.md
@@ -0,0 +1,102 @@
+# luarocks
+
+**luarocks** is the command-line interface for LuaRocks, the Lua package manager.
+
+# Usage
+
+```
+luarocks [--server=<server> | --only-server=<server>] [--tree=<tree>] [--only-sources=<url>] [--deps-mode=<mode>] [<VAR>=<VALUE>]... <command> [<argument>]
+```
+
+Variables from the "variables" table of the [configuration file](config_file_format.md) can be overriden with VAR=VALUE assignments.
+
+{|
+| --server=_server_ || Fetch rocks/rockspecs from this server (takes priority over config file)
+|-
+| --only-server=_server_ || Fetch rocks/rockspecs from this server only (overrides any entries in the config file)
+|-
+| --only-sources=_url_ || Restrict downloads of sources to URLs starting with the given URL. For example, --only-sources=http://luarocks.org will allow LuaRocks to download sources only if the URL given in the rockspec starts with http://luarocks.org .
+|-
+| --tree=_tree_ || Which tree to operate on.
+|-
+| --local || Use the tree in the user's home directory. To enable it, see `[luarocks path](luarocks_path.md)`
+|-
+| --deps-mode=_mode_ || Select dependencies mode:
+
+How to handle the list of rocks servers given in the rocks_servers array in the [config file](config_file_format.md).
+
+* **one** - Consider only the tree at the top of the list (possibly, the one given by the --tree flag, overriding all entries from rocks_trees), ignore all others
+* **all** - Consider all trees: if a dependency is installed in any tree of the rocks_trees list, we have a positive match.
+* **order** - Consider only trees starting from the "current" one in the order, where the "current" is either:
+  * the one at the bottom of the rocks_trees list,
+  * or one explicitly given with --tree
+  * or the "home" tree if --local was given or local_by_default=true is configured (usually at the top of the list)
+|-
+| --verbose || Display verbose output of commands executed.
+|-
+| --timeout || Timeout on network operations, in seconds.  0 means no timeout (wait forever). Default is 30.
+|}
+
+# Supported commands
+
+{|
+| [build](luarocks_build.md)   || Build/compile and install a rock.
+|-
+| [doc](luarocks_doc.md)     || Shows documentation for an installed rock.
+|-
+| [download](luarocks_download.md)|| Download a specific rock or rockspec file from a rocks server.
+|-
+| [help](luarocks_help.md)    || Help on commands.
+|-
+| [install](luarocks_install.md) || Install a rock.
+|-
+| [lint](luarocks_lint.md)    || Check syntax of a rockspec.
+|-
+| [list](luarocks_list.md)    || Lists currently installed rocks.
+|-
+| [config](luarocks_config.md)  || Query and set the LuaRocks configuration.
+|-
+| [make](luarocks_make.md)    || Compile package in current directory using a rockspec and install it.
+|-
+| [new_version](luarocks_new_version.md) || Auto-write a rockspec for a new version of a rock.
+|-
+| [pack](luarocks_pack.md)    || Create a rock, packing sources or binaries.
+|-
+| [path](luarocks_path.md)    || Return the currently configured package path.
+|-
+| [purge](luarocks_purge.md)   || Remove all installed rocks from a tree.
+|-
+| [remove](luarocks_remove.md)  || Uninstall a rock.
+|-
+| [search](luarocks_search.md)  || Query the LuaRocks repositories.
+|-
+| [test](luarocks_test.md)    || Run the test suite in the current directory.
+|-
+| [show](luarocks_show.md)    || Shows information about an installed rock.
+|-
+| [unpack](luarocks_unpack.md)  || Unpack the contents of a rock.
+|-
+| [upload](luarocks_upload.md)  || Upload a rockspec to the public rocks repository.
+|-
+| [write_rockspec](luarocks_write_rockspec.md)  || Write a template for a rockspec file.
+|}
+
+# Overview of the difference between "make", "build", "install" and "pack"
+
+{|
+| luarocks install modulename || downloads a binary .rock file and installs it to the local tree (falls back to "luarocks build modulename" behavior if a binary rock is not found)
+|-
+| luarocks build modulename || downloads a .src.rock or a rockspec and builds+installs it to the local tree.
+|-
+| luarocks build modulename-1.0-1.linux-x86.rock || extracts the rockspec from the rock and builds it as if the rockspec was passed in the command-line (i.e., redownloading sources and recompiling C modules if any).
+|-
+| luarocks build modulename-1.0-1.rockspec || builds+installs the rock using the given rockspec downloading the sources
+|-
+| luarocks make modulename-1.0-1.rockspec || builds+installs the rock using the rockspec using the contents of your current directory (kind of like the way make uses a Makefile) instead of downloading sources
+|-
+| luarocks pack modulename || grabs the rock from your local tree and packs it into a binary .rock file
+|-
+| luarocks pack modulename-1.0-1.rockspec || downloads the sources from the url and packs it into a .src.rock file
+|}
+
+
diff --git a/docs/luarocks_admin.md b/docs/luarocks_admin.md
new file mode 100644
index 00000000..ca673e76
--- /dev/null
+++ b/docs/luarocks_admin.md
@@ -0,0 +1,19 @@
+# luarocks-admin
+
+**luarocks-admin** is the repository management tool for LuaRocks, the Lua package manager.
+
+# Usage
+
+```
+luarocks-admin <command> [<arguments>]...
+```
+
+# Supported commands
+
+* [help](luarocks_admin_help.md) - Help on commands.
+* [make-manifest](luarocks_admin_make_manifest.md) - Compile a manifest file for a repository.
+* [add](luarocks_admin_add.md) - Add a rock or rockspec to a rocks server.
+* [remove](luarocks_admin_remove.md) - Remove a rock or rockspec from a rocks server.
+* [refresh-cache](luarocks_admin_refresh_cache.md) - Refresh local cache of a remote rocks server.
+
+
diff --git a/docs/luarocks_admin_add.md b/docs/luarocks_admin_add.md
new file mode 100644
index 00000000..6e15b429
--- /dev/null
+++ b/docs/luarocks_admin_add.md
@@ -0,0 +1,53 @@
+# luarocks-admin add
+
+Add a rock or rockspec to a rocks server.
+
+## Usage
+
+`luarocks-admin add [--server=<server>] [--no-refresh] [--index] {<rockspec>|<rock>}...`
+
+Arguments may be local rockspecs or rock files. The flag `--server` indicates
+which server to use. If not given, the default server set in the
+`upload_server` variable from the [configuration file](config_file_format.md)
+is used instead. You need to either explicitly pass a full URL to `--server`
+or configure an upload server in your configuration file prior to using the
+`add` command.
+
+Flags:
+
+* `--no-refresh` - The local cache should not be refreshed prior to generation of the updated manifest.
+* `--index` - Produce an `index.html` file for the manifest. This flag is automatically set if an `index.html` file already exists.
+
+## Examples
+
+### Basic example
+
+Add a rockspec to your default configured upload server:
+
+```
+luarocks-admin add lpeg-0.9-1.rockspec
+```
+
+### Handling multiple repositories
+
+Assuming your `~/.luarocks/config.lua` file looks like this:
+
+```lua
+upload_server = "main"
+upload_servers = {
+   main = {
+      http = "www.example.com/repos/main",
+      sftp = "myuser@example.com/var/www/repos/main"
+   },
+   dev = {
+      http = "www.example.com/repos/devel-rocks",
+      sftp = "myuser@example.com/var/www/repos/devel-rocks"
+   },
+}
+```
+
+you can specify which repository to use with the `--server` flag:
+
+```
+luarocks-admin add --server=dev my_rock-scm-1.rockspec
+```
diff --git a/docs/luarocks_admin_help.md b/docs/luarocks_admin_help.md
new file mode 100644
index 00000000..92232b87
--- /dev/null
+++ b/docs/luarocks_admin_help.md
@@ -0,0 +1,17 @@
+# luarocks-admin help
+
+Help on commands.
+
+## Usage
+
+`luarocks-admin help [<command>]`
+
+`<command>` is the command to show help for. If no argument is given, a list
+of supported commands, with summaries, is shown.
+
+## Example
+
+```
+luarocks-admin help make-manifest
+```
+
diff --git a/docs/luarocks_admin_make_manifest.md b/docs/luarocks_admin_make_manifest.md
new file mode 100644
index 00000000..03f7785c
--- /dev/null
+++ b/docs/luarocks_admin_make_manifest.md
@@ -0,0 +1,72 @@
+# luarocks-admin make manifest
+
+Compile a manifest file for a repository.
+
+## Usage
+
+`luarocks-admin make-manifest [--local-tree] [<repository>]`
+
+`<repository>`, if given, is a local repository pathname. If no argument is
+given, rebuilds the manifest for the local repository of installed packages.
+
+This command is used to update the [manifest file](manifest_file_format.md) in
+a directory containing rocks. By publishing a directory in a web server
+containing rocks and a manifest file, one creates a remote repository -
+LuaRocks clients can then configure their [configuration files](config_file_format.md) to search this repository.
+
+If `--local-tree` is passed, versioned versions of the manifest file are not
+created. Use this when rebuilding the manifest of a local rocks tree.
+
+## Example
+
+Suppose you wrote a rockspec for your module called "LuaSomething" and you
+want to publish a LuaRocks repository in your site. (Normally, you don't need
+to do this, just upload your rockspec to the public rocks repository, so that
+LuaRocks users can access your module without further configuration. But let's
+proceed with the example.) Your module, LuaSomething, is now installed in your
+local repository: you can find it at `~/.luarocks/rocks/luasomething/1.0-1/`.
+To prepare a public repository, let's first pack your new rock:
+
+```
+luarocks pack luasomething
+```
+
+If LuaSomething is a pure-Lua module, this will generate
+`luasomething-1.0-1.all.rock` - this is a portable rock. If it contains C
+code, it generated a non-portable rock, such as
+`luasomething-1.0-1.linux-x86.rock` (in the Linux case specifically, it's
+probably not a good idea to publish binary rocks as they most likely won't be
+portable across Linux distributions). As an alternative, run [luarocks
+pack](luarocks_pack.md) on the rockspec, to create a source rock:
+
+```
+luarocks pack ~/.luarocks/rocks/luasomething/1.0-1/luasomething-1.0-1.rockspec
+```
+
+This will create `luasomething-1.0-1.src.rock`. 
+
+Now, create a directory that we'll use to create your public repository, and copy the files you want to publish.
+
+```
+mkdir ~/myrocksrepo
+cp luasomething-1.0-1.src.rock ~/myrocksrepo
+cp ~/.luarocks/rocks/luasomething/1.0-1/luasomething-1.0-1.rockspec ~/myrocksrepo
+```
+
+Perhaps you may have also a Windows build of your rock, packed with [luarocks
+pack](luarocks_pack.md) on a Windows machine:
+
+```
+cp luasomething-1.0-1.win32-x86.rock ~/myrocksrepo
+```
+
+Now create a manifest file for this directory:
+
+```
+luarocks-admin make-manifest ~/myrocksrepo
+```
+
+And we're done: you can now just copy these files and the generated manifest
+to a public directory in a web server and your users will be able to use your
+rock by adding the URL you published the files at to their "repositories"
+array in their LuaRocks configuration file.
diff --git a/docs/luarocks_admin_refresh_cache.md b/docs/luarocks_admin_refresh_cache.md
new file mode 100644
index 00000000..e41293c0
--- /dev/null
+++ b/docs/luarocks_admin_refresh_cache.md
@@ -0,0 +1,47 @@
+# luarocks-admin refresh cache
+
+Refresh local cache of a remote rocks server.
+
+## Usage
+
+`luarocks-admin refresh-cache [--from=<server>]`
+
+The flag `--from` indicates which server to use. If not given, the default
+server set in the `upload_server` variable from the [configuration
+files](config_file_format.md) is used instead. You need to either explicitly
+pass a full URL to `--from` or configure an upload server in your
+configuration file prior to using the `refresh-cache` command.
+
+## Examples
+
+### Basic example
+
+Refresh the cache of your main upload server:
+
+```
+luarocks-admin refresh-cache
+```
+
+### Handling multiple repositories
+
+Assuming your `~/.luarocks/config.lua` file looks like this:
+
+```lua
+upload_server = "main"
+upload_servers = {
+   main = {
+      http = "www.example.com/repos/main",
+      sftp = "myuser@example.com/var/www/repos/main"
+   },
+   dev = {
+      http = "www.example.com/repos/devel-rocks",
+      sftp = "myuser@example.com/var/www/repos/devel-rocks"
+   },
+}
+```
+
+you can specify which cache to refresh with the `--from` flag:
+
+```
+luarocks-admin refresh-cache --from=dev
+```
diff --git a/docs/luarocks_admin_remove.md b/docs/luarocks_admin_remove.md
new file mode 100644
index 00000000..7a861a23
--- /dev/null
+++ b/docs/luarocks_admin_remove.md
@@ -0,0 +1,47 @@
+# luarocks-admin remove
+
+Remove a rock or rockspec from a rocks server.
+
+## Usage
+
+`luarocks-admin remove [--server=<server>] [--no-refresh] {<rockspec>|<rock>}...`
+
+Arguments are local files, which may be rockspecs or rocks.
+
+The flag `--server` indicates which server to use. If not given, the default server set in the `upload_server` variable from the [configuration files](config_file_format.md) is used instead.
+
+The flag `--no-refresh` indicates the local cache should not be refreshed prior to generation of the updated manifest.
+
+You need to have [rsync](https://rsync.samba.org/) installed in order to use this command.
+
+## Examples
+
+### Basic example
+
+Remove a rockspec from your default configured upload server:
+
+```
+luarocks-admin remove lpeg-0.9-1.rockspec
+```
+
+### Handling multiple repositories
+
+Assuming your `~/.luarocks/config.lua` file looks like this:
+
+```lua
+upload_server = "main"
+upload_servers = {
+   main = {
+      rsync = "www.example.com/repos/main",
+   },
+    dev = {
+      rsync = "www.example.com/repos/devel-rocks",
+   },
+}
+```
+
+you can specify which repository to use with the `--server` flag:
+
+```
+luarocks-admin remove --server=dev my_rock-scm-1.rockspec
+```
diff --git a/docs/luarocks_build.md b/docs/luarocks_build.md
new file mode 100644
index 00000000..75b7898d
--- /dev/null
+++ b/docs/luarocks_build.md
@@ -0,0 +1,22 @@
+# luarocks build
+
+Build/compile and install a rock.
+
+## Usage
+
+`luarocks build [--pack-binary-rock] {<rockspec> | <rock> | <name> [<version>]}`
+
+Builds and installs a rock, compiling its C parts if any. Argument may be a
+rockspec file, a source rock file or the name of a rock to be fetched from a
+repository, in which case a version may be passed as well. In case of more
+than one rock matching the request, the `build` command favors source rocks.
+
+If `--pack-binary-rock` is passed, the rock is not installed; instead, a
+`.rock` file with the contents of compilation is produced in the current
+directory.
+
+## Example
+
+```
+luarocks build luasocket
+```
diff --git a/docs/luarocks_config.md b/docs/luarocks_config.md
new file mode 100644
index 00000000..54553399
--- /dev/null
+++ b/docs/luarocks_config.md
@@ -0,0 +1,60 @@
+# luarocks config
+
+Query information about the LuaRocks configuration.
+
+# Usage
+
+```
+luarocks config (<key> | <key> <value> --scope=<scope> | <key> --unset --scope=<scope> | )
+```
+
+When given a configuration key, it prints the value of that key
+according to the currently active configuration (taking into account
+all config files and any command-line flags passed)
+
+Examples:
+
+* `luarocks config lua_interpreter`
+* `luarocks config variables.LUA_INCDIR`
+* `luarocks config lua_version`
+
+When given a configuration key and a value,
+it overwrites the config file (see the --scope option below to determine which)
+and replaces the value of the given key with the given value.
+
+* `lua_dir` is a special key as it checks for a valid Lua installation
+  (equivalent to --lua-dir) and sets several keys at once.
+* `lua_version` is a special key as it changes the default Lua version
+  used by LuaRocks commands (equivalent to passing --lua-version). 
+
+Examples:
+
+* `luarocks config variables.OPENSSL_DIR /usr/local/openssl`
+* `luarocks config lua_dir /usr/local`
+* `luarocks config lua_version 5.3`
+
+When given a configuration key and --unset,
+it overwrites the config file (see the --scope option below to determine which)
+and deletes that key from the file.
+
+Example: `luarocks config variables.OPENSSL_DIR --unset`
+
+When given no arguments, it prints the entire currently active
+configuration, resulting from reading the config files from
+all scopes.
+
+Example: `luarocks config`
+
+## Options
+
+```
+--scope=<scope>   The scope indicates which config file should be rewritten.
+                   Accepted values are "system", "user" or "project".
+                   * Using a wrapper created with `luarocks init`,
+                     the default is "project".
+                   * Using --local (or when `local_by_default` is `true`),
+                     the default is "user".
+                   * Otherwise, the default is "system".
+
+--json           Output as JSON
+```
diff --git a/docs/luarocks_doc.md b/docs/luarocks_doc.md
new file mode 100644
index 00000000..d39e708b
--- /dev/null
+++ b/docs/luarocks_doc.md
@@ -0,0 +1,21 @@
+# luarocks doc
+
+Show documentation for an installed rock.
+
+## Usage
+
+`luarocks doc [--home] [--list] <name> [<version>]`
+
+Attempts to open documentation for an installed rock using a number
+of heuristics.
+
+If `--home` is passed, opens the home page of the project.
+
+If `--list` is passed, documentation files bundled with the rock
+are listed but not opened.
+
+## Example
+
+```
+luarocks doc luasocket
+```
diff --git a/docs/luarocks_download.md b/docs/luarocks_download.md
new file mode 100644
index 00000000..1a3597ab
--- /dev/null
+++ b/docs/luarocks_download.md
@@ -0,0 +1,19 @@
+# luarocks download
+
+Download a specific rock or rockspec file from a rocks server.
+
+## Usage
+
+`luarocks download [--all] [--arch=<arch> | --source | --rockspec] [<name> [<version>]]`
+
+If `--all` is passed, all matching files are downloaded, and `<name>` argument
+becomes optional. `--arch`, `--source` and `--rockspec` options select file
+type.
+
+## Example
+
+Download rockspec for the latest version of a rock:
+
+```
+luarocks download --rockspec lpeg
+```
diff --git a/docs/luarocks_help.md b/docs/luarocks_help.md
new file mode 100644
index 00000000..3a39f7fe
--- /dev/null
+++ b/docs/luarocks_help.md
@@ -0,0 +1,17 @@
+# luarocks help
+
+Help on commands.
+
+## Usage
+
+`luarocks help [<command>]`
+
+`<command>` is the command to show help for. If no argument is given, a list
+of supported commands, with summaries, is shown.
+
+## Example
+
+```
+luarocks help remove
+```
+
diff --git a/docs/luarocks_install.md b/docs/luarocks_install.md
new file mode 100644
index 00000000..f3eddbd6
--- /dev/null
+++ b/docs/luarocks_install.md
@@ -0,0 +1,37 @@
+# luarocks install
+
+Install a rock.
+
+## Usage
+
+`luarocks install [--keep] [--only-deps] {<rock> | <name> [<version>]}`
+
+Argument may be the name of a rock to be fetched from a server, with optional
+version, or the direct URL or filename of a rockspec. In case of more than one
+rock matching the request, the `install` command favors binary rocks.
+
+Unless `--keep` is passed, other versions of the rock are removed after
+installing the new one.
+
+If `--only-deps` is passed, the rock itself is not installed, but its
+dependencies are.
+
+## Examples
+
+Installing a rock:
+
+```
+luarocks install luasocket
+```
+
+Installing a specific version of a rock:
+
+```
+luarocks install luasocket 3.0rc1
+```
+
+Installing a rock ignoring its dependencies:
+
+```
+luarocks install busted --deps-mode=none
+```
diff --git a/docs/luarocks_lint.md b/docs/luarocks_lint.md
new file mode 100644
index 00000000..f2d0f411
--- /dev/null
+++ b/docs/luarocks_lint.md
@@ -0,0 +1,15 @@
+# luarocks lint
+
+Check syntax of a rockspec.
+
+## Usage
+
+`luarocks lint <rockspec>`
+
+Checks syntax and format of a local rockspec.
+
+## Example
+
+```
+luarocks lint my-rock-0.1.0-1.rockspec
+```
diff --git a/docs/luarocks_list.md b/docs/luarocks_list.md
new file mode 100644
index 00000000..b9627d5f
--- /dev/null
+++ b/docs/luarocks_list.md
@@ -0,0 +1,27 @@
+# luarocks list
+
+Lists currently installed rocks.
+
+## Usage
+
+`luarocks list [--outdated] [--porcelain] [<query>] [<version>]`
+
+`<query>` is a substring of a rock name to filter by. When no arguments are
+supplied, a list of all rocks you have installed is returned.
+
+If `--outdated` is passed, only rocks for which there is a higher version
+available in the rocks server are listed.
+
+If `--porcelain` is passed, machine-friendly output is produced.
+
+The `list` command queries the local repository (the rocks you have
+installed). To query remote repositories (the rocks available for download at
+the LuaRocks server), use [luarocks search](luarocks_search.md).
+
+## Example
+
+List all installed rocks:
+
+```
+luarocks list
+```
diff --git a/docs/luarocks_make.md b/docs/luarocks_make.md
new file mode 100644
index 00000000..88629334
--- /dev/null
+++ b/docs/luarocks_make.md
@@ -0,0 +1,27 @@
+# luarocks make
+
+Compile package in current directory using a rockspec.
+
+## Usage
+
+`luarocks make [--pack-binary-rock] [<rockspec>]`
+
+Builds sources in the current directory, but unlike [luarocks
+build](luarocks_build.md), it does not fetch sources, etc., assuming
+everything is available in the current directory. After the build is complete,
+it also installs the rock.
+
+If no argument is given, it looks for a rockspec in the current directory and
+in `./rockspec` and `./rockspecs` subdirectories. Of all the rockspecs the one
+with the highest version is used. If rockspecs for more than one rock are
+found, you must specify which one to use through the command-line.
+
+If `--pack-binary-rock` is passed, the rock is not installed; instead, a
+`.rock` file with the contents of compilation is produced in the current
+directory.
+
+## Example
+
+```
+luarocks make
+```
diff --git a/docs/luarocks_new_version.md b/docs/luarocks_new_version.md
new file mode 100644
index 00000000..087a9235
--- /dev/null
+++ b/docs/luarocks_new_version.md
@@ -0,0 +1,37 @@
+# luarocks new_version
+
+Auto-write a rockspec for a new version of a rock.
+
+## Usage
+
+`luarocks new_version [--tag=<tag>] [<package>|<rockspec>] [<new_version>] [<new_url>]`
+
+Creates a rockspec for a new version of a rock based on data from an existing
+rockspec.
+
+If a package name is given, it downloads the latest rockspec from the public
+rocks server. If a rockspec URL or path is given, it uses it instead. If no
+argument is given, it looks for a rockspec same way the [luarocks
+make](luarocks_make.md) command does.
+
+New version of the rockspec can be specified by passing it as the second
+argument or by using `--tag` option: the tag will be used as version, with
+leading "v" removed.
+
+New URL (value of `source.url` rockspec field) can be passed as the third
+argument. If it's not passed explicitly it will be inferred from the old URL
+by replacing occurrences of the old version in it with the new one. If new tag
+(value of `source.tag`) is not set explicitly using `--tag`, it is updated in
+the same way.
+
+## Example
+
+Creating a rockspec for version `0.2.0` from an scm rockspec in current
+directory, with new tag `v0.2.0`:
+
+```
+luarocks new_version --tag=v0.2.0
+```
+
+This creates a rockspec called `my-rock-0.2.0-1.rockspec` in current directory.
+
diff --git a/docs/luarocks_pack.md b/docs/luarocks_pack.md
new file mode 100644
index 00000000..7721ba34
--- /dev/null
+++ b/docs/luarocks_pack.md
@@ -0,0 +1,31 @@
+# luarocks pack
+
+Create a rock, packing sources or binaries.
+
+## Usage
+
+`luarocks pack {<rockspec> | <name> [<version>]}`
+
+Argument may be a rockspec file, for creating a source rock, or the name of an
+installed package, for creating a binary rock. In the latter case, the package
+version may be given as a second argument.
+
+## Examples
+
+```
+luarocks pack luafilesystem 1.4.0
+```
+
+Assuming you have LuaFileSystem 1.4.0 installed in your local tree, this
+creates in the current directory a file called
+`luafilesystem-1.4.0-1.linux-x86.rock` (filename will of course vary according
+to the platform), using the binary that is already installed.
+
+```
+luarocks pack copas-1.1.1-1.rockspec
+```
+
+Assuming you have `copas-1.1.1-1.rockspec` in the current directory, this
+creates (also in the current directory) a file called
+`copas-1.1.1-1.src.rock`, fetching sources as specified in the rockspec.
+
diff --git a/docs/luarocks_path.md b/docs/luarocks_path.md
new file mode 100644
index 00000000..05f36fe0
--- /dev/null
+++ b/docs/luarocks_path.md
@@ -0,0 +1,32 @@
+# luarocks path
+
+Return the currently configured package path.
+
+## Usage
+
+`luarocks path [--append] [--bin] [--lr-path | --lr-cpath | --lr-bin]`
+
+Prints package paths for this installation of Luarocks formatted as a shell
+script. The script prepends these values to default system ones
+(`package.path` and `package.cpath`) and updates `$LUA_PATH` and `$LUA_CPATH`
+environment variables. On Unix systems, you may run:
+
+```
+eval $(luarocks path)
+```
+
+If `--append` is passed, LuaRocks paths are appended to system values instead
+of being prepended.
+
+If `--bin` is passed it also prints path to the directories where
+command-line scripts provided by rocks are located, prepending it to
+`$PATH` (or appending if `--append` is used).
+
+`--lr-path`, `--lr-cpath`, and `--lr-bin` flags print just corresponding
+paths, without systems values and not formatted as a shell script.
+
+## Example
+
+```
+luarocks path
+```
diff --git a/docs/luarocks_purge.md b/docs/luarocks_purge.md
new file mode 100644
index 00000000..7fda2565
--- /dev/null
+++ b/docs/luarocks_purge.md
@@ -0,0 +1,22 @@
+# luarocks purge
+
+Remove all installed rocks from a tree.
+
+## Usage
+
+`luarocks purge --tree=<tree> [--old-versions]`
+
+Removes all installed rocks from a given tree. The tree must be provided
+explicitly using `--tree`.
+
+If `--old-versions` is passed, the highest version
+of each rock is kept.
+
+## Example
+
+Deleting all rocks from local tree:
+
+```
+luarocks purge --tree=~/.luarocks
+```
+
diff --git a/docs/luarocks_remove.md b/docs/luarocks_remove.md
new file mode 100644
index 00000000..0a74a2d9
--- /dev/null
+++ b/docs/luarocks_remove.md
@@ -0,0 +1,22 @@
+# luarocks remove
+
+Uninstall a rock.
+
+## Usage
+
+`luarocks remove [--force|--force-fast] <name> [<version>]`
+
+`<name>` is the name of a rock to be uninstalled. If a `<version>` is not
+given, try to remove all versions at once. Will only perform the removal if it
+does not break dependencies.
+
+To override this check and force the removal, use `--force`.
+
+To perform a forced removal without looking for broken dependencies,
+use `--force-fast`.
+
+## Example
+
+```
+luarocks remove --force luafilesystem 1.3.0
+```
diff --git a/docs/luarocks_search.md b/docs/luarocks_search.md
new file mode 100644
index 00000000..70cea427
--- /dev/null
+++ b/docs/luarocks_search.md
@@ -0,0 +1,29 @@
+# luarocks search
+
+Query the LuaRocks servers.
+
+## Usage
+
+`luarocks search [--porcelain] [--source] [--binary] { <query> [<version>] | --all }`
+
+Lists files available on LuaRocks servers. `<query>` is a substring of a rock
+name to filter by. The search can be narrowed further narrowed down using a
+version. To list files for all rocks pass `--all`.
+
+If `--porcelain` is passed, machine-friendly output is produced.
+
+If `--source` is passed, only rockspecs and source rocks are shown.
+
+If `--binary` is passed, only binary and pure-Lua rocks are shown.
+
+Rocks not supporting version of Lua used by LuaRocks are not listed.
+
+The `luarocks search` command queries remote repositories.
+To query your local repository (the rocks you have installed), use [luarocks list](luarocks_list.md).
+
+## Example
+
+```
+luarocks search socket
+```
+
diff --git a/docs/luarocks_show.md b/docs/luarocks_show.md
new file mode 100644
index 00000000..353935c5
--- /dev/null
+++ b/docs/luarocks_show.md
@@ -0,0 +1,25 @@
+# luarocks show
+
+Shows information about an installed rock.
+
+## Usage
+
+`luarocks show <name> [<version>]`
+
+`<name>` is an installed package name.
+Without any flags, show all module information.
+With these flags, return only the desired information:
+
+* `--home` - home page of project
+* `--modules` - all modules provided by this package as used by `require()`
+* `--deps` - packages this package depends on, including indirect dependencies
+* `--rockspec` - the full path of the rockspec file
+* `--mversion` - the package version
+* `--rock-tree` - local tree where rock is installed
+* `--rock-dir` - data directory of the installed rock
+
+## Example
+
+```
+luarocks show luasocket
+```
diff --git a/docs/luarocks_test.md b/docs/luarocks_test.md
new file mode 100644
index 00000000..035d316e
--- /dev/null
+++ b/docs/luarocks_test.md
@@ -0,0 +1,104 @@
+# luarocks test
+
+Run the test suite for the Lua project in the current directory.
+
+## Usage
+
+`luarocks test [-h] [--test-type <type>] [<rockspec>] [<args>] ...`
+
+If the first argument is a rockspec, it will use it to determine the
+parameters for running tests; otherwise, it will attempt to detect the
+rockspec.
+
+Any additional arguments are forwarded to the test suite. To make sure that
+test suite flags are not interpreted as LuaRocks flags, use `--` to separate
+LuaRocks arguments from test suite arguments.
+
+### Arguments
+
+* `rockspec` - Project rockspec.
+* `args` - Test suite arguments.
+
+### Options
+
+* `--test-type <type>` - Specify the test suite type manually if it was not
+  specified in the rockspec and it could not be auto-detected.
+
+## Test types
+
+There are two test types that ship by default with LuaRocks: `busted` and
+`command`. They can be specified explicitly in a rockspec in the `test.type`
+field. Custom test types can be loaded using the `test_dependencies` field; a
+dependency can declare a new test type by adding a module in the
+`luarocks.test.*` namespace; it can then be used as a test type in the
+rockspec.
+
+### `busted` test type
+
+You can enable the `busted` test type adding a top-level `test` table in a
+rockspec and setting its `type` to `busted`. The `busted` type can be
+auto-detected if the project's source contains a configuration file called
+`.busted`, so if a project has that file `luarocks test` can be used to launch
+Busted even if it doesn't have a `test` section in the rockspec. 
+
+Here's an example of a `busted` test section, also using the `flags` option to
+pass extra flags to Busted, and using per-platform overrides.
+
+```
+test = {
+   type = "busted",
+   platforms = {
+      windows = {
+         flags = { "--exclude-tags=ssh,git,unix" }
+      },
+      unix = {
+         flags = { "--exclude-tags=ssh,git" }
+      }
+   }
+}
+```
+
+### `command` test type
+
+You can enable the `command` test type adding a top-level `test` table in a
+rockspec and setting its `type` to `command`. The `command` type can be
+auto-detected if the project's source contains a file called `test.lua` at the
+root of the source tree, so if a project has that file `luarocks test` can be
+used to run it using the default Lua interpreter even if it doesn't have a
+`test` section in the rockspec.
+
+The `test` block for a `command` test type can take either a `script`
+argument, which is a Lua script to be launched using the configured Lua
+interpreter, or a `command` argument, which is a command to be launched
+directly on a shell. Both can take additional arguments via the `flags` array
+entry.
+
+Here is an example using a script:
+
+```
+test = {
+   type = "command",
+   script = "tests/test_all.lua",
+}
+```
+
+And here is an example using a command:
+
+```
+test = {
+   type = "command",
+   command = "make test",
+}
+```
+
+## Invocation example
+
+In the following example, assume a project uses Busted as its test tool. The
+current directory contains the source code of a Lua project with a rockspec in
+its root, this will run Busted, pass any additional arguments specified in the
+`test.flags` field of the rockspec, plus the `--exclude-tags=ssh` argument
+given explicitly via the command-line:
+
+```
+luarocks test -- --exclude-tags=ssh
+```
diff --git a/docs/luarocks_through_a_proxy.md b/docs/luarocks_through_a_proxy.md
new file mode 100644
index 00000000..589142fc
--- /dev/null
+++ b/docs/luarocks_through_a_proxy.md
@@ -0,0 +1,36 @@
+# LuaRocks through a proxy
+
+LuaRocks performs network access through either helper applications (typically
+`curl` on macOS, or `wget` on other platforms), or using built-in modules
+LuaSocket and LuaSec. All of them use the same method to configure proxies:
+the `http_proxy`, `https_proxy` and `ftp_proxy` environment variables.
+
+## Environment variable example
+
+On Unix systems, you can set the `http_proxy` environment variable like
+this:
+
+    export http_proxy=http://server:1234
+
+On Windows systems, the command syntax is:
+
+    set http_proxy=http://server:1234
+
+## Git
+
+If you are behind a firewall that blocks the `git://` protocol, you may
+configure your Git to use HTTPS instead. The solution is to tell Git to always
+use HTTPS instead of `git://` by running the following command:
+
+    git config --global url."https://".insteadOf git://
+
+This adds the following to your `~/.gitconfig`:
+
+    [url "https://"]
+       insteadOf = git://
+
+## External references
+
+* [curl manpage](http://www.hmug.org/man/1/curl.php)
+* ["How to use wget through proxy"](http://blog.taragana.com/index.php/archive/how-to-use-wget-through-proxy/)
+* ["Tell git to use https instead of git protocol"](http://jgoodall.me/posts/2013/05/29/git-use-https)
diff --git a/docs/luarocks_unpack.md b/docs/luarocks_unpack.md
new file mode 100644
index 00000000..4fa8754a
--- /dev/null
+++ b/docs/luarocks_unpack.md
@@ -0,0 +1,61 @@
+# luarocks unpack
+
+Unpack the contents of a rock.
+
+## Usage
+
+`luarocks unpack [--force] {<rock> | <rockspec> | <name> [<version>]}`
+
+Unpacks the contents of a rock in a newly created directory under the current
+directory. Argument may be a rock file, a rockspec file, or the name of a
+rock/rockspec in a remote repository.
+
+If `--force` is passed, files are unpacked even if the output directory
+already exists.
+
+When a rock is given, LuaRocks creates a directory and extracts the contents
+of a rock inside it. If it is a `.src.rock` file, it also extracts the
+sources, and copies the rock's rockspec to the root of the sources directory,
+so that you can run [luarocks make](luarocks_make.md).
+
+When a rockspec is given, LuaRocks creates a directory and then fetches and
+extracts the sources for the module inside it. It also copies the rockspec to
+the root of the sources directory.
+
+When a binary rock is given, it just extracts the contents of the rock in the
+created directory for further inspection. To fetch the sources, you can run
+`luarocks unpack` again on the rockspec file that will be extracted from the
+binary rock.
+
+When a name (and optionally a version) is given, LuaRocks tries to download a
+source rock or a rockspec from remote repositories, and then proceeds as if
+the obtained file was provided locally.
+
+## Examples
+
+```
+luarocks unpack luafilesystem 1.4.0
+```
+
+This fetches `luafilesystem-1.4.0-1.src.rock` from the remote repository and
+creates in the current directory a directory called `luafilesystem-1.4.0-1`
+with the contents of the rock, including the LuaFileSystem sources unpacked.
+You will then be able to go into the
+`luafilesystem-1.4.0-1/luafilesystem-1.4.0` directory and run [luarocks
+make](luarocks_make.md).
+
+```
+luarocks unpack copas-1.1.1-1.rockspec
+```
+
+Assuming you have `copas-1.1.1-1.rockspec` in the current directory, this
+creates in the current directory a directory called `copas-1.1.1-1` with the
+rockspec and the Copas sources unpacked. You will then be able to go into the
+`copas-1.1.1-1/copas-1.1.1` directory and run [luarocks
+make](luarocks_make.md).
+
+While the extracted directory names may look repetitive, note that the first
+directory is a directory in a LuaRocks "name-version-revision" format, and the
+second directory is the directory contained inside the sources archives, which
+may be in any format, and in some cases may not even exist.
+
diff --git a/docs/luarocks_upload.md b/docs/luarocks_upload.md
new file mode 100644
index 00000000..167ec803
--- /dev/null
+++ b/docs/luarocks_upload.md
@@ -0,0 +1,26 @@
+# luarocks upload
+
+Upload a rockspec to the public rocks repository.
+
+## Usage
+
+`luarocks upload [--skip-pack] [--api-key=<key>] [--force] <rockspec>`
+
+Packs a source rock file (`.src.rock`) using a rockspec and uploads it
+and the rockspec to the public rocks repository.
+
+To access the server, an API key is required. It is passed using `--api-key`
+option and can be issued at the [LuaRocks site](https://luarocks.org/) on
+the "Setting" page after logging in.
+
+If `--skip-pack` is passed, the source rock is not packed and only the rockspec
+is uploaded.
+
+If `--force` is passed, existing files will be overwritten if the same version
+of the package already exists.
+
+## Example
+
+```
+luarocks upload my-rock-0.1.0-1.rockspec --api-key=<REDACTED>
+```
diff --git a/docs/luarocks_write_rockspec.md b/docs/luarocks_write_rockspec.md
new file mode 100644
index 00000000..59b3fbe0
--- /dev/null
+++ b/docs/luarocks_write_rockspec.md
@@ -0,0 +1,75 @@
+# luarocks write_rockspec
+
+Write a template for a rockspec file.
+
+## Usage
+
+`[--output=<file>] [...] [<name>] [<version>] [<url>|<path>]`
+
+This commands creates an initial version of a rockspec for a rock
+based on name, version, and location of its sources. The resulting
+rockspec is just a template: several fields, such as `dependencies`,
+have to be filled by hand.
+
+If only two arguments are given, the first one is considered the name and the
+second one is the location.
+If only one argument is given, it must be the location.
+If no arguments are given, current directory is used as location.
+LuaRocks will attempt to infer name and version if not given,
+using "scm" as default version.
+
+If location is a local directory and a Git or Mercurial repository,
+source URL will be inferred from it.
+
+Resulting rockspec is created in current directory, with file name
+based on rock name and version. Output location can be changed using `--output` option.
+
+Several fields of the rockspec can be set explicitly:
+
+* `--license=<license>` sets license name, such as `MIT/X11` (by default inferred
+  from `COPYING`, `LICENSE`, or `MIT-LICENSE.txt` files, if they exist).
+* `--summary=<text>` sets short description (by default inferred from
+  `README.md` or `README` files, if they exist).
+* `--detailed=<text>` sets detailed description (by default inferred
+  from `README.md` or `README` files, if they exist).
+* `--homepage` sets project home page URL (by default may be inferred from source URL).
+* `--lua-version=<versions>` sets supported Lua versions. `<versions>` must be one of
+  "5.1", "5.2", "5.3", "5.1,5.2", "5.2,5.3", or "5.1,5.2,5.3".
+* `--rockspec-format=<version>` sets rockspec format version.
+* `--tag=<tag>` sets tag to use. Will attempt to extract version number from it.
+* `--lib=<lib>[,<lib>]` sets libraries that C files need to link with, filling [external_dependencies](rockspec_format.md#dependency-information) table. The argument should be a comma delimited list of names.
+
+LuaRocks will attempt to fill `build` table of the rockspec using
+[builtin build back-end](rockspec_format.md#builtin), listing files from `src`
+and `lua` directories in project sources.
+
+## Example
+
+Creating an scm rockspec for a project hosted in a Git repository:
+
+```
+mkdir my-rock
+cd my-rock
+git init .
+git remote add origin https://github.com/my-username/my-rock
+luarocks write-rockspec
+```
+
+This creates `my-rock-scm-1.rockspec` file:
+
+```lua
+package = "my-rock"
+version = "scm-1"
+source = {
+   url = "git+https://github.com/my-username/my-rock"
+}
+description = {
+   homepage = "https://github.com/my-username/my-rock",
+   license = "*** please specify a license ***"
+}
+dependencies = {}
+build = {
+   type = "builtin",
+   modules = {}
+}
+```
diff --git a/docs/manifest_file_format.md b/docs/manifest_file_format.md
new file mode 100644
index 00000000..2fe57dee
--- /dev/null
+++ b/docs/manifest_file_format.md
@@ -0,0 +1,41 @@
+# Manifest file format
+
+A manifest file describes files contained in a rocks tree or server. Each
+rocks tree or server has a `manifest` file in its root. Rocks servers may also
+have versioned manifests (e.g. `manifest-5.1` for Lua 5.1) and compressed
+manifests (e.g. `manifest-5.1.zip`). These must match the contents of the
+uncompressed manifest.
+
+Like a rockspec, a manifest file contains a Lua program setting several
+globals. Three of them are mandatory:
+
+* `repository`: a table where each key is a package name and its value is a table describing versions of the package
+  hosted on a server or installed in a rocks tree.
+  * `repository[package_name]`: a table where each key is a package version (including revision, e.g. `1.0.0-1`)
+  and its value provides information for that version.
+    * `repository[package_name][package_version]`: a list of tables containing several fields:
+      * `arch`: architecture of the rock as a string. Always set to `installed` in rock tree manifests.
+      * `modules` (only for rock tree manifests): a table mapping module names to paths under installation
+        directory for Lua or C modules.
+      * `commands` (only for rock tree manifests): a table mapping script names to paths under installation
+        directory for binaries.
+      * `dependencies` (only for rock tree manifests): a table mapping names of packages the rock depends on
+        (perhaps indirectly) to versions of installed packages satisfying the dependency.
+* `modules`: empty table in rock server manifests (may change in future releases). In rock tree manifests
+  it's a table mapping module names to lists of packages and versions providing that module. Each value in the
+  list is a string in `module/version` format (e.g. `foo/1.0.0-1`).
+* `commands`: empty table in rock server manifests (may change in future releases). In rock tree manifests
+  it's a table mapping script names to lists of packages and versions providing that script, using same
+  format as `modules` table.
+* `dependencies` (only for rock tree manifests): a table containing precomputed dependency information
+  to be used by `luarocks.loader`. Each key is a package name.
+  * `dependencies[package_name]`: A table where each key is a version (with revision) and its value describes
+    dependencies of that version of the package.
+    * `dependencies[package_name][package_version]`: An array of direct dependencies represented as tables
+      with the following fields:
+      * `name`: name of the rock that is depended on.
+      * `constraints`: an array of parsed version constraints. Each constraint is represented as
+        a table with fields:
+        * `op`: an operator as a string (e.g. `>=`).
+        * `version`: version to the right of the operator as an array of parts, e.g. `{1, 0, 0}` for `1.0.0`.
+          It also contains version as a string in `string` field and may contain revision in `revision` field.
diff --git a/docs/more_resources.md b/docs/more_resources.md
new file mode 100644
index 00000000..587ebb67
--- /dev/null
+++ b/docs/more_resources.md
@@ -0,0 +1,32 @@
+# Community support and more resources
+
+On LuaRocks:
+
+* [Matrix chat-room](https://app.gitter.im/#/room/#luarocks_luarocks:gitter.im)
+  - for all things LuaRocks!
+* [luarocks GitHub issues](https://github.com/luarocks/luarocks/issues) - for
+  reporting bugs in the CLI tool
+* [luarocks-site GitHub issues](https://github.com/luarocks/luarocks/issues) -
+  for reporting bugs related to the [luarocks.org](https://luarocks.org)
+  website itself
+
+On Lua:
+
+* [Lua mailing list](http://www.lua.org/lua-l.html) - for questions about the Lua language itself or specific Lua modules (most module authors hang out there!)
+* [Lua documentation](http://www.lua.org/docs.html) - documentation on the Lua language, including the reference manual
+* [Lua Forum](https://luaforum.com) - a beginner friendly Lua community
+
+On LuaJIT:
+
+* [LuaJIT mailing list](http://luajit.org/list.html) - for LuaJIT-specific discussion
+
+## Presentations on LuaRocks
+
+Some past presentations discussing LuaRocks:
+
+* [LuaRocks: fostering an ecosystem for Lua modules](http://hisham.hm/talks#fosdem2015), presented by Hisham Muhammad at FOSDEM 2015, Brussels, Belgium
+* [What's new in LuaRocks](http://hisham.hm/talks#luawshop14), presented by Hisham Muhammad at the Lua Workshop 2014, Moscow, Russia
+* [LuaRocks - past, present and future](http://hisham.hm/talks#luawshop13), presented by Hisham Muhammad at the Lua Workshop 2013, Toulouse, France
+* [LuaRocks 2.0](http://hisham.hm/talks#luawshop09), presented by Hisham Muhammad at the Lua Workshop 2009, Rio de Janeiro, Brazil
+* [LuaRocks: o sistema de pacotes de extensão para a linguagem Lua](http://hisham.hm/talks#fisl9), presented by Hisham Muhammad at FISL 9.0 - IX International Forum on Free Software, Porto Alegre, Brazil
+
diff --git a/docs/namespaces.md b/docs/namespaces.md
new file mode 100644
index 00000000..f00c692a
--- /dev/null
+++ b/docs/namespaces.md
@@ -0,0 +1,71 @@
+# Namespaces
+
+The LuaRocks.org repository allows for each user to published their own
+collection of rocks. Since LuaRocks 3, this concept of per-user rocks has been
+integrated into the tool, in the form of **namespaces**.
+
+What you can do with namespaces:
+
+* Install packages using a namespace:
+  * `luarocks install my_user/my_rock`
+* Depend on a specific namespaced version of a rock in your rockspec:
+  * `dependencies = { "my_user/my_rock > 2.0" }`
+
+## Background
+
+LuaRocks has always supported multiple repositories, which can be set in the
+[config file](config_file_format.md) with the `rocks_servers` entry. A
+repository is an address (a local directory or a remote URL) where LuaRocks
+can find a `manifest-5.x` file and .rock and .rockspec files. We also call
+such repository a "manifest", for short. 
+
+The [LuaRocks.org](LuaRocks.org)(LuaRocks.org)(https://luarocks.org) website
+features a root manifest at `https://luarocks.org` as well as per-user
+manifests at `https://luarocks.org/manifests/<your-user-name>`. Entries in the
+root manifest are operated in a first-come first-served manner, but even if
+someone else has already taken a rock name, you can upload your own version of
+it to your user manifest. You can refer to a per-user manifest the same way as
+any other rocks server, adding to your configuration or using it with the
+`--server` flag. This means that you were always able to install your own
+version of a rock using a command such as `luarocks install <my-rock>
+--server=https://luarocks.org/manifests/<your-user-name>`. However, you could
+not specifically depend on it from another rockspec, and once installed, the
+information that this rock came from a specific manifest was lost. With
+namespaces, now you can!
+
+## Using namespaces
+
+All `luarocks` commands that accept a rock name as command line argument can
+now take a namespaced variant:
+
+```
+luarocks install my_user/my_rock
+```
+
+LuaRocks will take your `rocks_trees` configuration and search for namespaced
+manifests on each entry: for example, given the default server
+`https://luarocks.org` it will look in
+`https://luarocks.org/manifests/my_user`.
+
+When installing, LuaRocks will internally store the information that this copy
+of `my_rock` came from the `my_user` namespace, so it will be able to use that
+information when another rockspec specifically asks for `my_user/my_rock` in
+its dependencies. (The namespace information is stored in a separate
+`rock_namespace` metadata file, at
+`lib/luarocks/rocks-5.x/my_rock/1.0-1/rock_namespace`, relative to your local
+rocks tree.)
+
+## Compatibility between non-namespaced and namespaced rocks
+
+A namespaced package can stand for a non-namespaced one. If you have
+`my_user/my_rock 1.0` installed and a rock depends on `my_rock 1.0`, the
+installed rock will satisfy the dependency.
+
+The opposite is not true: if you have `my_rock 1.0` installed but that did not
+come from a `my_user` namespace, it will not satisfy a dependency for
+`my_user/my_rock`.
+
+## Current limitations
+
+You cannot have two rocks with the same name and version but different
+namespaces installed at the same time in the same local rocks tree.
diff --git a/docs/paths_and_external_dependencies.md b/docs/paths_and_external_dependencies.md
new file mode 100644
index 00000000..c7a59408
--- /dev/null
+++ b/docs/paths_and_external_dependencies.md
@@ -0,0 +1,43 @@
+# Paths and external dependencies
+
+Many Lua rocks are bindings to C libraries: for example,
+[luaossl](https://luarocks.org/modules/daurnimator/luaossl) is a binding
+library to the [OpenSSL](https://openssl.org) library. This means that, in our
+example, luaossl _depends on_ OpenSSL. But since this is not a regular
+rock-to-rock dependency (if it were, LuaRocks could solve this by itself), we
+call this an **external dependency**.
+
+When building a rock with external dependencies, LuaRocks needs to make sure
+the necessary C libraries and headers are installed, and know where those C
+libraries are.
+
+## Specifying external dependencies in your rockspecs
+
+When writing a rock with external dependencies, one needs to be careful to
+avoid the "works on my machine" situation: when you write code that hardcodes
+the location of external dependencies as they are in your system, but then
+fails to build in other people's systems. 
+
+The way to avoid this problem is to avoid any hardcoded paths. Instead, the
+`build` section of a [rockspec](rockspec_format.md) should make use of path
+variables. If not using the `builtin` build type, paths set by the module's
+own build system must not be relied on and explicit paths should be passed to
+it by the rockspec instead.
+
+Paths where LuaRocks should install files into are defined as the `PREFIX`,
+`LUADIR`, `LIBDIR` and `BINDIR` variables. (See the [Config file
+format](config_file_format.md) page for details.)
+
+Paths for external dependencies (such as C libraries used in the compilation
+of modules) are generated from the `external_dependencies` section of the
+rockspec (see the [Rockspec format](rockspec_format.md) page for details.) Lua
+itself is considered a special external dependency.
+
+These path variables are set in the global `variables` table defined in the
+[config file](config_file_format.md). Their values are populated automatically
+by LuaRocks, but can be overriden by the user (either by setting them directly
+in the config file, or by passing them through the "luarocks" command line). 
+
+The `variables` table always contains entries for `LUA_BINDIR`, `LUA_INCDIR`
+and `LUA_LIBDIR`. Like the other external dependency variables, these can be
+overriden in the LuaRocks config file or in the command line.
\ No newline at end of file
diff --git a/docs/pinning_versions_with_a_lock_file.md b/docs/pinning_versions_with_a_lock_file.md
new file mode 100644
index 00000000..19ccb3ae
--- /dev/null
+++ b/docs/pinning_versions_with_a_lock_file.md
@@ -0,0 +1,52 @@
+# Pinning versions with a lock file
+
+Pinning dependency versions is a way to get more predictable builds. As
+explained in [this
+page](https://before-you-ship.18f.gov/infrastructure/pinning-dependencies/):
+
+> The practice of “pinning dependencies” refers to making explicit the
+versions of software your application depends on (defining the dependencies of
+new software libraries is outside the scope of this document). Dependency
+pinning takes different forms in different frameworks, but the high-level idea
+is to “freeze” dependencies so that deployments are repeatable. Without this,
+we run the risk of executing different software whenever servers are restaged,
+a new team-member joins the project, or between development and production
+environments. 
+
+## Pinning dependencies in LuaRocks
+
+To pin dependencies in LuaRocks, you build a package as usual, using `luarocks
+build` or `luarocks make`, and add the `--pin` option. This will build the
+package and its dependencies, and will also create a `luarocks.lock` file in
+the current directory. This is a text file containing the names and versions
+of all dependencies (and its dependencies, recursively) that were installed,
+with the exact versions used when building.
+
+## Using pinned dependencies in LuaRocks
+
+When building a package with `luarocks build`, `luarocks make` (or via
+`luarocks install` if there is not prebuilt binary package), *without* using
+`--pin`, if the current directory contains a `luarocks.lock` file, it is used
+as the authoritative source for exact version of all dependencies, both
+immediate and recursively loaded dependencies. For each dependency that is
+recursively scanned, LuaRocks will attempt to use the version in the
+`luarocks.lock` file, ignoring the version constraints in the rockspec.
+
+When building a package using a lock file, `luarocks.lock` is copied to the
+package's metadata directory (e.g.
+`/usr/local/luarocks/rocks/5.3/name/version/luarocks.lock`) — if you later
+pack it as a binary rock with `luarocks pack`, the lock file will be packaged
+inside the rock, and will be used when that binary rock is installed with
+`luarocks install`.
+
+## Updating pinned dependencies
+
+Building a package again with the `--pin` flag ignores any existing
+`luarocks.lock` file and recreates this file, by scanning dependency based on
+the dependency constraints specified in the rockspec.
+
+It is also possible to edit the `luarocks.lock` by hand, of course, but there
+are no checks: if the versions you set for the various dependencies are not
+compatible with each other, LuaRocks won't be able to do anything about it and
+will blindly follow what is set on the `luarocks.lock` file.
+
diff --git a/docs/platform_agnostic_external_dependencies.md b/docs/platform_agnostic_external_dependencies.md
new file mode 100644
index 00000000..97f983fa
--- /dev/null
+++ b/docs/platform_agnostic_external_dependencies.md
@@ -0,0 +1,93 @@
+# Platform-agnostic external dependencies
+
+Since 0.6, LuaRocks supports specifying files for external dependency search
+in a platform-agnostic way. When filenames given in the
+`external_dependencies` section of a [rockspec](rockspec_format.md) don't
+have any dot (".") characters, their contents are substituted according to the
+patterns given in the `external_deps_patterns` table of the [configuration
+file](config_file_format.md).
+
+These patterns will typically not be used in the configuration file, as
+LuaRocks provides sensible defaults. The default patterns defined on Unix are:
+
+```
+bin = {"?"}
+lib = {"lib?.a", "lib?.so"}
+include = {"?.h"}
+```
+
+On Windows the defaults are:
+
+```
+bin = {"?.exe", "?.bat"}
+lib = {"?.lib", "?.dll"}
+include = {"?.h"}
+```
+
+For example, a [rockspec](rockspec_format.md) can define an external
+dependency like this:
+
+```
+external_dependencies = {
+    FOO = {
+       library = "foo"
+    }
+ }
+```
+
+and this will result in searches for libfoo.a or libfoo.so on Unix systems,
+and foo.lib or foo.dll on Windows. For entries that have more than one
+pattern, such as lib, only one entry needs to be satisfied.
+
+In other words, the value "foo" you see in the
+external_dependencies.FOO.library entry is the same value you would use when
+linking the library, for example -lfoo. In addition, once you added FOO in the
+external_dependencies, this means you can pass entries such as FOO_DIR and
+FOO_LIBDIR to the `luarocks` command-line tool, in case you have these
+libraries in non-standard locations. For example, if the user installed the
+library in a custom location in their own home directory, it would still be
+usable, like this:
+
+```
+luarocks install my_rockspec_using_foo-1.0-1.rockspec FOO_LIBDIR=/home/joeuser/foo/lib
+```
+
+When performing external dependency checks during installation (as opposed to
+build) of rocks, static libraries and headers are not searched. The
+`runtime_external_deps_patterns` table is used instead.
+
+Since 3.4.0, the variable DEPS_DIR which doesn't depend on the name FOO, could
+also used, like this:
+
+```
+luarocks install my_rockspec_using_foo-1.0-1.rockspec DEPS_DIR=/home/joeuser/foo/lib
+```
+
+# When filenames don't match 
+
+If the pattern system is not enough to hide platform differences, you can
+always resort to [per-platform overrides](platform_overrides.md). For example:
+
+```
+external_dependencies = {
+   FOO = {
+      library = "foo"
+   }
+   platforms = {
+      win32 = {
+         FOO = {
+            library = "winfoo32.dll"
+         }
+      }
+   }
+}
+```
+
+# Statically linked libraries and dependencies 
+
+If your rock links a library statically, avoid adding a library search in its
+[rockspec](rockspec_format.md)'s `external_dependencies` table. Search for a
+header instead, so that the external dependency search does not fail when
+users install a binary rock and they don't have the library installed
+separately.
+
diff --git a/docs/platform_overrides.md b/docs/platform_overrides.md
new file mode 100644
index 00000000..ddda180f
--- /dev/null
+++ b/docs/platform_overrides.md
@@ -0,0 +1,20 @@
+# Platform overrides
+
+To specify platform-specific information in rockspecs, one should use the
+`platforms` field of top-level tables.
+
+In top-level tables, a field `platforms` is treated specially. If present,
+it may contain a table containing sub-tables representing different platforms.
+For example, `build.platforms.unix`, if present, as the name implies, would
+be a table containing specifics for building on Unix systems.
+
+The contents of platform tables override the contents of the top-level table
+where `platforms` is located. For example, in a Linux system, an entry
+`build.platforms.linux.foo` will override `build.foo`. Tables are
+scanned deeply, so if `build.foo` is a table, the contents of
+`build.platforms.linux.foo` will add to or replace the contents of
+`build.foo`, instead of just replacing the entire table. Therefore, you
+don't need to rewrite the entire `build` section in a platform table, only
+the fields should change.
+
+
diff --git a/docs/recommended_practices_for_makefiles.md b/docs/recommended_practices_for_makefiles.md
new file mode 100644
index 00000000..1391ec3b
--- /dev/null
+++ b/docs/recommended_practices_for_makefiles.md
@@ -0,0 +1,176 @@
+# Recommended practices for Makefiles
+
+When authoring a Lua module, especially those containing C code, developers
+are always faced with some build and deployment issues: where to find
+libraries, where to install modules, which flags to pass when building, and so
+on. Looking at the existing modules available in the web, it is clear to see
+that there are no _de facto_ standards in Makefiles for Lua modules, and that
+many of them are incomplete copies of one another, and many of them share the
+same deficiencies. Here is a list of some of those issues we found during the
+development of LuaRocks, and how to avoid them. Following the recommendations
+below will improve the portability of your Makefiles and make things easier
+for writing rocks, other packagers such as Linux distributions, and your
+users.
+
+# Do not ask users to edit files "by hand" 
+
+Asking users to hand-edit things is error-prone. Even though systems like
+LuaRocks support applying patches -- which is the automated equivalent of
+hand-tweaking files -- this adds maintenance burden, as patches have to be
+updated on each release if any change happens in the file. Always use
+variables, so that they can be overridden by automated processes. Hand-tweaks
+in the code can be avoided by propagating C defines from Makefiles as well.
+
+Don't:
+```
+// Edit this to suit your installation
+const char* bla_dir = "/usr/local/share/bla";
+```
+
+Do:
+
+```
+BLA_DIR=/usr/local/share/bla
+# ...
+bla.o:
+        $(CC) -c bla.c -DBLA_DIR=\"$(BLA_DIR)\"
+```
+
+## Do not hardcode any paths 
+
+This is a corollary to the above recommendation, really. Whenever you are
+passing any paths, don't write them directly in Makefile rules. Always factor
+them out into variables.
+
+# Provide a nice "install" rule 
+
+A large number of Makefiles for Lua modules ship without an "install" rule,
+probably due to the long-standing lack of standard install locations for
+modules that plagued the Lua world in the past. Nowadays, however, the
+convention of using .../lib/lua/5.1/ for C modules and .../share/lua/5.1/ for
+Lua modules (relative to the prefix where Lua is installed) is well
+established, and there is no reason not to use it. To make things even easier
+for your users, you can also factor out the common Lua prefix. /usr/local is a
+good default, since it is also the default for the vanilla Lua tarball.
+
+Don't:
+
+```
+# no make install rule!
+```
+
+Do:
+
+```
+LUA_DIR=/usr/local
+LUA_LIBDIR=$(LUA_DIR)/lib/lua/5.1
+LUA_SHAREDIR=$(LUA_DIR)/share/lua/5.1
+
+# ...
+
+install:
+        mkdir -p $(LUA_LIBDIR)/bla
+        cp bla/core.so $(LUA_LIBDIR)/bla
+        mkdir -p $(LUA_SHAREDIR)/bla
+        cp bla.lua $(LUA_SHAREDIR)
+        cp bla/extras.lua $(LUA_SHAREDIR)/bla
+```
+
+Some packagers recommend prepending an empty `$(DESTDIR)` variable to all target
+paths in your install rule, but that's not strictly necessary if your paths
+are all set into variables, which can be redefined for the "make install" run,
+like in the example above.
+
+# Do not assume libraries are in the system path 
+
+If your program uses LibPNG, adding "-lpng" to your Makefile is not enough.
+Your users may have the LibPNG library somewhere else, so let them specify the
+locations of both the libraries and headers. The default values you pick are
+not really important, as long as they're overridable by the user, but
+/usr/local is always a good choice on Unix systems as this is the first
+typical "non-system path" that users may want to use.
+
+Of course, use one library per value; don't assume all third-party libraries
+can be found in the same place.
+
+Don't:
+
+```
+gcc -o bla bla.c -lpng
+```
+
+Do:
+
+```
+LIBPNG_DIR=/usr/local
+LIBPNG_INCDIR=$(LIBPNG_DIR)/include
+LIBPNG_LIBDIR=$(LIBPNG_DIR)/lib
+
+# ...
+        $(CC) -o bla bla.c -lpng -L$(LIBPNG_LIBDIR) -I$(LIBPNG_INCDIR)
+```
+
+# Avoid compiler assumptions 
+
+Even if your code only compiles in GCC and is Unix-only, there are still build portability issues to look out for. The main ones are:
+
+* **Not all GCCs link libraries with the same flags** - for instance, linking
+  shared libraries is done with "-shared" on Linux and "-bundle -undefined
+  dynamic_lookup -all_load" on Mac OSX. Factoring the flags in a variable is
+  a nice gesture for users of other operating systems. (LuaRocks can take
+  care of the detection part and set the flag appropriately, but packages of
+  other systems will benefit as well.)
+
+* **The compiler is not always called "gcc"** - this one is for the people in
+  the embedded world; in their toolchains, their cross-compilers often have
+  names like "arm-nofpu-gcc". $(CC) is a standard variable in make. Just use
+  that instead of "gcc" and you're good to go.
+
+Don't:
+
+```
+bla.so:
+        gcc -o bla.so -shared bla.o
+```
+
+Do:
+
+```
+LIBFLAG=-shared
+# ...
+bla.so:
+        $(CC) -o bla.so $(LIBFLAG) bla.o
+```
+
+# Do not "overload" variables 
+
+As mentioned in the topic about third-party libraries above, don't reuse variables just because two conceptually different locations happen to point to the same place. For example, do not assume that the directory you're using to _find_ libraries and the directory you're _installing_ libraries to is the same. That little economy will only cause confusion and trouble to your users.
+
+Don't:
+
+```
+LIBDIR=/usr/local/lib
+INCDIR=/usr/local/include
+# ...
+bla.so:
+        $(CC) $(LIBFLAG) -o bla.so -lpng -L$(LIBDIR) -I$(INCDIR)
+install:
+        mkdir -p $(LIBDIR)
+        cp bla.so $(LIBDIR)/lua/5.1
+```
+
+Do:
+
+```
+LIBPNG_DIR=/usr/local
+LIBPNG_LIBDIR=$(LIBPNG_DIR)/lib
+LIBPNG_INCDIR=$(LIBPNG_DIR)/include
+LUA_DIR=/usr/local
+LUA_LIBDIR=$(LUA_DIR)/lib/lua/5.1
+# ...
+bla.so:
+        $(CC) $(LIBFLAG) -o bla.so -lpng -L$(LIBPNG_LIBDIR) -I$(LIBPNG_INCDIR)
+install:
+        mkdir -p $(LUA_LIBDIR)
+        cp bla.so $(LUA_LIBDIR)
+```
diff --git a/docs/release_history.md b/docs/release_history.md
new file mode 100644
index 00000000..4759fe17
--- /dev/null
+++ b/docs/release_history.md
@@ -0,0 +1,597 @@
+# Release history
+
+**Version 3.11.1** - 31/May/2024 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.11.1.tar.gz) -
+[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.11.1-windows-32.zip) -
+[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.11.1-windows-64.zip) -
+[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.11.1-linux-x86_64.zip) -
+[other files](http://luarocks.github.io/luarocks/releases)
+
+**Version 3.11.0** - 13/Mar/2024 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.11.0.tar.gz) -
+[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.11.0-windows-32.zip) -
+[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.11.0-windows-64.zip) -
+[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.11.0-linux-x86_64.zip) -
+[other files](http://luarocks.github.io/luarocks/releases)
+
+**Version 3.10.0** - 27/Feb/2024 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.10.0.tar.gz) -
+[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.10.0-windows-32.zip) -
+[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.10.0-windows-64.zip) -
+[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.10.0-linux-x86_64.zip) -
+[other files](http://luarocks.github.io/luarocks/releases)
+
+**Version 3.9.2** - 08/Dec/2022 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.9.2.tar.gz) -
+[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.9.2-windows-32.zip) -
+[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.9.2-windows-64.zip) -
+[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.9.2-linux-x86_64.zip) -
+[other files](http://luarocks.github.io/luarocks/releases)
+
+**Version 3.9.1** - 01/Jul/2022 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.9.1.tar.gz) -
+[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.9.1-windows-32.zip) -
+[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.9.1-windows-64.zip) -
+[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.9.1-linux-x86_64.zip) -
+[other files](http://luarocks.github.io/luarocks/releases)
+
+**Version 3.9.0** - 17/Apr/2022 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.9.0.tar.gz) -
+[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.9.0-windows-32.zip) -
+[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.9.0-windows-64.zip) -
+[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.9.0-linux-x86_64.zip) -
+[other files](http://luarocks.github.io/luarocks/releases)
+
+* `builtin` build mode now always respects CC, CFLAGS and LDFLAGS
+* Check that lua.h version matches the desired Lua version
+* Check that the version of the Lua C library matches the desired Lua version
+* Fixed deployment of non-wrapped binaries
+* Fixed crash when `--lua-version` option is malformed
+* Fixed help message for `--pin` option
+* Unix: use native methods and don't always rely on $USER to determine user
+* Windows: use native CLI tooling more
+* macOS: support .tbd extension when checking for libraries
+* macOS: add XCode SDK path to search paths
+* macOS: add best-effort heuristic for library search using Homebrew paths
+* macOS: avoid quoting issues with LIBFLAG
+* macOS: deployment target is now 11.0 on macOS 11+
+* added DragonFly BSD support
+* LuaRocks test suite now runs on Lua 5.4 and LuaJIT
+* Internal dependencies of standalone LuaRocks executable were bumped
+
+**Version 3.8.0** - 08/Nov/2021 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.8.0.tar.gz) -
+[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.8.0-windows-32.zip) -
+[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.8.0-windows-64.zip) -
+[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.8.0-linux-x86_64.zip) -
+[other files](http://luarocks.github.io/luarocks/releases)
+
+**Version 3.7.0** - 13/Apr/2021 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.7.0.tar.gz) -
+[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.7.0-windows-32.zip) -
+[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.7.0-windows-64.zip) -
+[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.7.0-linux-x86_64.zip) -
+[other files](http://luarocks.github.io/luarocks/releases)
+
+**Version 3.6.0** - 30/Mar/2021 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.6.0.tar.gz) -
+[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.6.0-windows-32.zip) -
+[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.6.0-windows-64.zip) -
+[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.6.0-linux-x86_64.zip) -
+[other files](http://luarocks.github.io/luarocks/releases)
+
+**Version 3.5.0** - 10/Dec/2020 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.5.0.tar.gz) -
+[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.5.0-windows-32.zip) -
+[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.5.0-windows-64.zip) -
+[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.5.0-linux-x86_64.zip) -
+[other files](http://luarocks.github.io/luarocks/releases)
+
+**Version 3.4.0** - 25/Sep/2020 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.4.0.tar.gz) -
+[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.4.0-windows-32.zip) -
+[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.4.0-windows-64.zip) -
+[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.4.0-linux-x86_64.zip) -
+[other files](http://luarocks.github.io/luarocks/releases)
+
+* `luarocks make` now supports `--only-deps`
+* `luarocks make` new flag: `--no-install`, which only performs the compilation step
+* `--deps-only` is now an alias for `--only-deps` (useful in case you always kept getting it wrong, like me!)
+* `luarocks build` and `luarocks make` now support using `--pin` and `--only-deps` at the same time, to produce a lock file of dependencies in use without installing the main package.
+* `luarocks show` can now accept a substring of the rock's name, like `list`.
+* `luarocks config`: when running without system-wide permissions, try storing the config locally by default. Also, if setting both lua_dir and --lua-version explicitly, auto-switch the default Lua version.
+* `luarocks` with no arguments now prints more info about the location of the Lua interpreter which is being used
+* `luarocks new_version` now keeps the old URL if the MD5 doesn't change.
+* `DEPS_DIR` is now accepted as a generic variable for dependency directories (e.g. `luarocks install foo DEPS_DIR=/usr/local`)
+* Handle quoting of arguments at the application level, for improved Windows support
+* All-in-one binary bundles `dkjson`, so it runs `luarocks upload` without requiring any additional dependencies.
+* Tweaks for Terra compatibility
+* win32: generate proper temp filename
+* No longer assume that Lua 5.3 is built with compat libraries and bundles `bit32`
+* `luarocks show`: do not crash when rockspec description is empty
+* When detecting the location of `lua.h`, check that its version matches the version of Lua being used
+* Fail gracefully when a third-party tool (wget, etc.) is missing
+* Fix logic for disabling mirrors that return network errors
+* Fix detection of Lua path based on arg variable
+* Fix regression on dependency matching of luarocks.loader
+
+**Version 3.3.1** - 07/Feb/2020 - [All Unix](http://luarocks.org/releases/luarocks-3.3.1.tar.gz) -
+[Windows all-in-one executable (32-bit)](http://luarocks.org/releases/luarocks-3.3.1-windows-32.zip) -
+[Windows all-in-one executable (64-bit)](http://luarocks.org/releases/luarocks-3.3.1-windows-64.zip) -
+[other files](http://luarocks.github.io/luarocks/releases)
+
+* Fix downgrades of rocks containing directories: stop it from creating spurious 0-byte files where directories have been
+* Fix error message when attempting to copy a file that is missing
+* Detect OpenBSD-specific dependency paths
+
+**Version 3.3.0** - 28/Jan/2020 - [All Unix](http://luarocks.org/releases/luarocks-3.3.0.tar.gz) -
+[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.3.0-windows-32.zip) -
+[other files](http://luarocks.github.io/luarocks/releases)
+
+**Version 3.2.1** - 05/Sep/2019 - [All Unix](http://luarocks.org/releases/luarocks-3.2.1.tar.gz) -
+[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.2.1-windows-32.zip) -
+[other files](http://luarocks.github.io/luarocks/releases)
+
+**Version 3.2.0** - 28/Aug/2019 - [All Unix](http://luarocks.org/releases/luarocks-3.2.0.tar.gz) -
+[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.2.0-windows-32.zip) - [other files](https://luarocks.github.io/luarocks/releases)
+
+* Bugfix: luarocks path does not change the order of pre-existing path items when prepending or appending to path variables
+* Bugfix: fix directory detection on the Mac
+* When building with --force-config, LuaRocks now never uses the "project" directory, but only the forced configuration
+* Lua libdir is now only checked for commands/platforms that really need to link Lua explicitly
+* LuaJIT is now detected dynamically
+* RaptorJIT is now detected as a LuaJIT variant
+* Improvements in Lua autodetection at runtime
+* luarocks new_version: new option --dir
+* luarocks which: report modules found via package.path and package.cpath as well
+* install.bat: Improved detection for Visual Studio 2017 and higher
+* Bundled LuaSec in all-in-one binary bumped to version 0.8.1
+
+**Version 3.1.3** - 06/Jun/2019 - [All Unix](http://luarocks.org/releases/luarocks-3.1.3.tar.gz) -
+[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.1.3-windows-32.zip)
+
+**Version 3.1.2** - 07/May/2019 - [All Unix](http://luarocks.org/releases/luarocks-3.1.2.tar.gz) -
+[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.1.2-windows-32.zip)
+
+**Version 3.1.1** - 06/May/2019 - [All Unix](http://luarocks.org/releases/luarocks-3.1.1.tar.gz) -
+[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.1.1-windows-32.zip)
+
+**Version 3.1.0** - 30/Apr/2019 - [All Unix](http://luarocks.org/releases/luarocks-3.1.0.tar.gz) - 
+[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.1.0-windows-32.zip)
+
+* config: add git-like modes for setting and inspecting configuration
+* make: run rockspec patches on first `luarocks make` run and use a lockfile to avoid double patching
+* persist selected Lua version when setting `luarocks config lua_version 5.x`
+* new flag --global for overriding local_by_default = true
+* do not complain if home cache cannot be created (use temp dir instead)
+* caching improvements for increased performance
+* project-based workflow: if ./.luarocks/config-5.x.lua exists, assume Lua 5.x
+* install, pack, build, make: new flags --sign and --verify (using GPG)
+* install: new flag --no-doc
+* Improve Lua paths auto-detection
+* Various bugfixes
+
+**Version 3.0.4** - 30/Oct/2018 - [All Unix](http://luarocks.org/releases/luarocks-3.0.4.tar.gz) - 
+[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.0.4-windows-32.zip)
+
+* Fork-free platform detection at startup
+* Improved detection of the default rockspec in commands such as `luarocks test`
+* Various minor bugfixes
+
+**Version 3.0.3** - 15/Sep/2018 - [All Unix](http://luarocks.org/releases/luarocks-3.0.3.tar.gz) - 
+[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.0.3-windows-32.zip)
+
+* Minor bugfixes
+
+**Version 3.0.2** - 07/Sep/2018 - [All Unix](http://luarocks.org/releases/luarocks-3.0.2.tar.gz) - 
+[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.0.2-windows-32.zip)
+
+* Improvements in luarocks init, new --reset flag
+* write_rockspec: --lua-version renamed to --lua-versions
+* Improved behavior in module autodetection
+* Bugfixes in luarocks show
+* Fix upgrade/downgrade when a single rock has clashing module filenames
+* Fix for autodetected external dependencies with non-alphabetic characters
+
+**Version 3.0.1** - 14/Aug/2018 - [All Unix](http://luarocks.org/releases/luarocks-3.0.1.tar.gz) - 
+[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.0.1-windows-32.zip)
+
+* Numerous bugfixes
+* Store Lua location in config file, so that a user can run `luarocks init --lua-dir=/my/lua/location` and have that location remain active for that project
+* Various improvements to the Unix makefile, including $(DESTDIR) support and an uninstall rule
+* Autodetect FreeBSD-style include paths (/usr/include/lua5x/)
+
+**Version 3.0.0** - 25/Jul/2018 - [All Unix](http://luarocks.org/releases/luarocks-3.0.0.tar.gz) - 
+[Windows batch installer](http://luarocks.org/releases/luarocks-3.0.0-win32.zip)
+
+* New rockspec format
+* New commands, including `luarocks init` for per-project workflows
+* New flags, including `--lua-dir` and `--lua-version` for using multiple Lua installs with a single LuaRocks
+* New build system, gearing towards a new distribution model
+* General improvements, including namespaces
+* User-visible changes, including some breaking changes
+* Internal changes
+
+**Version 2.4.4** - 12/Mar/2018 - [All Unix](http://luarocks.org/releases/luarocks-2.4.4.tar.gz) - 
+[Windows](http://luarocks.org/releases/luarocks-2.4.4-win32.zip)
+
+* Do not halt a package deletion process when a file from the package is missing
+* Updated bundled binaries in Windows package: Lua 5.1.5, Wget 1.19.4, 7zip 18.01
+* Updated Windows installer to better handle gcc toolchains
+* Fix detection of directories on Windows
+* Fixes .def generation on Windows
+
+**Version 2.4.3** - 12/Sep/2017 - [All Unix](http://luarocks.org/releases/luarocks-2.4.3.tar.gz) - 
+[Windows](http://luarocks.org/releases/luarocks-2.4.3-win32.zip)
+
+* Fixed display of pathnames in `luarocks show`
+* Improved check for write permissions when installing
+* Plus assorted bugfixes and improvements
+
+**Version 2.4.2** - 30/Nov/2016 - [All Unix](http://luarocks.org/releases/luarocks-2.4.2.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.4.2-win32.zip)
+
+* Fixed conflict resolution on deploy/delete
+* Improved dependency check messages
+* Performance improvements when removing packages
+* Support user-defined `platforms` array in config file
+* Improvements in Lua interpreter version detection in Unix configure script
+* Relaxed Lua version detection to improve support for alternative implementations (e.g. Ravi)
+* Plus assorted bugfixes and improvements
+
+**Version 2.4.1** - 06/Oct/2016 - [All Unix](http://luarocks.org/releases/luarocks-2.4.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.4.1-win32.zip)
+
+* Avoid coroutine use in luarocks.loader
+* Fix upgrade issues for very old versions
+
+**Version 2.4.0** - 08/Sep/2016 - [All Unix](http://luarocks.org/releases/luarocks-2.4.0.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.4.0-win32.zip)
+
+* New test suite based on Busted; runs on Linux, OSX and Windows
+* git+ssh:// fetch protocol
+* Improved behavior preserving permissions
+* Improved listing of dependencies on installation
+* Improved behavior of argument handling in `pack`
+* MSYS and Haiku platform detection
+* Feature-based detection of internal bit32 and utf8 modules
+* Internal reorganization of luarocks.fs code
+* `remove` option --force=fast renamed to --force-fast
+* Plus assorted bugfixes and cleanups
+
+**Version 2.3.0** - 09/Jan/2016 - [All Unix](http://luarocks.org/releases/luarocks-2.3.0.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.3.0-win32.zip)
+
+* Windows: major redesign of the install tree structure
+* Windows: Auto setup of MSVC environments
+* Improve error messages when tools are not installed
+* CMake: generate 64-bit builds when appropriate
+* Improve check of location of config files
+* MacOSX: set MACOSX_DEPLOYMENT_TARGET using env
+* Remove --extensions flag; use rockspec_format instead
+* New `luarocks config` command to query configuration
+* Improved UI for messages when external deps are missing
+* Unix: Robustness improvement in configure script
+* Plus tweaks and bugfixes. See the changelog for details.
+
+**Version 2.2.2** - 24/Apr/2015 - [All Unix](http://luarocks.org/releases/luarocks-2.2.2.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.2.2-win32.zip)
+
+* `luarocks build --only-deps` and `luarocks install --only-deps` for installing dependencies only
+* Mercurial support
+* Improved command-line argument parser, now validates arguments (it previously ignored unrecognized arguments) and accepts both `--flag=option` and `--flag option` in flags that take arguments.
+* For consistency with `luarocks show`, `luarocks doc --homepage` is now `luarocks doc --home`
+* Improvements to CMake build backend
+* Improved Makefiles for handling simultaneous bootstrapped installations
+* Various bugfixes
+
+**Version 2.2.1** - 17/Mar/2015 - [All Unix](http://luarocks.org/releases/luarocks-2.2.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.2.1-win32.zip)
+
+* Improved compatibility with Lua 5.3
+* `luarocks list --outdated` for listing modules with available upgrades
+* Assorted bugfixes
+
+**Version 2.2.0** - 15/Aug/2014 - [All Unix](http://luarocks.org/releases/luarocks-2.2.0.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.2.0-win32.zip)
+
+* MoonRocks is the new default repository: http://rocks.moonscript.org - Rocks don't need to be sent to the LuaRocks mailing list anymore, you can upload them directly at the website or using...
+* ...`luarocks upload` command for uploading rocks to MoonRocks via the command-line
+* Preliminary support for Lua 5.3
+* No longer uses the module() function, for Lua 5.2 installations built without Lua 5.1 compatibility
+* --branch flag for `luarocks build` and `luarocks make`
+* various improvements in `luarocks doc` command
+* "git+http" transport for source.url
+
+**Version 2.1.2** - 10/Jan/2014 - [All Unix](http://luarocks.org/releases/luarocks-2.1.2.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.1.2-win32.zip)
+
+* major improvements in the Windows install.bat script. Now installs by default on standard Windows locations, while the old self-contained all-under-one-dir installation is still supported through an option flag. The documentation at luarocks.org didn't catch up with it yet, so please refer to "install /?" for instructions.
+* a new command, "luarocks doc <module>" that tries to find any installed documentation. Due to the lack of documentation standards for Lua, this uses a few heuristics. Feedback on the feature is appreciated.
+* a rocks_provided configuration entry in which you can preload dependencies that are already fulfulled in your system; a few defaults are included (bit32 is auto-provided in Lua 5.2; luabitop is auto-provided in LuaJIT)
+* generated script wrappers are now more robust
+* Graceful handling of permission errors on Windows
+* Minor performance improvements
+* Support for "named trees", so you can label your rocks trees and use flags such as --tree=system  or --tree=user instead of the full path
+* "luarocks" with no arguments presents more useful diagnostics
+* Improved Lua detection in Unix installer
+* plus assorted bugfixes
+
+**Version 2.1.1** - 29/Oct/2013 - [All Unix](http://luarocks.org/releases/luarocks-2.1.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.1.1-win32.zip)
+
+* Remote manifests are now compressed and locally cached, making commands faster
+* New command "write_rockspec" which generates rockspec file templates
+* detection of multiarch directories on Linux
+* environment and performance improvements on Windows
+* New --force=fast option for 'luarocks remove'
+* New --local-tree flag for 'luarocks-admin make-manifest'
+* Improved error checking
+* plus assorted bugfixes
+
+**Version 2.1.0** - 09/Aug/2013 - [All Unix](http://luarocks.org/releases/luarocks-2.1.0.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.1.0-win32.zip)
+
+* accesses manifest-{5.1,5.2} in remote servers to provide properly filtered results for Lua 5.1 or 5.2
+* Remove old versions when installing a new one and old versions are no longer needed to honor dependencies.
+* 'make bootstrap' is now an advertised option for installing LuaRocks itself as a rock on Unix systems
+* 'luarocks purge --old-versions' for cleaning up a local tree
+* --keep flag to produce the old behavior of keeping old versions around (can be made permanent setting keep_old_versions=true in the config file)
+* security config options 'accepted_build_types' and 'hooks_enabled'
+* 'lua_version' is now available as a global for your config.lua
+* new flags --lr-path, --lr-cpath, --lr-bin for 'luarocks path' for use in scripts
+* friendlier error messages
+* plus bugfixes
+
+**Version 2.0.13** - 16/Apr/2013 - [All Unix](http://luarocks.org/releases/luarocks-2.0.13.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.13-win32.zip)
+
+* Support for Lua 5.2 is no longer marked as experimental
+* Support for installing two instances of LuaRocks, for Lua 5.1 and 5.2, in parallel
+* Improvements for the 'builtin' build mode on Windows
+* rclauncher on Windows does not rely on a precompiled object anymore
+* Improvements for the Windows installer, including optional registry entries for context-menu operations
+* Improvements in 'luarocks new_version` command for autogenerating updated rockspecs
+* 'luarocks remove' command accepts rock and rockspec filenames
+
+**Version 2.0.12** - 05/Nov/2012 - [All Unix](http://luarocks.org/releases/luarocks-2.0.12.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.12-win32.zip)
+
+* "Dependencies mode" selection to configure how to work with multiple local trees
+* New command "purge" that erases a local tree
+* --porcelain flag for "list" and "search"
+* More consistent user-agent reporting
+* Code cleanups, removal of dead code
+* Fixes regressions on Mac and Windows
+
+**Version 2.0.11** - 21/Sep/2012 - [All Unix](http://luarocks.org/releases/luarocks-2.0.11.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.11-win32.zip)
+
+* Work around LuaSocket crash when given proxy URLs without the scheme part
+* Save manifest file in a single fs operation to make it more atomic
+* Fix tree loading order on luarocks.loader with multiple trees
+* Fix detection of write permissions
+* Improve dependency detection using configurable patterns, now a file like "libfoo.so.1" satisfies "libfoo.so"
+* --bin flag for "luarocks path" command, exports $PATH
+* Support for mirrors in the rocks_servers list, default list of mirrors included
+* Avoid using Lua modules internally on Windows, to avoid file system locking
+* Add NetBSD support
+* Rename luarocks.rep to luarocks.repos
+* Fail gracefully on the absence of cmake, on cmake build mode
+* New command "lint", to check the syntax of a rockspec
+* Fix builtin build mode on Mac OSX < 10.5
+* Improve configure tests for Debian-based platforms
+
+**Version 2.0.10** - 12/Jul/2012 - [All Unix](http://luarocks.org/releases/luarocks-2.0.10.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.10-win32.zip)
+
+* Fix fetching Git tags/branches 
+* Fix strictness issue with parameter of io.open
+* Builtin mode sets rpath when compiling on Unix
+* Use full path in $(LUA) when configured with --with-lua
+* Cleanup of .svn dir in svn-based rocks
+* Improvement for 'make bootstrap'
+
+**Version 2.0.9** - 31/May/2012 - [All Unix](http://luarocks.org/releases/luarocks-2.0.9.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.9-win32.zip)
+
+* Experimental support for Lua 5.2 (auto-detection and explicit --lua-version flag in configure)
+* Solaris support and BSD fixes
+* --nodeps flag for forced installation without dependencies
+* "new_version" command to streamline writing of updated rockspecs
+* Improved handling of LUAROCKS_SYSCONFIG variable
+* Clickable URLs in descriptions in rocks repo index.html
+* Nicer-looking persisted tables
+* Assorted bugfixes
+
+**Version 2.0.8** - 29/Feb/2012 - [All Unix](http://luarocks.org/releases/luarocks-2.0.8.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.8-win32.zip)
+
+* Fix in CMake build backend
+* Fix handling error condition of --pack-binary-rock
+* Fixes for Windows .bat installer
+* Improved arch detection when packing binary rocks
+* Workaround LuaPosix 5.1.15 problem with chmod()
+* Proper error messages when config files are invalid
+* Avoid checking permissions when it's not necessary
+* Fix behavior of 'builtin' rocks which install init.lua scripts
+* git+file:// pseudoprotocol for local Git repos
+* New binaries from GnuWin32 shipped in Win32 zip
+* Nicer-looking help
+
+**Version 2.0.7.1** - 10/Jan/2012 - [All Unix](http://luarocks.org/releases/luarocks-2.0.7.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.7.1-win32.zip)
+
+* Fix installation of files in build operation
+* Deprecate --to and --from, use --server and --tree instead
+* Improved documentation, thanks to LDoc
+
+**Version 2.0.7** - 10/Dec/2011 - [All Unix](http://luarocks.org/releases/luarocks-2.0.7.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.7-win32.zip)
+
+* Quieter git checkout
+* --only-sources flag to restrict download of sources from a single domain
+* Copy entries to bin/ with proper permissions
+* Fix --pack-binary-rock and add support for it in "luarocks make" as well
+* Isolate references to "5.1" to luarocks.cfg module
+* More logical names for flags: --tree, --server
+* Improved documentation
+
+**Version 2.0.6** - 04/Oct/2011 - [All Unix](http://luarocks.org/releases/luarocks-2.0.6.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.6-win32.zip)
+
+* Fixes for rockspecs missing 'description' or the contents of 'source.url'
+* Escape fixes for LuaJIT/Metalua
+* Support for building a rock without installing it
+* Site-local configuration is now at luarocks.site_config
+* Support for Mercurial
+* Flag for experimental extensions
+* Plus assorted bugfixes
+
+**Version 2.0.5** - 17/Aug/2011 - [All Unix](http://luarocks.org/releases/luarocks-2.0.5.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.5-win32.zip)
+
+* External commands are overridable through variables or config.lua
+* No longer uses print() - output goes to stdout, errors to stderr
+* Handle redirects between http (LuaSocket) and https (LuaSec)
+* Avoid relying on the $PWD variable
+* Code cleanups
+
+**Version 2.0.4.1** - 17/Jan/2011 - [All Unix](http://luarocks.org/releases/luarocks-2.0.4.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.4.1-win32.zip)
+
+* Minor bugfix release
+
+**Version 2.0.4** - 23/Dec/2010 - [All Unix](http://luarocks.org/releases/luarocks-2.0.4.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.4-win32.zip)
+
+* Command "remove" for luarocks-admin
+* Check for write permissions in repository and suggest --local
+* Remove .git from source tree when downloading from Git
+* Display of external dependencies in index.html
+* OpenBSD support
+* More thorough search for external libraries
+* Normalize paths to fix behavior when LFS is used under Windows
+* Add HTTPS support using LuaSec when using LuaSocket, for consistency
+* Better propagation of error messages
+* Stable sort of persisted files such as manifests
+* Plus assorted bugfixes
+
+**Version 2.0.3** - 14/Sep/2010 - [All Unix](http://luarocks.org/releases/luarocks-2.0.3.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.3-win32.zip)
+
+* Check for permissions and warn user instead of just installing in local tree
+* --local flag for operations on the local tree
+* -fPIC is always set in CFLAGS exported to makefiles
+* respect permissions when copying files in Unix systems
+* display license after build/installation
+* svn:// protocol for scm rockspecs
+* "luarocks list" and "luarocks search" are now case-insensitive
+* "luarocks-admin add" supports adding multiple files at once
+* "luarocks-admin add" supports rsync for download and upload and scp for upload
+* new command: "luarocks show" displays information about an installed rock
+* new command: "luarocks path" to make it easy to export Lua env variables
+* plus assorted bugfixes
+
+**Version 2.0.2** - 01/Apr/2010 - [All Unix](http://luarocks.org/releases/luarocks-2.0.2.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.2-win32.zip)
+
+* use LuaSocket if available for downloading files
+* use LuaZip if available for unzipping files
+* MinGW support in builtin build backend
+* updated installation files for Windows, including a LuaForWindows-compatible package
+
+**Version 2.0.1** - 27/Oct/2009 - [All Unix](http://luarocks.org/releases/luarocks-2.0.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.1-win32.zip)
+
+* luarocks.cfg is no longer edited during installation; a separate site-local luarocks.config module is created.
+* robustness fixes and improvements for luarocks.add
+* cleanup of configure options and references to the old LuaForge URLs
+* install LuaRocks as a rock
+* plus assorted bugfixes
+
+**Version 2.0** - 17/Oct/2009 - [All Unix](http://luarocks.org/releases/luarocks-2.0.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0-win32.zip)
+
+* module files are now deployed to standard Lua-style paths
+* new package loader module luarocks.loader, superseding the require()-override module luarocks.require
+* new abstraction system for file system operations: the OS-specific back-ends for luarocks.fs were split between native-Lua and tool-based implementations
+* new format for local manifest
+* new command for luarocks: "download", to fetch .rock and .rockspec files
+* new commands for luarocks-admin: "add", to upload rocks to a repository, and "refresh_cache", to refresh the cache used by the "add" command
+* plus a number of cleanups and bugfixes
+
+**Version 1.0.1** - 13/Mar/2009 - [All Unix](http://luarocks.org/releases/luarocks-1.0.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-1.0.1-win32.zip)
+
+* Improve portability in usage of Unix tools
+* Allow use of local rocks servers in the --from flag
+* Improve detection of external libraries on Mac OSX
+* Fix build of the 'builtin' backend under Windows
+* Support for the 'md5' binary as a MD5 checker
+
+**Version 1.0** - 01/Sep/2008 - [All Unix](http://luarocks.org/releases/luarocks-1.0.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-1.0-win32.zip)
+
+* Add support for post-install hooks
+* Path helper scripts for binaries on Windows systems.
+* Git support, contributed by Thomas Harning.
+* Improve shell compatibility for different Unix systems.
+* Add the @ operator for no-upgrade dependencies.
+* Add check for rockspec version format.
+* Generate index.html when building a manifest for a repository.
+* Plus assorted bugfixes.
+
+**Version 0.6** - 30/Jun/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.6.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.6-win32.zip)
+
+* Check external deps on binary installs. Allow rockspecs to specify supported platforms. Support platform-agnostic specification of external deps files.  Allow overriding external deps subdirs.
+* Structured build systems in subdirectories.
+* Smarter check to decide if a rock is pure Lua or not, also checking bin/
+* Restructuring of fs code.
+* Modularized fetch code to support multiple SCMs.
+* Added specific support for 'doc' directory in rockspecs. Auto-install files in 'lua' in builtin builds.
+* Support for Surround SCM, contributed by Ignacio Burgueño.
+* "module" build type renamed to "builtin"; "cvs_tag" and "cvs_module" renamed to "tag" and "module". Old names still supported for compatibility for now, to be cleaned up by 1.0.
+* Plus many bugfixes.
+
+**Version 0.5.2** - 13/May/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.5.2.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.5.2-win32.zip)
+
+* Fixes problems with removal of read-only files on Windows
+* Fixes issues with external libraries on the 'module' build type on Windows
+* Fixes the --only-from flag
+* Renames the luarocks.config module to luarocks.cfg avoiding conflict's with the user configuration file config.lua
+
+**Version 0.5.1** - 25/Apr/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.5.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.5.1-win32.zip)
+
+* Added function get_rock_from_module in luarocks.require, allowing apps to inspect which rock they're getting modules from.
+* Added variables LUA, LIB_EXTENSION and OBJ_EXTENSION, now available for rockspec authors.
+* Assorted bugfixes, especially for the Windows package.
+* Build system improvements: add DESTDIR variable to makefile to make things easier for distros packaging LuaRocks.
+
+**Version 0.5** - 03/Apr/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.5.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.5-win32.zip)
+
+* New flags in the ./configure on Unix (see configure --help) and install.bat on Windows (see install.bat /?)
+* Support for multiple local repositories. By extension, LuaRocks features more intuitive configuration defaults (it installs rocks to $PREFIX/lib/luarocks if you have the permission, and to $HOME/.luarocks if you don't).
+* Flags --from=_server_, --only-from=_server_ and --to=_tree_, to allow specifying exactly where to get rocks from and where to install them to.
+* The manifest file now stores dependency info -- luarocks.require no longer scans rockspec files.
+* 'unpack' command allows unpacking binary and pure-Lua rocks, for inspecting.
+* Plus assorted bugfixes.
+
+**Version 0.4.3** - 03/Mar/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.4.3.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.4.3-win32.zip)
+
+* The MD5 check feature added in 0.4.2 can now use openssl instead of md5sum (making LuaRocks friendlier to OSX).
+* Added a license file in the tarball (making LuaRocks friendlier to Debian).
+* Plus assorted bugfixes.
+
+**Version 0.4.2** - 09/Feb/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.4.2.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.4.2-win32.zip)
+
+* Support .lua files directly in the URL field.
+* Perform check of MD5 checksum in sources.
+* Accept plain strings in all fields of the source table of the "module" build type.
+* Bugfixes.
+
+**Version 0.4.1** - 25/Jan/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.4.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.4.1-win32.zip)
+
+* New configure/install.bat flags for setting scripts dir and local repository dir.
+* "unpack" command now supports rockspec files as well.
+* Complete code documentation.
+* Many assorted bugfixes.
+
+**Version 0.4** - 18/Jan/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.4.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.4-win32.zip)
+
+* Adds the "unpack" command for debugging rocks (.src.rock only at this point).
+* Support curl as an alternative downloader for OSX, removing the dependency on wget.
+* Support for installing non-Lua entries in bin/ dirs.
+* Support for specifying libdirs, incdirs, libraries and defines in "module"-type builds.
+* x86_64 support, by Brian Hetro.
+* FreeBSD support, by Matthew M. Burke.
+* Performance improvements.
+* Many assorted bugfixes.
+
+**Version 0.3.2** - 21/Dec/2007 - [All Unix](http://luarocks.org/releases/luarocks-0.3.2.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.3.2-win32.zip)
+
+* Support for patching and inclusion of extra files (such as Makefiles) through a rockspec.
+* Support "platforms" overrides table for dependencies, external dependencies and source URLs.
+* Many assorted bugfixes.
+
+**Version 0.3.1** - 18/Dec/2007 - [All Unix](http://luarocks.org/releases/luarocks-0.3.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.3.1-win32.zip)
+
+* Improved search: results now feature separate lists for source and binary rocks.
+* Windows support for the "module" build type (using Visual Studio).
+* Many assorted bugfixes.
+
+**Version 0.3** - 04/Dec/2007 - [All Unix](http://luarocks.org/releases/luarocks-0.3.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.3-win32.zip)
+
+* Includes Windows package.
+* Adds the "module" build type.
+* Performance improvements.
+
+**Version 0.2** - 23/Oct/2007 - [All Unix](http://luarocks.org/releases/luarocks-0.2.tar.gz)
+
+* Bugfixes and improvements to build infrastructure.
+* Adds the LuaRocks "remove" command.
+
+**Version 0.1** - 09/Aug/2007 - [All Unix](http://luarocks.org/releases/luarocks-0.1.tar.gz)
+
+* Initial release.
diff --git a/docs/rock_file_format.md b/docs/rock_file_format.md
new file mode 100644
index 00000000..10748bde
--- /dev/null
+++ b/docs/rock_file_format.md
@@ -0,0 +1,51 @@
+# Rock file format
+
+This page describes the .rock file format used by LuaRocks.
+
+Note that there are different [types of rocks](types_of_rocks.md). 
+
+## Filenames
+
+* .rock and .rockspec filenames must be all-lowercase
+* Rock names must follow the format "$NAME-$VERSION-$REVISION.$PLATFORM.rock", where:
+
+ * $NAME is an arbitrary name (matchable via `"[a-z0-9_-]+"`)
+ * $VERSION is a version number parseable by LuaRocks (e.g. "1.0", "2.1beta1", "scm" for git-HEAD/svn-master rockspecs)
+ * $REVISION is the rockspec revision number, a positive integer
+ * $PLATFORM must follow the format "$OS-$ARCH", where:
+
+    * $OS is an operating system identifier known by LuaRocks
+    * $ARCH is a hardware architecture identifier known by LuaRocks
+
+## Source rocks
+
+A source rock must contain at its root the rockspec file. For a rock called `myrock-1.0-1.src.rock` it would be called:
+
+* `myrock-1.0-1.rockspec` - the [rockspec file](Rockspec format) in the archive root
+
+Additionally, it must contain the sources:
+
+* If the `source.url` field is specified using a file download protocol-type URL (`http://`, `https://`, `file://` and so on) pointing to the source archive (or source file in case of a single-file rock), the rock should contain the product of downloading this URL. 
+  * For example, a source rock may contain two files: `myrock-1.0-1.rockspec` and `myrock-1.0.tar.gz`
+* If the `source.url` field is specified using a Source Control Manager (SCM) protocol-type URL (`git://`, `hg://`, `svn://` and so on), the rock should contain the corresponding checked-out sources. The SCM metadata (e.g. the `.git` directory) does not need to be present. (Note: This is not specific to "scm" rocks that point to in-development repositories; a stable-version rockspec may use a SCM-based URL and an SCM tag with `source.tag` in the rockspec to point to a release version).
+  * For example, a source rock may contain at the root the rockspec `myrock-1.0-1.rockspec` and a directory `myrock` that would be the result of `git clone https://github.com/example/myrock`
+
+## Binary rocks
+
+A binary rock must contain at its root two files. For a rock called `myrock-1.0-1.linux-x86.rock` they would be called:
+
+* `myrock-1.0-1.rockspec` - the [rockspec file](Rockspec-format) in the archive root
+* `rock_manifest` - a [rock manifest file](Rock-manifest-file-format)
+
+These standard directories are handled specially:
+
+* `lib/` - a directory containing binary modules (the contents of this directory are files that go into `$PREFIX/lib/lua/5.x/` in a vanilla Lua installation on Unix). The directory structure inside this directory is replicated when installing.
+* `lua/` - a directory containing Lua modules (the contents of this directory are files that go into `$PREFIX/share/lua/5.x/` in a vanilla Lua installation on Unix). The directory structure inside this directory is replicated when installing.
+* `bin/` - a directory containing executable Lua scripts (the contents of this directory are files that go into `$PREFIX/bin/` in a vanilla Lua installation on Unix) 
+* `doc/` or `docs/` - documentation files - if present, their contents are listed when running `luarocks doc`. The directory structure inside this directory is replicated when installing.
+
+Any additional directories in the .rock file are copied verbatim (including subdirectories) to `$ROCK_TREE/lib/luarocks/rocks-5.x/myrock/1.0-1/` (common directories are `tests`, `samples`, `examples`, etc.
+
+### Pure-Lua rocks
+
+Pure-Lua rocks are identical to binary rocks, except that they don't have a `lib/` directory containing binary modules. When a rock contains only `lua/` files and no `lib/` files, it automatically gains the `.all.rock` file extension. If the rock is platform-specific, the packager may rename the file to the proper platform, or specify the list of supported platforms in the `supported_platforms` table of the rockspec.
diff --git a/docs/rock_manifest_file_format.md b/docs/rock_manifest_file_format.md
new file mode 100644
index 00000000..e7838d11
--- /dev/null
+++ b/docs/rock_manifest_file_format.md
@@ -0,0 +1,19 @@
+# Rock manifest file format
+
+The `rock_manifest` file lists the files contained in a binary rock, with the
+MD5 checksum for each file.
+
+It is a Lua file containing a single global variable definition, that defines
+the variable **rock_manifest**, assigning to it a _table of file checksums_ of
+the [archive file's root directory](Rock file format) (except for the
+`rock_manifest` file itself).
+
+A table of file checksums is defined as a table describing a directory, where
+for each entry in the directory, there is a string key with its filename (only
+the basename).
+
+If the filename is a non-directory, the value of its key is a string with the
+MD5 checksum of the file.
+
+If the filename is a directory, the value of its key is itself a table of file
+checksums of that directory.
diff --git a/docs/rocks_repositories.md b/docs/rocks_repositories.md
new file mode 100644
index 00000000..6e0f38cb
--- /dev/null
+++ b/docs/rocks_repositories.md
@@ -0,0 +1,54 @@
+# Rocks repositories
+
+For normal use, rocks repositories are manipulated by the `luarocks`
+command-line tool. LuaRocks fetches rocks from one kind of repository -- rocks
+servers -- and installs them into another kind of repository -- rocks trees.
+
+Generally speaking, a rocks repository is a directory containing rocks and/or
+rockspecs, and a manifest file which catalogs the rocks contained therein. 
+Rocks servers may contain [packed rocks](types_of_rocks.md) and rockspecs, and
+may be located in remote (HTTP or FTP) URLs or paths in the local filesystem.
+Rocks trees can contain only [unpacked](types_of_rocks.md) (installed) rocks,
+and are always local.
+
+LuaRocks can be configured to use multiple rocks trees and multiple rocks
+servers. See the [Config file format](config_file_format.md) for details and
+the reference for the [luarocks](luarocks.md) command-line tool for details.
+
+Publishing a repository as a rocks server consists of making a directory
+containing rocks and a manifest file available online. A manifest file can be
+created using the make-manifest command of the `luarocks-admin` command-line
+tool, included in LuaRocks. For the rocks tree, the manifest file is updated
+automatically by LuaRocks.
+
+# Rocktree structure 
+
+A rocks tree has this (default) layout;
+
+```
+{base}                (base rocks tree directory)
+  ├── bin              (deployment of command line scripts)
+  ├── lib
+  │    ├── luarocks
+  │    │    └── rocks  (contains manifest and sub-dirs with rocks)
+  │    │
+  │    └── lua
+  │         └── 5.1    (deployment of binary modules)
+  │
+  └── share
+       └── lua
+            └── 5.1    (deployment of Lua modules)
+```
+
+Whenever LuaRocks installs a rock it will install them (the executable parts)
+in the deployment directories. These directories should be included in your
+system path, `LUA_PATH`, and `LUA_CPATH` to be able to
+`require` the modules from your own scripts or use the command line
+scripts from a prompt. Other included elements (see `copy_directories`
+in rockspec), including the manifest and rockspecs, will be stored in the
+`base/lib/luarocks/rocks`.
+
+When multiple versions of the same rock are being installed, the older ones in
+the deployment directories will be renamed to a name including the version.
+The `luarocks.loader` module will be able to load the proper version of
+the modules despite the changed names.
diff --git a/docs/rockspec_format.md b/docs/rockspec_format.md
new file mode 100644
index 00000000..d74daa9e
--- /dev/null
+++ b/docs/rockspec_format.md
@@ -0,0 +1,164 @@
+# Rockspec format
+
+For number fields, strings are accepted and converted using tonumber().
+
+## Package metadata
+
+* **rockspec_format** (string) - the file format version. Example: "1.0"
+* **package** (string, mandatory field) - the name of the package. Example: "LuaSocket"
+* **version** (string, mandatory field) - the version of the package, plus a suffix indicating the revision of the rockspec. Example: "2.0.1-1"
+* **description** (table)
+   * **description.summary** (string) - A one-line description of the package. Example: "Network support for the Lua language"
+   * **description.detailed** (string) - A longer description of the package. Example: "LuaSocket is a Lua extension library that is composed by two parts: a C core that provides support for the TCP and UDP transport layers, and a set of Lua modules that add support for functionality commonly needed by applications that deal with the Internet."
+   * **description.license** (string) - The license used by the package. A short name, such as "MIT" and "GPL-2" is preferred. Software using the same license as Lua 5.x should use "MIT".
+   * **description.homepage** (string) - An URL for the project. This is not the URL for the tarball, but the address of a website. Example: "http://github.com/keplerproject/rings"
+   * **description.issues_url** (string) (since 3.0) - An URL for the project's issue tracker. Example: "http://github.com/keplerproject/rings/issues"
+   * **description.maintainer** (string) - Contact information for the _rockspec_ maintainer (which may or may not be the package maintainer -- contact for the package maintainer can usually be obtained through the address in the homepage field). Example: "John Doe &lt;john@doe.gov&gt;"
+   * **description.labels** (array of strings) (since 3.0) - A list of short strings that specify labels for categorization of this rock. See the list of labels at [http://luarocks.org] for inspiration. Example: { "crypto", "network", "tls", "https" }
+
+## Dependency information
+
+Dependencies are represented in LuaRocks through strings with a package name followed by a comma-separated list of constraints. Each constraint consists of an operator and a version number. In this string format, version numbers are represented as naturally as possible, like they are used by upstream projects (e.g. "2.0beta3"). Internally, LuaRocks converts them to a purely numeric representation, allowing comparison following some common sense heuristics. The precise specification of the comparison criteria is the source code of the luarocks.deps module, but the test/test_deps.lua file included with LuaRocks provides some insights on what these criteria are.
+
+* **supported_platforms** (array of strings) - If this array is not present, the rock is assumed to be portable to any platform. If present, this should contain strings containing LuaRocks platform identifiers, optionally preceded by a "!" to indicate a negative match. If only negative entries are listed, the rock is assumed to be portable to any platform except those listed. If any positive entry exists, then at least one entry must match positively to the currently running platform. Currently supported LuaRocks platform identifiers are: "unix", "windows", "win32", "cygwin", "macosx", "linux", "freebsd". Platforms may have more than one valid identifier; e.g. Linux defines both "unix" and "linux". Note that, as of 0.6, Cygwin under Windows defines {"unix", "cygwin"} but *not* "windows".
+* **dependencies** (array of strings) - Each string represents a package this rock depends on, containing a package name followed by a comma-separated list of constraints. Example: `{"lfs >= 1.0, &lt; 2.0"}`. Accepted operators are the relational operators of Lua: `==` `~=` `<` `>` `<=` `>=` , as well as a special operator, `~>`, inspired by the "pessimistic operator" of RubyGems (`"~> 2"` means `">= 2, < 3"`; `"~> 2.4"` means `">= 2.4, < 2.5"`). The absence of an operator means an implicit `==` (i.e., `"lfs 1.0"` is the same as `"lfs == 1.0"`). "lua" is an special dependency name; it matches not a rock, but the version of Lua in use. Supports [per-platform overrides](platform-overrides).
+* **build_dependencies** (array of strings) (since 3.0) - Dependencies that apply at build-time only, but not when installing binary (`.<platform>.rock`) or pure-Lua (`.all.rock`) rocks. Each string represents a package this rock depends on at build time, containing a package name followed by a comma-separated list of constraints. The syntax in the same as the `dependencies` field. Supports [per-platform overrides](platform-overrides).
+* **external_dependencies** (table) - For each key in the external_dependencies table in the rockspec file, four variables available to the build rules are created: <i>key</i>_DIR, <i>key</i>_BINDIR, <i>key</i>_INCDIR and <i>key</i>_LIBDIR. These are not overwritten if already set (e.g. by the LuaRocks config file or through the command-line). The base prefix for these can be given explicitly setting <i>key</i>_DIR in the config file or through the command-line, or implicitly, defaulting to the value of default_external_deps_dir, set in the config file. Values in the external_dependencies table are tables that may contain a "header" or a "library" field, with filenames to be tested for existence. Example: `{ EXPAT = { header = "expat.h" } }` -- on Unix, this will check that EXPAT_DIR/include/expat.h exists and will create variables accordingly. You can also use platform overrides or specify files of external dependencies in a [platform-agnostic manner](platform-agnostic-external-dependencies). Supports [per-platform overrides](platform-overrides).
+* **test_dependencies** (array of strings) (since 3.0) - Dependencies that apply at test-time only, that is, only needed when running `luarocks test`. Each string represents a package this rock depends on at test time, containing a package name followed by a comma-separated list of constraints. The syntax in the same as the `dependencies` field. Supports [per-platform overrides](platform-overrides).
+
+## Build rules
+
+* **source** (table, mandatory field) - Contains information on how to fetch sources to build this rock. Supports [per-platform overrides](platform-overrides).
+   * **source.url** (string, mandatory field) - the URL of the package source archive. Examples: "http://github.com/downloads/keplerproject/wsapi/wsapi-1.3.4.tar.gz", "git://github.com/keplerproject/wsapi.git". Note that this field is ignored when running [luarocks make](luarocks_make.md), which uses the sources from your current directory instead. Different protocols are supported:
+      * `cvs://` - for the CVS source control manager
+      * `file://` - for URLs in the local filesystem (note that for Unix paths, the root slash is the third slash, resulting in paths like `"file:///full/path/filename"`
+      * `ftp://` - for FTP URLs
+      * `git://` - for the Git source control manager
+      * `git+file://` - for the Git source control manager when using repositories that need file:// URLs
+      * `git+http://` - for the Git source control manager when using repositories that need http:// URLs
+      * `git+https://` - for the Git source control manager when using repositories that need https:// URLs
+      * `git+ssh://` - for the Git source control manager when using repositories that need SSH login, such as `git@example.com/myrepo`
+      * `hg://` - for the Mercurial source control manager
+      * `hg+http://` - for the Mercurial source control manager using repositories that need http:// URLs
+      * `hg+https://` - for the Mercurial source control manager using repositories that need https:// URLs
+      * `hg+ssh://` - for the Mercurial source control manager using repositories that need SSH login
+      * `http://` - for HTTP URLs
+      * `https://` - for HTTPS URLs
+      * `hg://` - for the Mercurial source control manager
+      * `sscm://` - for the SurroundSCM source control manager
+      * `svn://` - for the Subversion source control manager
+   * **source.md5** (string) - the MD5 sum for the source archive. Example: "9ca22fd9f9413b54802d3d40b38c4e5c"
+   * **source.file** (string) - the filename of the source archive. Can be omitted if it can be inferred from the `source.url` field. Example: "luasocket-2.0.1.tar.gz"
+   * **source.dir** (string) - the name of the directory created when the source archive is unpacked. Can be omitted if it can be inferred from the `source.file` field. Example: "luasocket-2.0.1"
+   * **source.tag** (string) - for SCM-based URL protocols such as "cvs://" and "git://", this field can be used to specify a tag for checking out sources. Example: "HEAD" (For compatibility reasons, `source.cvs_tag` is also accepted.)
+   * **source.branch** (string) - for SCM-based URL protocols such as "git://", this field can be used to specify a branch for checking out sources. Example: "v1.0"
+   * **source.module** (string) - for SCM-based URL protocols such as "cvs://" and "git://", this field can be used to specify the module to be checked out. Can be omitted if it is the same as the basename of the `source.url` field. Example: "cgilua"  (For compatibility reasons, `source.cvs_module` is also accepted.)
+* **build** (table) - Contains all information pertaining _how_ to build a rock. Supports [per-platform overrides](platform-overrides).
+   * **build.type** (string) - The LuaRocks build back-end to use. Example: "make"
+   * **build.install** (table) - For packages which don't provide means to install modules and expect the user to copy the .lua or library files by hand to the proper locations. This table contains categories of files. Each category is itself a table, where the array part is a list of filenames to be copied. For module directories only, in the hash part, other keys are identifiers in Lua module format, to indicate which subdirectory the file should be copied to. For example, `build.install.lua = {["foo.bar"] = "src/bar.lua"}` will copy src/bar.lua to the foo directory under the rock's Lua files directory. The available categories are:
+      * **build.install.lua** (table) - Lua modules written in Lua. 
+      * **build.install.lib** (table) - Dynamic libraries implemented compiled Lua modules. 
+      * **build.install.conf** (table) - Configuration files.
+      * **build.install.bin** (table) - Lua command-line scripts.
+   * **build.copy_directories** (array of strings) (since 1.0) - A list of directories in the source directory to be copied to the rock installation prefix as-is. Useful for installing documentation and other files such as samples and tests. Default is {"doc"} for documentation to be locally installed in the rocktree.
+      * :warning: **Warning:** - do not use the following directory names: "lua", "lib", "rock_manifest" or the name of your rockspec; those names are used by the .rock format internally, and attempting to copy directories with those names using the build.copy_directories directive will cause a clash.
+   * **build.patches** (table) - A rockspec can embed patches in unified diff ("diff -u") format, which are applied prior to building the modules. Each entry in this table should contain a descriptive file name for the patch a the key, and the text of the patch as the value (typically, as a long string). The patch is applied from within the source.dir directory, and file names ignore the first directory level (in other word, patches are applied with the equivalent of "patch -p 1"). Keep in mind that the actual text of the patch cannot be indented. Example: 
+```
+patches = {
+   ["lua51-support.diff"] = [[
+--- old/mymodule.c....
+]]
+}
+```
+
+### Build back-ends
+
+Build back-ends indicate how to build a package. 
+Fields of the `build` table other than `build.type`, `build.platforms` and `build.install` are specific to the given type. 
+
+#### builtin
+
+This is a mode for packages distributing pure Lua or simple C modules. All pathnames used are relative to `source.dir`. The goal is to allow module authors to specify compilation of their C code in a clean, simple and portable way.
+
+* **build.modules** (array) - An array in which keys are module names in the format normally used by the require() function, and values may be:
+   * strings - pathnames of Lua files or C sources, for modules based on a single source file.
+   * array of strings - pathnames of C sources of a simple module written in C composed of multiple files.
+   * table - a table containing one or more fields:
+      * **build.sources** (array of strings) - the only mandatory field, pathnames of C sources.
+      * **build.libraries** (array of strings) - external libraries to be linked.
+      * **build.defines** (array of strings) - a list of C defines. eg. { "FOO=bar", "USE_BLA" }
+      * **build.incdirs** (array of strings) - directories to be added to the compiler's headers lookup directory list.
+      * **build.libdirs** (array of strings) - directories to be added to the linker's library lookup directory list.
+
+#### make
+
+Indicates the package uses a Makefile.
+
+   * **build.makefile** (string) - Makefile to be used. Default is "Makefile" on Unix variants and "Makefile.win" under Win32.
+   * **build.build_target** (string) - Default is "".
+   * **build.build_pass** (boolean) - Whether to perform a make pass on the target indicated by `build.build_target`. Default is true (i.e., to run make).
+   * **build.install_target** (string) - Default is "install".
+   * **build.install_pass** (boolean) - Whether to perform a make pass on the target indicated by `build.build_target`. Default is true (i.e., to run make).
+   * **build.build_variables** (table) - Assignments to be passed to make during the build pass. Default is {}.
+   * **build.install_variables** (table) - Assignments to be passed to make during the install pass. Default is {}.
+   * **build.variables** (table) - Assignments to be passed to make on both passes. Default is {}.
+
+Variables expected by this back-end to be provided by the configuration file are:
+
+   * **CC** - Command to call the C compiler.
+   * **CFLAGS** - Flags to be passed to the C compiler. May be empty.
+   * **LIBFLAG** - Flag to be passed to the C compiler to instruct it to build a shared library.
+
+These are usually detected by the default configuration, but can be overridden
+by the [configuration file](config-file-format). See also the "Variables"
+section of the [Config file format](config_file_format.md) specification for
+other path variables that are defined automatically, and the documentation on
+the `external_dependencies` entry above for variables that are automatically
+generated based on paths of external dependencies.
+
+#### cmake
+
+Indicates the package uses CMake for building.
+
+* **build.cmake** (string) - If given, its contents are used as the CMakeLists.txt file. If not given, it is assumed that the package provides a CMakeLists.txt file.
+* **build.variables** (table) - Additional variables to be passed to CMake. Equals to calling CMake with attributes: `cmake -Dkey1=value1 -Dkey2=value2 ...`
+
+Additionally you can specify these environment variables when calling LuaRocks:
+
+   * **CMAKE_MODULE_PATH** - Tells CMake where to search for additional modules.
+   * **CMAKE_INCLUDE_PATH** - Path to desired include directory.
+   * **CMAKE_LIBRARY_PATH** - Path to libraries.
+
+#### command
+
+A simple backend called "command" is also provided, in which build commands are typed in directly in the rockspec file.
+
+* **build.build_command** (string) - Command to run to build the package.
+* **build.install_command** (string) - Command to run to install the package.
+
+#### none
+
+A null build back-end. Indicates that there is no build to perform.
+
+## Test rules
+
+* **test** (table) - Contains all information pertaining how to test a rock. Supports [per-platform overrides](platform-overrides).
+
+### Test back-ends
+
+Test back-ends indicate how to test a package. 
+Fields of the `test` table other than `test.type` and `test.platforms` are specific to the given type. 
+
+#### busted
+
+If `test.type` is not specified, this type is auto-detected if `.busted` is present in the root of the source tree.
+
+* **test.flags** (array of string) - Additional CLI flags to pass to Busted when running.
+
+#### command
+
+If `test.type` is not specified, this type is auto-detected if a file called `test.lua` is present in the root of the source tree.
+
+* **test.script** (string) - Filename of a Lua script to run as a test. Only one of `script` or `command` should be passed.
+* **test.command** (string) - Filename of a shell command to run as a test. Only one of `script` or `command` should be passed.
+* **test.flags** (array of string) - Additional CLI flags to pass to either the script or command when running.
diff --git a/docs/tools/docs.tl b/docs/tools/docs.tl
new file mode 100644
index 00000000..502de3c4
--- /dev/null
+++ b/docs/tools/docs.tl
@@ -0,0 +1,74 @@
+local lfs = require("lfs")
+
+local args = {...}
+
+if not args[1] then
+   print("missing argument: <dirname>")
+   os.exit(1)
+end
+
+local dirname = args[1]
+
+local function path(filename: string): string
+   return dirname .. "/" .. filename
+end
+
+local function process_md(filename: string)
+   local data = assert(io.open(path(filename))):read("*a")
+   local missing = {}
+   for link in data:gmatch("%]%(([^)]*%.md)[^)]*%)") do
+      if not lfs.attributes(path(link)) then
+         table.insert(missing, { at = filename, link = link })
+      end
+   end
+   
+   if #missing == 0 then
+      return
+   end
+   
+   print("Broken links:")
+
+   for _, link in ipairs(missing) do
+      print("* At " .. link.at .. " : " .. link.link)
+   end
+
+   os.exit(1)
+end 
+
+local function check_index(filename: string, all_pages: {string: boolean})
+   local data = assert(io.open(path(filename))):read("*a")
+   for link in data:gmatch("%]%(([^)]*%.md)[^)]*%)") do
+      all_pages[link] = nil
+   end
+   
+   if not next(all_pages) then
+      return
+   end
+   
+   local missing = {}
+   for k, _ in pairs(all_pages) do
+      table.insert(missing, k)
+   end
+   table.sort(missing)
+   
+   print("Pages not referenced in index:")
+
+   for _, page in ipairs(missing) do
+      print("* " .. page)
+   end
+
+   os.exit(1)
+end 
+
+local all_pages = {}
+for f in lfs.dir(args[1]) do
+   if f:match("%.md$") then
+      process_md(f)
+      all_pages[f] = true
+   end
+end
+
+check_index("index.md", all_pages)
+
+print("All ok!")
+
diff --git a/docs/tools/lfs.d.tl b/docs/tools/lfs.d.tl
new file mode 100644
index 00000000..12535ca4
--- /dev/null
+++ b/docs/tools/lfs.d.tl
@@ -0,0 +1,82 @@
+local record lfs
+
+   enum FileMode
+      "file"
+      "directory"
+      "link"
+      "socket"
+      "named pipe"
+      "char device"
+      "block device"
+      "other"
+   end
+
+   record Attributes
+      dev: number
+      ino: number
+      mode: FileMode
+      nlink: number
+      uid: number
+      gid: number
+      rdev: number
+      access: number
+      modification: number
+      change: number
+      size: number
+      permissions: string
+      blocks: number
+      blksize: number
+   end
+
+   enum OpenFileMode
+      "binary"
+      "text"
+   end
+
+   enum LockMode
+      "r"
+      "w"
+   end
+
+   record Lock
+      free: function()
+   end
+
+   dir: function(string): function(): string
+
+   chdir: function(string): boolean, string
+
+   lock_dir: function(string, number): Lock, string
+
+   -- returns number on success, really!? this should be fixed in the lfs library
+   link: function(string, string, boolean): number, string
+
+   mkdir: function(string): boolean, string
+
+   rmdir: function(string): boolean, string
+
+   setmode: function(string, OpenFileMode): boolean, string
+
+   currentdir: function(): string
+
+   attributes: function(string): Attributes
+   attributes: function(string, string): string
+   attributes: function(string, string): number
+   attributes: function(string, string): FileMode
+   attributes: function(string, Attributes): Attributes
+
+   symlinkattributes: function(string): Attributes
+   symlinkattributes: function(string, string): string
+   symlinkattributes: function(string, string): number
+   symlinkattributes: function(string, string): FileMode
+   symlinkattributes: function(string, Attributes): Attributes
+
+   touch: function(string, number, number): boolean, string
+
+   -- TODO: FILE needs to be renamed to io.FILE in tl itself
+   lock: function(FILE, LockMode, number, number): boolean, string
+   unlock: function(FILE, number, number): boolean, string
+
+end
+
+return lfs
diff --git a/docs/types_of_rocks.md b/docs/types_of_rocks.md
new file mode 100644
index 00000000..7e69253d
--- /dev/null
+++ b/docs/types_of_rocks.md
@@ -0,0 +1,32 @@
+# Types of rocks
+
+A **rock** is a bundle containing a specification file (called a "rockspec")
+and files providing Lua modules.
+
+A **[rockspec](rockspec_format.md)** is a Lua file containing a series of
+assignments to variables that provide various information about the rock, such
+as description metadata, dependency relations and build rules. Rocks are
+created from rockspecs.
+
+When packed, a rock is an archive file in ZIP format, with the .rock filename
+extension. When installed, a rock is unpacked into a directory in the local
+rocks repository.
+
+There are several types of rocks, and when packed they are identified by their
+filename extensions. These are:
+
+* Source rocks (`.src.rock`): these contain the rockspec and the source code
+  for the Lua modules provided by the rock. When installing a source rock, the
+  source code needs to be compiled.
+
+* Binary rocks (`_.system-arch_.rock`: `.linux-x86.rock,
+  .macosx-powerpc.rock`): these contain the rockspec and modules in compiled
+  form. Modules written in Lua may be in source .lua format, but modules
+  compiled as C dynamic libraries are compiled to their platform-specific
+  format.
+
+* Pure-Lua rocks (`.all.rock`): these contain the rockspec and the Lua modules
+  they provide in .lua format. These rocks are directly installable without a
+  compilation stage and are platform-independent.
+
+
diff --git a/docs/using_luarocks.md b/docs/using_luarocks.md
new file mode 100644
index 00000000..c65ef432
--- /dev/null
+++ b/docs/using_luarocks.md
@@ -0,0 +1,198 @@
+# Using LuaRocks
+
+So, you have followed the installation instructions (either on
+[Unix](installation_instructions_for_unix.md) or
+[Windows](installation_instructions_for_windows.md)) and now you have LuaRocks
+installed on your machine. Now you probably want to install some rocks
+(packages containing Lua modules) and use them in your Lua code. 
+
+For LuaRocks to function properly, we have a quick checklist to go through
+first:
+
+# Command-line tools (and the system path) 
+
+LuaRocks installs some command-line tools which are your interface for
+managing your rocks: [luarocks](luarocks.md) and
+[luarocks-admin](luarocks_admin.md). Make sure the directory where they are
+located is in your PATH -- the exact location depends on the flags you gave
+when installing LuaRocks.
+
+Run [luarocks](luarocks.md) to see the available commands:
+
+```
+luarocks 
+```
+
+You can get help on any command by using the [luarocks help](luarocks_help.md) command:
+
+```
+luarocks help install
+```
+
+Installing packages is done by typing commands such as:
+
+```
+luarocks install dkjson
+```
+
+# Rocks trees and the Lua libraries path 
+
+When you install rocks using the `luarocks install`, you get new modules
+available for loading via `require()` from Lua. For example, after we install
+the dkjson rock, type `luarocks show dkjson` to show the module installed by
+the rock:
+
+```
+luarocks show dkjson
+```
+
+This should output something like this:
+
+```
+dkjson 2.5-2 - David Kolf's JSON module for Lua
+  
+dkjson is a module for encoding and decoding JSON data. It supports UTF-8.
+  
+JSON (JavaScript Object Notation) is a format for serializing data based on the
+syntax for JavaScript data structures.
+  
+dkjson is written in Lua without any dependencies, but when LPeg is available
+dkjson uses it to speed up decoding.
+  
+License:        MIT/X11
+Homepage:       http://dkolf.de/src/dkjson-lua.fsl/
+Installed in:   /usr/local
+  
+Modules:
+        dkjson (/usr/local/share/lua/5.3/dkjson.lua)
+```
+
+It presents a short description of the rock, its license, and the list of
+modules it provides (in this case, only one, `dkjson`). Note that "Installed
+in:" shows the directory tree where the rock was installed. This is the "rocks
+tree" in use.
+
+Most LuaRocks installations will feature two rocks trees:
+
+* "system" [rock tree](rocks_repositories.md) (used by default)
+* "user" [rock tree](rocks_repositories.md)
+
+To be able to use the module, we need to make sure that Lua can find that
+dkjson.lua file when we run `require("dkjson")`. You can check your Lua paths
+from the Lua environment, using
+
+```
+print(package.path)
+print(package.cpath)
+```
+
+These variables can be pre-configured from outside Lua, using the LUA_PATH and
+LUA_CPATH environment variables. 
+
+If you installed both Lua and LuaRocks in their default directories
+(/usr/local on Linux and Mac OSX), then the "system" tree is /usr/local and it
+will work by default. However, the "user" tree (for installing rocks without
+admin privileges) is not detected by Lua by default. For that we'll need to
+configure these environment variables.
+
+LuaRocks offers a semi-automated way to do this. If you type the following
+command:
+
+```
+luarocks path --bin
+```
+
+...it will print commands suitable for your platform for setting up your
+environment. On typical Unix terminal environments, you can type this:
+
+```
+eval "$(luarocks path --bin)"
+```
+
+and it apply the changes, temporarily, to your shell. To have these variables
+set permanently, you have to configure the environment variables to your shell
+configuration (for example, by adding the above line to your `.bashrc` file if
+your shell is Bash).
+
+# Multiple versions using the LuaRocks package loader 
+
+If you want to make use of LuaRocks' support for multiple installed versions
+of modules, you need to load a custom package loader: luarocks.loader.
+
+You should be able to launch the Lua interpreter with the LuaRocks-enabled
+loader by typing:
+
+```
+lua -lluarocks.loader
+```
+
+Alternatively, you can load the LuaRocks module loader from Lua by issuing
+this command:
+
+```
+require "luarocks.loader"
+```
+
+If your system is correctly set up so that this command runs with no errors,
+subsequent calls to `require()` are LuaRocks-aware and the exact version of
+each module will be determined based on the dependency tree of previously
+loaded modules. 
+
+# Scripts installed by rocks (and the scripts path) 
+
+Besides modules, rocks can also install command-line scripts. The default
+location of this directory (unless you configured your local repository
+differently) is /usr/local/bin for system-wide installs and ~/.luarocks/bin
+for per-user installs on Unix and %APPDATA%/luarocks/bin on Windows -- make
+sure it is in your PATH as well.
+
+If you use the `--bin` argument in `luarocks path`, it will also print the
+appropriate PATH configuration:
+
+```
+luarocks path --bin
+```
+
+# Using in Unix systems with sudo 
+
+When you use LuaRocks to install a package while you aren't root, the package
+will get installed in $HOME/.luarocks/ instead of the system-wide (by default,
+/usr/local/) and become only available for you. Moreover Lua doesn't know with
+its default setup that packages can be available in the current user's home.
+If you want to install a package available for all users, you should run it as
+superuser, typically using sudo.
+
+For example:
+
+```
+sudo luarocks install stdlib
+```
+
+After that, some files may not have correct permissions. For example, if
+/usr/local/share/lua/5.1/base.lua is only readable by root user, you should at
+least set them to readable for all users (chmod a+r or chmod 644).
+
+For example:
+
+```
+cd /usr/local/share/lua/5.1
+ sudo chmod a+r *
+```
+
+# Using a C compiler 
+
+Because rocks are generally available in the repository as [source
+rocks](types_of_rocks.md) rather than binary rocks, it is best to have a C
+compiler available.
+
+On Windows, MinGW and Microsoft compilers are supported. The compiler should
+be in the system path, or explicitly configured in the LuaRocks config files.
+On Windows systems, one way of getting the compiler in the system path is to
+open the appropriate command prompt as configured by your compiler package
+(for example, the MSVC Command Prompt for Visual Studio).
+
+Note that for compiling binary rocks that have dependencies on other
+libraries, LuaRocks needs to be able to find [external
+dependencies](paths_and_external_dependencies.md).
+
+
diff --git a/docs/welcome.md b/docs/welcome.md
new file mode 100644
index 00000000..300f740e
--- /dev/null
+++ b/docs/welcome.md
@@ -0,0 +1,17 @@
+<p align="center"><img src="http://luarocks.github.io/luarocks/luarocks.png" width="500px"/></p>
+
+This is **LuaRocks**, the package manager for the Lua programming language.
+
+LuaRocks allows you to install Lua modules as self-contained packages called
+**[rocks](types_of_rocks.md)**. LuaRocks supports both local and remote
+repositories, and multiple local rocks trees.
+
+LuaRocks is free software and uses the same [license](license.md) as Lua.
+
+## Quick start
+
+* [Download](download.md)
+* [Using LuaRocks](using_luarocks.md)
+* [Creating a rock](creating_a_rock.md)
+
+For more information, check the full [documentation index](index.md).