doc: desc. source-sh --ignore option

Author: xdelaruelle

NEWS.rst

@@ -148,6 +148,9 @@ Modules 5.4.0 (not yet released)
   :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)
+* Add ``--ignore`` option to :mfcmd:`source-sh` modulefile command to define
+  shell elements changed by shell script that should be ignored. (fix issue
+  #503)
 
 
 .. _5.3 release notes:

doc/source/changes.rst

@@ -1050,6 +1050,8 @@ The following modulefile Tcl commands appeared on Modules 5.
 
  Shell mode ``bash-eval`` is introduced on Modules version ``5.4``.
 
+ ``--ignore`` option is introduced on Modules version ``5.4``.
+
 :mfcmd:`unsetenv`
 
  Starting with version ``5.1``:

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

@@ -215,6 +215,18 @@ Specification
 
   - Instead of sourcing a bash shell script, execution output of this script is evaluated
 
+- ``--ignore`` option is added in version 5.4
+
+  - This option accepts a list of shell element separated by ``:`` character among:
+
+    - ``envvar``
+    - ``alias``
+    - ``function``
+    - ``chdir``
+    - ``complete``
+
+  - Shell elements changed by sourced script and listed on ``--ignore`` option are ignored (no modulefile command relative to these changes are produced)
+
 - **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/modulefile.rst

@@ -1177,7 +1177,7 @@ the *modulefile* is being loaded.
     .. versionchanged:: 5.1
        Option ``--set-if-undef`` added
 
-.. mfcmd:: source-sh shell script [arg...]
+.. mfcmd:: source-sh [--ignore eltlist] shell script [arg...]
 
  Evaluate with *shell* the designated *script* with defined *arguments* to
  find out the environment changes it does. Those changes obtained by comparing
@@ -1204,6 +1204,11 @@ the *modulefile* is being loaded.
  is not sourced but the output resulting from its execution is evaluated to
  determine the environment changes it does.
 
+ The ``--ignore`` option accepts a list of shell elements whose changes made
+ by *script* should be ignored. *eltlist* corresponds to the concatenation of
+ multiple shell element separated by colon character. Accepted shell elements
+ are: ``envvar``, ``alias``, ``function``, ``chdir`` and ``complete``.
+
  .. only:: html
 
     .. versionadded:: 4.6
@@ -1218,6 +1223,9 @@ the *modulefile* is being loaded.
     .. versionchanged:: 5.4
        Support for ``bash-eval`` shell mode added
 
+    .. versionchanged:: 5.4
+       Option ``--ignore`` added
+
 .. mfcmd:: system string
 
  Run *string* command through shell. On Unix, command is passed to the