[bug#36311] doc: Add subsection and note about environment variables.

[bug#36311] doc: Add subsection and note about environment variables.

[swedebugia]

[-- Attachment #1: Type: text/plain, Size: 23 bytes --]


-- 
Cheers Swedebugia

[-- Attachment #2: 0001-doc-Add-subsection-and-note-about-environment-variab.patch --]
[-- Type: text/x-patch, Size: 1971 bytes --]

From f7507682af3b4072596e36321b5ec240e7ab3a10 Mon Sep 17 00:00:00 2001
From: swedebugia <swedebugia@riseup.net>
Date: Thu, 20 Jun 2019 18:02:16 +0200
Subject: [PATCH] doc: Add subsection and note about environment variables.

* doc/guix.texi (Binary Installation and Application Setup): Clarify the
  importance of correct environment variables.
---
 doc/guix.texi | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 65c3b8a7f..470157669 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -601,7 +601,9 @@ where @command{guix pull} will install updates (@pxref{Invoking guix pull}):
          ~root/.config/guix/current
 @end example
 
-Source @file{etc/profile} to augment @code{PATH} and other relevant
+@c This is explained further in @node Application Setup - Importance of
+@c environment variables
+Source @file{etc/profile} from @file{~.bash_profile} to augment @code{PATH} and other relevant
 environment variables:
 
 @example
@@ -1575,6 +1577,20 @@ When using Guix on top of GNU/Linux distribution other than Guix System---a
 so-called @dfn{foreign distro}---a few additional steps are needed to
 get everything in place.  Here are some of them.
 
+@subsection Importance of environment variables
+@cindex environment variables
+Environment variables in the correct place are essential to the correct
+operation of guix in a foreign system.
+
+Following the installation we recommend putting all environment variables into
+ @file{~.bash_profile} to make sure they are only executed when your login to
+ a shell (ie. open up a virtual terminal).
+
+If you use bash and put them into @file{.bashrc} you will end up with errors
+because this file is executed by bash EVERY time a new environment is entered
+(e.g. when entering a pure environment with @command{guix environment guix
+--pure} and contaminate the environment).
+
 @subsection Locales
 
 @anchor{locales-and-locpath}
-- 
2.19.2

[bug#36311] doc: Add subsection and note about environment variables.

[swedebugia]

On 2019-06-20 18:13, swedebugia wrote:
> 
> -- 
> Cheers Swedebugia
> 
> 0001-doc-Add-subsection-and-note-about-environment-variab.patch
> 
>  From f7507682af3b4072596e36321b5ec240e7ab3a10 Mon Sep 17 00:00:00 2001
> From: swedebugia<swedebugia@riseup.net>
> Date: Thu, 20 Jun 2019 18:02:16 +0200
> Subject: [PATCH] doc: Add subsection and note about environment variables.
> 
> * doc/guix.texi (Binary Installation and Application Setup): Clarify the
>    importance of correct environment variables.
> ---
>   doc/guix.texi | 18 +++++++++++++++++-
>   1 file changed, 17 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 65c3b8a7f..470157669 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -601,7 +601,9 @@ where @command{guix pull} will install updates (@pxref{Invoking guix pull}):
>            ~root/.config/guix/current
>   @end example
>   
> -Source @file{etc/profile} to augment @code{PATH} and other relevant
> +@c This is explained further in @node Application Setup - Importance of
> +@c environment variables
> +Source @file{etc/profile} from @file{~.bash_profile} to augment @code{PATH} and other relevant
>   environment variables:
>   
>   @example
> @@ -1575,6 +1577,20 @@ When using Guix on top of GNU/Linux distribution other than Guix System---a
>   so-called @dfn{foreign distro}---a few additional steps are needed to
>   get everything in place.  Here are some of them.
>   
> +@subsection Importance of environment variables
> +@cindex environment variables
> +Environment variables in the correct place are essential to the correct
> +operation of guix in a foreign system.
> +
> +Following the installation we recommend putting all environment variables into
> + @file{~.bash_profile} to make sure they are only executed when your login to
> + a shell (ie. open up a virtual terminal).
> +
> +If you use bash and put them into @file{.bashrc} you will end up with errors
> +because this file is executed by bash EVERY time a new environment is entered
> +(e.g. when entering a pure environment with @command{guix environment guix
> +--pure} and contaminate the environment).
> +
>   @subsection Locales
>   
>   @anchor{locales-and-locpath}
> -- 2.19.2

Anyone up for reviewing?

-- 
Cheers
Swedebugia

[bug#36311] doc: Add subsection and note about environment variables.

[Nicolas Goaziou]

Hello,

swedebugia <swedebugia@riseup.net> writes:

>> +Following the installation we recommend putting all environment variables into
>> + @file{~.bash_profile} to make sure they are only executed when your login to
>> + a shell (ie. open up a virtual terminal).

I think @file{~/.bash_profile} is clearer.

Also "ie. open up…" -> "i.e., open up…" or "i.e.@: open up…"

>> +If you use bash and put them into @file{.bashrc} you will end up with errors
>> +because this file is executed by bash EVERY time a new environment is entered

Maybe @emph{every}, since emphasizing with capitals is typographically
suboptimal.

>> +(e.g. when entering a pure environment with @command{guix environment guix
>> +--pure} and contaminate the environment).

"e.g. when" -> "e.g., when" or "e.g.@: when". 

See (info "Not Ending a Sentence") for more information.

Also, according to (info "@command"), it shoud be either @samp or @code.
After a cursory look, "guix.texi" seems to use "@code" for entire shell
command invocations.

HTH,

-- 
Nicolas Goaziou

[bug#36311] doc: Add subsection and note about environment variables.

[Nicolas Goaziou]

Correcting myself,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> See (info "Not Ending a Sentence") for more information.

I meant (info "(texinfo)Not Ending a Sentence")
>
> Also, according to (info "@command")

and (info "(texinfo)@command")

[bug#36311] doc: Add subsection and note about environment variables.

[Maxim Cournoyer]

Hello,

swedebugia <swedebugia@riseup.net> writes:

> -- 
> Cheers Swedebugia
>
>>From f7507682af3b4072596e36321b5ec240e7ab3a10 Mon Sep 17 00:00:00 2001
> From: swedebugia <swedebugia@riseup.net>
> Date: Thu, 20 Jun 2019 18:02:16 +0200
> Subject: [PATCH] doc: Add subsection and note about environment variables.
>
> * doc/guix.texi (Binary Installation and Application Setup): Clarify the
>   importance of correct environment variables.

[...]

> +@subsection Importance of environment variables
> +@cindex environment variables
> +Environment variables in the correct place are essential to the correct
> +operation of guix in a foreign system.
> +
> +Following the installation we recommend putting all environment variables into
> + @file{~.bash_profile} to make sure they are only executed when your login to
> + a shell (ie. open up a virtual terminal).
> +
> +If you use bash and put them into @file{.bashrc} you will end up with errors
> +because this file is executed by bash EVERY time a new environment is entered
> +(e.g. when entering a pure environment with @command{guix environment guix
> +--pure} and contaminate the environment).

I think this is maybe no longer as necessary, since we now have 'guix
shell --check' that will produce this kind of recommendation?

-- 
Thanks,
Maxim