doc: Turn "Creating a Channel" into a step-by-step guide.

* doc/guix.texi (Creating a Channel): Rewrite as a step-by-step guide.
Move warning below and shorten it.

1 files changed, 93 insertions, 29 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index c961f706ec..853396f776 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -5771,18 +5771,99 @@ machines with limited resources.
 Let's say you have a bunch of custom package variants or personal packages
 that you think would make little sense to contribute to the Guix project, but
 would like to have these packages transparently available to you at the
-command line.  You would first write modules containing those package
-definitions (@pxref{Package Modules}), maintain them in a Git repository, and
-then you and anyone else can use it as an additional channel to get packages
-from.  Neat, no?
+command line.  By creating a @dfn{channel}, you can use and publish such
+a package collection.  This involves the following steps:
+
+@enumerate
+@item
+Channels live in a Git repository so the first step, when creating a
+channel, is to create its repository:
+
+@example
+mkdir my-channel
+cd my-channel
+git init
+@end example
+
+@item
+The next step is to create files containing package modules
+(@pxref{Package Modules}), each of which will contain one or more
+package definitions (@pxref{Defining Packages}).  A channel can provide
+things other than packages, such as build systems or services; we're
+using packages as most common use case.
+
+For example, Alice might want to provide a module called @code{(alice
+packages greetings)} that will provide her favorite ``hello world''
+implementations.  To do that Alice will create a directory corresponding
+to that module name.
+
+@example
+mkdir -p alice/packages
+$EDITOR alice/packages/greetings.scm
+git add alice/packages/greetings.scm
+@end example
+
+You can name your package modules however you like; the main constraint
+to keep in mind is to avoid name clashes with other package collections,
+which is why our hypothetical Alice wisely chose the @code{(alice
+packages @dots{})} name space.
+
+Note that you can also place modules in a sub-directory of the
+repository; @pxref{Package Modules in a Sub-directory}, for more info on
+that.
+
+@item
+With this first module in place, the next step is to test the packages
+it provides.  This can be done with @command{guix build}, which needs to
+be fold to look for modules in the Git checkout.  For example, assuming
+@code{(alice packages greetings)} provides a package called
+@code{hi-from-alice}, Alice will run this command from the Git checkout:
+
+@example
+guix build -L. hi-from-alice
+@end example
+
+@noindent
+... where @code{-L.} adds the current directory to Guile's load path
+(@pxref{Load Paths,,, guile, GNU Guile Reference Manual}).
+
+@item
+It might take Alice a few iterations to obtain satisfying package
+definitions.  Eventually Alice will commit this file:
+
+@example
+git commit
+@end example
+
+As a channel author, consider bundling authentication material with your
+channel so that users can authenticate it.  @xref{Channel
+Authentication}, and @ref{Specifying Channel Authorizations}, for info
+on how to do it.
+
+@item
+To use Alice's channel, anyone can now add it to their channel file
+(@pxref{Specifying Additional Channels}) and run @command{guix pull}
+(@pxref{Invoking guix pull}):
+
+@example
+$EDITOR ~/.config/guix/channels.scm
+guix pull
+@end example
+
+Guix will now behave as if the root directory of that channel's Git
+repository had been permanently added to the Guile load path.  In this
+example, @code{(alice packages greetings)} will automatically be found
+by the @command{guix} command.
+@end enumerate
+
+Voilà!  
 
 @c What follows stems from discussions at
 @c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
 @c earlier discussions on guix-devel@gnu.org.
 @quotation Warning
-Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
-publish your personal channel to the world, we would like to share a few words
-of caution:
+Before you publish your channel, we would like to share a few words of
+caution:
 
 @itemize
 @item
@@ -5793,13 +5874,11 @@ available to all Guix users and benefit from the project's quality assurance
 process.
 
 @item
-When you maintain package definitions outside Guix, we, Guix developers,
-consider that @emph{the compatibility burden is on you}.  Remember that
-package modules and package definitions are just Scheme code that uses various
-programming interfaces (APIs).  We want to remain free to change these APIs to
-keep improving Guix, possibly in ways that break your channel.  We never
-change APIs gratuitously, but we will @emph{not} commit to freezing APIs
-either.
+Package modules and package definitions are Scheme code that uses
+various programming interfaces (APIs).  We, Guix developers, never
+change APIs gratuitously, but we do @emph{not} commit to freezing APIs
+either.  When you maintain package definitions outside Guix, we consider
+that @emph{the compatibility burden is on you}.
 
 @item
 Corollary: if you're using an external channel and that channel breaks, please
@@ -5813,21 +5892,6 @@ share your improvements, which are basic tenets of
 email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
 @end quotation
 
-To create a channel, create a Git repository containing your own package
-modules and make it available.  The repository can contain anything, but a
-useful channel will contain Guile modules that export packages.  Once you
-start using a channel, Guix will behave as if the root directory of that
-channel's Git repository has been added to the Guile load path (@pxref{Load
-Paths,,, guile, GNU Guile Reference Manual}).  For example, if your channel
-contains a file at @file{my-packages/my-tools.scm} that defines a Guile
-module, then the module will be available under the name @code{(my-packages
-my-tools)}, and you will be able to use it like any other module
-(@pxref{Modules,,, guile, GNU Guile Reference Manual}).
-
-As a channel author, consider bundling authentication material with your
-channel so that users can authenticate it.  @xref{Channel
-Authentication}, and @ref{Specifying Channel Authorizations}, for info
-on how to do it.
 
 
 @node Package Modules in a Sub-directory