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

["Ludovic Courtès" <ludo@gnu.org>]

[-- Attachment #1: Type: text/plain, Size: 1254 bytes --]

Hello,

zimoun <zimon.toutoune@gmail.com> skribis:

> Effectively, profiles is not explicitly defined but implicitly, for
> instance:
>
> <https://guix.gnu.org/manual/devel/en/guix.html#Features>
>
> Otherwise, the most explicit definition is in the Cookbook:
>
>         Guix provides a very useful feature that may be quite foreign to
>         newcomers: profiles. They are a way to group package
>         installations together and all users on the same system are free
>         to use as many profiles as they want.
>
> <https://guix.gnu.org/cookbook/en/html_node/Guix-Profiles-in-Practice.html>

[...]

> <https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html>
>
> And from this old time, I remember that examples really helps, for
> instance.
>
> <https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-environments>.
>
> Therefore, the section «Getting Started» could be a bit extended with a
> paragraph about Profiles and one or two examples.  WDYT?
>
> <https://guix.gnu.org/manual/devel/en/guix.html#Getting-Started>

Thanks for the pointers!  How about these changes to “Getting Started”
and “Invoking guix package”?

Ludo’.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-patch, Size: 1372 bytes --]

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
 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: