On Wed, Sep 01 2021, Andrew Tropin wrote:

> * doc/guix.texi: Add Guix Home documentation.
> * doc/he-config-bare-bones.texi: Add home-environment example configuration.
> ---
> Reread and updated documentation for Guix Home to reflect latest changes,
> still a subject for review and proofreading.  Combined all changes into one
> commit.  Sections about Mcron and Shepherd (which are not in wip-guix-home
> yet) contains only placeholders, will be updated with patches for related home
> services.  There is no section about Gradual Migration to Guix Home and
> Invoking guix home's subsection about 'guix home import' subcommand yet, they
> are planned, but probably will come later.

Going to read this once again and leave some thoughts and comments while
reading.  (Edit: expect a long reply!)  :-)

>  doc/guix.texi | 687 ++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 687 insertions(+)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 2b8448c856..8a50678a80 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -96,6 +96,7 @@ Copyright @copyright{} 2021 Domagoj Stolfa@*
>  Copyright @copyright{} 2021 Hui Lu@*
>  Copyright @copyright{} 2021 pukkamustard@*
>  Copyright @copyright{} 2021 Alice Brenon@*
> +Copyright @copyright{} 2021 Andrew Tropin@*
>  
>  Permission is granted to copy, distribute and/or modify this document
>  under the terms of the GNU Free Documentation License, Version 1.3 or
> @@ -167,6 +168,7 @@ Weblate} (@pxref{Translating Guix}).
>  * Programming Interface::       Using Guix in Scheme.
>  * Utilities::                   Package management commands.
>  * System Configuration::        Configuring the operating system.
> +* Home Configuration::          Configuring the home environment.
>  * Documentation::               Browsing software user manuals.
>  * Installing Debugging Files::  Feeding the debugger.
>  * Security Updates::            Deploying security fixes quickly.
> @@ -328,6 +330,10 @@ System Configuration
>  * Running Guix in a VM::        How to run Guix System in a virtual machine.
>  * Defining Services::           Adding new service definitions.
>  
> +Home Environment Configuration
> +
> +* Invoking guix home::          Instantiating a home environment configuration.
> +
>  Services
>  
>  * Base Services::               Essential system services.
> @@ -35090,6 +35096,687 @@ system:
>  This service represents PID@tie{}1.
>  @end defvr
>  
> +@node Home Configuration
> +@chapter Home Configuration
> +@cindex home configuration
> +Guix supports declarative configuration of @dfn{home environment} by

@dfn{home environments} (plural form)

> +utilizing the configuration mechanism described in the previous chapter
> +(@pxref{Defining Services}), but for user's home. It works both on Guix
                                                    ^
Double spacing.

“users's home” sounds kind of vague; maybe “user's dotfiles and
packages”.

> +System and foreign distros and allows users to declare all the packages

Maybe “packages and services” instead of just “packages”?

> +that should be installed and configured for the user.  After that, such

It’s not super clear what “After that” is referring to.  Maybe

  Once a user has written a file containing a home environment

?

> +a @dfn{home configuration} can be @dfn{instantiated} by an unprivileged

What is the difference between “home environment” and “home
configuration”?

> +user with the @command{guix home} command (@pxref{Invoking guix home}).
> +@c Maybe later, it will be possible to make home configuration a part of
> +@c system configuration to make everything managed by guix system.
> +
> +User's home environment usually consists of three basic parts: software,

“The users's home environment”

> +configuration and state.  Software in mainstream distros are usually
                ^
Missing comma.

> +installed system-wide, but with GNU Guix most software packages can be
> +installed on a per-user basis without needing root privileges, and are
> +thus considered part of the user’s @dfn{home environment}.  Packages on
> +their own not very useful in many cases, because often they require some
> +additional configuration, usually config files that reside in
> +@env{XDG_CONFIG_HOME} (default value is @file{~/.config}) or other

Maybe just “(@file{~/.config} by default)” instead of “(default value is
@file{~/.config})”?

> +directories.  Everything else can be considered state, like media files,
> +application databases, and logs.
> +
> +Using Guix for managing home environments provides a number of
> +advantages:
> +
> +@itemize
> +
> +@item All software can be configured in one language (Guile Scheme),
> +this gives users to ability to share values between configurations of
                    ^^
