doc: Explain what's special about the (gnu packages ...) name space.

* doc/guix.texi (Invoking guix package): Explain where packages are
  searched for and link to "Package Modules".
  (Defining Packages) <example>: Use 'define-module' clause instead of
  'use-modules'.  Explain why and link to "Package Modules".
  (Invoking guix build): Explain where packages aer searched for and
  link to "Package Modules".
  (Package Modules): Explain that (gnu packages ...) is scanned.

1 files changed, 37 insertions, 13 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index baa1990484..97a725a5d4 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -699,7 +699,9 @@ such as @code{guile-1.8.8}.  If no version number is specified, the
 newest available version will be selected.  In addition, @var{package}
 may contain a colon, followed by the name of one of the outputs of the
 package, as in @code{gcc:doc} or @code{binutils-2.22:lib}
-(@pxref{Packages with Multiple Outputs}).
+(@pxref{Packages with Multiple Outputs}).  Packages with a corresponding
+name (and optionally version) are searched for among the GNU
+distribution modules (@pxref{Package Modules}).
 
 @cindex propagated inputs
 Sometimes packages have @dfn{propagated inputs}: these are dependencies
@@ -1212,10 +1214,11 @@ example, the package definition, or @dfn{recipe}, for the GNU Hello
 package looks like this:
 
 @example
-(use-modules (guix packages)
-             (guix download)
-             (guix build-system gnu)
-             (guix licenses))
+(define-module (gnu packages hello)
+  #:use-module (guix packages)
+  #:use-module (guix download)
+  #:use-module (guix build-system gnu)
+  #:use-module (guix licenses))
 
 (define hello
   (package
@@ -1237,13 +1240,19 @@ package looks like this:
 
 @noindent
 Without being a Scheme expert, the reader may have guessed the meaning
-of the various fields here.  This expression binds variable @var{hello}
+of the various fields here.  This expression binds variable @code{hello}
 to a @code{<package>} object, which is essentially a record
 (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
 This package object can be inspected using procedures found in the
 @code{(guix packages)} module; for instance, @code{(package-name hello)}
 returns---surprise!---@code{"hello"}.
 
+In the example above, @var{hello} is defined into a module of its own,
+@code{(gnu packages hello)}.  Technically, this is not strictly
+necessary, but it is convenient to do so: all the packages defined in
+modules under @code{(gnu packages @dots{})} are automatically known to
+the command-line tools (@pxref{Package Modules}).
+
 There are a few points worth noting in the above package definition:
 
 @itemize
@@ -1778,10 +1787,14 @@ guix build @var{options} @var{package-or-derivation}@dots{}
 @var{package-or-derivation} may be either the name of a package found in
 the software distribution such as @code{coreutils} or
 @code{coreutils-8.20}, or a derivation such as
-@file{/nix/store/@dots{}-coreutils-8.19.drv}.  Alternatively, the
-@code{--expression} option may be used to specify a Scheme expression
-that evaluates to a package; this is useful when disambiguation among
-several same-named packages or package variants is needed.
+@file{/nix/store/@dots{}-coreutils-8.19.drv}.  In the former case, a
+package with the corresponding name (and optionally version) is searched
+for among the GNU distribution modules (@pxref{Package Modules}).
+
+Alternatively, the @code{--expression} option may be used to specify a
+Scheme expression that evaluates to a package; this is useful when
+disambiguation among several same-named packages or package variants is
+needed.
 
 The @var{options} may be zero or more of the following:
 
@@ -2183,7 +2196,7 @@ the load.  To check whether a package has a @code{debug} output, use
 @section Package Modules
 
 From a programming viewpoint, the package definitions of the
-distribution are provided by Guile modules in the @code{(gnu packages
+GNU distribution are provided by Guile modules in the @code{(gnu packages
 @dots{})} name space@footnote{Note that packages under the @code{(gnu
 packages @dots{})} module name space are not necessarily ``GNU
 packages''.  This module naming scheme follows the usual Guile module
@@ -2192,8 +2205,19 @@ as part of the GNU system, and @code{packages} identifies modules that
 define packages.}  (@pxref{Modules, Guile modules,, guile, GNU Guile
 Reference Manual}).  For instance, the @code{(gnu packages emacs)}
 module exports a variable named @code{emacs}, which is bound to a
-@code{<package>} object (@pxref{Defining Packages}).  The @code{(gnu
-packages)} module provides facilities for searching for packages.
+@code{<package>} object (@pxref{Defining Packages}).
+
+The @code{(gnu packages @dots{})} module name space is special: it is
+automatically scanned for packages by the command-line tools.  For
+instance, when running @code{guix package -i emacs}, all the @code{(gnu
+packages @dots{})} modules are scanned until one that exports a package
+object whose name is @code{emacs} is found.  This package search
+facility is implemented in the @code{(gnu packages)} module.
+
+Users can store package definitions in modules with different
+names---e.g., @code{(my-packages emacs)}.  In that case, commands such
+as @command{guix package} and @command{guix build} have to be used with
+the @code{-e} option so that they know where to find the package.
 
 The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
 each package is built based solely on other packages in the