Add documentation for Idris Packages.

This is an initial copy and refinement of the existing documentation for packaging.
This commit also starts the Idris2 reference documentation, in which we can start documenting the language proper. Maybe we should include the contents of `Notes` here, but that is a question for later.

docs/index.rst

@@ -21,3 +21,4 @@ This is a placeholder, to get set up with readthedocs.
    :maxdepth: 1
 
    faq/faq
+   reference/index

docs/reference/index.rst

@@ -0,0 +1,19 @@
+**********************
+Idris2 Reference Guide
+**********************
+
+.. note::
+
+   The documentation for Idris 2 has been published under the Creative
+   Commons CC0 License. As such to the extent possible under law, *The
+   Idris Community* has waived all copyright and related or neighboring
+   rights to Documentation for Idris.
+
+   More information concerning the CC0 can be found online at: http://creativecommons.org/publicdomain/zero/1.0/
+
+This is a placeholder, to get set up with readthedocs.
+
+.. toctree::
+   :maxdepth: 1
+
+   packages

docs/reference/packages.rst

@@ -0,0 +1,102 @@
+.. _ref-sect-packages:
+
+********
+Packages
+********
+
+Idris includes a simple system for building packages from a package
+description file.  These files can be used with the Idris compiler to
+manage the development process of your Idris programmes and packages.
+
+Package Descriptions
+====================
+
+A package description includes the following:
+
++ A header, consisting of the keyword package followed by the package
+  name. Package names can be any valid Idris identifier. The iPKG
+  format also takes a quoted version that accepts any valid filename.
++ Fields describing package contents, ``<field> = <value>``
+
+At least one field must be the modules field, where the value is a
+comma separated list of modules.  For example, a library test which
+has two modules ``Foo.idr`` and ``Bar.idr`` as source files would be
+written as follows::
+
+    package test
+
+    modules = Foo, Bar
+
+Other examples of package files can be found in the ``libs`` directory
+of the main Idris repository, and in `third-party libraries <https://github.com/idris-lang/Idris-dev/wiki/Libraries>`_.
+
+Metadata
+--------
+
+The `iPKG` format supports additional metadata associated with the package.
+The added fields are:
+
++ ``brief = "<text>"``, a string literal containing a brief description
+  of the package.
+
++ ``version = "<text>""``, a version string to associate with the package.
+
++ ``readme = "<file>""``, location of the README file.
+
++ ``license = "<text>"``, a string description of the licensing
+  information.
+
++ ``authors = "<text>"``, the author information.
+
++ ``maintainers = "<text>"``, Maintainer information.
+
++ ``homepage = "<url>"``, the website associated with the package.
+
++ ``sourceloc = "<url>"``, the location of the DVCS where the source
+  can be found.
+
++ ``bugtracker = "<url>"``, the location of the project's bug tracker.
+
+
+Common Fields
+-------------
+
+Other common fields which may be present in an ``ipkg`` file are:
+
++ ``executable = <output>``, which takes the name of the executable
+  file to generate. Executable names can be any valid Idris
+  identifier. the iPKG format also takes a quoted version that accepts
+  any valid filename.
+
++ ``main = <module>``, which takes the name of the main module, and
+  must be present if the executable field is present.
+
++ ``opts = "<idris options>"``, which allows options to be passed to
+  Idris.
+
++ ``depends = <pkg name> (',' <pkg name>)+``, a comma separated list of
+  package names that the Idris package requires.
+
+
+Comments
+---------
+
+Package files support comments using the standard Idris singleline ``--`` and multiline ``{- -}`` format.
+
+Using Package files
+===================
+
+Given an Idris package file ``test.ipkg`` it can be used with the Idris compiler as follows:
+
++ ``idris2 --build test.ipkg`` will build all modules in the package
+
++ ``idris2 --install test.ipkg`` will install the package, making it
+  accessible by other Idris libraries and programs.
+
++ ``idris2 --clean test.ipkg`` will clean the intermediate build files.
+
+Once the test package has been installed, the command line option
+``--package test`` makes it accessible (abbreviated to ``-p test``).
+For example::
+
+    idris -p test Main.idr