doc: desc. bash-eval source-sh/sh-to-mod shell mode

Author: xdelaruelle

NEWS.rst

@@ -144,6 +144,10 @@ Modules 5.4.0 (not yet released)
 * Path element equals to delimiter character is allowed on
   :mfcmd:`append-path` and :mfcmd:`prepend-path` modulefile commands. (fix
   issue #522)
+* Add ``bash-eval`` shell mode to :mfcmd:`source-sh` modulefile command and
+  :subcmd:`sh-to-mod` sub-command. With this mode, the generated output of the
+  bash shell script is evaluated to get the environment changes instead of
+  sourcing this script. (fix issue #519)
 
 
 .. _5.3 release notes:

doc/source/changes.rst

@@ -892,8 +892,10 @@ The following module sub-commands appeared on Modules 5.
 
 :subcmd:`sh-to-mod`
 
- Starting Modules 5.1, this sub-command also tracks shell completion changes
- for bash, tcsh and fish shells.
+ Starting Modules ``5.1``, this sub-command also tracks shell completion
+ changes for bash, tcsh and fish shells.
+
+ Shell mode ``bash-eval`` is introduced on Modules version ``5.4``.
 
 :subcmd:`source`
 
@@ -1043,8 +1045,10 @@ The following modulefile Tcl commands appeared on Modules 5.
 
 :mfcmd:`source-sh`
 
- Starting Modules 5.1, this modulefile command also tracks shell completion
- changes for bash, tcsh and fish shells.
+ Starting Modules ``5.1``, this modulefile command also tracks shell
+ completion changes for bash, tcsh and fish shells.
+
+ Shell mode ``bash-eval`` is introduced on Modules version ``5.4``.
 
 :mfcmd:`unsetenv`
 

doc/source/design/source-shell-script-in-modulefile.rst

@@ -211,6 +211,10 @@ Specification
   - A separator string ``%ModulesSubShToMod%`` is printed between each function definition not to get main and nested functions mixed up
   - Such sub-separator is only applied on fish shell
 
+- ``bash-eval`` shell is added in version 5.4
+
+  - Instead of sourcing a bash shell script, execution output of this script is evaluated
+
 - **FUTURE**: this feature may be extended to translate environment changes made by tools like Spack, Lmod or pkg-config. It may provide this way bridges between different realms.
 
 .. vim:set tabstop=2 shiftwidth=2 expandtab autoindent:

doc/source/module.rst

@@ -2260,6 +2260,10 @@ Module Sub-Commands
  The following shells are supported: sh, dash, csh, tcsh, bash, ksh, ksh93,
  zsh and fish.
 
+ *Shell* could also be set to ``bash-eval``. In this mode, bash shell *script*
+ is not sourced but the output resulting from its execution is evaluated to
+ determine the environment changes it does.
+
  .. only:: html
 
     .. versionadded:: 4.6
@@ -2271,6 +2275,9 @@ Module Sub-Commands
        Support for tracking shell completion changes on bash, tcsh and fish
        shells added
 
+    .. versionchanged:: 5.4
+       Support for ``bash-eval`` shell mode added
+
 .. subcmd:: show modulefile...
 
  See :subcmd:`display`.

doc/source/modulefile.rst

@@ -1200,6 +1200,10 @@ the *modulefile* is being loaded.
  The following shells are supported: sh, dash, csh, tcsh, bash, ksh, ksh93,
  zsh and fish.
 
+ *Shell* could also be set to ``bash-eval``. In this mode, bash shell *script*
+ is not sourced but the output resulting from its execution is evaluated to
+ determine the environment changes it does.
+
  .. only:: html
 
     .. versionadded:: 4.6
@@ -1211,6 +1215,9 @@ the *modulefile* is being loaded.
        Support for tracking shell completion changes on bash, tcsh and fish
        shells added
 
+    .. versionchanged:: 5.4
+       Support for ``bash-eval`` shell mode added
+
 .. mfcmd:: system string
 
  Run *string* command through shell. On Unix, command is passed to the