diff --git a/doc/manual.xml b/doc/manual.xml
index b067549e8fdf..a16b783af310 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -31,6 +31,7 @@
+
diff --git a/doc/meta.xml b/doc/meta.xml
new file mode 100644
index 000000000000..5e53609a2368
--- /dev/null
+++ b/doc/meta.xml
@@ -0,0 +1,200 @@
+
+
+Meta-attributes
+
+Nix packages can declare meta-attributes
+that contain information about a package such as a description, its
+homepage, its license, and so on. For instance, the GNU Hello package
+has a meta declaration like this:
+
+
+meta = {
+ description = "A program that produces a familiar, friendly greeting";
+ longDescription = ''
+ GNU Hello is a program that prints "Hello, world!" when you run it.
+ It is fully customizable.
+ '';
+ homepage = http://www.gnu.org/software/hello/manual/;
+ license = "GPLv3+";
+};
+
+
+
+
+Meta-attributes are not passed to the builder of the package.
+Thus, a change to a meta-attribute doesn’t trigger a recompilation of
+the package. The value of a meta-attribute must a string.
+
+The meta-attributes of a package can be queried from the
+command-line using nix-env:
+
+
+$ nix-env -qa hello --meta --xml
+<?xml version='1.0' encoding='utf-8'?>
+<items>
+ <item attrPath="hello" name="hello-2.3" system="i686-linux">
+ <meta name="description" value="A program that produces a familiar, friendly greeting" />
+ <meta name="homepage" value="http://www.gnu.org/software/hello/manual/" />
+ <meta name="license" value="GPLv3+" />
+ <meta name="longDescription" value="GNU Hello is a program that prints "Hello, world!" when you run it.
It is fully customizable.
" />
+ </item>
+</items>
+
+
+nix-env knows about the
+description field specifically:
+
+
+$ nix-env -qa hello --description
+hello-2.3 A program that produces a familiar, friendly greeting
+
+
+
+
+
+Standard meta-attributes
+
+The following meta-attributes have a standard
+interpretation:
+
+
+
+
+ description
+ A short (one-line) description of the package.
+ Don’t include a period at the end. This is shown by
+ nix-env -q --description and also on the
+ Nixpkgs release pages. Example: "A program that produces
+ a familiar, friendly greeting"
+
+
+
+ longDescription
+ An arbitrarily long description of the
+ package.
+
+
+
+ homepage
+ The package’s homepage. Example:
+ http://www.gnu.org/software/hello/manual/
+
+
+
+ license
+ The license for the package. See below for the
+ allowed values.
+
+
+
+ priority
+ The priority of the package,
+ used by nix-env to resolve file name conflicts
+ between packages. See the Nix manual page for
+ nix-env for details. Example:
+ "10" (a low-priority
+ package).
+
+
+
+
+
+
+
+
+Licenses
+
+This is just a first attempt at standardising the license
+attribute.
+
+The meta.license attribute must be one of the
+following:
+
+
+
+
+ GPL
+ GNU General Public License; version not
+ specified.
+
+
+
+ GPLv2
+ GNU General Public License, version
+ 2.
+
+
+
+ GPLv2+
+ GNU General Public License, version
+ 2 or higher.
+
+
+
+ GPLv3
+ GNU General Public License, version
+ 3.
+
+
+
+ GPLv3+
+ GNU General Public License, version
+ 3 or higher.
+
+
+
+ free
+ Catch-all for free software licenses not listed
+ above.
+
+
+
+ free-copyleft
+ Catch-all for free, copyleft software licenses not
+ listed above.
+
+
+
+ unfree-redistributable
+ Unfree package that can be redistributed in binary
+ form. That is, it’s legal to redistribute the
+ output of the derivation. This means that
+ the package can be included in the Nixpkgs
+ channel.
+
+ Sometimes proprietary software can only be redistributed
+ unmodified. Make sure the builder doesn’t actually modify the
+ original binaries; otherwise we’re breaking the license. For
+ instance, the NVIDIA X11 drivers can be redistributed unmodified,
+ but our builder applies patchelf to make them
+ work. Thus, its license is unfree and it
+ cannot be included in the Nixpkgs channel.
+
+
+
+ unfree
+ Unfree package that cannot be redistributed. You
+ can build it yourself, but you cannot redistribute the output of
+ the derivation. Thus it cannot be included in the Nixpkgs
+ channel.
+
+
+
+ unfree-redistributable-firmware
+ This package supplies unfree, redistributable
+ firmware. This is a separate value from
+ unfree-redistributable because not everybody
+ cares whether firmware is free.
+
+
+
+
+
+
+
+
+
+
+