diff --git a/readme.markdown b/readme.markdown
index 16e6d66..0cd604d 100644
--- a/readme.markdown
+++ b/readme.markdown
@@ -95,6 +95,10 @@ created instead.
 
 Other files will be copied in the same way as they are for library packages.
 
+Binary packages should not install .nim files so you should include
+``SkipExt = "nim"`` in your .babel file, unless you intend for your package to
+be a binary/library combo which is fine.
+
 Dependencies are automatically installed before building.
 
 ## Dependencies
@@ -114,6 +118,57 @@ greater-than (``>``), less-than-or-equal-to (``<=``) and greater-than-or-equal-t
 ``> 0.2 & < 1.0`` which will install a package with the version greater than 0.2
 and less than 1.0.
 
+## .babel reference
+
+### [Package]
+
+#### Required
+
+* ``name`` - The name of the package.
+* ``version`` - The *current* version of this package. This should be incremented
+  after tagging the current version using ``git tag``.
+* ``author`` - The name of the author of this package.
+* ``description`` - A string describing the package.
+* ``license`` - The name of the license in which this package is licensed under.
+
+#### Optional
+
+* ``SkipDirs`` - A list of directory names which should be skipped during
+  installation, separated by commas.
+* ``SkipFiles`` - A list of file names which should be skipped during
+  installation, separated by commas.
+* ``SkipExt`` - A list of file extensions which should be skipped during
+  installation, the extensions should be specified without a leading ``.`` and
+  should be separated by commas.
+* ``InstallDirs`` - A list of directories which should exclusively be installed,
+  if this option is specified nothing else will be installed except the dirs
+  listed here, the files listed in ``InstallFiles``, the files which share the
+  extensions listed in ``InstallExt``, the .babel file and the binary
+  (if ``bin`` is specified). Separated by commas.
+* ``InstallFiles`` - A list of files which should be exclusively installed,
+  this complements ``InstallDirs`` and ``InstallExt``. Only the files listed
+  here, directories listed in ``InstallDirs``, files which share the extension
+  listed in ``InstallExt``, the .babel file and the binary (if ``bin`` is
+  specified) will be installed. Separated by commas.
+* ``InstallExt`` - A list of file extensions which should be exclusively
+  installed, this complements ``InstallDirs`` and ``InstallFiles``.
+  Separated by commas.
+* ``srcDir`` - Specifies the directory which contains the .nim source files.
+  **Default**: The directory in which the .babel file resides; i.e. root dir of
+  package.
+* ``bin`` - A list of files which should be built separated by commas with
+  no file extension required. This option turns your package into a *binary
+  package*, babel will build the files specified and install them appropriately.
+
+### [Deps]/[Dependencies]
+
+#### Optional
+
+* ``requires`` - Specified a list of package names with an optional version
+  range separated by commas.
+  **Example**: ``nimrod >= 0.9.2, jester``; with this value your package will
+  depend on ``nimrod`` version 0.9.2 or greater and on any version of ``jester``.
+
 ## Submitting your package to the package list.
 Babel's packages list is stored on github and everyone is encouraged to add
 their own packages to it! Take a look at