Merge branch 'staging' into core-updates

3 files changed, 433 insertions, 58 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index e1902f120f..02c7c5ae59 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -29,6 +29,7 @@ choice.
 * Tracking Bugs and Patches::   Keeping it all organized.
 * Commit Access::               Pushing to the official repository.
 * Updating the Guix Package::   Updating the Guix package definition.
+* Writing Documentation::       Improving documentation in GNU Guix.
 * Translating Guix::            Make Guix speak your native language.
 @end menu
 
@@ -224,8 +225,7 @@ $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
 @noindent
 @cindex REPL
 @cindex read-eval-print loop
-@dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile
-Reference Manual}):
+@dots{} and for a REPL (@pxref{Using Guix Interactively}):
 
 @example
 $ ./pre-inst-env guile
@@ -278,8 +278,8 @@ prepared Guile object (@file{.go}) files.
 
 You can run @command{make} automatically as you work using
 @command{watchexec} from the @code{watchexec} package.  For example,
-to build again each time you update a package file, you can run
-@samp{watchexec -w gnu/packages make -j4}.
+to build again each time you update a package file, run
+@samp{watchexec -w gnu/packages -- make -j4}.
 
 @node The Perfect Setup
 @section The Perfect Setup
@@ -291,7 +291,7 @@ Manual}).  First, you need more than an editor, you need
 wonderful @url{https://nongnu.org/geiser/, Geiser}.  To set that up, run:
 
 @example
-guix package -i emacs guile emacs-geiser emacs-geiser-guile
+guix install emacs guile emacs-geiser emacs-geiser-guile
 @end example
 
 Geiser allows for interactive and incremental development from within
@@ -664,7 +664,7 @@ hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}).  However you
 should be careful when using some characters for example @samp{@@} and
 curly braces which are the basic special characters in Texinfo
 (@pxref{Special Characters,,, texinfo, GNU Texinfo}).  User interfaces
-such as @command{guix package --show} take care of rendering it
+such as @command{guix show} take care of rendering it
 appropriately.
 
 Synopses and descriptions are translated by volunteers
@@ -1118,11 +1118,11 @@ Development is done using the Git distributed version control system.
 Thus, access to the repository is not strictly necessary.  We welcome
 contributions in the form of patches as produced by @code{git
 format-patch} sent to the @email{guix-patches@@gnu.org} mailing list
-(@pxref{submitting patches,, Submitting patches to a project, git, Git
-User Manual}).  Contributors are encouraged to take a moment to set some
-Git repository options (@pxref{Configuring Git}) first, which can
-improve the readability of patches.  Seasoned Guix developers may also
-want to look at the section on commit access (@pxref{Commit Access}).
+(@pxref{Submitting patches to a project,,, git, Git User Manual}).
+Contributors are encouraged to take a moment to set some Git repository
+options (@pxref{Configuring Git}) first, which can improve the
+readability of patches.  Seasoned Guix developers may also want to look
+at the section on commit access (@pxref{Commit Access}).
 
 This mailing list is backed by a Debbugs instance, which allows us to
 keep track of submissions (@pxref{Tracking Bugs and Patches}).  Each
@@ -1779,6 +1779,47 @@ This check can be disabled, @emph{at your own peril}, by setting the
 this variable is set, the updated package source is also added to the
 store.  This is used as part of the release process of Guix.
 
