On Mon, 16 Nov 2015 21:06:00 +0100
ludo@gnu.org (Ludovic Courtès) wrote:

> Sure.  I think we would need a new section for (gnu packages), maybe
> “Distribution API” under “GNU Distribution”?  It would describe
> ‘fold-packages’, ‘specification->package’, and so on.

Let's start smaller :) [I'm still fighting with emacs - I gave it many 
chances over the years, but we'll never find true happy puppies' love -
and a few other things...]

--snip
diff --git a/doc/guix.texi b/doc/guix.texi
index 3b6955c..32bedd7 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -5482,6 +5482,25 @@ above, such as @code{host-name} and @code{bootloader}, are mandatory.
 Others, such as @code{packages} and @code{services}, can be omitted, in
 which case they get a default value.
 
+The attentive reader might have noticed that the @code{tcpdump} package
+is defined in the @code{gnu packages admin} module. While it is generally
+encouraged to install packages in users' profiles it might be
+necessary to install a few more packages in the base system. Maintaining
+the list of used modules (and figuring out which are the correct
+ones) can become a burden and error prone. But the system configuration
+is a lisp program, so we can make use of the power of lisp to automate
+this task. The @code{gnu packages} module provides the
+@code{specification->package} procedure which can help us here:
+
+@lisp
+  ;; Globally-installed packages.
+  (packages
+     (append
+        (map (specification->package
+                `("tcpdump" "emacs" "htop" "tmux")))
+        %base-packages))
+@end lisp
+
 @vindex %base-packages
 The @code{packages} field lists
 packages that will be globally visible on the system, for all user
--snip