doc: Make 'guix publish' more visible.

* doc/guix.texi (Substitutes): Add xref to "Invoking guix publish".
  (Invoking guix publish): Add xref to "Substitutes".  Explain what
  Hydra is.

1 files changed, 13 insertions, 7 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 35cb8f148b..3a9f91e7dc 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -1349,7 +1349,9 @@ determination to subvert the computing infrastructure and exploit its
 weaknesses.  While using @code{hydra.gnu.org} substitutes can be
 convenient, we encourage users to also build on their own, or even run
 their own build farm, such that @code{hydra.gnu.org} is less of an
-interesting target.
+interesting target.  One way to help is by publishing the software you
+build using @command{guix publish} so that others have one more choice
+of server to download substitutes from (@pxref{Invoking guix publish}).
 
 Guix has the foundations to maximize build reproducibility
 (@pxref{Features}).  In most cases, independent builds of a given
@@ -3643,11 +3645,14 @@ build} supports (@pxref{Invoking guix build, common build options}).
 @section Invoking @command{guix publish}
 
 The purpose of @command{guix publish} is to enable users to easily share
-their store with others.  When @command{guix publish} runs, it spawns an
-HTTP server which allows anyone with network access to obtain
-substitutes from it.  This means that any machine running Guix can also
-act as if it were a build farm, since the HTTP interface is
-Hydra-compatible.
+their store with others, which can then use it as a substitute server
+(@pxref{Substitutes}).
+
+When @command{guix publish} runs, it spawns an HTTP server which allows
+anyone with network access to obtain substitutes from it.  This means
+that any machine running Guix can also act as if it were a build farm,
+since the HTTP interface is compatible with Hydra, the software behind
+the @code{hydra.gnu.org} build farm.
 
 For security, each substitute is signed, allowing recipients to check
 their authenticity and integrity (@pxref{Substitutes}).  Because
@@ -3684,7 +3689,8 @@ Listen for HTTP requests on @var{port}.
 @item --repl[=@var{port}]
 @itemx -r [@var{port}]
 Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
-Reference Manual}) on @var{port} (37146 by default).
+Reference Manual}) on @var{port} (37146 by default).  This is used
+primarily for debugging a running @command{guix publish} server.
 @end table
 
 @c *********************************************************************