s/to/the

> +different programs and other benifits.

“and other benifits” doesn’t really fit here; I suggest we remove it.

> +@item A well-defined home environment is self-contained and can be
> +created in a declarative and reproducible way.  There is no need to grab
> +external binaries or manually edit some configuration file.

I would personally use “---” instead of putting a period and starting a
new sentence.

  @item A well-defined home environment is self-contained and can be
  created in a declarative and reproducible way---there is no need to grab
  external binaries or manually edit some configuration file.

> +@item After every @command{guix home reconfigure} invocation, a new home
> +environment generation will be created.  This means that users can
> +rollback to a previous home environment generation so they don’t have to
> +worry about breaking their configuration.
> +
> +@item It is possible to manage stateful data with Guix Home, this
> +includes the ability to automatically clone Git repositories on the
> +initial setup of the machine, and periodically running commands like
> +@command{rsync} to sync data with another host.  This functionality is
> +still in an experimental stage, though.
> +
> +@end itemize
> +
> +@menu
> +* Declaring the Home Environment::  Customizing your Home.
> +* Configuring the Shell::     Enabling home environment.
> +* Home Services::             Specifying home services.
> +* Invoking guix home::        Instantiating a home configuration.
> +@end menu
> +
> +@node Declaring the Home Environment
> +@section Declaring the Home Environment
> +The home environment is configured by providing @code{home-environment}
                                                  ^
Missing “a”

> +declaration in a file that can be passed to the @command{guix home}
> +command (@pxref{Invoking guix home}).  A simple setup can include Bash
> +and custom text configuration, like in the example below.  Don't be
             ^
Missing “a” :-)

> +afraid to declare home environment parts, which overlaps with your
> +current dotfiles, before installing any configuration files Guix Home
                                                              ^
Missing comma.

> +will back up existing config files to a separate place in the home
> +folder.
> +
> +@quotation Note
> +It is highly recommended that you manage your shell or shells with Guix
> +Home, because it will make sure that all the necessary scripts are
> +sourced by shell configuration file.  Otherwise you will need to do it
             ^
Missing “the”

> +manually. (@pxref{Configuring the Shell}).
> +@end quotation
> +
> +@findex home-environment
> +@lisp
> +@include he-config-bare-bones.texi
> +@end lisp
> +
> +The @code{packages} field should be self-explanatory, it will install
> +the list of packages into the user's profile.  The most important field
> +is @code{services}, it contains a list of @dfn{home services}, which are
> +the basic building blocks of a home environment.
> +
> +There is no daemon (at least not necessary) related to home service,

s/necessary/necessarily (adverb form)

s/service/services (plural form)

> +it's just an element that is used to declare part of home environment
> +and extend other parts of it.

I don’t quite understand this part.

> The extension mechanism discussed in the
> +previous chapter (@pxref{Defining Services}) should not be confused with
> +@ref{Shepherd Services}.  Using this extension mechanism and some Scheme
> +code that glues things together gives a lot of freedom in declaring of
> +very custom home environments.

I would rephrase the last sentence

  Using this extension mechanism and some Scheme code that glues things
  together giver the user the freedom to declare their own, very custom,
  home environment.
  
> +@node Configuring the Shell
> +@section Configuring the Shell
> +This section is safe to skip if your shell or shells are managed by
> +Guix Home.  Otherwise, read it carefully.
> +
> +There are a few scripts that must be evaluated by a login shell to
> +activate the home environment.  The shell startup files only read by
> +login shells often have @code{profile} suffix.  For more information
> +about login shells see @ref{Invoking Bash,,, bash, The GNU Bash
> +Reference Manual} and see @ref{Bash Startup Files,,, bash, The GNU Bash
> +Reference Manual}.
> +
> +The first script is @file{setup-environment}, which sets all the

“The first script that needs to be sourced is @file{setup-environment}”

> +necessary environment variables (including variables declared by user)
                                                                   ^
Missing “the”

