doc: clarify script exec properties through source-sh/sh-to-mod

Fixes #646

Signed-off-by: Xavier Delaruelle <xavier.delaruelle@cea.fr>

Author: xdelaruelle

NEWS.rst

@@ -126,6 +126,10 @@ Modules 5.7.0 (not yet released)
   which causes :instopt:`--enable-set-pythonpath` to append the Modules
   ``init`` directory to :envvar:`PYTHONPATH` instead of prepending it.
   (contribution from Byron Boulton)
+* Doc: clarify shell script, executed by :mfcmd:`source-sh` modulefile command
+  or :subcmd:`sh-to-mod` sub-command, does not get access to shell aliases,
+  functions or completions settings only available in interactive sessions or
+  defined in profile files. (fix issue #646)
 
 
 .. _5.6 release notes:

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

@@ -103,6 +103,8 @@ Specification
 
   - if this module is unloaded and if it does not trigger the unload of the modulefile using ``source-sh``, variable will be unset as source-sh script has not increased variable reference counter
 
+- **Limitation**: Script will not get access to shell aliases, functions or completions defined in interactive mode or shell profile configurations
+
 - **Note**: environment change done through ``source-sh`` will not preserve change order occurring in sourced script, as all changes are analyzed after sourcing script
 
 - Most shell will not get the full environment content when spawned as a sub-process

doc/source/module.rst

@@ -2634,6 +2634,11 @@ Module Sub-Commands
  is not sourced but the output resulting from its execution is evaluated to
  determine the environment changes it does.
 
+ .. note:: *shell* is run in non-interactive mode without loading any shell
+    configuration or profile. As a result, script does not have access to
+    transient definitions that are only available in interactive sessions or
+    profile files, such as shell aliases, functions, or completion settings.
+
  .. only:: html or latex
 
     .. versionadded:: 4.6

doc/source/modulefile.rst

@@ -1602,6 +1602,11 @@ the *modulefile* is being loaded.
  multiple shell element separated by colon character. Accepted shell elements
  are: ``envvar``, ``alias``, ``function``, ``chdir`` and ``complete``.
 
+ .. note:: *shell* is run in non-interactive mode without loading any shell
+    configuration or profile. As a result, script does not have access to
+    transient definitions that are only available in interactive sessions or
+    profile files, such as shell aliases, functions, or completion settings.
+
  .. only:: html or latex
 
     .. versionadded:: 4.6