doc: Document "guix download".

* doc/guix.texi (Defining Packages): Linke to "Invoking guix download".
  (Utilities): Add an overview paragraph.
  (Invoking guix download): New node.

1 files changed, 41 insertions, 4 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index b14310f908..c0f8f0fc82 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -835,8 +835,8 @@ The @code{sha256} field specifies the expected SHA256 hash of the file
 being downloaded.  It is mandatory, and allows Guix to check the
 integrity of the file.  The @code{(base32 @dots{})} form introduces the
 base32 representation of the hash.  You can obtain this information with
-the @code{guix hash} (@pxref{Invoking guix hash}) and @code{guix
-download} tools.
+@code{guix download} (@pxref{Invoking guix download}) and @code{guix
+hash} (@pxref{Invoking guix hash}).
 
 @item
 @cindex GNU Build System
@@ -1115,8 +1115,13 @@ space.
 @node Utilities
 @chapter Utilities
 
+This section describes tools primarily targeted at developers and users
+who write new package definitions.  They complement the Scheme
+programming interface of Guix in a convenient way.
+
 @menu
 * Invoking guix build::         Building packages from the command line.
+* Invoking guix download::      Downloading a file and printing its hash.
 * Invoking guix hash::          Computing the cryptographic hash of a file.
 * Invoking guix refresh::       Updating package definitions.
 @end menu
@@ -1214,10 +1219,42 @@ the @code{package-derivation} procedure of the @code{(guix packages)}
 module, and to the @code{build-derivations} procedure of the @code{(guix
 store)} module.
 
+@node Invoking guix download
+@section Invoking @command{guix download}
+
+When writing a package definition, developers typically need to download
+the package's source tarball, compute its SHA256 hash, and write that
+hash in the package definition (@pxref{Defining Packages}).  The
+@command{guix download} tool helps with this task: it downloads a file
+from the given URI, adds it to the store, and prints both its file name
+in the store and its SHA256 hash.
+
+The fact that the downloaded file is added to the store saves bandwidth:
+when the developer eventually tries to build the newly defined package
+with @command{guix build}, the source tarball will not have to be
+downloaded again because it is already in the store.  It is also a
+convenient way to temporarily stash files, which may be deleted
+eventually (@pxref{Invoking guix gc}).
+
+The @command{guix download} command supports the same URIs as used in
+package definitions.  In particular, it supports @code{mirror://} URIs.
+@code{https} URIs (HTTP over TLS) are supported @emph{provided} the
+Guile bindings for GnuTLS are available in the user's environment; when
+they are not available, an error is raised.
+
+The following option is available:
+
+@table @code
+@item --format=@var{fmt}
+@itemx -f @var{fmt}
+Write the hash in the format specified by @var{fmt}.  For more
+information on the valid values for @var{fmt}, @ref{Invoking guix hash}.
+@end table
+
 @node Invoking guix hash
 @section Invoking @command{guix hash}
 
-The @command{guix hash} command allows to check the integrity of a file.
+The @command{guix hash} command computes the SHA256 hash of a file.
 It is primarily a convenience tool for anyone contributing to the
 distribution: it computes the cryptographic hash of a file, which can be
 used in the definition of a package (@pxref{Defining Packages}).
@@ -1234,7 +1271,7 @@ guix hash @var{option} @var{file}
 
 @item --format=@var{fmt}
 @itemx -f @var{fmt}
-Write the hash in the given format.
+Write the hash in the format specified by @var{fmt}.
 
 Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
 (@code{hex} and @code{hexadecimal} can be used as well).