diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml
index 33c6e767ba..548ce1cab8 100644
--- a/doc/manual/bugs.xml
+++ b/doc/manual/bugs.xml
@@ -15,6 +15,23 @@
+
+
+ Unify the concepts of successors and substitutes into a general notion
+ of equivalent expressions. Expressions are
+ equivalent if they have the same target paths with the same
+ identifiers. However, even though they are functionally equivalent,
+ they may differ stronly with respect to their performance
+ characteristics. For example, realising a slice is more
+ efficient that realising the derivation from which that slice was
+ produced. On the other hand, distributing sources may be more
+ efficient (storage- or bandwidth-wise) than distributing binaries. So
+ we need to be able to attach weigths or priorities or performance
+ annotations to expressions; Nix can then choose the most efficient
+ expression dependent on the context.
+
+
+
diff --git a/doc/manual/nix-reference.xml b/doc/manual/nix-reference.xml
index 39c83518c3..75009b1d04 100644
--- a/doc/manual/nix-reference.xml
+++ b/doc/manual/nix-reference.xml
@@ -126,6 +126,8 @@
+
+
Operation <option>--install</option>
@@ -162,6 +164,8 @@
+
+
Operation <option>--delete</option>
@@ -203,6 +207,216 @@
+
+
+
+ Operation <option>--query</option>
+
+
+ Synopsis
+
+ nix
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ args
+
+
+
+
+ Description
+
+
+ The operation displays various bits of
+ information about Nix expressions or paths in the store. The queries
+ are described in . At most one query
+ can be specified; the default query is .
+
+
+
+
+
+ Queries
+
+
+
+
+
+
+
+ Prints out the target paths of the Nix expressions indicated by
+ the identifiers args. In the case of
+ a derivation expression, these are the paths that will be
+ produced by the builder of the expression. In the case of a
+ slice expression, these are the root paths (which are generally
+ the paths that were produced by the builder of the derivation
+ expression of which the slice is a normal form).
+
+
+
+ This query has one option:
+
+
+
+
+
+
+
+
+ Causes the target paths of the normal
+ forms of the expressions to be printed, rather
+ than the target paths of the expressions themselves.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Prints out the requisite paths of the Nix expressions indicated
+ by the identifiers args. The
+ requisite paths of a Nix expression are the paths that need to be
+ present in the system to be able to realise the expression. That
+ is, they form the closure of the expression
+ in the file system (i.e., no path in the set of requisite paths
+ points to anything outside the set of requisite paths).
+
+
+
+ The notion of requisite paths is very useful when one wants to
+ distribute Nix expressions. Since they form a closure, they are
+ the only paths one needs to distribute to another system to be
+ able to realise the expression on the other system.
+
+
+
+ This query is generally used to implement various kinds of
+ distribution. A source distribution is
+ obtained by distributing the requisite paths of a derivation
+ expression. A binary distribution is
+ obtained by distributing the requisite paths of a slice
+ expression (i.e., the normal form of a derivation expression; you
+ can directly specify the identifier of the slice expression, or
+ use and specify the identifier of a
+ derivation expression). A cache
+ distribution is obtained by distributing the
+ requisite paths of a derivation expression and specifying the
+ option . This will include
+ not just the paths of a source and binary distribution, but also
+ all expressions and paths of subterms of the source. This is
+ useful if one wants to realise on the target system a Nix
+ expression that is similar but not quite the same as the one
+ being distributed, since any common subterms will be reused.
+
+
+
+ This query has a number of options:
+
+
+
+
+
+
+
+
+ Causes the requisite paths of the normal
+ forms of the expressions to be printed, rather
+ than the requisite paths of the expressions themselves.
+
+
+
+
+
+
+
+
+ Excludes the paths of Nix expressions. This causes the
+ closure property to be lost, that is, the resulting set of
+ paths is not enough to ensure realisibility.
+
+
+
+
+
+
+
+
+ Also include the requisites of successors (normal forms).
+ Only the requisites of known
+ successors are included, i.e., the normal forms of
+ derivation expressions that have never been normalised will
+ not be included.
+
+
+
+ Note that not just the successor of a derivation expression
+ will be included, but also the successors of all input
+ expressions of that derivation expression. I.e., all
+ normal forms of subterms involved in the normalisation of
+ the top-level term are included.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ For each identifier in args, prints
+ all expansions of that identifier, that is, all paths whose
+ current content matches the identifier.
+
+
+
+
+
+
+
+
+ Prints a graph of the closure of the expressions identified by
+ args in the format of the
+ dot tool of AT&T's GraphViz package.
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml
index 018b3555fc..6c40775dbe 100644
--- a/doc/manual/troubleshooting.xml
+++ b/doc/manual/troubleshooting.xml
@@ -35,8 +35,7 @@
- $ rm `db_archive -a -h
- prefix/var/nix/db`
+ $ rm `db_archive -a -h prefix/var/nix/db`