> +and the second one is @file{on-first-login}, which starts Shepherd for
> +the current user and performs actions declared by other home services
> +extending @code{home-run-on-first-login-service-type}.

s/extending/that extends/

> +Guix Home will always create @file{~/.profile}, which contains the
> +following lines:
> +
> +@example
> +HOME_ENVIRONMENT=$HOME/.guix-home
> +. $HOME_ENVIRONMENT/setup-environment
> +$HOME_ENVIRONMENT/on-first-login
> +@end example
> +
> +That makes POSIX compliant login shells activate the home environment.

s/That/This/

> +However, in most cases this file won't be read by most modern shells,
> +because they are run in non POSIX mode by default and have their own
> +@file{*profile} startup files.  For example Bash will prefer
> +@file{~/.bash_profile} in case it exists and only if it doesn't will it
> +fallback to @file{~/.profile}.  Zsh (if no additional options specified)
                                                                ^
Missing “are”

> +will ignore @file{~/.profile}, even if @file{~/.zprofile} doesn't exist.
> +
> +To make your shell respect @file{~/.profile}, add @code{. ~/.profile} or
> +@code{source ~/profile} to the startup file for the login shell.  In
> +case of Bash, it is @file{~/.bash_profile}, and in case of Zsh, it is
> +@file{~/.zprofile}.
> +
> +@quotation Note
> +This step is only required if your shell is NOT managed by Guix Home.
> +Otherwise, everything will be done automatically.
> +@end quotation
> +
> +@node Home Services
> +@section Home Services
> +@cindex home services
> +
> +A @dfn{home service} is not necessarily something that has a daemon and
> +is managed by Shepherd (@pxref{Jump Start,,, shepherd, The GNU Shepherd
> +Manual}), in most cases it doesn't.  It's a simple building block of
> +home environment, often declaring a set of packages to be installed in
  ^
Missing “the”

> +the home environment profile, a set of config files to be symlinked into
> +@env{XDG_CONFIG_HOME} (default value is @file{~/.config}) and
                                                            ^
“(@file{~/.config} by default)”

Missing comma.

> +environment variables to be set by a login shell.
> +
> +There is a service extension mechanism (@pxref{Service Composition}),
> +which allows home services to extend other home services and utilize
> +capabilities they provide, for example: declare mcron jobs
> +(@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home
> +Service}, declare daemons by extending @ref{Shepherd Home Service}, add
> +commands, which will be invoked on by the Bash by extending
> +@ref{Shells Home Services, @code{home-bash-service-type}}.

I would use semicolons instead of commas for separating the clauses.

  There is a service extension mechanism (@pxref{Service Composition})
  which allows home services to extend other home services and utilize
  capabilities they provide; for example: declare mcron jobs
  (@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home
  Service}; declare daemons by extending @ref{Shepherd Home Service}; add
  commands, which will be invoked on by the Bash by extending
  @ref{Shells Home Services, @code{home-bash-service-type}}.

> +The good way to discover avaliable home services is using the

I would “A” instead of “The”, which sounds a bit authoritative.

