doc: adapt and extend path_entry_reorder doc

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

Author: xdelaruelle

INSTALL.rst

@@ -750,6 +750,19 @@ instance :instopt:`--disable-set-manpath<--enable-set-manpath>`):
     .. versionchanged:: 5.6
        Enables automated *require via* mechanism
 
+.. instopt:: --enable-path-entry-reorder
+
+ Change order of entry in a path-like environment variable, when
+ :mfcmd:`prepend-path`, :mfcmd:`append-path` or :subcmd:`use` target a path
+ entry that is already defined in the environment variable. (default=no)
+
+ This installation option defines the default value of the
+ :mconfig:`path_entry_reorder` configuration option which could be changed
+ after installation with the :subcmd:`config` sub-command.
+
+ .. only:: html or latex
+
+    .. versionadded:: 5.7
 
 .. instopt:: --enable-quarantine-support
 

Makefile.inc.in

@@ -158,7 +158,7 @@ variantshortcut := @variantshortcut@
 # editor
 editor := @editor@
 
-# Lmod path order
+# path change behavior
 pathentryreorder := @pathentryreorder@
 
 # shell completion location

NEWS.rst

@@ -38,6 +38,13 @@ Modules 5.7.0 (not yet released)
   environment variable on Fish shell version 4.3.
 * When fetching user's groups, in case a group name cannot be resolved use
   this group gid number as name instead of raising an error. (fix issue #604)
+* Introduce :mconfig:`path_entry_reorder` configuration option that change
+  order of entry in a path-like environment variable when it is added again.
+  This new configuration option is disabled by default. This option can be
+  changed at installation time with :instopt:`--enable-path-entry-reorder`.
+  When :mconfig:`path_entry_reorder` is changed with :subcmd:`config`
+  sub-command, it sets the :envvar:`MODULES_PATH_ENTRY_REORDER` environment
+  variable. (fix issue #595 with contribution from Achim Gsell)
 
 
 .. _5.6 release notes:

configure

@@ -292,6 +292,9 @@ Optional Features:
   --enable-require-via    set modulecmd.tcl to consider that a module enabling
                           a modulepath is a requirement for the loaded modules
                           stored in this modulepath [no]
+  --enable-path-entry-reorder
+                          change order of entry in a path-like environment
+                          variable when it is added again [no]
   --enable-implicit-requirement
                           implicitly define a requirement toward modules
                           specified on ``module load`` or ``module unload``

doc/source/changes.rst

@@ -1071,6 +1071,8 @@ The following environment variables appeared on Modules 5.
 |            | :envvar:`__MODULES_LMUSE`,                                      |
 |            | :envvar:`MODULES_REQUIRE_VIA`                                   |
 +------------+-----------------------------------------------------------------+
+| 5.7        | :envvar:`MODULES_PATH_ENTRY_REORDER`                            |
++------------+-----------------------------------------------------------------+
 
 Modules Specific Tcl Commands
 """""""""""""""""""""""""""""

doc/source/module.rst

@@ -1373,8 +1373,8 @@ Module Sub-Commands
  .. mconfig:: path_entry_reorder
 
   Change order of entry in a path-like environment variable, when 
-  :mfcmd:`prepend-path`, :mfcmd:`append-path` or :subcmd:`use` target 
-  a path entry that is already defined in the environment variable.
+  :mfcmd:`prepend-path`, :mfcmd:`append-path` or :subcmd:`use` target a path
+  entry that is already defined in the environment variable.
 
   Default value is ``0``. It can be changed at installation time with the
   :instopt:`--enable-path-entry-reorder` option. The
@@ -1383,7 +1383,7 @@ Module Sub-Commands
   its default value. See :envvar:`MODULES_PATH_ENTRY_REORDER` description
   for details.
 
-  .. only:: html
+  .. only:: html or latex
 
      .. versionadded:: 5.7
 
@@ -5293,30 +5293,33 @@ ENVIRONMENT
 
 .. envvar:: MODULES_PATH_ENTRY_REORDER
 
- This environment variable changes the behavior of :mfcmd:`prepend-path`, :mfcmd:`append-path` and :subcmd:`use`.
+ This environment variable changes the behavior of :mfcmd:`prepend-path`,
+ :mfcmd:`append-path` and :mfcmd:`module use<module>` modulefile commands and
+ sub-commands.
 
- If set to ``1``, and one of these commands targets a path entry that already exists in the environment variable, the entry is moved to the beginning or end (depending on the command), unless duplicates are allowed. This is the default behavior in Lmod.
- If set to ``0``, the environment variable is not modified when the entry already exists.
-
- Example:
-
-  .. parsed-literal::
-
-   :ps:`$` module config path_entry_reorder 0
-   :ps:`$` module append-path PATHVAR /foo
-   :ps:`$` module append-path PATHVAR /bar
-   :ps:`$` module append-path PATHVAR /foo
-   :ps:`$` echo $PATHVAR
-   /foo:/bar
-   :ps:`$` module config path_entry_reorder 1
-   :ps:`$` module append-path PATHVAR /foo
-   :ps:`$` echo $PATHVAR
-   /bar:/foo
-   :ps:`$` module append-path --duplicates PATHVAR /bar
-   :ps:`$` echo $PATHVAR
-   /bar:/foo:/bar
-
- .. only:: html
+ If set to ``1``, and one of these commands targets a path entry that already
+ exists in the environment variable, the entry is moved to the beginning or
+ end (depending on the command), unless duplicates are allowed. If set to
+ ``0``, the environment variable is not modified when the entry already
+ exists.
+
+ .. parsed-literal::
+
+     :ps:`$` module config path_entry_reorder 0
+     :ps:`$` module append-path PATHVAR /foo
+     :ps:`$` module append-path PATHVAR /bar
+     :ps:`$` module append-path PATHVAR /foo
+     :ps:`$` echo $PATHVAR
+     /foo:/bar
+     :ps:`$` module config path_entry_reorder 1
+     :ps:`$` module append-path PATHVAR /foo
+     :ps:`$` echo $PATHVAR
+     /bar:/foo
+     :ps:`$` module append-path --duplicates PATHVAR /bar
+     :ps:`$` echo $PATHVAR
+     /bar:/foo:/bar
+
+ .. only:: html or latex
 
     .. versionadded:: 5.7
 

doc/source/other-implementations.rst

@@ -43,7 +43,6 @@ table highlights features that are unique to each implementation.
        * `i18n`_
        * `Find best module`_
        * `Path entry priorities`_
-       * `Update path entry order`_
        * ``--regexp`` search option
        * `settarg`_
        * `Hook functions`_
@@ -158,6 +157,8 @@ implementation.
      - :ref:`Requiring via module`
    * - `Autoswap`_
      - :ref:`Conflict unload MIGRATING`
+   * - `Update path entry order`_
+     - :mconfig:`path_entry_reorder` configuration option
    * - |LMOD_DOWNSTREAM_CONFLICTS|_ environment variable
      - :ref:`Dependencies between modulefiles`
    * - |LMOD_QUARANTINE_VARS|_ environment variable
@@ -286,5 +287,5 @@ additional tools that enhance how modulefiles are handled.
 If you're aware of a ``module``-related project missing from this list, feel
 free to :ref:`contact us<Community>` so we can add it.
 
-.. |modules_version| replace:: Modules 5.6.0
+.. |modules_version| replace:: Modules 5.7.0 (not yet released)
 .. |lmod_version| replace:: Lmod 9.0.5