doc: add path_entry_reorder configuration option

Signed-off-by: Achim Gsell <achim.gsell@psi.ch>

Author: gsell

.hunspell.en.dic

@@ -1324,3 +1324,5 @@ structs
 reimplementation
 gid
 cmp
+Achim
+Gsell

INSTALL.rst

@@ -1723,6 +1723,9 @@ installation.
 |                                   |                                              | :envvar:`MODULES_PAGER`,                     |              |           |
 |                                   |                                              | :option:`--paginate`, :option:`--no-pager`   |              |           |
 +-----------------------------------+----------------------------------------------+----------------------------------------------+--------------+-----------+
+| :mconfig:`path_entry_reorder`     | ``0``                                        | :instopt:`--enable-path-entry-reorder`,      |              |           |
+|                                   |                                              | :envvar:`MODULES_PATH_ENTRY_REORDER`         |              |           |
++-----------------------------------+----------------------------------------------+----------------------------------------------+--------------+-----------+
 | :mconfig:`protected_envvars`      | *Unset by default*                           | :envvar:`MODULES_PROTECTED_ENVVARS`          |              |           |
 +-----------------------------------+----------------------------------------------+----------------------------------------------+--------------+-----------+
 | :mconfig:`quarantine_support`     | ``0``                                        | :instopt:`--enable-quarantine-support`,      | X            |           |

doc/source/changes.rst

@@ -1279,6 +1279,8 @@ The following Modules configuration option has been introduced on Modules 5.
 | 5.6        | :mconfig:`spider_output`, :mconfig:`spider_terse_output`,       |
 |            | :mconfig:`spider_indepth`, :mconfig:`require_via`               |
 +------------+-----------------------------------------------------------------+
+| 5.7        | :mconfig:`path_entry_reorder`                                   |
++------------+-----------------------------------------------------------------+
 
 :mconfig:`auto_handling`
 

doc/source/module.rst

@@ -1370,6 +1370,23 @@ Module Sub-Commands
   sub-command when changing this configuration option from its default value.
   See :envvar:`MODULES_PAGER` description for details.
 
+ .. 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.
+
+  Default value is ``0``. It can be changed at installation time with the
+  :instopt:`--enable-path-entry-reorder` option. The
+  :envvar:`MODULES_PATH_ENTRY_REORDER` environment variable is defined by
+  :subcmd:`config` sub-command when changing this configuration option from
+  its default value. See :envvar:`MODULES_PATH_ENTRY_REORDER` description
+  for details.
+
+  .. only:: html
+
+     .. versionadded:: 5.7
+
  .. mconfig:: protected_envvars
 
   Prevents any modification of listed environment variables (colon `:`
@@ -5274,6 +5291,35 @@ ENVIRONMENT
     .. versionchanged:: 5.5
        No pager when :file:`modulecmd.tcl` is run for scripting languages
 
+.. envvar:: MODULES_PATH_ENTRY_REORDER
+
+ This environment variable changes the behavior of :mfcmd:`prepend-path`, :mfcmd:`append-path` and :subcmd:`use`.
+ 
+ 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
+
+    .. versionadded:: 5.7
+
 .. envvar:: MODULES_PROTECTED_ENVVARS
 
  A colon separated list of environment variable names that should not be