1 files changed, 25 insertions, 28 deletions
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 712c131a51..3d86fca396 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -3714,7 +3714,7 @@ reference.
 @section Guix Profiles in Practice
 
 Guix provides a very useful feature that may be quite foreign to newcomers:
-@emph{profiles}.  They are a way to group package installations together and all users
+@dfn{profiles}.  They are a way to group package installations together and all users
 on the same system are free to use as many profiles as they want.
 
 Whether you're a developer or not, you may find that multiple profiles bring you
@@ -3722,6 +3722,16 @@ great power and flexibility.  While they shift the paradigm somewhat compared to
 @emph{traditional package managers}, they are very convenient to use once you've
 understood how to set them up.
 
+@quotation Note
+This section is an opinionated guide on the use of multiple profiles.
+It predates @command{guix shell} and its fast profile cache
+(@pxref{Invoking guix shell,,, guix, GNU Guix Reference Manual}).
+
+In many cases, you may find that using @command{guix shell} to set up
+the environment you need, when you need it, is less work that
+maintaining a dedicated profile.  Your call!
+@end quotation
+
 If you are familiar with Python's @samp{virtualenv}, you can think of a profile as a
 kind of universal @samp{virtualenv} that can hold any kind of software whatsoever, not
 just Python software.  Furthermore, profiles are self-sufficient: they capture
@@ -3977,7 +3987,9 @@ without having to specify the path to a profile.
 @node The benefits of manifests
 @subsection The benefits of manifests
 
-Manifests are a convenient way to keep your package lists around and, say,
+Manifests let you @dfn{declare} the set of packages you'd like to have
+in a profile (@pxref{Writing Manifests,,, guix, GNU Guix Reference Manual}).
+They are a convenient way to keep your package lists around and, say,
 to synchronize them across multiple machines using a version control system.
 
 A common complaint about manifests is that they can be slow to install when they
@@ -4034,29 +4046,12 @@ profiles, they are not strictly equivalent: profiles have the side effect that
 they ``pin'' packages in the store, which prevents them from being
 garbage-collected (@pxref{Invoking guix gc,,, guix, GNU Guix Reference Manual})
 and ensures that they will still be available at any point in
-the future.
-
-Let's take an example:
-
-@enumerate
-@item
-We have an environment for hacking on a project for which there isn't a Guix
-package yet.  We build the environment using a manifest, and then run @code{guix
-   environment -m manifest.scm}.  So far so good.
+the future.  The @command{guix shell} command also protects
+recently-used profiles from garbage collection; profiles that have not
+been used for a while may be garbage-collected though, along with the
+packages they refer to.
 
-@item
-Many weeks pass and we have run a couple of @code{guix pull} in the mean time.
-Maybe a dependency from our manifest has been updated; or we may have run
-@code{guix gc} and some packages needed by our manifest have been
-garbage-collected.
-
-@item
-Eventually, we set to work on that project again, so we run @code{guix shell
-   -m manifest.scm}.  But now we have to wait for Guix to build and install
-stuff!
-@end enumerate
-
-Ideally, we could spare the rebuild time.  And indeed we can, all we need is to
+To be 100% sure that a given profile will never be collected,
 install the manifest to a profile and use @code{GUIX_PROFILE=/the/profile;
 . "$GUIX_PROFILE"/etc/profile} as explained above: this guarantees that our
 hacking environment will be available at all times.
@@ -4071,16 +4066,18 @@ To reproduce a profile bit-for-bit, we need two pieces of information:
 
 @itemize
 @item
-a manifest,
+a manifest (@pxref{Writing Manifests,,, guix, GNU Guix Reference Manual});
 @item
-a Guix channel specification.
+a Guix channel specification (@pxref{Replicating Guix,,, guix, GNU Guix
+Reference Manual}).
 @end itemize
 
 Indeed, manifests alone might not be enough: different Guix versions (or
 different channels) can produce different outputs for a given manifest.
 
 You can output the Guix channel specification with @samp{guix describe
---format=channels}.
+--format=channels} (@pxref{Invoking guix describe,,, guix, GNU Guix
+Reference Manual}).
 Save this to a file, say @samp{channel-specs.scm}.
 
 On another computer, you can use the channel specification file and the manifest
@@ -4331,7 +4328,7 @@ guix build -f guix.scm --target=x86_64-w64-mingw32
 @end lisp
 
 You can also use @dfn{package transformations} to test package variants
-(@pxref{Package Transformations,,, guix, GNU Guix Reference Manual}):
+(@pxref{Package Transformation Options,,, guix, GNU Guix Reference Manual}):
 
 @example
 # What if we built with Clang instead of GCC?