From mboxrd@z Thu Jan  1 00:00:00 1970
From: Nils Gillmann <ng0@n0.is>
Subject: Re: [doc RFC] Tame the Guix profile blizzard?
Date: Tue, 10 Jul 2018 08:54:26 +0000
Message-ID: <20180710085426.nl3mzzbv7clkszm4@abyayala>
References: <87tvp8q8pj.fsf@gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
Return-path: <guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org>
Received: from eggs.gnu.org ([2001:4830:134:3::10]:49551)
	by lists.gnu.org with esmtp (Exim 4.71) (envelope-from <ng0@n0.is>)
	id 1fcoP6-0001kH-Q4
	for guix-devel@gnu.org; Tue, 10 Jul 2018 04:53:49 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <ng0@n0.is>) id 1fcoP5-0002Jt-Tu
	for guix-devel@gnu.org; Tue, 10 Jul 2018 04:53:48 -0400
Received: from conspiracy.of.n0.is ([2a01:4f8:1c0c:7ad0::1]:37132)
	by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32)
	(Exim 4.71) (envelope-from <ng0@n0.is>) id 1fcoP5-0002IN-IN
	for guix-devel@gnu.org; Tue, 10 Jul 2018 04:53:47 -0400
Content-Disposition: inline
In-Reply-To: <87tvp8q8pj.fsf@gmail.com>
List-Id: "Development of GNU Guix and the GNU System distribution."
	<guix-devel.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/guix-devel>,
	<mailto:guix-devel-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/guix-devel/>
List-Post: <mailto:guix-devel@gnu.org>
List-Help: <mailto:guix-devel-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/guix-devel>,
	<mailto:guix-devel-request@gnu.org?subject=subscribe>
Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org
Sender: "Guix-devel" <guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org>
To: George Clemmer <myglc2@gmail.com>
Cc: guix-devel <guix-devel@gnu.org>

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
>