Re: [PATCH] doc: Clarify need to update search paths on foreign distro (was Re: Feedback of the GNU Guix manual)

[Matt]

---- On Sat, 11 May 2024 10:14:15 +0200  pelzflorian (Florian Pelz)  wrote ---
> Instead, there already is advice for .config/guix/current documented in
> the Guix manual’s Getting Started section.  The advice should be a
> cross-reference that users should follow the steps from Getting Started,
> so search paths are set up properly instead of advising to set PATH and
> INFOPATH.
>
> The advice of setting PATH really should go away.

Sorry for the late and lengthy reply.  Life is life and when I returned to the 
issue I noticed that the problem is really that the concept of profiles could 
use some revision within the manual.  That will make for a rather complex 
change set.  I hoped to have one ready yet, again, life is life.  So, here are 
my thoughts and, after hearing yours, I can put together  the necessary changes 
if my points hold.

I see two fundamental issues:

1. should there be a single point of reference for the concept of "profile" and 
where should it be?

2. what information about profiles is relevant to addressing the reported issue 
and where is it?

We'll need to discuss possible solutions because, unfortunately, the concept of 
"profiles" isn't conveniently documented.

ISSUE 1 - should there be a single point of reference for the concept of 
"profile" and where should it be?

tl;dr create a new subsection for the profile concept

I find your suggestion reasonable; document concepts in a single place and then 
favor references to that place.  Unfortunately, there is currently no single 
place of reference for the concept of "profile".

Important facts about profiles are spread across the following sections (a list 
is given at the end of this section):

- Section 4: Getting Started (1)
- Section 5.1: Features (and isn't indexed there) (1)
- Section 5.2: Invoking 'guix package' (13)
- Section 5.7: Invoking 'guix pull' (3)
- Section 8.8: Search Paths (1)
- Section 9.1: Invoking 'guix build' (1)
- Section 11.3: operating-system Reference (2), and
- Section 11.19.3: Service Reference (1)

Should we make Section 4: Getting Started the common reference point?

I say no.  The Getting Started section is intended to help readers get started 
with Guix and get a feel of what it's like.  Therefore, it should contain a 
simple how-to with minimal explanation.  As the GNU Press Styleguide[1] advises,

"Move slowly. Do not impose too much of a cognitive load at once on the reader."

I think the Getting Started section has too much profile information in it as 
is.  For example, GUIX_PYTHONPATH is a convention, hard-coded into package 
definitions whereas GUIX_PROFILE is a literary shorthand for the concept that 
multiple profiles may exist and that the profile is the $HOME/.guix-profile in 
this case.

Of all the sections that discuss profiles, Invoking 'guix package' contains the 
most information (13 facts).  It's also given as the point of reference by 5 
other sections:

1. Invoking 'guix pull' (twice)
2. Invoking 'guix shell'
3. Invoking 'guix environment'
4. Invoking 'guix build'
5. operating-system Reference

Should we make Invoking 'guix package' be the common reference point for 
profiles?

Again, I say no. AFAIU, profiles have two forms: a system profile, sometimes 
called the global profile, which manages Guix itself and user profiles, 
including "default" or "current", which dictate package accessibility.  While 
system and user profiles "work exactly" like each other (see Invoking guix 
pull), there are separate commands for each: 'guix package' is for user 
profiles and 'guix pull' is for the system profile.  It's easy to confuse all 
this.  Therefore, it would be better to have a separate section that explains 
profiles and let Invoking 'guix package' and Invoking 'guix pull' focus on the 
command options.

The best common reference point for profiles is in a new section just below 
Section 5.1: Features. As the Styleguide[1] says,

"Put important notes to the reader in subsections of their own. This tells the 
reader the notes really are important."

Profiles are first introduced in Section 4: Getting Started.  It does a good 
job introducing the idea and could actually provide less information.  The 
concept, however, is first explained in Section 5.1: Features.  The majority of 
Features is about how profiles are useful and a core concept of Guix.  I think 
we could switch the focus of Features to be about the benefits of the store, 
the symlink forest, transactions, control of the build environment, and 
provenance tracking and move the explanation and details of profiles to a new 
subsection.

Information about profiles grouped by section:

- Getting Started
  + A profile is a directory containing installed packages
- Features (not indexed)
  + A profile is a reference to the store kept in each user's home
    directory managed by 'guix package'
- Invoking 'guix package'
  + a profile is a directory of installed packages
  + profiles exist per user
  + there exists a "default" profile
  + guix package operations create and modify profiles
  + profiles are created in $HOME/.guix-profile
  + $HOME/.guix-profile is a symlink
  + In a multi-user setup, user profiles are stored in a place
    registered as a "garbage-collector root"
  + there is a notion of "current profile"
  + profiles have generations
  + generations within a profile are linear, starting with a "zeroth
    generation", which contains no files apart from its own metadata.
  + multiple profiles may be referenced at a time
  + removing a profile means removing the symlink previously specified
    by "guix project --profile" as well as any corresponding '-*-link'
    suffixed symlinks
  + profiles are handles on state (that is, the state of which
    software is installed and available)
- Invoking guix pull
  + the latest Guix is determined by a profile
  + 'guix pull' and 'guix package' both create profiles and how these
    profiles work is similar
  + there are two types of profiles; those managed by 'guix pull' and
    those managed by 'guix package'
- Search Paths
  + installing packages in the default profile creates the file
    '~/.guix-profile/etc/profile' which defines search path
    environment variables
- Invoking 'guix build'
  + modifying the user's profile is the job of 'guix package'
- operating-system Reference
  + the global profile is accessible at '/run/current-system/profile'
  + it is good practice to install non-core utilities in user profiles
- Service Reference
  + the "system profile" is the programs under
    '/run/current-system/profile'

ISSUE 2- what information about profiles is relevant to addressing the reported 
issue and where is it?

tldr; we should create a new subsection rather than expand Getting Started

I'm able to reduce the information necessary to address the reported issue to:

1. the user environment must be configured so that the shell and other 
applications can find software installed with Guix
2. Guix provides a file, $GUIX_PROFILE/etc/profile, to configure the user 
environment
3. $GUIX_PROFILE/etc/profile is created for *each* profile
4. $GUIX_PROFILE/etc/profile must be sourced

Section 4: Getting Started explicitly states the first and forth points and 
implies the second.  AFAICT, the third isn't actually in the manual (although 
it is in the Cookbook)!

I think explaining $GUIX_PROFILE/etc/profile in more detail within Getting 
Started wouldn't make sense.  Therefore, because of this, and the points I made 
above, we should consider breaking out profiles into their own section.

[1] https://www.fsf.org/licensing/gnu-press/GNU-Press-styleguide.pdf