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

[Liliana Marie Prikler <liliana.prikler@gmail.com>]

Hi Ludo,

Am Samstag, dem 22.01.2022 um 17:04 +0100 schrieb Ludovic Courtès:
> Hi Liliana,
> 
> Liliana Marie Prikler <liliana.prikler@gmail.com> 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?
I think there are too many examples to exhaustively list them all, but
to give an example, [1, 2, 3, 4] are all the same bug and in [2] Carlo
said we should document this under "Application Setup".  My personal
stance is that the Guix behaviour is not a bug and other distros are
weird for not explicitly binding it.

I know my wording is not the best here, but "If X then Y" is a little
too late when your session broke.  But if your session broke and you
read the manual saying "blah blah unset environment variables evil",
you are more likely to suspect "hmm, maybe evil environment variables
were evil".  Fortunately, with distros trying out Flatpaks and Snaps,
XDG_DATA_DIRS is less likely to break them, but still.  We never know
which variable will be the next to blow things up.

Cheers

[1] https://issues.guix.gnu.org/26202
[2] https://issues.guix.gnu.org/45360
[3] https://issues.guix.gnu.org/48300
[4] https://issues.guix.gnu.org/53379