> +@command{guix home search} command (@pxref{Invoking guix home}).  After
> +the required home services are found, include its module with the
> +@code{use-modules} form (@pxref{use-modules,, Using Guile Modules,
> +guile, The GNU Guile Reference Manual}), or the @code{#:use-modules}
> +directive (@pxref{define-module,, Creating Guile Modules, guile, The GNU
> +Guile Reference Manual}) and declare a home service using the
> +@code{service} function, or extend a service type by declaring a new
> +service with the @code{simple-service} procedure from @code{(gnu
> +services)}.
> +
> +@menu
> +* Essential Home Services::  Environment variables, packages, on-* scripts.
> +* Shells: Shells Home Services.          POSIX shells, Bash, Zsh.
> +* Mcron: Mcron Home Service.             Scheduled User's Job Execution.
> +* Shepherd: Shepherd Home Service.       Managing User's Daemons.
> +@end menu
> +@c In addition to that Home Services can provide
> +
> +@node Essential Home Services
> +@subsection Essential Home Services
> +There are a few essential services defined in @code{(gnu
> +home-services)}, they are mostly for internal use and are required to
> +build a home environment, but some of them will be useful for the end
> +user.
> +
> +@cindex environment variables
> +
> +@defvr {Scheme Variable} home-environment-variables-service-type
> +The service of this type will be instantiated by every home environment
> +automatically by default, there is no need to define it, but someone may
> +want to extend it with a list of pairs to set some environment
> +variables.
> +
> +@lisp
> +(list ("ENV_VAR1" . "value1")
> +      ("ENV_VAR2" . "value2"))
> +@end lisp
> +
> +The easiest way to extend service type, without defining new service
                            ^
Missing “a”

> +type is to use the @code{simple-service} helper from @code{(gnu
> +services)}.
> +
> +@lisp
> +(simple-service 'some-useful-env-vars-service
> +		home-environment-variables-service-type
> +		`(("LESSHISTFILE" . "$XDG_CACHE_HOME/.lesshst")
> +                  ("SHELL" . ,(file-append zsh "/bin/zsh"))
> +                  ("USELESS_VAR" . #f)
> +                  ("_JAVA_AWT_WM_NONREPARENTING" . #t)))
> +@end lisp
> +
> +If you include such service to you home environment definition, it will

s/to/in/

> +add the following content to the @file{setup-environment} script (which
> +is expected to be sourced by the login shell):
> +
> +@example
> +export LESSHISTFILE=$XDG_CACHE_HOME/.lesshst
> +export SHELL=/gnu/store/2hsg15n644f0glrcbkb1kqknmmqdar03-zsh-5.8/bin/zsh
> +export _JAVA_AWT_WM_NONREPARENTING
> +@end example
> +
> +@quotation Note
> +Make sure that module @code{(gnu packages shells)} is imported with
> +@code{use-modules} or any other way, this namespace contains definition
> +of @code{zsh} packages, which is used in the example above.

“this namespace contains the definition of the @code{zsh} package, …”

> +The key of the association list (@pxref{Association Lists, alists,
> +Association Lists, guile, The GNU Guile Reference manual}) is always a
> +string, the value can be a string, string-valued gexp
> +(@pxref{G-Expressions}) file-like object (@pxref{G-Expressions,
> +file-like object}) or boolean. For gexps, the variable will be set to

Maybe use ‘car’/‘cdr’ instead of ‘key’/‘value’?  At first I though that
“the value can be a string, …” was referring to the previous clause,
which obviously doesn’t make sense.  ;-)

> +the value of the gexp; for file-like objects, it will be set to the path
> +of the file in the store (@pxref{The Store}); for @code{#t}, it will
> +export the variable without any value; and for @code{#f}, it will omit
> +variable.
> +
> +@end defvr
> +
> +@defvr {Scheme Variable} home-profile-service-type
> +The service of this type will be instantiated by every home environment
> +automatically, there is no need to define it, but you may want to extend
> +it with a list of packages if you want to install additional packages
> +into your profile.  Other services, which need to make some programs
> +avaliable to the user will also extend this service type.
> +
> +The extension value is just a list of packages:
> +
> +@lisp
> +(list htop vim emacs)
> +@end lisp
> +
> +The same approach as @code{simple-service} (@pxref{Service Reference,
> +simple-service}) for @code{home-environment-variables-service-type} can
> +be used here, too.  Make sure that modules containing the specified
> +packages are imported with @code{use-modules}.  To find a package or
> +information about its module use @command{guix search} (@pxref{Invoking
> +guix package}).  Alternatively, @code{specification->package} can be
> +used to get the package record from string without importing related
> +module.
> +@end defvr
> +
> +There are few more essential services, but users are not expected to
> +extend them.
> +
> +@defvr {Scheme Variable} home-service-type
> +The root of home services DAG, it generates a folder, which later will be
> +symlinked to @file{~/.guix-home}, it contains configurations,
> +profile with binaries and libraries, and some necessary scripts to glue
> +things together.
> +@end defvr
> +
> +@defvr {Scheme Variable} home-run-on-first-login-service-type
> +The service of this type generates a Guile script, which is expected to
> +be executed by the login shell.  It is only executed if the special flag
> +file inside @env{XDG_RUNTIME_DIR} hasn't been created, this prevents
> +redundant executions of the script if multiple login shells are spawned.
> +
> +It Can be extended with a gexp.  However, to autostart an application,

s/Can/can/

> +users SHOULD NOT use this service, in most cases it's better to extend

Maybe @emph{should not} instead?

> +@code{home-shpeherd-service-type} with a Shepherd service
> +(@pxref{Shepherd Services}), or extend the shell's startup file with
> +required command using the appropriate service type.
> +@end defvr
> +
> +@defvr {Scheme Variable} home-activation-service-type
> +The service of this type generates a guile script, which runs on every
> +@command{guix home reconfigure} invocation or any other action, which
> +leads to activation of home environment.

“leads to the activation of the home environment.”

> +@end defvr
> +
> +@node Shells Home Services
> +@subsection Shells
> +
> +@cindex shell
> +@cindex login shell
> +@cindex interactive shell
> +@cindex bash
> +@cindex zsh
> +
> +Shells play a quite important role in the environment initialization
> +process, you can configure them manually as described in section
> +@ref{Configuring the Shell}, but the recommended way is to use home services
> +listed below.  It's both easier and more reliable.
> +
> +Each home environment instantiates
> +@code{home-shell-profile-service-type}, which creates a
> +@file{~/.profile} startup file for all POSIX-compatible shells.  This
> +file contains all the necessary steps to properly initialize the
> +environment, but many modern shells like Bash or Zsh prefer their own
> +startup files, that's why the respective home services
> +(@code{home-bash-service-type} and @code{home-zsh-service-type}) ensure
> +that @file{~/.profile} is sourced by @file{~/.bash_profile} and
> +@file{~/.zprofile}, respectively.
> +
> +@subsubheading Shell Profile Service
> +
> +Available @code{home-shell-profile-configuration} fields are:

This section should be re-generated using the updated
‘generate-documenation’ procedure (see commit
ad945029a2dbd1fb741be573f13e42c061e72d0f).

> +
> +@deftypevr {@code{home-shell-profile-configuration} parameter} text-config profile
> +@code{home-shell-profile} is instantiated automatically by
> +@code{home-environment}, DO NOT create this service manually, it can
> +only be extended.
> +
> +@code{profile} is a list of strings or gexps, which will go to
> +@file{~/.profile}.  By default @file{~/.profile} contains the
> +initialization code, which have to be evaluated by login shell to make
> +home-environment's profile avaliable to the user, but other commands can
> +be added to the file if it is really necessary.
> +
> +In most cases shell's configuration files are preferred places for
> +user's customizations.  Extend home-shell-profile service only if you
> +really know what you do.
> +
> +Defaults to @samp{()}.
> +
> +@end deftypevr
> +
> +@subsubheading Bash Home Service
> +
> +Available @code{home-bash-configuration} fields are:
> +
> +@deftypevr {@code{home-bash-configuration} parameter} package package
> +The Bash package to use.
> +
> +@end deftypevr
> +
> +@deftypevr {@code{home-bash-configuration} parameter} boolean guix-defaults?
> +Add sane defaults like reading @file{/etc/bashrc}, coloring output for
> +@code{ls} provided by guix to @file{.bashrc}.
> +
> +Defaults to @samp{#t}.
> +
> +@end deftypevr
> +
> +@deftypevr {@code{home-bash-configuration} parameter} text-config bash-profile
> +List of strings or gexps, which will be added to @file{.bash_profile}.
> +Used for executing user's commands at start of login shell (In most
> +cases the shell started on tty just after login).  @file{.bash_login}
> +won't be ever read, because @file{.bash_profile} always present.
> +
> +Defaults to @samp{()}.
> +
> +@end deftypevr
> +
> +@deftypevr {@code{home-bash-configuration} parameter} text-config bashrc
> +List of strings or gexps, which will be added to @file{.bashrc}.  Used
> +for executing user's commands at start of interactive shell (The shell
> +for interactive usage started by typing @code{bash} or by terminal app
> +or any other program).
> +
> +Defaults to @samp{()}.
> +
> +@end deftypevr
> +
> +@deftypevr {@code{home-bash-configuration} parameter} text-config bash-logout
> +List of strings or gexps, which will be added to @file{.bash_logout}.
> +Used for executing user's commands at the exit of login shell.  It won't
> +be read in some cases (if the shell terminates by exec'ing another
> +process for example).
> +
> +Defaults to @samp{()}.
> +
> +@end deftypevr
> +
> +@subsubheading Zsh Home Service
> +
> +Available @code{home-zsh-configuration} fields are:
> +
> +@deftypevr {@code{home-zsh-configuration} parameter} package package
> +The Zsh package to use.
> +
> +@end deftypevr
> +
> +@deftypevr {@code{home-zsh-configuration} parameter} boolean xdg-flavor?
> +Place all the configs to @file{$XDG_CONFIG_HOME/zsh}.  Makes
> +@file{~/.zshenv} to set @env{ZDOTDIR} to @file{$XDG_CONFIG_HOME/zsh}.
> +Shell startup process will continue with
> +@file{$XDG_CONFIG_HOME/zsh/.zshenv}.
> +
> +Defaults to @samp{#t}.
> +
> +@end deftypevr
> +
> +@deftypevr {@code{home-zsh-configuration} parameter} text-config zshenv
> +List of strings or gexps, which will be added to @file{.zshenv}.  Used
> +for setting user's shell environment variables.  Must not contain
> +commands assuming the presence of tty or producing output.  Will be read
> +always.  Will be read before any other file in @env{ZDOTDIR}.
> +
> +Defaults to @samp{()}.
> +
> +@end deftypevr
> +
> +@deftypevr {@code{home-zsh-configuration} parameter} text-config zprofile
> +List of strings or gexps, which will be added to @file{.zprofile}.  Used
> +for executing user's commands at start of login shell (In most cases the
> +shell started on tty just after login).  Will be read before
> +@file{.zlogin}.
> +
> +Defaults to @samp{()}.
> +
> +@end deftypevr
> +
> +@deftypevr {@code{home-zsh-configuration} parameter} text-config zshrc
> +List of strings or gexps, which will be added to @file{.zshrc}.  Used
> +for executing user's commands at start of interactive shell (The shell
> +for interactive usage started by typing @code{zsh} or by terminal app or
> +any other program).
> +
> +Defaults to @samp{()}.
> +
> +@end deftypevr
> +
> +@deftypevr {@code{home-zsh-configuration} parameter} text-config zlogin
> +List of strings or gexps, which will be added to @file{.zlogin}.  Used
> +for executing user's commands at the end of starting process of login
> +shell.
> +
> +Defaults to @samp{()}.
> +
> +@end deftypevr
> +
> +@deftypevr {@code{home-zsh-configuration} parameter} text-config zlogout
> +List of strings or gexps, which will be added to @file{.zlogout}.  Used
> +for executing user's commands at the exit of login shell.  It won't be
> +read in some cases (if the shell terminates by exec'ing another process
> +for example).
> +
> +Defaults to @samp{()}.
> +
> +@end deftypevr
> +
> +@node Mcron Home Service
> +@subsection Scheduled User's Job Execution
> +
> +@cindex cron
> +@cindex mcron
> +@cindex scheduling jobs
> +
> +mcron info here
> +
> +@node Shepherd Home Service
> +@subsection Managing User's Daemons
> +shepherd info here
> +
> +@node Invoking guix home
> +@section Invoking @code{guix home}
> +
> +Once you have written a home environment declaration (@pxref{Declaring
> +the Home Environment,,,,}, it can be @dfn{instantiated} using the
> +@command{guix home} command.  The synopsis is:
> +
> +@example
> +guix home @var{options}@dots{} @var{action} @var{file}
> +@end example
> +
> +@var{file} must be the name of a file containing a
> +@code{home-environment} declaration.  @var{action} specifies how the
> +home environment is instantiated, but there are few auxuliary actions,
                                                                        ^
This comma isn’t needed.

> +which don't instantiate it.  Currently the following values are
> +supported:
> +
> +@table @code
> +@item search
> +Display available home service type definitions that match the given
> +regular expressions, sorted by relevance:
> +
> +@cindex shell
> +@cindex shell-profile
> +@cindex bash
> +@cindex zsh
> +@example
> +$ guix home search shell
> +name: home-shell-profile
> +location: gnu/home-services/shells.scm:73:2
> +extends: home-files
> +description: Create `~/.profile', which is used for environment initialization
> ++ of POSIX compatible login shells.  Can be extended with a list of strings or
> ++ gexps.
> +relevance: 6
> +
> +name: home-zsh-plugin-manager
> +location: gnu/home-services/shellutils.scm:28:2
> +extends: home-zsh home-profile
> +description: Install plugins in profile and configure Zsh to load them.
> +relevance: 1
> +
> +name: home-zsh-direnv
> +location: gnu/home-services/shellutils.scm:69:2
> +extends: home-profile home-zsh
> +description: Enables `direnv' for `zsh'.  Adds hook to `.zshrc' and installs a
> ++ package in the profile.
> +relevance: 1
> +
> +name: home-zsh-autosuggestions
> +location: gnu/home-services/shellutils.scm:43:2
> +extends: home-zsh-plugin-manager home-zsh
> +description: Enables Fish-like fast/unobtrusive autosuggestions for `zsh' and
> ++ sets reasonable default values for some plugin's variables to improve perfomance
> ++ and adjust behavior: `(history completion)' is set for strategy, manual rebind
> ++ and async are enabled.
> +relevance: 1
> +
> +name: home-zsh
> +location: gnu/home-services/shells.scm:236:2
> +extends: home-files home-profile
> +description: Install and configure Zsh.
> +relevance: 1
> +
> +name: home-bash
> +location: gnu/home-services/shells.scm:388:2
> +extends: home-files home-profile
> +description: Install and configure Bash.
> +relevance: 1
> +
> +@dots{}
> +@end example
> +
> +As for @command{guix package --search}, the result is written in
> +@code{recutils} format, which makes it easy to filter the output
> +(@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
> +
> +@item reconfigure
> +Build the home environment described in @var{file}, and switch to it.
> +Switching means that activation script will be evaluated and (in basic
                       ^
Missing “the”

> +scenario) symlinks to configuration files generated from
> +@code{home-environment} declaration will be created in @file{~}.  If the
> +file with the same path already exists in home folder it will be moved
> +to @file{~/TIMESTAMP-guix-home-legacy-configs-backup}, where TIMESTAMP
> +is a current UNIX epoch time.
> +
> +@c @footnote{This action (and the related actions
> +@c @code{switch-generation} and @code{roll-back}) are usable after home
> +@c environmet initialized.}.

Why is this commented out?

> +@quotation Note
> +It is highly recommended to run @command{guix pull} once before you run
> +@command{guix home reconfigure} for the first time (@pxref{Invoking guix
> +pull}).
> +@end quotation
> +
> +This effects all the configuration specified in @var{file}.
> +The command starts shepherd services specified in @var{file} that are not

s/shepherd/Shepherd

> +currently running; if a service is currently running this command will
                                                       ^
Missing comma

> +arrange for it to be upgraded the next time it is stopped (e.g.@: by
> +@code{herd stop X} or @code{herd restart X}).

I would rephrase this part

  if a service is currently running, this command will make it so that
  the service gets updated the next time it is stopped (e.g., by
  @command{herd stop X} or @command{herd restart X}).

> +This command creates a new generation whose number is one greater than
> +the current generation (as reported by @command{guix home
> +list-generations}).  If that generation already exists, it will be
> +overwritten.  This behavior mirrors that of @command{guix package}
> +(@pxref{Invoking guix package}).
> +
> +@cindex provenance tracking, of the home environment
> +Upon completion, the new home is deployed under @file{~/.guix-home}.
> +This directory contains @dfn{provenance meta-data}: the list of channels
> +in use (@pxref{Channels}) and @var{file} itself, when available.  You
> +can view it by running:

s/it/the provenance information/

Excited to see Guix Home get merged soon!  :-)