From 733aedd0eb1748d997a90e9366b40a85286ffa16 Mon Sep 17 00:00:00 2001
From: Xavier Delaruelle <xavier.delaruelle@cea.fr>
Date: Tue, 25 Aug 2020 07:21:23 +0200
Subject: [PATCH] doc: desc. nearly_forbidden_days config in man/diff docs

---
 doc/source/diff_v3_v4.rst |  4 +++-
 doc/source/module.rst     | 20 ++++++++++++++++++++
 doc/source/modulefile.rst |  8 ++++++++
 3 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/doc/source/diff_v3_v4.rst b/doc/source/diff_v3_v4.rst
index 132b1127..9e42cf56 100644
--- a/doc/source/diff_v3_v4.rst
+++ b/doc/source/diff_v3_v4.rst
@@ -485,7 +485,9 @@ Environment
 
 :envvar:`MODULES_LMSOURCESH``
 
- This environment variable appeared on version ``4.6`` and is not supported on compatibility version.
+:envvar:`MODULES_NEARLY_FORBIDDEN_DAYS``
+
+ These environment variables appeared on version ``4.6`` and are not supported on compatibility version.
 
 
 Modules Specific Tcl Commands
diff --git a/doc/source/module.rst b/doc/source/module.rst
index 64d123e9..cdba70ea 100644
--- a/doc/source/module.rst
+++ b/doc/source/module.rst
@@ -499,6 +499,9 @@ Module Sub-Commands
  * ``locked_configs``: configuration options that cannot be superseded
  * ``ml``: define :command:`ml` command at initialization time (defines
    :envvar:`MODULES_ML`)
+ * ``nearly_forbidden_days``: set the number of days a module should be
+   considered *nearly forbidden* prior reaching its expiry date (defines
+   :envvar:`MODULES_NEARLY_FORBIDDEN_DAYS`)
  * ``pager``: text viewer to paginate message output (defines
    :envvar:`MODULES_PAGER`)
  * ``rcfile``: global run-command file location (defines
@@ -1484,6 +1487,23 @@ ENVIRONMENT
 
     .. versionadded:: 4.5
 
+.. envvar:: MODULES_NEARLY_FORBIDDEN_DAYS
+
+ Number of days a module is considered *nearly forbidden* prior reaching its
+ expiry date set by :mfcmd:`module-forbid` modulefile command. When a *nearly
+ forbidden* module is evaluated a warning message is issued to inform module
+ will soon be forbidden. If set to ``0``, modules will never be considered
+ *nearly forbidden*. Accepted values are integers.
+
+ This configuration is defined in the following order of preference:
+ :envvar:`MODULES_NEARLY_FORBIDDEN_DAYS` environment variable then the default
+ set in :file:`modulecmd.tcl` script configuration. Which means
+ :envvar:`MODULES_NEARLY_FORBIDDEN_DAYS` overrides default configuration.
+
+ .. only:: html
+
+    .. versionadded:: 4.6
+
 .. envvar:: MODULES_PAGER
 
  Text viewer for use to paginate message output if error output stream is
diff --git a/doc/source/modulefile.rst b/doc/source/modulefile.rst
index 4ed28c1b..16ee2f50 100644
--- a/doc/source/modulefile.rst
+++ b/doc/source/modulefile.rst
@@ -263,6 +263,14 @@ the *modulefile* is being loaded.
  Error message returned when trying to evaluate a forbidden module can be
  supplemented with the *text message* set through ``--message`` option.
 
+ If ``--after`` option is set, modules are considered *nearly forbidden*
+ during a number of days defined by the ``nearly_forbidden_days``
+ :file:`modulecmd.tcl` configuration option
+ (see :envvar:`MODULES_NEARLY_FORBIDDEN_DAYS`), prior reaching the expiry
+ date fixed by ``--after`` option. When a *nearly forbidden* module is
+ evaluated a warning message is issued to inform module will soon be
+ forbidden.
+
  If a :mfcmd:`module-forbid` command applies to a *modulefile* also targeted
  by a :mfcmd:`module-hide --hard<module-hide>` command, this module is
  unveiled when precisely named to return an access error.