[doc RFC] Tame the Guix profile blizzard?

[doc RFC] Tame the Guix profile blizzard?

[George Clemmer]

ISTM our doc is a veritable "Profile Blizzard."


The term occurs 173 times in guix.texi


The "user profile" is referred to in multiple ways:

 (guix) Application Setup: "your Guix profile"

 (guix) Features: 'own “profile”', "per-user profiles", "their profile"

 (guix) Invoking guix package: "user’s own profile", "user’s default
 profile", ‘$HOME/.guix-profile’

 (guix) Invoking guix environment: "package profile"


The "system profile" is referred to in multiple ways:

 (guix) Using the Configuration System: "Globally-installed packages"

 (guix) operating-system Reference: "global profile",
 ‘/run/current-system/profile’

 (guix) Networking Services: "system profile"


An unnamed type of "environment profile" is produced by 'guix
environment'

 (guix) Invoking guix environment" ‘GUIX_ENVIRONMENT’ variable


An unnamed type of "custom profile" is produced by the 'guix package' -p
option.


(guix) Top mentions only an entirely different use of the term:

 * Invoking guix size::          Profiling disk usage.


(guix) Concept Index contains only (guix) Invoking guix package
references.


ISTM we can improve this situation as follows:

1) agree on a canonical term to use for the 4 types of profiles

2) update the doc accordingly

3) add a top level discussion of profiles

WDYT? - George

Re: [doc RFC] Tame the Guix profile blizzard?

[Nils Gillmann]

George Clemmer transcribed 1.4K bytes:
> ISTM our doc is a veritable "Profile Blizzard."
> 
> 
> The term occurs 173 times in guix.texi
> 
> 
> The "user profile" is referred to in multiple ways:
> 
>  (guix) Application Setup: "your Guix profile"
> 
>  (guix) Features: 'own “profile”', "per-user profiles", "their profile"
> 
>  (guix) Invoking guix package: "user’s own profile", "user’s default
>  profile", ‘$HOME/.guix-profile’
> 
>  (guix) Invoking guix environment: "package profile"
> 
> 
> The "system profile" is referred to in multiple ways:
> 
>  (guix) Using the Configuration System: "Globally-installed packages"
> 
>  (guix) operating-system Reference: "global profile",
>  ‘/run/current-system/profile’
> 
>  (guix) Networking Services: "system profile"
> 
> 
> An unnamed type of "environment profile" is produced by 'guix
> environment'
> 
>  (guix) Invoking guix environment" ‘GUIX_ENVIRONMENT’ variable
> 
> 
> An unnamed type of "custom profile" is produced by the 'guix package' -p
> option.
> 
> 
> (guix) Top mentions only an entirely different use of the term:
> 
>  * Invoking guix size::          Profiling disk usage.
> 
> 
> (guix) Concept Index contains only (guix) Invoking guix package
> references.
> 
> 
> ISTM we can improve this situation as follows:
> 
> 1) agree on a canonical term to use for the 4 types of profiles
> 
> 2) update the doc accordingly
> 
> 3) add a top level discussion of profiles

  4) before each profile kind is used for the first time,
     make use of something like this for the brief introduction
     of it again (our manual is not very long, but it is still
     long):

@cartouche
@quotation Note
In the following ``spacejump'' refers to …
@end quotation
@end cartouche

this renders at least in HTML and PDF output of texinfo. I haven't
used this very much so far.

A visual example can be found in 'Exchange', Chapter 'Configuration'
in https://docs.taler.net/

> WDYT? - George
> 

Re: [doc RFC] Tame the Guix profile blizzard?

[Ludovic Courtès]

Hi George,

George Clemmer <myglc2@gmail.com> skribis:

> ISTM we can improve this situation as follows:
>
> 1) agree on a canonical term to use for the 4 types of profiles

I think you mentioned only two types of “profiles”: one is profiles
created by ‘guix package’ or ‘guix environment’ or ‘guix system’ (they
are all the same kind of “profile”), and the other one is execution
profile, which has nothing to do with that.

So to me it seems that “profile” is in fact used fairly consistently,
isn’t it?

However…

> 3) add a top level discussion of profiles

… we surely need this.  Someone we should clearly define “profile”
somewhere upfront.  Perhaps we also need a glossary.

Thoughts?

Ludo’.

Re: [doc RFC] Tame the Guix profile blizzard?

[George Clemmer]

Ludovic Courtès writes:

> Hi George,
>
> George Clemmer <myglc2@gmail.com> skribis:
>
>> ISTM we can improve this situation as follows:
>>
>> 1) agree on a canonical term to use for the 4 types of profiles
>
> I think you mentioned only two types of “profiles”: one is profiles
> created by ‘guix package’ or ‘guix environment’ or ‘guix system’ (they
> are all the same kind of “profile”), and the other one is execution
> profile, which has nothing to do with that.
>
> So to me it seems that “profile” is in fact used fairly consistently,
> isn’t it?

Yes ... but ... the use of these profiles produces subtly different
"side-effects". Package operations cause changes in the user's "default"
profile that are immediately "used" in the user environment.  However
'guix package -p foo' does not cause foo to be "used".  'guix
environment --ad-hoc' causes the environment profile to be "added" to
the user's environment, but --pure substitutes it for both system and
"default" profiles IIUC.  IMO these could be better explained and more
easily referenced by users if we develop a structured nomenclature to
distinquish between these.

> However…
>
>> 3) add a top level discussion of profiles
>
> … we surely need this.  Someone we should clearly define “profile”
> somewhere upfront.  Perhaps we also need a glossary.

Agreed

Re: [doc RFC] Tame the Guix profile blizzard?

[George Clemmer]

Hi Nils,

Nils Gillmann <ng0@n0.is> writes:

>   4) before each profile kind is used for the first time,
>      make use of something like this for the brief introduction
>      of it again (our manual is not very long, but it is still
>      long):

I Agee.

> @cartouche
> @quotation Note
> In the following ``spacejump'' refers to …
> @end quotation
> @end cartouche
>
> this renders at least in HTML and PDF output of texinfo. I haven't
> used this very much so far.
>
> A visual example can be found in 'Exchange', Chapter 'Configuration'
> in https://docs.taler.net/

I assume you refer to the box that reads, "Note: The rationale behind
having multiple bank accounts ..." and I agreed this would work well.

- George

Re: [doc RFC] Tame the Guix profile blizzard?

[Nils Gillmann]

George Clemmer transcribed 733 bytes:
> Hi Nils,
> 
> Nils Gillmann <ng0@n0.is> writes:
> 
> >   4) before each profile kind is used for the first time,
> >      make use of something like this for the brief introduction
> >      of it again (our manual is not very long, but it is still
> >      long):
> 
> I Agee.
> 
> > @cartouche
> > @quotation Note
> > In the following ``spacejump'' refers to …
> > @end quotation
> > @end cartouche
> >
> > this renders at least in HTML and PDF output of texinfo. I haven't
> > used this very much so far.
> >
> > A visual example can be found in 'Exchange', Chapter 'Configuration'
> > in https://docs.taler.net/
> 
> I assume you refer to the box that reads, "Note: The rationale behind
> having multiple bank accounts ..." and I agreed this would work well.

yes.

> - George
>