Subject: [bug#53447] [PATCH] doc: Unset environment variables considered harmful

From: Ludovic Courtès <[email-masked]>
Date: Sat, 22 Jan 2022 17:04:25 +0100

Hi Liliana,

Liliana Marie Prikler <[email-masked]> skribis:

> * doc/guix.texi (Application Setup): Add subsection for implicit environment
> variables.
> ---
>  doc/guix.texi | 27 +++++++++++++++++++++++++++
>  1 file changed, 27 insertions(+)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 912a8e3c5a..805e3b611f 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -2023,6 +2023,33 @@ want to avoid auto-loading the Emacs packages installed with Guix, you
>  can do so by running Emacs with the @option{--no-site-file} option
>  (@pxref{Init File,,, emacs, The GNU Emacs Manual}).
>  
> +@subsection Implicit Environment Variables
> +
> +Many environment variables are defined in a way that assumes a certain
> +default value, even if unset.  For example, bash uses the current
> +working directory as @env{PATH} if unset, or @env{XDG_CONFIG_HOME}
> +expands to @file{$HOME/.config}.  Some of these defaults remain the same
> +whether a package is used through Guix or not---however, environment
> +variables referring to @file{/etc} or @file{/usr} typically have their
> +meaning subtly changed in Guix.  An application installed via Guix might
> +instead look up files in its own @file{etc} structure, or (if a
> +search-path was specified) even override the default for packages from
> +the foreign distro.

I think I miss some context: what concrete problem is this trying to
solve?  What is it telling me to do?

I wonder to what extent this is actionable for a user, due to wording
that leaves it up to the reader to figure out how this applies to them:

  “Many environment variables”
  “a certain default value”
  “Some of these”
  “An application installed via Guix might”
  “problems coming from such implicitly defined”
  …

I think the “Application Setup” section should be as concrete as
possible, with clear instructions (“If X then type Y”), possibly
followed by explanations that curious readers can read and that others
can skip.

WDYT?

Ludo’.