+@cindex documentation
+@node Writing Documentation
+@section Writing Documentation
+
+Guix is documented using the Texinfo system.  If you are not yet
+familiar with it, we accept contributions for documentation in most
+formats.  That includes plain text, Markdown, Org, etc.
+
+Documentation contributions can be sent to
+@email{guix-patches@@gnu.org}.  Prepend @samp{[DOCUMENTATION]} to the
+subject.
+
+When you need to make more than a simple addition to the documentation,
+we prefer that you send a proper patch as opposed to sending an email
+as described above.  @xref{Submitting Patches} for more information on
+how to send your patches.
+
+To modify the documentation, you need to edit @file{doc/guix.texi} and
+@file{doc/contributing.texi} (which contains this documentation
+section), or @file{doc/guix-cookbook.texi} for the cookbook.  If
+you compiled the Guix repository before, you will have
+many more @file{.texi} files that are translations of these
+documents.  Do not modify them, the translation is managed through
+@uref{https://translate.fedoraproject.org/projects/guix, Weblate}.
+@xref{Translating Guix} for more information.
+
+To render documentation, you must first make sure that you ran
+@command{./configure} in your source tree (@pxref{Running Guix Before
+It Is Installed}).  After that you can run one of the following
+commands:
+
+@itemize
+@item @samp{make doc/guix.info} to compile the Info manual.
+      You can check it with @command{info doc/guix.info}.
+@item @samp{make doc/guix.html} to compile the HTML version.
+      You can point your browser to the relevant file in the
+      @file{doc/guix.html} directory.
+@item @samp{make doc/guix-cookbook.info} for the cookbook Info manual.
+@item @samp{make doc/guix-cookbook.html} for the cookbook HTML version.
+@end itemize
+
 @cindex translation
 @cindex l10n
 @cindex i18n
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 06fb872177..b61adc06da 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -122,7 +122,7 @@ language, install it with @code{guix install guile} and start a
 @dfn{REPL}---short for @uref{https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop,
 @dfn{read-eval-print loop}}---by running @code{guile} from the command line.
 
-Alternatively you can also run @code{guix environment --ad-hoc guile -- guile}
+Alternatively you can also run @code{guix shell guile -- guile}
 if you'd rather not have Guile installed in your user profile.
 
 In the following examples, lines show what you would type at the REPL;
@@ -284,24 +284,41 @@ depends on the @code{(guix store)} module and it exports two variables,
 @code{ruby-build} and @code{ruby-build-system}.
 @end itemize
 
-For a more detailed introduction, check out
-@uref{http://www.troubleshooters.com/codecorn/scheme_guile/hello.htm, Scheme
-at a Glance}, by Steve Litt.
-
-One of the reference Scheme books is the seminal ``Structure and
-Interpretation of Computer Programs'', by Harold Abelson and Gerald Jay
-Sussman, with Julie Sussman.  You'll find a
-@uref{https://mitpress.mit.edu/sites/default/files/sicp/index.html, free copy
-online}, together with
-@uref{https://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-001-structure-and-interpretation-of-computer-programs-spring-2005/video-lectures/,
-videos of the lectures by the authors}.  The book is available in Texinfo
-format as the @code{sicp} Guix package.  Go ahead, run @code{guix install
-sicp} and start reading with @code{info sicp} (@pxref{Top,,, sicp, Structure and Interpretation of Computer Programs}).
-An @uref{https://sarabander.github.io/sicp/, unofficial ebook is also
-available}.
+@quotation Going further
+Scheme is a language that has been widely used to teach programming and
+you'll find plenty of material using it as a vehicle.  Here's a
+selection of documents to learn more about Scheme:
+
+@itemize
+@item
+@uref{https://spritely.institute/static/papers/scheme-primer.html, @i{A
+Scheme Primer}}, by Christine Lemmer-Webber and the Spritely Institute.
+
+@item
+@uref{http://www.troubleshooters.com/codecorn/scheme_guile/hello.htm,
+@i{Scheme at a Glance}}, by Steve Litt.
+
+@item
+@uref{https://mitpress.mit.edu/sites/default/files/sicp/index.html,
+@i{Structure and Interpretation of Computer Programs}}, by Harold
+Abelson and Gerald Jay Sussman, with Julie Sussman.  Colloquially known
+as ``SICP'', this book is a reference.
+
+You can also install it and read it from your computer:
+
+@example
+guix install sicp info-reader
+info sicp
+@end example
+
+An @uref{https://sarabander.github.io/sicp/, unofficial ebook} is also
+available.
+
+@end itemize
 
 You'll find more books, tutorials and other resources at
 @url{https://schemers.org/}.
+@end quotation
 
 
 @c *********************************************************************
@@ -1600,7 +1617,7 @@ letting you know what you're missing.  If the file is blank then you're
 missing everything.  The next step is to run:
 
 @example shell
-guix environment linux-libre -- make localmodconfig
+guix shell -D linux-libre -- make localmodconfig
 @end example
 
 and note the output.  Do note that the @file{.config} file is still empty.
@@ -2787,7 +2804,7 @@ Maybe a dependency from our manifest has been updated; or we may have run
 garbage-collected.
 
 @item
-Eventually, we set to work on that project again, so we run @code{guix environment
+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
diff --git a/doc/guix.texi b/doc/guix.texi
index 8affc235e1..6a4773189e 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -30,7 +30,7 @@ Copyright @copyright{} 2015, 2016 Mathieu Lirzin@*
 Copyright @copyright{} 2014 Pierre-Antoine Rault@*
 Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
 Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021 Leo Famulari@*
-Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ricardo Wurmus@*
+Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022 Ricardo Wurmus@*
 Copyright @copyright{} 2016 Ben Woodcroft@*
 Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@*
 Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021, 2022 Efraim Flashner@*
@@ -105,6 +105,7 @@ Copyright @copyright{} 2022 Aleksandr Vityazev@*
 Copyright @copyright{} 2022 Philip M@sup{c}Grath@*
 Copyright @copyright{} 2022 Karl Hallsby@*
 Copyright @copyright{} 2022 Justin Veilleux@*
+Copyright @copyright{} 2022 Reily Siegel@*
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -298,6 +299,7 @@ Programming Interface
 * The Store Monad::             Purely functional interface to the store.
 * G-Expressions::               Manipulating build expressions.
 * Invoking guix repl::          Programming Guix in Guile.
+* Using Guix Interactively::    Fine-grain interaction at the REPL.
 
 Defining Packages
 
@@ -7099,6 +7101,7 @@ package definitions.
 * The Store Monad::             Purely functional interface to the store.
 * G-Expressions::               Manipulating build expressions.
 * Invoking guix repl::          Programming Guix in Guile
+* Using Guix Interactively::    Fine-grain interaction at the REPL.
 @end menu
 
 @node Package Modules
@@ -8524,14 +8527,8 @@ the number specified as the @option{--cores} option of
 This Boolean, @code{#t} by default, determines whether to ``validate''
 the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well
 as executables) previously installed by the @code{install} phase.
-
-This validation step consists in making sure that all the shared
-libraries needed by an ELF binary, which are listed as
-@code{DT_NEEDED} entries in its @code{PT_DYNAMIC} segment, appear in the
-@code{DT_RUNPATH} entry of that binary.  In other words, it ensures that
-running or using those binaries will not result in a ``file not found''
-error at run time.  @xref{Options, @option{-rpath},, ld, The GNU
-Linker}, for more information on @code{RUNPATH}.
+@xref{phase-validate-runpath, the @code{validate-runpath} phase}, for
+details.
 
 @item #:substitutable?
 This Boolean, @code{#t} by default, tells whether the package outputs
@@ -9619,6 +9616,21 @@ Patch shebangs on the installed executable files.
 Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
 is false), copying them to the @code{debug} output when available
 (@pxref{Installing Debugging Files}).
+
+@cindex RUNPATH, validation
+@anchor{phase-validate-runpath}
+@item validate-runpath
+Validate the @code{RUNPATH} of ELF binaries, unless
+@code{#:validate-runpath?} is false (@pxref{Build Systems}).
+
+This validation step consists in making sure that all the shared
+libraries needed by an ELF binary, which are listed as @code{DT_NEEDED}
+entries in its @code{PT_DYNAMIC} segment, appear in the
+@code{DT_RUNPATH} entry of that binary.  In other words, it ensures that
+running or using those binaries will not result in a ``file not found''
+error at run time.  @xref{Options, @option{-rpath},, ld, The GNU
+Linker}, for more information on @code{RUNPATH}.
+
 @end table
 
 Other build systems have similar phases, with some variations.  For
@@ -10859,8 +10871,9 @@ So, to exit the monad and get the desired effect, one must use
 @end lisp
 
 Note that the @code{(guix monad-repl)} module extends the Guile REPL with
-new ``meta-commands'' to make it easier to deal with monadic procedures:
-@code{run-in-store}, and @code{enter-store-monad}.  The former is used
+new ``commands'' to make it easier to deal with monadic procedures:
+@code{run-in-store}, and @code{enter-store-monad} (@pxref{Using Guix
+Interactively}).  The former is used
 to ``run'' a single monadic value through the store:
 
 @example
@@ -10885,6 +10898,9 @@ scheme@@(guile-user)>
 Note that non-monadic values cannot be returned in the
 @code{store-monad} REPL.
 
+Other meta-commands are available at the REPL, such as @code{,build} to
+build a file-like object (@pxref{Using Guix Interactively}).
+
 The main syntactic forms to deal with monads in general are provided by
 the @code{(guix monads)} module and are described below.
 
@@ -11777,7 +11793,8 @@ lines at the top of the script:
 @code{!#}
 @end example
 
-Without a file name argument, a Guile REPL is started:
+Without a file name argument, a Guile REPL is started, allowing for
+interactive use (@pxref{Using Guix Interactively}):
 
 @example
 $ guix repl
@@ -11833,6 +11850,132 @@ Inhibit loading of the @file{~/.guile} file.  By default, that
 configuration file is loaded when spawning a @code{guile} REPL.
 @end table
 
+@node Using Guix Interactively
+@section Using Guix Interactively
+
+@cindex interactive use
+@cindex REPL, read-eval-print loop
+The @command{guix repl} command gives you access to a warm and friendly
+@dfn{read-eval-print loop} (REPL) (@pxref{Invoking guix repl}).  If
+you're getting into Guix programming---defining your own packages,
+writing manifests, defining services for Guix System or Guix Home,
+etc.---you will surely find it convenient to toy with ideas at the REPL.
+
+If you use Emacs, the most convenient way to do that is with Geiser
+(@pxref{The Perfect Setup}), but you do not have to use Emacs to enjoy
+the REPL@.  When using @command{guix repl} or @command{guile} in the
+terminal, we recommend using Readline for completion and Colorized to
+get colorful output.  To do that, you can run:
+
+@example
+guix install guile guile-readline guile-colorized
+@end example
+
+@noindent
+... and then create a @file{.guile} file in your home directory containing
+this:
+
+@lisp
+(use-modules (ice-9 readline) (ice-9 colorized))
+
+(activate-readline)
+(activate-colorized)
+@end lisp
+
+The REPL lets you evaluate Scheme code; you type a Scheme expression at
+the prompt, and the REPL prints what it evaluates to:
+
+@example
+$ guix repl
+scheme@@(guix-user)> (+ 2 3)
+$1 = 5
+scheme@@(guix-user)> (string-append "a" "b")
+$2 = "ab"
+@end example
+
+It becomes interesting when you start fiddling with Guix at the REPL.
+The first thing you'll want to do is to ``import'' the @code{(guix)}
+module, which gives access to the main part of the programming
+interface, and perhaps a bunch of useful Guix modules.  You could type
+@code{(use-modules (guix))}, which is valid Scheme code to import a
+module (@pxref{Using Guile Modules,,, guile, GNU Guile Reference
+Manual}), but the REPL provides the @code{use} @dfn{command} as a
+shorthand notation (@pxref{REPL Commands,,, guile, GNU Guile Reference
+Manual}):
+
+@example
+scheme@@(guix-user)> ,use (guix)
+scheme@@(guix-user)> ,use (gnu packages base)
+@end example
+
+Notice that REPL commands are introduced by a leading comma.  A REPL
+command like @code{use} is not valid Scheme code; it's interpreted
+specially by the REPL.
+
+Guix extends the Guile REPL with additional commands for convenience.
+Among those, the @code{build} command comes in handy: it ensures that
+the given file-like object is built, building it if needed, and returns
+its output file name(s).  In the example below, we build the
+@code{coreutils} and @code{grep} packages, as well as a ``computed
+file'' (@pxref{G-Expressions, @code{computed-file}}), and we use the
+@code{scandir} procedure to list the files in Grep's @code{/bin}
+directory:
+
+@example
+scheme@@(guix-user)> ,build coreutils
+$1 = "/gnu/store/@dots{}-coreutils-8.32-debug"
+$2 = "/gnu/store/@dots{}-coreutils-8.32"
+scheme@@(guix-user)> ,build grep
+$3 = "/gnu/store/@dots{}-grep-3.6"
+scheme@@(guix-user)> ,build (computed-file "x" #~(mkdir #$output))
+building /gnu/store/@dots{}-x.drv...
+$4 = "/gnu/store/@dots{}-x"
+scheme@@(guix-user)> ,use(ice-9 ftw)
+scheme@@(guix-user)> (scandir (string-append $3 "/bin"))
+$5 = ("." ".." "egrep" "fgrep" "grep")
+@end example
+
+At a lower-level, a useful command is @code{lower}: it takes a file-like
+object and ``lowers'' it into a derivation (@pxref{Derivations}) or a
+store file:
+
+@example
+scheme@@(guix-user)> ,lower grep
+$6 = #<derivation /gnu/store/@dots{}-grep-3.6.drv => /gnu/store/@dots{}-grep-3.6 7f0e639115f0>
+scheme@@(guix-user)> ,lower (plain-file "x" "Hello!")
+$7 = "/gnu/store/@dots{}-x"
+@end example
+
+The full list of REPL commands can be seen by typing @code{,help guix}
+and is given below for reference.
+
+@deffn {REPL command} build @var{object}
+Lower @var{object} and build it if it's not already built, returning its
+output file name(s).
+@end deffn
+
+@deffn {REPL command} lower @var{object}
+Lower @var{object} into a derivation or store file name and return it.
+@end deffn
+
+@deffn {REPL command} verbosity @var{level}
+Change build verbosity to @var{level}.
+
+This is similar to the @option{--verbosity} command-line option
+(@pxref{Common Build Options}): level 0 means total silence, level 1
+shows build events only, and higher levels print build logs.
+@end deffn
+
+@deffn {REPL command} run-in-store @var{exp}
+Run @var{exp}, a monadic expresssion, through the store monad.
+@xref{The Store Monad}, for more information.
+@end deffn
+
+@deffn {REPL command} enter-store-monad
+Enter a new REPL to evaluate monadic expressions (@pxref{The Store
+Monad}).  You can quit this ``inner'' REPL by typing @code{,q}.
+@end deffn
+
 @c *********************************************************************
 @node Utilities
 @chapter Utilities
@@ -14002,6 +14145,10 @@ The @option{--input-simplification} option described below provides
 fine-grain control over when inputs should be simplified.
 @end table
 
+@item --list-stylings
+@itemx -l
+List and describe the available styling rules and exit.
+
 @item --load-path=@var{directory}
 @itemx -L @var{directory}
 Add @var{directory} to the front of the package module search path
@@ -14950,7 +15097,9 @@ any given store item.
 The command output looks like this:
 
 @smallexample
-$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
+$ guix challenge \
+  --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org" \
+  openssl git pius coreutils grep
 updating substitutes from 'https://@value{SUBSTITUTE-SERVER-1}'... 100.0%
 updating substitutes from 'https://guix.example.org'... 100.0%
 /gnu/store/@dots{}-openssl-1.0.2d contents differ:
@@ -14977,18 +15126,20 @@ updating substitutes from 'https://guix.example.org'... 100.0%
 
 @dots{}
 
-6,406 store items were analyzed:
-  - 4,749 (74.1%) were identical
-  - 525 (8.2%) differed
-  - 1,132 (17.7%) were inconclusive
+5 store items were analyzed:
+  - 2 (40.0%) were identical
+  - 3 (60.0%) differed
+  - 0 (0.0%) were inconclusive
 @end smallexample
 
 @noindent
-In this example, @command{guix challenge} first scans the store to
-determine the set of locally-built derivations---as opposed to store
-items that were downloaded from a substitute server---and then queries
-all the substitute servers.  It then reports those store items for which
-the servers obtained a result different from the local build.
+In this example, @command{guix challenge} queries all the substitute
+servers for each of the fives packages specified on the command line.
+It then reports those store items for which the servers obtained a
+result different from the local build (if it exists) and/or different
+from one another; here, the @samp{local hash} lines indicate that a
+local build result was available for each of these packages and shows
+its hash.
 
 @cindex non-determinism, in package builds
 As an example, @code{guix.example.org} always gets a different answer.
@@ -15044,19 +15195,21 @@ whether @code{@value{SUBSTITUTE-SERVER-1}} and other substitute servers obtain t
 same build result as you did with:
 
 @example
-$ guix challenge @var{package}
+guix challenge @var{package}
 @end example
 
-@noindent
-where @var{package} is a package specification such as
-@code{guile@@2.0} or @code{glibc:debug}.
-
 The general syntax is:
 
 @example
-guix challenge @var{options} [@var{packages}@dots{}]
+guix challenge @var{options} @var{argument}@dots{}
 @end example
 
+@noindent
+where @var{argument} is a package specification such as
+@code{guile@@2.0} or @code{glibc:debug} or, alternatively, a store file
+name as returned, for example, by @command{guix build} or @command{guix
+gc --list-live}.
+
 When a difference is found between the hash of a locally-built item and
 that of a server-provided substitute, or among substitutes provided by
 different servers, the command displays it as in the example above and
@@ -18709,6 +18862,75 @@ String or gexp denoting the corresponding mcron job schedule
 @end table
 @end deftp
 
+@cindex logging, anonymization
+@subheading Anonip Service
+
+Anonip is a privacy filter that removes IP address from web server logs.
+This service creates a FIFO and filters any written lines with anonip
+before writing the filtered log to a target file.
+
+The following example sets up the FIFO
+@file{/var/run/anonip/https.access.log} and writes the filtered log file
+@file{/var/log/anonip/https.access.log}.
+
+@lisp
+(service anonip-service-type
+         (anonip-configuration
+           (input  "/var/run/anonip/https.access.log")
+           (output "/var/log/anonip/https.access.log")))
+@end lisp
+
+Configure your web server to write its logs to the FIFO at
+@file{/var/run/anonip/https.access.log} and collect the anonymized log
+file at @file{/var/web-logs/https.access.log}.
+
+@deftp {Data Type} anonip-configuration
+This data type represents the configuration of anonip.
+It has the following parameters:
+
+@table @asis
+@item @code{anonip} (default: @code{anonip})
+The anonip package to use.
+
+@item @code{input}
+The file name of the input log file to process.  The service creates a
+FIFO of this name.  The web server should write its logs to this FIFO.
+
+@item @code{output}
+The file name of the processed log file.
+@end table
+
+The following optional settings may be provided:
+
+@table @asis
+@item @code{skip-private?}
+When @code{#true} do not mask addresses in private ranges.
+
+@item @code{column}
+A 1-based indexed column number.  Assume IP address is in the specified
+column (default is 1).
+
+@item @code{replacement}
+Replacement string in case address parsing fails, e.g. @code{"0.0.0.0"}.
+
+@item @code{ipv4mask}
+Number of bits to mask in IPv4 addresses.
+
+@item @code{ipv6mask}
+Number of bits to mask in IPv6 addresses.
+
+@item @code{increment}
+Increment the IP address by the given number.  By default this is zero.
+
+@item @code{delimiter}
+Log delimiter string.
+
+@item @code{regex}
+Regular expression for detecting IP addresses.  Use this instead of @code{column}.
+@end table
+@end deftp
+
+
 @node Networking Setup
 @subsection Networking Setup
 
@@ -28507,6 +28729,9 @@ prefix @samp{unix:}.  For addresses using an IP address or domain name,
 the default port is 80, and a different port can be specified
 explicitly.
 
+@item @code{extra-content}
+A string or list of strings to add to the upstream block.
+
 @end table
 @end deftp
 
@@ -35082,6 +35307,11 @@ allocation plan in the database.
 An association list of hooks.  These provide a way to execute arbitrary
 code upon certain events, like a build result being processed.
 
+@item @code{parallel-hooks} (default: @var{'()})
+Hooks can be configured to run in parallel.  This parameter is an
+association list of hooks to do in parallel, where the key is the symbol
+for the hook and the value is the number of threads to run.
+
 @item @code{guile} (default: @code{guile-3.0-latest})
 The Guile package with which to run the Guix Build Coordinator.
 
@@ -37527,6 +37757,13 @@ bootloader boot menu:
 Describe the running system generation: its file name, the kernel and
 bootloader used, etc., as well as provenance information when available.
 
+The @code{--list-installed} flag is available, with the same
+syntax that is used in @command{guix package --list-installed}
+(@pxref{Invoking guix package}).  When the flag is used,
+the description will include a list of packages that are currently
+installed in the system profile, with optional filtering based on a
+regular expression.
+
 @quotation Note
 The @emph{running} system generation---referred to by
 @file{/run/current-system}---is not necessarily the @emph{current}
@@ -37554,6 +37791,11 @@ generations that are up to 10 days old:
 $ guix system list-generations 10d
 @end example
 
+The @code{--list-installed} flag may also be specified, with the same
+syntax that is used in @command{guix package --list-installed}.  This
+may be helpful if trying to determine when a package was added to the
+system.
+
 @end table
 
 The @command{guix system} command has even more to offer!  The following
@@ -39313,6 +39555,7 @@ services)}.
 * Shepherd: Shepherd Home Service.       Managing User's Daemons.
 * SSH: Secure Shell.                     Setting up the secure shell client.
 * Desktop: Desktop Home Services.        Services for graphical environments.
+* Guix: Guix Home Services.              Services for Guix.
 @end menu
 @c In addition to that Home Services can provide
 
@@ -39541,6 +39784,23 @@ contents of the extensions will be added to the end of the corresponding
 Bash configuration files (@pxref{Bash Startup Files,,, bash, The GNU
 Bash Reference Manual}.
 
+For example, here is how you would define a service that extends the
+Bash service such that @file{~/.bash_profile} defines an additional
+environment variable, @env{PS1}:
+
+@lisp
+(define bash-fancy-prompt-service
+  (simple-service 'bash-fancy-prompt
+                  home-bash-service-type
+                  (home-bash-extension
+                   (environment-variables
+                    '(("PS1" . "\\u \\wλ "))))))
+@end lisp
+
+You would then add @code{bash-fancy-prompt-service} to the list in the
+@code{services} field of your @code{home-environment}.  The reference of
+@code{home-bash-extension} follows.
+
 @deftp {Data Type} home-bash-extension
 Available @code{home-bash-extension} fields are:
 
@@ -39953,6 +40213,37 @@ format.
 
 @end deftp
 
+@node Guix Home Services
+@subsection Guix Home Services
+
+The @code{(gnu home services guix)} module provides services for
+user-specific Guix configuration.
+
+@defvr {Scheme Variable} home-channels-service-type
+This is the service type for managing
+@file{$XDG_CONFIG_HOME/guix/channels.scm}, the file that controls the
+channels received on @command{guix pull} (@pxref{Channels}).  Its
+associated value is a list of @code{channel} records, defined in the
+@code{(guix channels)} module.
+
+Generally, it is better to extend this service than to directly
+configure it, as its default value is the default guix channel(s)
+defined by @code{%default-channels}.  If you configure this service
+directly, be sure to include a guix channel.  @xref{Specifying
+Additional Channels} and @ref{Using a Custom Guix Channel} for more
+details.
+
+A typical extension for adding a channel might look like this:
+
+@lisp
+(simple-service 'variant-packages-service
+                home-channels-service-type
+                (list
+                 (channel
+                  (name 'variant-packages)
+                  (url "https://example.org/variant-packages.git")))
+@end lisp
+@end defvr
 
 @node Invoking guix home
 @section Invoking @code{guix home}
@@ -40192,6 +40483,17 @@ install anything.
 Describe the current home generation: its file name, as well as
 provenance information when available.
 
+To show installed packages in the current home generation's profile, the
+@code{--list-installed} flag is provided, with the same syntax that is
+used in @command{guix package --list-installed} (@pxref{Invoking guix
+package}).  For instance, the following command shows a table of all the
+packages with ``emacs'' in their name that are installed in the current
+home generation's profile:
+
+@example
+guix home describe --list-installed=emacs
+@end example
+
 @item list-generations
 List a summary of each generation of the home environment available on
 disk, in a human-readable way.  This is similar to the
@@ -40204,9 +40506,14 @@ generations displayed.  For instance, the following command displays
 generations that are up to 10 days old:
 
 @example
-$ guix home list-generations 10d
+guix home list-generations 10d
 @end example
 
+The @code{--list-installed} flag may also be specified, with the same
+syntax that is used in @command{guix home describe}.  This may be
+helpful if trying to determine when a package was added to the home
+profile.
+
 @item import
 Generate a @dfn{home environment} from the packages in the default
 profile and configuration files found in the user's home directory.  The
@@ -40634,6 +40941,16 @@ package, you can try and import it (@pxref{Invoking guix import}):
 guix import texlive @var{package}
 @end example
 
+Additional options include:
+
+@table @code
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
+@end table
+
 @quotation Note
 @TeX{} Live packaging is still very much work in progress, but you can
 help!  @xref{Contributing}, for more information.