[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[bug#50313] [PATCH] doc: Add Guix Home documentation.
From: |
Xinglu Chen |
Subject: |
[bug#50313] [PATCH] doc: Add Guix Home documentation. |
Date: |
Wed, 01 Sep 2021 13:57:32 +0200 |
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! :-)
signature.asc
Description: PGP signature