doc: detail path variable elt counter in man-pages

doc/source/module.rst

@@ -245,10 +245,22 @@ Module Sub-Commands
  variable.  The *--append* flag will append the *directory* to
  **MODULEPATH**.
 
+ Reference counter environment variable **MODULEPATH_modshare** is
+ also set to increase the number of times *directory* has been added to
+ **MODULEPATH**.
+
 **unuse** directory...
 
  Remove one or more *directories* from the **MODULEPATH** environment
- variable.
+ variable if reference counter of these *directories* is equal to 1
+ or unknown.
+
+ Reference counter of *directory* in **MODULEPATH** denotes the number of
+ times *directory* has been enabled. When attempting to remove *directory*
+ from **MODULEPATH**, reference counter variable **MODULEPATH_modshare**
+ is checked and *directory* is removed only if its relative counter is
+ equal to 1 or not defined. Elsewhere *directory* is kept and reference
+ counter is decreased by 1.
 
 **refresh**
 
@@ -478,6 +490,14 @@ ENVIRONMENT
 
  A colon separated list of the full pathname for all loaded *modulefiles*.
 
+**<VAR>_modshare**
+
+ Reference counter variable for path-like variable *<VAR>*. A colon
+ separated list containing pairs of elements. A pair is formed by a path
+ element followed its usage counter which represents the number of times
+ this path has been enabled in variable *<VAR>*. A colon separates the
+ two parts of the pair.
+
 **MODULES_COLLECTION_TARGET**
 
  The collection target that determines what collections are valid thus

doc/source/modulefile.rst

@@ -146,16 +146,28 @@ the *modulefile* is being loaded.
  the Tcl specially by enclosing it in " " or { }). A space, however,
  can not be specified by the *--delim=C* form.
 
+ A reference counter environment variable is also set to increase the
+ number of times *value* has been added to environment *variable*. This
+ reference counter environment variable is named by suffixing *variable*
+ by *_modshare*.
+
  If the *variable* is not set, it is created. When a *modulefile* is
  unloaded, **append-path** and **prepend-path** become **remove-path**.
 
 **remove-path** [-d C|--delim C|--delim=C] variable value
 
- Remove *value* from the colon, or *delimiter*, separated list
- in *variable*. See **prepend-path** or **append-path** for further
- explanation of using an arbitrary delimiter. Every string between colons,
- or delimiters, in *variable* is compared to *value*. If the two match,
- *value* is removed from *variable*.
+ Remove *value* from the colon, or *delimiter*, separated list in
+ *variable*. See **prepend-path** or **append-path** for further explanation
+ of using an arbitrary delimiter. Every string between colons, or delimiters,
+ in *variable* is compared to *value*. If the two match, *value* is removed
+ from *variable* if its reference counter is equal to 1 or unknown.
+
+ Reference counter of *value* in *variable* denotes the number of times
+ *value* has been added to *variable*. This information is stored in
+ environment *variable_modshare*. When attempting to remove *value* from
+ *variable*, relative reference counter is checked and *value* is removed
+ only if counter is equal to 1 or not defined. Elsewhere *value* is kept
+ in *variable* and reference counter is decreased by 1.
 
 **prereq** modulefile...