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

[Liliana Marie Prikler]

* 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.
+
+In order to avoid problems coming from such implicitly defined
+environment variables, it is best to explicitly define them somewhere.
+Startup files like @file{~/.bash_profile} are usually a good location
+to do so.  However, not all setups treat them equally.  While on Guix
+System, the user's login shell is used to spawn a graphical session,
+other distros may choose a different approach.  For instance, systemd
+is capable of spawning graphical applications in a clean environment,
+but allows said environments to be modified through an
+@file{override.conf} placed in the right directory.
+
+Regardless of which method is used to set such environment variables,
+they typically should only be set once at login.  Placing them in files
+like @file{~/.bashrc} or similar has adverse effects on other commands
+that want to create clean environments, such as @command{guix shell}.
 
 @node Upgrading Guix
 @section Upgrading Guix
-- 
2.34.0