bug#46803: User manual does not explain Profiles (nor GUIX_PROFILE)

[zimoun]

Hi Ludo,

On Sun, 14 Mar 2021 at 11:56, Ludovic Courtès <ludo@gnu.org> wrote:

> diff --git a/doc/guix.texi b/doc/guix.texi
> index 4cf241c56a..00bd087628 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -2751,7 +2751,10 @@ you can go ahead and install it (run this command as a 
> regular user,
>  guix install emacs
>  @end example
>  
> -You've installed your first package, congrats!  In the process, you've
> +You've installed your first package, congrats!  The package is now
> +visible in your default @dfn{profile}, @file{$HOME/.guix-profile}---a
> +profile is a directory containing installed packages.
> +In the process, you've

I would add a link to the index term ’profile’ in “Invoking guix package”:

--8<---------------cut here---------------start------------->8---
@cindex profile
For each user, a symlink to the user's default profile is automatically
created in @file{$HOME/.guix-profile}.  This symlink always points to the
…
--8<---------------cut here---------------end--------------->8---


>  probably noticed that Guix downloaded pre-built binaries; or, if you
>  explicitly chose to @emph{not} use pre-built binaries, then probably
>  Guix is still building software (@pxref{Substitutes}, for more info).
> @@ -3061,7 +3064,10 @@ retaining precise @dfn{provenance tracking} of the 
> software.
>  @cindex package removal
>  The @command{guix package} command is the tool that allows users to
>  install, upgrade, and remove packages, as well as rolling back to
> -previous configurations.  It operates only on the user's own profile,
> +previous configurations.  These operations work on a user
> +@dfn{profile}---a directory of installed packages.  Each user has a
> +default profile in @file{$HOME/.guix-profile}.
> +The command operates only on the user's own profile,
>  and works with normal user privileges (@pxref{Features}).  Its syntax
>  is:

I would add an index term and/or anchor and points to the option:

--8<---------------cut here---------------start------------->8---
@item --profile=@var{profile}
@itemx -p @var{profile}
Use @var{profile} instead of the user's default profile.

@var{profile} must be the name of a file that will be created upon
completion.  Concretely, @var{profile} will be a mere symbolic link
(``symlink'') pointing to the actual profile where packages are
installed:
…
--8<---------------cut here---------------end--------------->8---


Well, LGTM. :-)

Cheers,
simon