4 files changed, 82 insertions, 7 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index 082c034f195a..58712d785ea8 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -18,7 +18,8 @@ MANUAL_SRCS = manual.xml introduction.xml installation.xml \
  build-farm.xml \
  $(man1_MANS:.1=.xml) \
  troubleshooting.xml bugs.xml opt-common.xml opt-common-syn.xml \
- env-common.xml quick-start.xml nix-lang-ref.xml style.css images
+ env-common.xml quick-start.xml nix-lang-ref.xml glossary.xml \
+ style.css images
 
 manual.is-valid: $(MANUAL_SRCS) version.txt
 	$(XMLLINT) --xinclude $< | $(XMLLINT) --noout --valid -
diff --git a/doc/manual/glossary.xml b/doc/manual/glossary.xml
new file mode 100644
index 000000000000..2c4f55c7e7f0
--- /dev/null
+++ b/doc/manual/glossary.xml
@@ -0,0 +1,79 @@
+<appendix><title>Glossary</title>
+
+<glosslist>
+
+
+<glossentry><glossterm>derivation</glossterm>
+
+  <glossdef><para>A description of a build action.  The result of a
+  derivation is a store object.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry><glossterm>store</glossterm>
+
+  <glossdef><para>The location in the file system where store objects
+  live.  Typically <filename>/nix/store</filename>.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry><glossterm>store path</glossterm>
+
+  <glossdef><para>The location in the file system of a store object,
+  i.e., an immediate child of the Nix store
+  directory.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry><glossterm>store object</glossterm>
+
+  <glossdef><para>A file that is an immediate child of the Nix store
+  directory.  These can be regular files, but also entire directory
+  trees.  Store objects can be sources (objects copied from outside of
+  the store), derivation outputs (objects produced by running a build
+  action), or derivations (files describing a build
+  action).</para></glossdef>
+
+</glossentry>
+
+
+<glossentry><glossterm>substitute</glossterm>
+
+  <glossdef><para>A substitute is a command invocation stored in the
+  Nix database that describes how to build a store object, bypassing
+  normal the build mechanism (i.e., derivations).  Typically, the
+  substitute builds the store object by downloading a pre-built
+  version of the store object from some server.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry><glossterm>purity</glossterm>
+
+  <glossdef><para>The assumption that equal Nix derivations when run
+  always produce the same output.  This cannot be guaranteed in
+  general (e.g., a builder can rely on external inputs such as the
+  network or the system time) but the Nix model assumes
+  it.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry><glossterm>Nix expression</glossterm>
+
+  <glossdef><para>A high-level description of software components and
+  compositions thereof.  Deploying software using Nix entails writing
+  Nix expressions for your components.  Nix expressions are translated
+  to derivations that are stored in the Nix store.  These derivations
+  can then be built.</para></glossdef>
+
+</glossentry>
+
+
+</glosslist>
+
+
+</appendix>
\ No newline at end of file
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index 244c4ca23881..9f0e4ae94c50 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -69,5 +69,6 @@
 
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="troubleshooting.xml" />
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="bugs.xml" />
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="glossary.xml" />
 
 </book>
diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml
index 529943f91fa6..cc3cd361f8b5 100644
--- a/doc/manual/troubleshooting.xml
+++ b/doc/manual/troubleshooting.xml
@@ -6,9 +6,3 @@
   </para>
 	
 </appendix>
-
-<!--
-local variables:
-sgml-parent-document: ("book.xml" "appendix")
-end:
--->